Merge pull request #260 from usu/feat/embedded-collection-standalone

Fix: embedded collections without standalone link

Author: usu

package-lock.json

@@ -42,16 +42,15 @@
   },
   "homepage": "https://github.com/ecamp/hal-json-vuex#readme",
   "dependencies": {
-    "hal-json-normalizer": "^4.0.3",
-    "url-template": "^2.0.8"
+    "hal-json-normalizer": "4.1.1",
+    "url-template": "2.0.8"
   },
   "devDependencies": {
     "@babel/plugin-transform-regenerator": "7.16.7",
     "@babel/plugin-transform-runtime": "7.16.10",
     "@babel/preset-env": "7.16.11",
     "@babel/preset-typescript": "7.16.7",
     "@nuxt/types": "2.15.8",
-    "@types/url-template": "2.0.28",
     "@typescript-eslint/eslint-plugin": "5.10.1",
     "@typescript-eslint/parser": "5.10.1",
     "@vue/eslint-config-standard": "6.1.0",

package.json

@@ -0,0 +1,105 @@
+import { isEntityReference } from './halHelpers'
+import LoadingCollection from './LoadingCollection'
+import ResourceInterface from './interfaces/ResourceInterface'
+import CollectionInterface from './interfaces/CollectionInterface'
+import { Link } from './interfaces/StoreData'
+import Resource from './Resource'
+
+/**
+  * Filter out items that are marked as deleting (eager removal)
+  */
+function filterDeleting (array: Array<ResourceInterface>): Array<ResourceInterface> {
+  return array.filter(entry => !entry._meta.deleting)
+}
+
+class Collection extends Resource {
+  /**
+     * Get items excluding ones marked as 'deleting' (eager remove)
+     * 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.
+     */
+  public get items (): Array<ResourceInterface> {
+    return filterDeleting(this._mapArrayOfEntityReferences(this._storeData.items))
+  }
+
+  /**
+     * Get all items including ones marked as 'deleting' (lazy remove)
+     */
+  public get allItems (): Array<ResourceInterface> {
+    return this._mapArrayOfEntityReferences(this._storeData.items)
+  }
+
+  /**
+     * Returns a promise that resolves to the collection object, once all items have been loaded
+     */
+  public $loadItems () :Promise<CollectionInterface> {
+    return this._itemLoader(this._storeData.items)
+  }
+
+  /**
+     *  Returns a promise that resolves to the collection object, once all items have been loaded
+     */
+  private _itemLoader (array: Array<Link>) : Promise<CollectionInterface> {
+    if (!this._containsUnknownEntityReference(array)) {
+      return Promise.resolve(this as unknown as CollectionInterface) // we know that this object must be of type CollectionInterface
+    }
+
+    // eager loading of 'fetchAllUri' (e.g. parent for embedded collections)
+    if (this.config.avoidNPlusOneRequests) {
+      return this.apiActions.reload(this as unknown as CollectionInterface) as Promise<CollectionInterface> // we know that reload resolves to a type CollectionInterface
+
+      // no eager loading: replace each reference (Link) with a Resource (ResourceInterface)
+    } else {
+      const arrayWithReplacedReferences = this._replaceEntityReferences(array)
+
+      return Promise.all(
+        arrayWithReplacedReferences.map(entry => entry._meta.load)
+      ).then(() => this as unknown as CollectionInterface) // we know that this object must be of type CollectionInterface
+    }
+  }
+
+  /**
+     * 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 LoadingCollection 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 LoadingCollection if any of the array
+     *                         elements is still loading.
+     */
+  private _mapArrayOfEntityReferences (array: Array<Link>): Array<ResourceInterface> {
+    if (!this._containsUnknownEntityReference(array)) {
+      return this._replaceEntityReferences(array)
+    }
+
+    const itemsLoaded = this._itemLoader(array).then(() => this._replaceEntityReferences(array))
+
+    // eager loading of 'fetchAllUri' (e.g. parent for embedded collections)
+    if (this.config.avoidNPlusOneRequests) {
+      return LoadingCollection.create(itemsLoaded)
+
+      // no eager loading: replace each reference (Link) with a Resource (ResourceInterface)
+    } else {
+      return LoadingCollection.create(itemsLoaded, this._replaceEntityReferences(array))
+    }
+  }
+
+  /**
+   * Replace each item in array with a proper Resource (or LoadingResource)
+   */
+  private _replaceEntityReferences (array: Array<Link>): Array<ResourceInterface> {
+    return array
+      .filter(entry => isEntityReference(entry))
+      .map(entry => this.apiActions.get(entry.href))
+  }
+
+  /**
+   * Returns true if any of the items within 'array' is not yet known to the API (meaning it has never been loaded)
+   */
+  private _containsUnknownEntityReference (array: Array<Link>): boolean {
+    return array.some(entry => isEntityReference(entry) && this.apiActions.isUnknown(entry.href))
+  }
+}
+
+export default Collection

src/Collection.ts

@@ -1,40 +1,40 @@
-import LoadingStoreValue from './LoadingStoreValue'
-import Resource from './interfaces/Resource'
+import LoadingResource from './LoadingResource'
+import ResourceInterface from './interfaces/ResourceInterface'
 
-class LoadingStoreCollection {
+class LoadingCollection {
   /**
    * 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 loadArray       Promise that resolves once the array has finished loading
    * @param existingContent optionally set the elements that are already known, for random access
    */
-  static create (loadArray: Promise<Array<Resource> | undefined>, existingContent: Array<Resource> = []): Array<Resource> {
+  static create (loadArray: Promise<Array<ResourceInterface> | undefined>, existingContent: Array<ResourceInterface> = []): Array<ResourceInterface> {
     // if Promsise resolves to undefined, provide empty array
-    // this could happen if items is accessed from a LoadingStoreValue, which resolves to a normal entity without 'items'
+    // this could happen if items is accessed from a LoadingResource, which resolves to a normal entity without 'items'
     const loadArraySafely = loadArray.then(array => array ?? [])
 
-    // proxy array function 'find' to a LoadingStoreValue (Resource)
+    // proxy array function 'find' to a LoadingResource (Resource)
     const singleResultFunctions = ['find']
     singleResultFunctions.forEach(func => {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       existingContent[func] = (...args: any[]) => {
-        const resultLoaded = loadArraySafely.then(array => array[func](...args) as Resource)
-        return new LoadingStoreValue(resultLoaded)
+        const resultLoaded = loadArraySafely.then(array => array[func](...args) as ResourceInterface)
+        return new LoadingResource(resultLoaded)
       }
     })
 
-    // proxy array functions with multiple results to a LoadingStoreCollection (Array<Resource>)
+    // proxy array functions with multiple results to a LoadingCollection (Array<ResourceInterface>)
     const arrayResultFunctions = ['map', 'flatMap', 'filter']
     arrayResultFunctions.forEach(func => {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       existingContent[func] = (...args: any[]) => {
-        const resultLoaded = loadArraySafely.then(array => array[func](...args) as Array<Resource>) // TODO: return type for .map() is not necessarily an Array<Resource>
-        return LoadingStoreCollection.create(resultLoaded)
+        const resultLoaded = loadArraySafely.then(array => array[func](...args) as Array<ResourceInterface>) // TODO: return type for .map() is not necessarily an Array<ResourceInterface>
+        return LoadingCollection.create(resultLoaded)
       }
     })
     return existingContent
   }
 }
 
-export default LoadingStoreCollection
+export default LoadingCollection