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

package/dist/index.js

@@ -3,6 +3,7 @@ import { logGroup, isStableIdentifier, isDocumentIdentifier } from '@warp-drive-
 import Fuse from 'fuse.js';
 import jsonToAst from 'json-to-ast';
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
+
 function validateDocumentFields(schema, jsonApiDoc) {
   const {
     data,
@@ -97,6 +98,7 @@ function validateHasManyToLinksMode(resourceType, field, _relationshipDoc, _opti
     throw new Error(`Cannot fetch ${resourceType}.${field.name} because the field is in linksMode but async hasMany is not yet supported`);
   }
 }
+
 function inspectType(obj) {
   if (obj === null) {
     return 'null';
@@ -424,6 +426,7 @@ function getRemoteField(fields, key) {
   }
   return field;
 }
+
 const VALID_TOP_LEVEL_MEMBERS = ['data', 'included', 'meta', 'jsonapi', 'links'];
 
 /**
@@ -534,6 +537,7 @@ function validateTopLevelDocumentMembers(reporter, doc) {
     }
   }
 }
+
 const VALID_COLLECTION_LINKS = ['self', 'related', 'first', 'last', 'prev', 'next'];
 const VALID_RESOURCE_RELATIONSHIP_LINKS = ['self', 'related'];
 const VALID_RESOURCE_LINKS = ['self'];
@@ -575,7 +579,7 @@ function validateLinks(reporter, doc, type, path = ['links']) {
       reporter.warn([...path, key], `Unrecognized top-level link. The data it provides may be ignored as it is not a valid {JSON:API} link for a ${type}`);
     }
     // links may be either a string or an object with an href property or null
-    if (links[key] === null) ;else if (typeof links[key] === 'string') {
+    if (links[key] === null) ; else if (typeof links[key] === 'string') {
       if (links[key].length === 0) {
         reporter.warn([...path, key], `Expected a non-empty string, but received an empty string`);
       }
@@ -608,6 +612,7 @@ function validateLinks(reporter, doc, type, path = ['links']) {
     }
   }
 }
+
 const SINGULAR_OPS = ['createRecord', 'updateRecord', 'deleteRecord', 'findRecord', 'queryRecord'];
 
 /**
@@ -850,6 +855,7 @@ function validateResourceRelationships(reporter, type, resource, path) {
   // TODO @runspired we should warn if the discovered resource-type in a relationship is the abstract
   //   type instead of the concrete type.
 }
+
 function validateDocument(capabilities, doc) {
   macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
     if (!test) {
@@ -917,6 +923,7 @@ function validateResourceDocument(reporter, doc) {
 
   reporter.report();
 }
+
 function isImplicit(relationship) {
   return relationship.definition.isImplicit;
 }
@@ -949,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/)
 
-  What cache the store uses is configurable. Using a different
-  implementation can be achieved by implementing the store's
-  createCache hook.
+  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.
 
-  This is the cache implementation used by `ember-data`.
+  If a cache built to understand another format would do better for your app then
+  it just needs to follow the same interface.
 
-  ```js
-  import Cache from '@ember-data-mirror/json-api';
-  import Store from '@ember-data-mirror/store';
+  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.
 
-  export default class extends Store {
-    createCache(wrapper) {
-      return new Cache(wrapper);
+  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
+
+  ```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
+  ```
+
+  :::
+
+  ### Setup
+
+  ```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
  */
 
@@ -976,9 +1052,7 @@ class JSONAPICache {
   /**
    * The Cache Version that this implementation implements.
    *
-   * @type {'2'}
    * @public
-   * @property version
    */
 
   /** @internal */
@@ -1000,8 +1074,9 @@ class JSONAPICache {
     this.__documents = new Map();
   }
 
-  // Cache Management
-  // ================
+  ////////// ================ //////////
+  ////////// Cache Management //////////
+  ////////// ================ //////////
 
   /**
    * Cache the response to a request
@@ -1037,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
    */
 
@@ -1186,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)) {
@@ -1217,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) {
@@ -1271,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) {
@@ -1329,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);
@@ -1379,6 +1459,7 @@ class JSONAPICache {
     }
     return null;
   }
+
   /**
    * Peek the Cache for the existing request data associated with
    * a cacheable request.
@@ -1387,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) {
@@ -1398,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);
@@ -1417,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.
@@ -1427,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`);
@@ -1441,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`);
   }
 
@@ -1479,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`);
@@ -1512,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
@@ -1529,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)) {
@@ -1604,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);
@@ -1659,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;
@@ -1781,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);
@@ -1811,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;
@@ -1881,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;
@@ -1954,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) {
@@ -2014,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
@@ -2113,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);
@@ -2138,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);
@@ -2163,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);
@@ -2196,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);
   }
@@ -2228,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);
@@ -2243,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);
@@ -2259,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
@@ -2280,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);
@@ -2294,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 || [];
@@ -2305,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);
@@ -2318,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?
@@ -2331,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?
@@ -2344,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?
@@ -2357,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 => {
@@ -2375,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);
@@ -2392,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);
@@ -3154,4 +3227,6 @@ function patchCache(Cache, op) {
     }
   }
 }
-export { JSONAPICache };
+
+export { JSONAPICache };
+//# sourceMappingURL=index.js.map