@warp-drive-mirror/json-api 5.8.0-alpha.4 → 5.8.0-alpha.41

package/README.md

@@ -1,54 +1,41 @@
-<h1 align="center">
-  <img
-    class="project-logo"
-    src="./logos/github-header.svg#gh-light-mode-only"
-    alt="WarpDrive | Boldly go where no app has gone before"
-    title="WarpDrive | Boldly go where no app has gone before"
-    />
+<p align="center">
   <img
     class="project-logo"
-    src="./logos/github-header.svg#gh-dark-mode-only"
-    alt="WarpDrive | Boldly go where no app has gone before"
-    title="WarpDrive | Boldly go where no app has gone before"
+    src="./logos/logo-yellow-slab.svg"
+    alt="WarpDrive"
+    width="180px"
+    title="WarpDrive"
     />
-</h1>
+</p>
 
-![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=FFC474)
-![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=FFC474)
-![License](https://img.shields.io/github/license/emberjs/data.svg?style=flat&color=FFC474)
-[![Docs](./logos/docs-badge.svg)](https://docs.warp-drive.io)
-[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=FFC474)](https://discord.gg/zT3asNS
+![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=fdb155)
+![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=fdb155)
+![License](https://img.shields.io/github/license/warp-drive-data/warp-drive.svg?style=flat&color=fdb155)
+[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS
 )
-[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=FFC474)](https://discord.gg/n8BptgFzNt
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S
 )
 
+# @warp-drive-mirror/json-api
 
-<br>
-
-<p align="center">
-A {JSON:API} Cache Implementation for <em>Warp</em><strong>Drive</strong>.
-</p>
-
-<br>
+A {json:api} Cache Implementation for ***Warp*Drive**.
 
-## Installation
+`{json:api}` excels at simplifying common complex problems around cache consistency and information density, especially in regards to relational or polymorphic data.
 
-```sh
-pnpm add -E @warp-drive-mirror/json-api
-```
+Because most API responses can be quickly transformed into the `{json:api}` format without losing any information, ***Warp*Drive** recommends that most-if-not-all apps should use this Cache implementation.
 
 <br>
 
 ## Documentation
 
-*Get Started* → [Guides](https://docs.warp-drive.io)
+*Get Started* → [Guides](https://warp-drive.io)
 
 
 <br>
 
 ## Code of Conduct
 
-Refer to the [Code of Conduct](https://github.com/emberjs/data/blob/main/CODE_OF_CONDUCT.md) for community guidelines and inclusivity.
+Refer to the [Code of Conduct](https://github.com/warp-drive-data/warp-drive/blob/main/CODE_OF_CONDUCT.md) for community guidelines and inclusivity.
 
 <br>
 

package/declarations/-private/cache.d.ts

@@ -11,82 +11,12 @@ import type { CollectionResourceDataDocument, ResourceDocument, ResourceErrorDoc
 import type { ApiError } from "@warp-drive-mirror/core/types/spec/error";
 import type { CollectionResourceDocument, ExistingResourceObject, ResourceObject, SingleResourceDocument } from "@warp-drive-mirror/core/types/spec/json-api-raw";
 /**
-* ### 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
-
-```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);
-}
-}
-```
-
+* A {@link Cache} implementation tuned for [{json:api}](https://jsonapi.org/)
+*
 * @categoryDescription Cache Management
 * APIs for primary cache management functionality
 * @categoryDescription Cache Forking
@@ -99,8 +29,8 @@ return new JSONAPICache(capabilities);
 * APIs that support granular field level management of resource data
 * @categoryDescription Resource State
 * APIs that support managing Resource states
-
-@public
+*
+* @public
 */
 export declare class JSONAPICache implements Cache {
 	/**
@@ -194,6 +124,15 @@ export declare class JSONAPICache implements Cache {
 	* of the Graph handling necessary entanglements and
 	* notifications for relational data.
 	*
+	* :::warning
+	* It is not recommended to use the return value as
+	* a serialized representation of the resource both
+	* due to it containing local mutations and because
+	* it may contain additional fields not recognized
+	* by the {json:api} API implementation such as `lid` and
+	* the various internal WarpDrive bookkeeping fields.
+	* :::
+	*
 	* @category Cache Management
 	* @public
 	*/
@@ -325,7 +264,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	willCommit(identifier: ResourceKey, _context: RequestContext | null): void;
+	willCommit(identifier: ResourceKey | ResourceKey[], _context: RequestContext | null): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was successfully updated as part of a save transaction.
@@ -333,7 +272,9 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	didCommit(committedIdentifier: ResourceKey, result: StructuredDataDocument<SingleResourceDocument> | null): SingleResourceDataDocument;
+	didCommit(committedIdentifier: ResourceKey, result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(committedIdentifier: ResourceKey[], result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(committedIdentifier: ResourceKey[], result: StructuredDataDocument<CollectionResourceDataDocument> | null): CollectionResourceDataDocument;
 	/**
 	* [LIFECYCLE] Signals to the cache that a resource
 	* was update via a save transaction failed.
@@ -341,7 +282,7 @@ export declare class JSONAPICache implements Cache {
 	* @category Resource Lifecycle
 	* @public
 	*/
-	commitWasRejected(identifier: ResourceKey, errors?: ApiError[]): void;
+	commitWasRejected(identifier: ResourceKey | ResourceKey[], errors?: ApiError[]): void;
 	/**
 	* [LIFECYCLE] Signals to the cache that all data for a resource
 	* should be cleared.

package/declarations/index.d.ts

@@ -1 +1,5 @@
+/**
+* @module
+* @mergeModuleWith <project>
+*/
 export { JSONAPICache } from "./-private/cache.js";