Implement requested changes from review

Author: manuelmeister

src/Collection.ts

@@ -41,22 +41,22 @@ class Collection<ItemType extends ResourceInterface, ResourceType extends Collec
   /**
      *  Returns a promise that resolves to the collection object, once all items have been loaded
      */
-  private _itemLoader (array: Array<ItemType>) : Promise<this> {
+  private _itemLoader (array: Array<ItemType | Link>) : Promise<this> {
     if (!this._containsUnknownEntityReference(array)) {
-      return Promise.resolve(this) // we know that this object must be of type CollectionInterface
+      return Promise.resolve(this)
     }
 
     // eager loading of 'fetchAllUri' (e.g. parent for embedded collections)
     if (this.config.avoidNPlusOneRequests) {
-      return this.apiActions.reload<ItemType>(this) as unknown as Promise<this> // we know that reload resolves to a type CollectionInterface
+      return this.apiActions.reload<this>(this)
 
       // 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) // we know that this object must be of type CollectionInterface
+      ).then(() => this)
     }
   }
 
@@ -65,12 +65,10 @@ class Collection<ItemType extends ResourceInterface, ResourceType extends Collec
      * (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<ItemType>): Array<ItemType> {
+  private _mapArrayOfEntityReferences (array: Array<Link>): Array<ItemType> {
     if (!this._containsUnknownEntityReference(array)) {
       return this._replaceEntityReferences(array)
     }
@@ -90,15 +88,15 @@ class Collection<ItemType extends ResourceInterface, ResourceType extends Collec
   /**
    * Replace each item in array with a proper Resource (or LoadingResource)
    */
-  private _replaceEntityReferences (array: Array<ItemType>): Array<ItemType> {
-    const links = array.filter(entry => isEntityReference(entry)) as unknown as Link[]
+  private _replaceEntityReferences (array: Array<ItemType | Link>): Array<ItemType> {
+    const links = array.filter(isEntityReference)
     return links.map(entry => this.apiActions.get<ItemType>(entry.href) as ItemType)
   }
 
   /**
    * 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<ItemType>): boolean {
+  private _containsUnknownEntityReference (array: Array<ItemType | Link>): array is Array<Link> {
     return array.some(entry => isEntityReference(entry) && this.apiActions.isUnknown(entry.href))
   }
 }

src/LoadingCollection.ts

@@ -10,7 +10,6 @@ class LoadingCollection {
    * @param loadArray       Promise that resolves once the array has finished loading
    * @param existingContent optionally set the elements that are already known, for random access
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   static create<ItemType extends ResourceInterface> (loadArray: Promise<Array<ItemType> | undefined>, existingContent: Array<ItemType> = []): Array<ItemType> {
     // if the Promise resolves to undefined, provide empty array
     // this could happen if items is accessed from a LoadingResource, which resolves to a normal entity without 'items'

src/ResourceCreator.ts

@@ -1,6 +1,6 @@
 import type { ApiActions } from './interfaces/Interfaces'
 import type { InternalConfig } from './interfaces/Config'
-import type { StoreData, StoreDataCollection, StoreDataEntity } from './interfaces/StoreData'
+import type { StoreData } from './interfaces/StoreData'
 import type ResourceInterface from './interfaces/ResourceInterface'
 import Resource from './Resource'
 import Collection from './Collection'
@@ -60,11 +60,11 @@ class ResourceCreator<RootEndpoint extends ResourceInterface = ResourceInterface
   wrapData<ResourceType extends ResourceInterface<ResourceType>> (data: StoreData<ResourceType>): ResourceType {
     // Store data looks like a collection --> return CollectionInterface
     if (isCollection<ResourceType>(data)) {
-      return new Collection<ResourceType>(data as StoreDataCollection<ResourceType>, this.apiActions, this, this.config) as unknown as ResourceType// these parameters are passed to Resource constructor
+      return new Collection<ResourceType>(data, this.apiActions, this, this.config) as unknown as ResourceType
 
     // else Store Data looks like an entity --> return normal Resource
     } else {
-      return new Resource<ResourceType>(data as StoreDataEntity<ResourceType>, this.apiActions, this, this.config) as unknown as ResourceType
+      return new Resource<ResourceType>(data, this.apiActions, this, this.config) as unknown as ResourceType
     }
   }
 }

src/halHelpers.ts

@@ -7,7 +7,7 @@ export type keyValueObject = Record<string, unknown>
 /**
  * Verifies that two arrays contain the same values while ignoring the order
  */
-function isEqualIgnoringOrder<T> (array: Array<T>, other: Array<T>) :boolean {
+function isEqualIgnoringOrder<T> (array: Array<T>, other: Array<T>): boolean {
   return array.length === other.length && array.every(elem => other.includes(elem))
 }
 
@@ -27,10 +27,9 @@ function isTemplatedLink (object: keyValueObject): object is TemplatedLink {
  * @param object    to be examined
  * @returns boolean true if the object looks like an entity reference, false otherwise
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function isEntityReference (object: any): object is Link {
+function isEntityReference (object: unknown): object is Link {
   if (!object) return false
-  return isEqualIgnoringOrder(Object.keys(object), ['href'])
+  return isEqualIgnoringOrder(Object.keys((object as Link)), ['href'])
 }
 
 /**
@@ -58,12 +57,10 @@ function isVirtualResource (resource: ResourceInterface): resource is VirtualRes
  * @param object    to be examined
  * @returns boolean true if the object looks like a standalone collection, false otherwise
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function isCollection<StoreType> (object: any): object is StoreDataCollection<StoreType> {
-  return !!(object && Array.isArray(object.items))
+function isCollection<StoreType> (object: unknown): object is StoreDataCollection<StoreType> {
+  return !!(object && Array.isArray((object as StoreDataCollection<StoreType>).items))
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function isCollectionInterface<Item extends ResourceInterface> (object: ResourceInterface): object is CollectionInterface<Item> {
   return isCollection(object._storeData)
 }

src/index.ts

@@ -1,12 +1,14 @@
 import type { CollectionInterface } from './interfaces/CollectionInterface'
 import type { ResourceInterface } from './interfaces/ResourceInterface'
+import type { ResourceReference, CollectionReference } from './interfaces/References'
 import type { HalJsonVuex } from './interfaces/Interfaces'
 import HalJsonVuexPlugin from './HalJsonVuexPlugin'
 import Resource from './Resource'
 import Collection from './Collection'
 import LoadingResource from './LoadingResource'
 
 export type { ResourceInterface, CollectionInterface, HalJsonVuex }
+export type { ResourceReference, CollectionReference }
 
 export { HalJsonVuexPlugin, Resource, Collection, LoadingResource }
 

src/interfaces/CollectionInterface.ts

@@ -1,5 +1,8 @@
 import type ResourceInterface from './ResourceInterface'
 
+/**
+ * Generic interface for a collection ResourceInterface (e.g. a HAl resource with an own store entry and a self link)
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface CollectionInterface<ItemType extends ResourceInterface, ResourceType extends CollectionInterface<ItemType, ResourceType> = any> extends ResourceInterface<ResourceType> {
     items: Array<ItemType>

src/interfaces/Interfaces.ts

@@ -1,5 +1,8 @@
 import type { ResourceInterface } from './ResourceInterface'
 
+/**
+ * This interface defines the API actions that can be performed with the HalJsonVuex plugin.
+ */
 export interface ApiActions<RootEndpoint extends ResourceInterface = ResourceInterface> {
     get:<ResourceType extends ResourceInterface = RootEndpoint> (uriOrEntity?: string | ResourceInterface) => ResourceType
     reload:<ResourceType extends ResourceInterface = RootEndpoint> (uriOrEntity: string | ResourceInterface) => Promise<ResourceType>
@@ -10,9 +13,15 @@ export interface ApiActions<RootEndpoint extends ResourceInterface = ResourceInt
     isUnknown: (uri: string) => boolean
 }
 
+/**
+ * These methods only modify the Vuex store. They do not interact with the API.
+ */
 export interface StoreActions {
     purge<Item extends ResourceInterface> (uriOrEntity: string | Item): void
     purgeAll (): void
 }
 
+/**
+ * This is the main interface for the HalJsonVuex plugin. It combines the API actions and the store actions.
+ */
 export type HalJsonVuex<RootEndpoint extends ResourceInterface = ResourceInterface> = ApiActions<RootEndpoint> & StoreActions

src/interfaces/References.ts

@@ -0,0 +1,26 @@
+import { ResourceInterface } from './ResourceInterface'
+import { CollectionInterface } from './CollectionInterface'
+
+/**
+ * Reference to a resource. This is used to create properties in a ResourceInterface that point to other resources.
+ * @param T      The type of the resource.
+ * @param Params Parameters that can be passed to the request, e.g. to modify the resource request.
+ */
+export type ResourceReference<T extends ResourceInterface<T>, Params = undefined> = Params extends undefined
+    ? () => T
+    : (arg: Params) => T;
+
+/**
+ * Reference to a collection. This is used to create properties in a ResourceInterface that point to a resource collection.
+ * @param Item   The type of the items in the collection.
+ * @param Params Parameters that can be passed to the request, e.g. to filter the collection.
+ * @param Self   The type of the collection itself. This is used to be able to create additional fields
+ *               besides items, allItems on the collection itself.
+ */
+export type CollectionReference<
+    Item extends ResourceInterface<Item>,
+    Params = undefined,
+    Self extends CollectionInterface<Item, Self> = CollectionInterface<Item>,
+> = Params extends undefined
+    ? () => CollectionInterface<Item, Self>
+    : (params: Params) => CollectionInterface<Item, Self>;

src/interfaces/ResourceInterface.ts

@@ -23,6 +23,10 @@ interface ResourceInterface<ResourceType extends ResourceInterface = any> {
     $href: (relation: string, templateParams: Record<string, string | number | boolean>) => Promise<string | undefined>
 }
 
+/**
+ * Generic interface for a ResourceInterface without own store entry and a self link. To reload this resource, the
+ * owning resource has to be reloaded.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 interface VirtualResource<Type extends ResourceInterface = any> extends ResourceInterface<Type> {
     _storeData: VirtualStoreData<Type>

tests/typescript/typecheck.ts

@@ -4,23 +4,13 @@ import { createStore, Store } from 'vuex'
 import HalJsonVuexPlugin from '../../src/HalJsonVuexPlugin'
 import { State } from '../../src/storeModule'
 
-import type CollectionInterface from '../../src/interfaces/CollectionInterface'
-import type ResourceInterface from '../../src/interfaces/ResourceInterface'
-
 /* eslint-disable no-unused-expressions */
 
-export type ResourceReference<T extends ResourceInterface<T>> = () => T;
-
-export type CollectionType<
-    Item extends ResourceInterface<Item>,
-    Self extends CollectionInterface<Item, Self> = CollectionInterface<Item>,
-> = CollectionInterface<Item, Self>;
+import type ResourceInterface from '../../src/interfaces/ResourceInterface'
+import type { ResourceReference, CollectionReference } from '../../src/interfaces/References'
 
-type SingleEndpointResource<T extends ResourceInterface<T>> = (params: { id: string }) => T;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type QueryEndpointResources<T extends ResourceInterface<T>, Param = Record<string, any>> = (
-    params?: Param,
-) => CollectionType<T>;
+type SingleEndpointResource<T extends ResourceInterface<T>> = ResourceReference<T, { id: string }>;
+type QueryEndpointResources<T extends ResourceInterface<T>, Params = undefined> = CollectionReference<T, Params>;
 
 interface PeriodEntity extends ResourceInterface<PeriodEntity> {
   name: string