Merge pull request #10 from ecamp/refactor-to-classes

Refactor to classes

Author: usu

src/CanHaveItems.js

@@ -0,0 +1,73 @@
+import { isEntityReference } from './halHelpers.js'
+import LoadingStoreCollection from './LoadingStoreCollection'
+
+class CanHaveItems {
+  constructor ({ get, reload, isUnknown }, config) {
+    this.apiActions = { get, reload, isUnknown }
+    this.config = config
+  }
+
+  /**
+     * Defines a property getter for the items property.
+     * The items property should always be a getter, in order to make the call to mapArrayOfEntityReferences
+     * lazy, since that potentially fetches a large number of entities from the API.
+     * @param items       array of items, which can be mixed primitive values and entity references
+     * @param fetchAllUri URI that allows fetching all collection items in a single network request, if known
+     * @param property    property name inside the entity fetched at fetchAllUri that contains the collection
+     * @returns object the target object with the added getter
+     */
+  addItemsGetter (items, fetchAllUri, property) {
+    Object.defineProperty(this, 'items', { get: () => this.filterDeleting(this.mapArrayOfEntityReferences(items, fetchAllUri, property)) })
+    Object.defineProperty(this, 'allItems', { get: () => this.mapArrayOfEntityReferences(items, fetchAllUri, property) })
+  }
+
+  filterDeleting (array) {
+    return array.filter(entry => !entry._meta.deleting)
+  }
+
+  /**
+     * Given an array, replaces any entity references in the array with the entity loaded from the Vuex store
+     * (or from the API if necessary), and returns that as a new array. In case some of the entity references in
+     * the array have not finished loading yet, returns a LoadingStoreCollection instead.
+     * @param array            possibly mixed array of values and references
+     * @param fetchAllUri      URI that allows fetching all array items in a single network request, if known
+     * @param fetchAllProperty property in the entity from fetchAllUri that will contain the array
+     * @returns array          the new array with replaced items, or a LoadingStoreCollection if any of the array
+     *                         elements is still loading.
+     */
+  mapArrayOfEntityReferences (array, fetchAllUri, fetchAllProperty) {
+    if (!this.containsUnknownEntityReference(array)) {
+      return this.replaceEntityReferences(array)
+    }
+
+    if (this.config.avoidNPlusOneRequests) {
+      const completelyLoaded = this.apiActions.reload({ _meta: { reload: { uri: fetchAllUri, property: fetchAllProperty } } }, true)
+        .then(() => this.replaceEntityReferences(array))
+      return new LoadingStoreCollection(completelyLoaded)
+    } else {
+      const arrayWithReplacedReferences = this.replaceEntityReferences(array)
+      const arrayCompletelyLoaded = Promise.all(array.map(entry => {
+        if (isEntityReference(entry)) {
+          return this.apiActions.get(entry.href)._meta.load
+        }
+        return Promise.resolve(entry)
+      }))
+      return new LoadingStoreCollection(arrayCompletelyLoaded, arrayWithReplacedReferences)
+    }
+  }
+
+  replaceEntityReferences (array) {
+    return array.map(entry => {
+      if (isEntityReference(entry)) {
+        return this.apiActions.get(entry.href)
+      }
+      return entry
+    })
+  }
+
+  containsUnknownEntityReference (array) {
+    return array.some(entry => isEntityReference(entry) && this.apiActions.isUnknown(entry.href))
+  }
+}
+
+export default CanHaveItems

src/EmbeddedCollection.js

@@ -0,0 +1,36 @@
+import CanHaveItems from './CanHaveItems.js'
+import LoadingStoreCollection from './LoadingStoreCollection'
+
+/**
+ * Imitates a full standalone collection with an items property, even if there is no separate URI (as it
+ * is the case with embedded collections).
+ * Reloading an embedded collection requires special information. Since the embedded collection has no own
+ * URI, we need to reload the whole entity containing the embedded collection. Some extra info about the
+ * containing entity must therefore be passed to this function.
+ * @param items          array of items, which can be mixed primitive values and entity references
+ * @param reloadUri      URI of the entity containing the embedded collection (for reloading)
+ * @param reloadProperty property in the containing entity under which the embedded collection is saved
+ * @param loadPromise    a promise that will resolve when the parent entity has finished (re-)loading
+ */
+class EmbeddedCollection extends CanHaveItems {
+  constructor (items, reloadUri, reloadProperty, { get, reload, isUnknown }, config, loadPromise = null) {
+    super({ get, reload, isUnknown }, config)
+    this._meta = {
+      load: loadPromise
+        ? loadPromise.then(loadedParent => new EmbeddedCollection(loadedParent[reloadProperty], reloadUri, reloadProperty, { get, reload, isUnknown }, config))
+        : Promise.resolve(this),
+      reload: { uri: reloadUri, property: reloadProperty }
+    }
+    this.addItemsGetter(items, reloadUri, reloadProperty)
+  }
+
+  $loadItems () {
+    return new Promise((resolve) => {
+      const items = this.items
+      if (items instanceof LoadingStoreCollection) items._meta.load.then(result => resolve(result))
+      else resolve(items)
+    })
+  }
+}
+
+export default EmbeddedCollection

src/LoadingStoreCollection.js

@@ -0,0 +1,31 @@
+import LoadingStoreValue from './LoadingStoreValue'
+
+/**
+ * Returns a placeholder for an array that has not yet finished loading from the API. The array placeholder
+ * will respond to functional calls (like .find(), .map(), etc.) with further LoadingStoreCollections or
+ * LoadingStoreValues. If passed the existingContent argument, random access and .length will also work.
+ * @param arrayLoaded     Promise that resolves once the array has finished loading
+ * @param existingContent optionally set the elements that are already known, for random access
+ */
+class LoadingStoreCollection {
+  constructor (arrayLoaded, existingContent = []) {
+    const singleResultFunctions = ['find']
+    const arrayResultFunctions = ['map', 'flatMap', 'filter']
+    this._meta = { load: arrayLoaded }
+    singleResultFunctions.forEach(func => {
+      existingContent[func] = (...args) => {
+        const resultLoaded = arrayLoaded.then(array => array[func](...args))
+        return new LoadingStoreValue(resultLoaded)
+      }
+    })
+    arrayResultFunctions.forEach(func => {
+      existingContent[func] = (...args) => {
+        const resultLoaded = arrayLoaded.then(array => array[func](...args))
+        return new LoadingStoreCollection(resultLoaded)
+      }
+    })
+    return existingContent
+  }
+}
+
+export default LoadingStoreCollection

src/LoadingStoreValue.js

@@ -0,0 +1,70 @@
+import LoadingStoreCollection from './LoadingStoreCollection'
+
+/**
+ * Creates a placeholder for an entity which has not yet finished loading from the API.
+ * Such a LoadingStoreValue can safely be used in Vue components, since it will render as an empty
+ * string and Vue's reactivity system will replace it with the real data once that is available.
+ *
+ * Accessing nested functions in a LoadingStoreValue yields another LoadingStoreValue:
+ * new LoadingStoreValue(...).author().organization() // gives another LoadingStoreValue
+ *
+ * Using a LoadingStoreValue or a property of a LoadingStoreValue in a view renders to empty strings:
+ * let user = new LoadingStoreValue(...)
+ * 'The "' + user + '" is called "' + user.name + '"' // gives 'The "" is called ""'
+ *
+ * @param entityLoaded a Promise that resolves to a StoreValue when the entity has finished
+ *                     loading from the API
+ * @param absoluteSelf optional fully qualified URI of the entity being loaded, if available. If passed, the
+ *                     returned LoadingStoreValue will return it in calls to .self and ._meta.self
+ */
+class LoadingStoreValue {
+  constructor (entityLoaded, absoluteSelf = null) {
+    const handler = {
+      get: function (target, prop, _) {
+        if (prop === Symbol.toPrimitive) {
+          return () => ''
+        }
+        if (['then', 'toJSON', Symbol.toStringTag, 'state', 'getters', '$options', '_isVue', '__file', 'render', 'constructor'].includes(prop)) {
+          // This is necessary so that Vue's reactivity system understands to treat this LoadingStoreValue
+          // like a normal object.
+          return undefined
+        }
+        if (prop === 'loading') {
+          return true
+        }
+        if (prop === 'load') {
+          return entityLoaded
+        }
+        if (prop === 'self') {
+          return absoluteSelf
+        }
+        if (prop === '_meta') {
+          // When _meta is requested on a LoadingStoreValue, we keep on using the unmodified promise, because
+          // ._meta.load is supposed to resolve to the whole object, not just the ._meta part of it
+          return new LoadingStoreValue(entityLoaded, absoluteSelf)
+        }
+        if (['$reload'].includes(prop)) {
+          // Skip reloading entities that are already loading
+          return () => entityLoaded
+        }
+        if (['$loadItems', '$post', '$patch', '$del'].includes(prop)) {
+          // It is important to call entity[prop] without first saving it into a variable, because saving to a
+          // variable would change the value of `this` inside the function
+          return (...args) => entityLoaded.then(entity => entity[prop](...args))
+        }
+        const propertyLoaded = entityLoaded.then(entity => entity[prop])
+        if (['items', 'allItems'].includes(prop)) {
+          return new LoadingStoreCollection(propertyLoaded)
+        }
+        // Normal property access: return a function that yields another LoadingStoreValue and renders as empty string
+        const result = templateParams => new LoadingStoreValue(propertyLoaded.then(property => property(templateParams)._meta.load))
+        result.loading = true
+        result.toString = () => ''
+        return result
+      }
+    }
+    return new Proxy(this, handler)
+  }
+}
+
+export default LoadingStoreValue

src/QueryablePromise.js

@@ -0,0 +1,53 @@
+/**
+ * This function allow you to modify a JS Promise by adding some status properties.
+ * Based on: http://stackoverflow.com/questions/21485545/is-there-a-way-to-tell-if-an-es6-promise-is-fulfilled-rejected-resolved
+ * But modified according to the specs of promises : https://promisesaplus.com/
+ */
+class QueryablePromise {
+  constructor (promise) {
+    // Don't modify any promise that has been already modified
+    if (Symbol.for('isPending') in promise) return promise
+
+    // Set initial state
+    let isPending = true
+    let isRejected = false
+    let isFulfilled = false
+
+    // Observe the promise, saving the fulfillment in a closure scope.
+    const queryablePromise = promise.then(
+      function (v) {
+        isFulfilled = true
+        isPending = false
+        return v
+      },
+      function (e) {
+        isRejected = true
+        isPending = false
+        throw e
+      }
+    )
+
+    Object.defineProperty(queryablePromise, Symbol.for('isFulfilled'), { get: function () { return isFulfilled } })
+    Object.defineProperty(queryablePromise, Symbol.for('isPending'), { get: function () { return isPending } })
+    Object.defineProperty(queryablePromise, Symbol.for('isRejected'), { get: function () { return isRejected } })
+    Object.defineProperty(queryablePromise, Symbol.for('done'), { get: function () { return !isPending } }) // official terminology would be 'isSettled' or 'isResolved' (https://stackoverflow.com/questions/29268569/what-is-the-correct-terminology-for-javascript-promises)
+
+    return queryablePromise
+  }
+
+  /**
+   * Returns a resolved Promise and immediately mark it as 'done'
+   */
+  static resolve (value) {
+    const promise = Promise.resolve(value)
+
+    promise[Symbol.for('isFulfilled')] = true
+    promise[Symbol.for('isPending')] = false
+    promise[Symbol.for('isRejected')] = false
+    promise[Symbol.for('done')] = true
+
+    return promise
+  }
+}
+
+export default QueryablePromise

src/StoreValue.js

@@ -0,0 +1,66 @@
+import urltemplate from 'url-template'
+import { isTemplatedLink, isEntityReference, isCollection } from './halHelpers.js'
+import QueryablePromise from './QueryablePromise.js'
+import EmbeddedCollection from './EmbeddedCollection.js'
+import CanHaveItems from './CanHaveItems.js'
+
+/**
+ * Creates an actual StoreValue, by wrapping the given Vuex store data. The data must not be loading.
+ * If the data has been loaded into the store before but is currently reloading, the old data will be
+ * returned, along with a ._meta.load promise that resolves when the reload is complete.
+ * @param data fully loaded entity data from the Vuex store
+ */
+class StoreValue extends CanHaveItems {
+  constructor (data, { get, reload, post, patch, del, isUnknown }, StoreValueCreator, config) {
+    super({ get, reload, isUnknown }, config)
+
+    this.apiActions = { get, reload, post, patch, del, isUnknown }
+    this.config = config
+
+    Object.keys(data).forEach(key => {
+      const value = data[key]
+      if (key === 'allItems' && isCollection(data)) return
+      if (key === 'items' && isCollection(data)) {
+        this.addItemsGetter(data[key], data._meta.self, key)
+      } else if (Array.isArray(value)) {
+        this[key] = () => new EmbeddedCollection(value, data._meta.self, key, { get, reload, isUnknown }, config, data._meta.load)
+      } else if (isEntityReference(value)) {
+        this[key] = () => this.apiActions.get(value.href)
+      } else if (isTemplatedLink(value)) {
+        this[key] = templateParams => this.apiActions.get(urltemplate.parse(value.href).expand(templateParams || {}))
+      } else {
+        this[key] = value
+      }
+    })
+
+    // Use a trivial load promise to break endless recursion, except if we are currently reloading the data from the API
+    const loadedPromise = data._meta.load && !data._meta.load[Symbol.for('done')]
+      ? data._meta.load.then(reloadedData => StoreValueCreator.wrap(reloadedData))
+      : QueryablePromise.resolve(this)
+
+    // Use a shallow clone of _meta, since we don't want to overwrite the ._meta.load promise or self link in the Vuex store
+    this._meta = { ...data._meta, load: loadedPromise, self: this.config.apiRoot + data._meta.self }
+  }
+
+  $reload () {
+    return this.apiActions.reload(this._meta.self)
+  }
+
+  $loadItems () {
+    return this._meta.load
+  }
+
+  $post (data) {
+    return this.apiActions.post(this._meta.self, data)
+  }
+
+  $patch (data) {
+    return this.apiActions.patch(this._meta.self, data)
+  }
+
+  $del () {
+    return this.apiActions.del(this._meta.self)
+  }
+}
+
+export default StoreValue

src/StoreValueCreator.js

@@ -0,0 +1,49 @@
+import StoreValue from './StoreValue.js'
+import LoadingStoreValue from './LoadingStoreValue.js'
+
+class StoreValueCreator {
+  constructor ({ get, reload, post, patch, del, isUnknown }, config = {}) {
+    this.apiActions = { get, reload, post, patch, del, isUnknown }
+    this.config = config
+  }
+
+  /**
+   * Takes data from the Vuex store and makes it more usable in frontend components. The data stored
+   * in the Vuex store should always be JSON serializable according to
+   * https://github.com/vuejs/vuex/issues/757#issuecomment-297668640. Therefore, we wrap the data into
+   * a new object, and provide accessor methods for related entities. Such an accessor method fetches the
+   * related entity from the Vuex store (or the API if necessary) when called. In case the related entity
+   * is still being loaded from the API, a LoadingStoreValue is returned.
+   *
+   * Example:
+   * // Data of an entity like it comes from the Vuex store:
+   * let storeData = {
+   *   numeric_property: 3,
+   *   reference_to_other_entity: {
+   *     href: '/uri/of/other/entity'
+   *   },
+   *   _meta: {
+   *     self: '/self/uri'
+   *   }
+   * }
+   * // Apply StoreValue
+   * let usable = storeValue(...)(storeData)
+   * // Now we can use accessor methods
+   * usable.reference_to_other_entity() // returns the result of this.api.get('/uri/of/other/entity')
+   *
+   * @param data                entity data from the Vuex store
+   * @returns object            wrapped entity ready for use in a frontend component
+   */
+  wrap (data) {
+    const meta = data._meta || { load: Promise.resolve() }
+
+    if (meta.loading) {
+      const entityLoaded = meta.load.then(loadedData => new StoreValue(loadedData, this.apiActions, this, this.config))
+      return new LoadingStoreValue(entityLoaded, this.config.apiRoot + meta.self)
+    }
+
+    return new StoreValue(data, this.apiActions, this, this.config)
+  }
+}
+
+export default StoreValueCreator