@warp-drive-mirror/json-api 5.6.0-alpha.12 → 5.6.0-alpha.13

package/dist/index.js

@@ -956,26 +956,95 @@ function makeCache() {
 }
 
 /**
-  A JSON:API Cache implementation.
+ * ### JSONAPICache
+ *
+ * ```ts
+ * import { JSONAPICache } from '@warp-drive-mirror/json-api';
+ * ```
+ *
+  A {@link Cache} implementation tuned for [{json:api}](https://jsonapi.org/)
+
+  This format excels at simiplifying common complex problems around cache
+  consistency and information density. Because most API responses can be quickly
+  transformed into {json:api} format without losing any information, WarpDrive
+  recommends that most apps use this Cache implementation.
+
+  If a cache built to understand another format would do better for your app then
+  it just needs to follow the same interface.
+
+  Do you really need a cache? Are sunsets beautiful? Caching is what powers features like
+  immutability, mutation management, and allows ***Warp*Drive** to understand your relational
+  data.
+
+  Some caches are simple request/response maps. ***Warp*Drive**'s is not. The Cache deeply
+  understands the structure of your data, ensuring your data remains consistent both within
+  and across requests.
+
+  ### Installation
+
+  ::: code-group
 
-  What cache the store uses is configurable. Using a different
-  implementation can be achieved by implementing the store's
-  createCache hook.
+  ```sh [pnpm]
+  pnpm add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
+  ```
+
+  ```sh [npm]
+  npm add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
+  ```
+
+  ```sh [yarn]
+  yarn add -E @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
+  ```
+
+  ```sh [bun]
+  bun add --exact @warp-drive-mirror/core@latest @warp-drive-mirror/json-api@latest
+  ```
 
-  This is the cache implementation used by `ember-data`.
+  :::
 
-  ```js
-  import Cache from '@ember-data-mirror/json-api';
-  import Store from '@ember-data-mirror/store';
+  ### Setup
 
-  export default class extends Store {
-    createCache(wrapper) {
-      return new Cache(wrapper);
+  ```ts [services/store.ts]
+  import { Fetch, RequestManager, Store } from '@warp-drive-mirror/core';
+  import {
+    registerDerivations,
+    SchemaService,
+  } from '@warp-drive-mirror/core/reactive';
+  import { CacheHandler } from '@warp-drive-mirror/core/store';
+  import type { CacheCapabilitiesManager } from '@warp-drive-mirror/core/types'; // [!code focus:2]
+  import { JSONAPICache } from '@warp-drive-mirror/json-api';
+
+  export default class AppStore extends Store {
+
+    requestManager = new RequestManager()
+      .use([Fetch])
+      .useCache(CacheHandler);
+
+    createSchemaService() {
+      const schema = new SchemaService();
+      registerDerivations(schema);
+      return schema;
+    }
+
+    createCache(capabilities: CacheCapabilitiesManager) { // [!code focus:3]
+      return new JSONAPICache(capabilities);
     }
   }
   ```
 
-  @class Cache
+ * @categoryDescription Cache Management
+ * APIs for primary cache management functionality
+ * @categoryDescription Cache Forking
+ * APIs that support Cache Forking
+ * @categoryDescription SSR Support
+ * APIs that support SSR functionality
+ * @categoryDescription Resource Lifecycle
+ * APIs that support management of resource data
+ * @categoryDescription Resource Data
+ * APIs that support granular field level management of resource data
+ * @categoryDescription Resource State
+ * APIs that support managing Resource states
+
   @public
  */
 
@@ -983,9 +1052,7 @@ class JSONAPICache {
   /**
    * The Cache Version that this implementation implements.
    *
-   * @type {'2'}
    * @public
-   * @property version
    */
 
   /** @internal */
@@ -1007,8 +1074,9 @@ class JSONAPICache {
     this.__documents = new Map();
   }
 
-  // Cache Management
-  // ================
+  ////////// ================ //////////
+  ////////// Cache Management //////////
+  ////////// ================ //////////
 
   /**
    * Cache the response to a request
@@ -1044,8 +1112,7 @@ class JSONAPICache {
    * associated resource membership order and contents preserved but linked
    * into the cache.
    *
-   * @param {StructuredDocument} doc
-   * @return {ResourceDocument}
+   * @category Cache Management
    * @public
    */
 
@@ -1193,9 +1260,9 @@ class JSONAPICache {
    * Update the "remote" or "canonical" (persisted) state of the Cache
    * by merging new information into the existing state.
    *
+   * @category Cache Management
    * @public
-   * @param {Operation|Operation[]} op the operation or list of operations to perform
-   * @return {void}
+   * @param op the operation or list of operations to perform
    */
   patch(op) {
     if (Array.isArray(op)) {
@@ -1224,8 +1291,7 @@ class JSONAPICache {
   /**
    * Update the "local" or "current" (unpersisted) state of the Cache
    *
-   * @param {Mutation} mutation
-   * @return {void}
+   * @category Cache Management
    * @public
    */
   mutate(mutation) {
@@ -1278,9 +1344,8 @@ class JSONAPICache {
    * of the Graph handling necessary entanglements and
    * notifications for relational data.
    *
+   * @category Cache Management
    * @public
-   * @param {StableRecordIdentifier | StableDocumentIdentifier} identifier
-   * @return {ResourceDocument | ResourceObject | null} the known resource data
    */
 
   peek(identifier) {
@@ -1336,6 +1401,14 @@ class JSONAPICache {
     }
     return null;
   }
+
+  /**
+   * Peek the remote resource data from the Cache.
+   *
+   * @category Cache Management
+   * @public
+   */
+
   peekRemoteState(identifier) {
     if ('type' in identifier) {
       const peeked = this.__safePeek(identifier, false);
@@ -1386,6 +1459,7 @@ class JSONAPICache {
     }
     return null;
   }
+
   /**
    * Peek the Cache for the existing request data associated with
    * a cacheable request.
@@ -1394,8 +1468,7 @@ class JSONAPICache {
    * that it will return the the request, response, and content
    * whereas `peek` will return just the `content`.
    *
-   * @param {StableDocumentIdentifier}
-   * @return {StructuredDocument<ResourceDocument> | null}
+   * @category Cache Management
    * @public
    */
   peekRequest(identifier) {
@@ -1405,11 +1478,9 @@ class JSONAPICache {
   /**
    * Push resource data from a remote source into the cache for this identifier
    *
+   * @category Cache Management
    * @public
-   * @param identifier
-   * @param data
-   * @param hasRecord
-   * @return {void | string[]} if `hasRecord` is true then calculated key changes should be returned
+   * @return if `calculateChanges` is true then calculated key changes should be returned
    */
   upsert(identifier, data, calculateChanges) {
     upgradeCapabilities(this._capabilities);
@@ -1424,8 +1495,9 @@ class JSONAPICache {
     return cacheUpsert(this, identifier, data, calculateChanges);
   }
 
-  // Cache Forking Support
-  // =====================
+  ////////// ============= //////////
+  ////////// Cache Forking //////////
+  ////////// ============= //////////
 
   /**
    * Create a fork of the cache from the current state.
@@ -1434,8 +1506,8 @@ class JSONAPICache {
    * preferring instead to fork at the Store level, which will
    * utilize this method to fork the cache.
    *
+   * @category Cache Forking
    * @internal
-   * @return {Promise<Cache>}
    */
   fork() {
     throw new Error(`Not Implemented`);
@@ -1448,11 +1520,10 @@ class JSONAPICache {
    * preferring instead to merge at the Store level, which will
    * utilize this method to merge the caches.
    *
-   * @param {Cache} cache
-   * @public
-   * @return {Promise<void>}
+   * @category Cache Forking
+   * @internal
    */
-  merge(cache) {
+  merge(_cache) {
     throw new Error(`Not Implemented`);
   }
 
@@ -1486,22 +1557,24 @@ class JSONAPICache {
    * }
    * ```
    *
-   * @public
+   * @category Cache Forking
+   * @internal
    */
   diff() {
     throw new Error(`Not Implemented`);
   }
 
-  // SSR Support
-  // ===========
+  ////////// =========== //////////
+  ////////// SSR Support //////////
+  ////////// =========== //////////
 
   /**
    * Serialize the entire contents of the Cache into a Stream
    * which may be fed back into a new instance of the same Cache
    * via `cache.hydrate`.
    *
-   * @return {Promise<ReadableStream>}
-   * @public
+   * @category SSR Support
+   * @internal
    */
   dump() {
     throw new Error(`Not Implemented`);
@@ -1519,16 +1592,16 @@ class JSONAPICache {
    * behavior supports optimizing pre/fetching of data for route transitions
    * via data-only SSR modes.
    *
-   * @param {ReadableStream} stream
-   * @return {Promise<void>}
-   * @public
+   * @category SSR Support
+   * @internal
    */
   hydrate(stream) {
     throw new Error('Not Implemented');
   }
 
-  // Resource Support
-  // ================
+  ////////// ================== //////////
+  ////////// Resource Lifecycle //////////
+  ////////// ================== //////////
 
   /**
    * [LIFECYCLE] Signal to the cache that a new record has been instantiated on the client
@@ -1536,9 +1609,8 @@ class JSONAPICache {
    * It returns properties from options that should be set on the record during the create
    * process. This return value behavior is deprecated.
    *
+   * @category Resource Lifecycle
    * @public
-   * @param identifier
-   * @param createArgs
    */
   clientDidCreate(identifier, options) {
     if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
@@ -1611,8 +1683,8 @@ class JSONAPICache {
    * [LIFECYCLE] Signals to the cache that a resource
    * will be part of a save transaction.
    *
+   * @category Resource Lifecycle
    * @public
-   * @param identifier
    */
   willCommit(identifier) {
     const cached = this.__peek(identifier, false);
@@ -1666,9 +1738,8 @@ class JSONAPICache {
    * [LIFECYCLE] Signals to the cache that a resource
    * was successfully updated as part of a save transaction.
    *
+   * @category Resource Lifecycle
    * @public
-   * @param identifier
-   * @param data
    */
   didCommit(committedIdentifier, result) {
     const payload = result.content;
@@ -1788,9 +1859,8 @@ class JSONAPICache {
    * [LIFECYCLE] Signals to the cache that a resource
    * was update via a save transaction failed.
    *
+   * @category Resource Lifecycle
    * @public
-   * @param identifier
-   * @param errors
    */
   commitWasRejected(identifier, errors) {
     const cached = this.__peek(identifier, false);
@@ -1818,8 +1888,8 @@ class JSONAPICache {
    *
    * This method is a candidate to become a mutation
    *
+   * @category Resource Lifecycle
    * @public
-   * @param identifier
    */
   unloadRecord(identifier) {
     const storeWrapper = this._capabilities;
@@ -1888,16 +1958,16 @@ class JSONAPICache {
     }
   }
 
-  // Granular Resource Data APIs
-  // ===========================
+  ////////// ============= //////////
+  ////////// Resource Data //////////
+  ////////// ============= //////////
 
   /**
    * Retrieve the data for an attribute from the cache
+   * with local mutations applied.
    *
+   * @category Resource Data
    * @public
-   * @param identifier
-   * @param field
-   * @return {unknown}
    */
   getAttr(identifier, attr) {
     const isSimplePath = !Array.isArray(attr) || attr.length === 1;
@@ -1961,6 +2031,13 @@ class JSONAPICache {
     }
     return current;
   }
+
+  /**
+   * Retrieve the remote data for an attribute from the cache
+   *
+   * @category Resource Data
+   * @public
+   */
   getRemoteAttr(identifier, attr) {
     const isSimplePath = !Array.isArray(attr) || attr.length === 1;
     if (Array.isArray(attr) && attr.length === 1) {
@@ -2021,10 +2098,8 @@ class JSONAPICache {
    *
    * This method is a candidate to become a mutation
    *
+   * @category Resource Data
    * @public
-   * @param identifier
-   * @param field
-   * @param value
    */
   setAttr(identifier, attr, value) {
     // this assert works to ensure we have a non-empty string and/or a non-empty array
@@ -2120,9 +2195,9 @@ class JSONAPICache {
   /**
    * Query the cache for the changed attributes of a resource.
    *
+   * @category Resource Data
    * @public
-   * @param identifier
-   * @return {ChangedAttributesHash} `{ <field>: [<old>, <new>] }`
+   * @return `{ '<field>': ['<old>', '<new>'] }`
    */
   changedAttrs(identifier) {
     const cached = this.__peek(identifier, false);
@@ -2145,9 +2220,8 @@ class JSONAPICache {
   /**
    * Query the cache for whether any mutated attributes exist
    *
+   * @category Resource Data
    * @public
-   * @param identifier
-   * @return {Boolean}
    */
   hasChangedAttrs(identifier) {
     const cached = this.__peek(identifier, true);
@@ -2170,9 +2244,9 @@ class JSONAPICache {
    *
    * This method is a candidate to become a mutation
    *
+   * @category Resource Data
    * @public
-   * @param identifier
-   * @return {String[]} the names of fields that were restored
+   * @return the names of fields that were restored
    */
   rollbackAttrs(identifier) {
     const cached = this.__peek(identifier, false);
@@ -2203,31 +2277,30 @@ class JSONAPICache {
   }
 
   /**
-     * Query the cache for the changes to relationships of a resource.
-     *
-     * Returns a map of relationship names to RelationshipDiff objects.
-     *
-     * ```ts
-     * type RelationshipDiff =
-    | {
+   * Query the cache for the changes to relationships of a resource.
+   *
+   * Returns a map of relationship names to RelationshipDiff objects.
+   *
+   * ```ts
+   * type RelationshipDiff =
+     | {
         kind: 'collection';
         remoteState: StableRecordIdentifier[];
         additions: Set<StableRecordIdentifier>;
         removals: Set<StableRecordIdentifier>;
         localState: StableRecordIdentifier[];
         reordered: boolean;
-      }
-    | {
+       }
+     | {
         kind: 'resource';
         remoteState: StableRecordIdentifier | null;
         localState: StableRecordIdentifier | null;
       };
       ```
-     *
-     * @public
-     * @param {StableRecordIdentifier} identifier
-     * @return {Map<string, RelationshipDiff>}
-     */
+   *
+   * @category Resource Data
+   * @public
+   */
   changedRelationships(identifier) {
     return this.__graph.getChanged(identifier);
   }
@@ -2235,9 +2308,8 @@ class JSONAPICache {
   /**
    * Query the cache for whether any mutated relationships exist
    *
+   * @category Resource Data
    * @public
-   * @param {StableRecordIdentifier} identifier
-   * @return {Boolean}
    */
   hasChangedRelationships(identifier) {
     return this.__graph.hasChanged(identifier);
@@ -2250,9 +2322,9 @@ class JSONAPICache {
    *
    * This method is a candidate to become a mutation
    *
+   * @category Resource Data
    * @public
-   * @param {StableRecordIdentifier} identifier
-   * @return {String[]} the names of relationships that were restored
+   * @return the names of relationships that were restored
    */
   rollbackRelationships(identifier) {
     upgradeCapabilities(this._capabilities);
@@ -2266,20 +2338,28 @@ class JSONAPICache {
   /**
    * Query the cache for the current state of a relationship property
    *
+   * @category Resource Data
    * @public
-   * @param identifier
-   * @param field
    * @return resource relationship object
    */
   getRelationship(identifier, field) {
     return this.__graph.getData(identifier, field);
   }
+
+  /**
+   * Query the cache for the remote state of a relationship property
+   *
+   * @category Resource Data
+   * @public
+   * @return resource relationship object
+   */
   getRemoteRelationship(identifier, field) {
     return this.__graph.getRemoteData(identifier, field);
   }
 
-  // Resource State
-  // ===============
+  ////////// ============== //////////
+  ////////// Resource State //////////
+  ////////// ============== //////////
 
   /**
    * Update the cache state for the given resource to be marked
@@ -2287,9 +2367,8 @@ class JSONAPICache {
    *
    * This method is a candidate to become a mutation
    *
+   * @category Resource State
    * @public
-   * @param identifier
-   * @param {Boolean} isDeleted
    */
   setIsDeleted(identifier, isDeleted) {
     const cached = this.__peek(identifier, false);
@@ -2301,9 +2380,8 @@ class JSONAPICache {
   /**
    * Query the cache for any validation errors applicable to the given resource.
    *
+   * @category Resource State
    * @public
-   * @param identifier
-   * @return {JsonApiError[]}
    */
   getErrors(identifier) {
     return this.__peek(identifier, true).errors || [];
@@ -2312,9 +2390,8 @@ class JSONAPICache {
   /**
    * Query the cache for whether a given resource has any available data
    *
+   * @category Resource State
    * @public
-   * @param identifier
-   * @return {Boolean}
    */
   isEmpty(identifier) {
     const cached = this.__safePeek(identifier, true);
@@ -2325,9 +2402,8 @@ class JSONAPICache {
    * Query the cache for whether a given resource was created locally and not
    * yet persisted.
    *
+   * @category Resource State
    * @public
-   * @param identifier
-   * @return {Boolean}
    */
   isNew(identifier) {
     // TODO can we assert here?
@@ -2338,9 +2414,8 @@ class JSONAPICache {
    * Query the cache for whether a given resource is marked as deleted (but not
    * necessarily persisted yet).
    *
+   * @category Resource State
    * @public
-   * @param identifier
-   * @return {Boolean}
    */
   isDeleted(identifier) {
     // TODO can we assert here?
@@ -2351,9 +2426,8 @@ class JSONAPICache {
    * Query the cache for whether a given resource has been deleted and that deletion
    * has also been persisted.
    *
+   * @category Resource State
    * @public
-   * @param identifier
-   * @return {Boolean}
    */
   isDeletionCommitted(identifier) {
     // TODO can we assert here?
@@ -2364,8 +2438,6 @@ class JSONAPICache {
    * Private method used to populate an entry for the identifier
    *
    * @internal
-   * @param {StableRecordIdentifier} identifier
-   * @return {CachedResource}
    */
   _createCache(identifier) {
     macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
@@ -2382,10 +2454,7 @@ class JSONAPICache {
    * Peek whether we have cached resource data matching the identifier
    * without asserting if the resource data is missing.
    *
-   * @param {StableRecordIdentifier} identifier
-   * @param {Boolean} allowDestroyed
    * @internal
-   * @return {CachedResource | undefined}
    */
   __safePeek(identifier, allowDestroyed) {
     let resource = this.__cache.get(identifier);
@@ -2399,10 +2468,7 @@ class JSONAPICache {
    * Peek whether we have cached resource data matching the identifier
    * Asserts if the resource data is missing.
    *
-   * @param {StableRecordIdentifier} identifier
-   * @param {Boolean} allowDestroyed
    * @internal
-   * @return {CachedResource}
    */
   __peek(identifier, allowDestroyed) {
     const resource = this.__safePeek(identifier, allowDestroyed);