@warp-drive-mirror/json-api 5.8.0-alpha.30 → 5.8.0-alpha.34

package/dist/unpkg/dev/declarations/-private/cache.d.ts

@@ -0,0 +1,445 @@
+import type { CacheCapabilitiesManager } from "@warp-drive-mirror/core/types";
+import type { Cache, ChangedAttributesHash, RelationshipDiff } from "@warp-drive-mirror/core/types/cache";
+import type { Change } from "@warp-drive-mirror/core/types/cache/change";
+import type { Operation } from "@warp-drive-mirror/core/types/cache/operations";
+import type { CollectionRelationship, ResourceRelationship } from "@warp-drive-mirror/core/types/cache/relationship";
+import type { LocalRelationshipOperation } from "@warp-drive-mirror/core/types/graph";
+import type { RequestKey, ResourceKey } from "@warp-drive-mirror/core/types/identifier";
+import type { Value } from "@warp-drive-mirror/core/types/json/raw";
+import type { RequestContext, StructuredDataDocument, StructuredDocument, StructuredErrorDocument } from "@warp-drive-mirror/core/types/request";
+import type { CollectionResourceDataDocument, ResourceDocument, ResourceErrorDocument, ResourceMetaDocument, SingleResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
+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";
+/**
+* ```ts
+* import { JSONAPICache } from '@warp-drive-mirror/json-api';
+* ```
+*
+* A {@link Cache} implementation tuned for [{json:api}](https://jsonapi.org/)
+*
+* @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
+*/
+export declare class JSONAPICache implements Cache {
+	/**
+	* The Cache Version that this implementation implements.
+	*
+	* @public
+	*/
+	version: "2";
+	constructor(capabilities: CacheCapabilitiesManager);
+	/**
+	* Cache the response to a request
+	*
+	* Implements `Cache.put`.
+	*
+	* Expects a StructuredDocument whose `content` member is a JsonApiDocument.
+	*
+	* ```js
+	* cache.put({
+	*   request: { url: 'https://api.example.com/v1/user/1' },
+	*   content: {
+	*     data: {
+	*       type: 'user',
+	*       id: '1',
+	*       attributes: {
+	*         name: 'Chris'
+	*       }
+	*     }
+	*   }
+	* })
+	* ```
+	*
+	* > **Note**
+	* > The nested `content` and `data` members are not a mistake. This is because
+	* > there are two separate concepts involved here, the `StructuredDocument` which contains
+	* > the context of a given Request that has been issued with the returned contents as its
+	* > `content` property, and a `JSON:API Document` which is the json contents returned by
+	* > this endpoint and which uses its `data` property to signify which resources are the
+	* > primary resources associated with the request.
+	*
+	* StructuredDocument's with urls will be cached as full documents with
+	* associated resource membership order and contents preserved but linked
+	* into the cache.
+	*
+	* @category Cache Management
+	* @public
+	*/
+	put<T extends SingleResourceDocument>(doc: StructuredDataDocument<T>): SingleResourceDataDocument;
+	put<T extends CollectionResourceDocument>(doc: StructuredDataDocument<T>): CollectionResourceDataDocument;
+	put<T extends ResourceErrorDocument>(doc: StructuredErrorDocument<T>): ResourceErrorDocument;
+	put<T extends ResourceMetaDocument>(doc: StructuredDataDocument<T>): ResourceMetaDocument;
+	/**
+	* Update the "remote" or "canonical" (persisted) state of the Cache
+	* by merging new information into the existing state.
+	*
+	* @category Cache Management
+	* @public
+	* @param op the operation or list of operations to perform
+	*/
+	patch(op: Operation | Operation[]): void;
+	/**
+	* Update the "local" or "current" (unpersisted) state of the Cache
+	*
+	* @category Cache Management
+	* @public
+	*/
+	mutate(mutation: LocalRelationshipOperation): void;
+	/**
+	* Peek resource data from the Cache.
+	*
+	* In development, if the return value
+	* is JSON the return value
+	* will be deep-cloned and deep-frozen
+	* to prevent mutation thereby enforcing cache
+	* Immutability.
+	*
+	* This form of peek is useful for implementations
+	* that want to feed raw-data from cache to the UI
+	* or which want to interact with a blob of data
+	* directly from the presentation cache.
+	*
+	* An implementation might want to do this because
+	* de-referencing records which read from their own
+	* blob is generally safer because the record does
+	* not require retainining connections to the Store
+	* and Cache to present data on a per-field basis.
+	*
+	* This generally takes the place of `getAttr` as
+	* an API and may even take the place of `getRelationship`
+	* depending on implementation specifics, though this
+	* latter usage is less recommended due to the advantages
+	* of the Graph handling necessary entanglements and
+	* notifications for relational data.
+	*
+	* @category Cache Management
+	* @public
+	*/
+	peek(identifier: ResourceKey): ResourceObject | null;
+	peek(identifier: RequestKey): ResourceDocument | null;
+	/**
+	* Peek the remote resource data from the Cache.
+	*
+	* @category Cache Management
+	* @public
+	*/
+	peekRemoteState(identifier: ResourceKey): ResourceObject | null;
+	peekRemoteState(identifier: RequestKey): ResourceDocument | null;
+	/**
+	* Peek the Cache for the existing request data associated with
+	* a cacheable request.
+	*
+	* This is effectively the reverse of `put` for a request in
+	* that it will return the the request, response, and content
+	* whereas `peek` will return just the `content`.
+	*
+	* @category Cache Management
+	* @public
+	*/
+	peekRequest(identifier: RequestKey): StructuredDocument<ResourceDocument> | null;
+	/**
+	* Push resource data from a remote source into the cache for this identifier
+	*
+	* @category Cache Management
+	* @public
+	* @return if `calculateChanges` is true then calculated key changes should be returned
+	*/
+	upsert(identifier: ResourceKey, data: ExistingResourceObject, calculateChanges?: boolean): void | string[];
+	/**
+	* Create a fork of the cache from the current state.
+	*
+	* Applications should typically not call this method themselves,
+	* preferring instead to fork at the Store level, which will
+	* utilize this method to fork the cache.
+	*
+	* @category Cache Forking
+	* @private
+	*/
+	fork(): Promise<Cache>;
+	/**
+	* Merge a fork back into a parent Cache.
+	*
+	* Applications should typically not call this method themselves,
+	* preferring instead to merge at the Store level, which will
+	* utilize this method to merge the caches.
+	*
+	* @category Cache Forking
+	* @private
+	*/
+	merge(_cache: Cache): Promise<void>;
+	/**
+	* Generate the list of changes applied to all
+	* record in the store.
+	*
+	* Each individual resource or document that has
+	* been mutated should be described as an individual
+	* `Change` entry in the returned array.
+	*
+	* A `Change` is described by an object containing up to
+	* three properties: (1) the `identifier` of the entity that
+	* changed; (2) the `op` code of that change being one of
+	* `upsert` or `remove`, and if the op is `upsert` a `patch`
+	* containing the data to merge into the cache for the given
+	* entity.
+	*
+	* This `patch` is opaque to the Store but should be understood
+	* by the Cache and may expect to be utilized by an Adapter
+	* when generating data during a `save` operation.
+	*
+	* It is generally recommended that the `patch` contain only
+	* the updated state, ignoring fields that are unchanged
+	*
+	* ```ts
+	* interface Change {
+	*  identifier: ResourceKey | RequestKey;
+	*  op: 'upsert' | 'remove';
+	*  patch?: unknown;
+	* }
+	* ```
+	*
+	* @category Cache Forking
+	* @private
+	*/
+	diff(): Promise<Change[]>;
+	/**
+	* 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`.
+	*
+	* @category SSR Support
+	* @private
+	*/
+	dump(): Promise<ReadableStream<unknown>>;
+	/**
+	* hydrate a Cache from a Stream with content previously serialized
+	* from another instance of the same Cache, resolving when hydration
+	* is complete.
+	*
+	* This method should expect to be called both in the context of restoring
+	* the Cache during application rehydration after SSR **AND** at unknown
+	* times during the lifetime of an already booted application when it is
+	* desired to bulk-load additional information into the cache. This latter
+	* behavior supports optimizing pre/fetching of data for route transitions
+	* via data-only SSR modes.
+	*
+	* @category SSR Support
+	* @private
+	*/
+	hydrate(stream: ReadableStream<unknown>): Promise<void>;
+	/**
+	* [LIFECYCLE] Signal to the cache that a new record has been instantiated on the client
+	*
+	* 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
+	*/
+	clientDidCreate(identifier: ResourceKey, options?: Record<string, Value>): Record<string, unknown>;
+	/**
+	* [LIFECYCLE] Signals to the cache that a resource
+	* will be part of a save transaction.
+	*
+	* @category Resource Lifecycle
+	* @public
+	*/
+	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.
+	*
+	* @category Resource Lifecycle
+	* @public
+	*/
+	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.
+	*
+	* @category Resource Lifecycle
+	* @public
+	*/
+	commitWasRejected(identifier: ResourceKey | ResourceKey[], errors?: ApiError[]): void;
+	/**
+	* [LIFECYCLE] Signals to the cache that all data for a resource
+	* should be cleared.
+	*
+	* This method is a candidate to become a mutation
+	*
+	* @category Resource Lifecycle
+	* @public
+	*/
+	unloadRecord(identifier: ResourceKey): void;
+	/**
+	* Retrieve the data for an attribute from the cache
+	* with local mutations applied.
+	*
+	* @category Resource Data
+	* @public
+	*/
+	getAttr(identifier: ResourceKey, attr: string | string[]): Value | undefined;
+	/**
+	* Retrieve the remote data for an attribute from the cache
+	*
+	* @category Resource Data
+	* @public
+	*/
+	getRemoteAttr(identifier: ResourceKey, attr: string | string[]): Value | undefined;
+	/**
+	* Mutate the data for an attribute in the cache
+	*
+	* This method is a candidate to become a mutation
+	*
+	* @category Resource Data
+	* @public
+	*/
+	setAttr(identifier: ResourceKey, attr: string | string[], value: Value): void;
+	/**
+	* Query the cache for the changed attributes of a resource.
+	*
+	* @category Resource Data
+	* @public
+	* @return `{ '<field>': ['<old>', '<new>'] }`
+	*/
+	changedAttrs(identifier: ResourceKey): ChangedAttributesHash;
+	/**
+	* Query the cache for whether any mutated attributes exist
+	*
+	* @category Resource Data
+	* @public
+	*/
+	hasChangedAttrs(identifier: ResourceKey): boolean;
+	/**
+	* Tell the cache to discard any uncommitted mutations to attributes
+	*
+	* This method is a candidate to become a mutation
+	*
+	* @category Resource Data
+	* @public
+	* @return the names of fields that were restored
+	*/
+	rollbackAttrs(identifier: ResourceKey): string[];
+	/**
+	* 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: ResourceKey[];
+	additions: Set<ResourceKey>;
+	removals: Set<ResourceKey>;
+	localState: ResourceKey[];
+	reordered: boolean;
+	}
+	| {
+	kind: 'resource';
+	remoteState: ResourceKey | null;
+	localState: ResourceKey | null;
+	};
+	```
+	*
+	* @category Resource Data
+	* @public
+	*/
+	changedRelationships(identifier: ResourceKey): Map<string, RelationshipDiff>;
+	/**
+	* Query the cache for whether any mutated relationships exist
+	*
+	* @category Resource Data
+	* @public
+	*/
+	hasChangedRelationships(identifier: ResourceKey): boolean;
+	/**
+	* Tell the cache to discard any uncommitted mutations to relationships.
+	*
+	* This will also discard the change on any appropriate inverses.
+	*
+	* This method is a candidate to become a mutation
+	*
+	* @category Resource Data
+	* @public
+	* @return the names of relationships that were restored
+	*/
+	rollbackRelationships(identifier: ResourceKey): string[];
+	/**
+	* Query the cache for the current state of a relationship property
+	*
+	* @category Resource Data
+	* @public
+	* @return resource relationship object
+	*/
+	getRelationship(identifier: ResourceKey, field: string): ResourceRelationship | CollectionRelationship;
+	/**
+	* Query the cache for the remote state of a relationship property
+	*
+	* @category Resource Data
+	* @public
+	* @return resource relationship object
+	*/
+	getRemoteRelationship(identifier: ResourceKey, field: string): ResourceRelationship | CollectionRelationship;
+	/**
+	* Update the cache state for the given resource to be marked
+	* as locally deleted, or remove such a mark.
+	*
+	* This method is a candidate to become a mutation
+	*
+	* @category Resource State
+	* @public
+	*/
+	setIsDeleted(identifier: ResourceKey, isDeleted: boolean): void;
+	/**
+	* Query the cache for any validation errors applicable to the given resource.
+	*
+	* @category Resource State
+	* @public
+	*/
+	getErrors(identifier: ResourceKey): ApiError[];
+	/**
+	* Query the cache for whether a given resource has any available data
+	*
+	* @category Resource State
+	* @public
+	*/
+	isEmpty(identifier: ResourceKey): boolean;
+	/**
+	* Query the cache for whether a given resource was created locally and not
+	* yet persisted.
+	*
+	* @category Resource State
+	* @public
+	*/
+	isNew(identifier: ResourceKey): boolean;
+	/**
+	* Query the cache for whether a given resource is marked as deleted (but not
+	* necessarily persisted yet).
+	*
+	* @category Resource State
+	* @public
+	*/
+	isDeleted(identifier: ResourceKey): boolean;
+	/**
+	* Query the cache for whether a given resource has been deleted and that deletion
+	* has also been persisted.
+	*
+	* @category Resource State
+	* @public
+	*/
+	isDeletionCommitted(identifier: ResourceKey): boolean;
+}

package/dist/unpkg/dev/declarations/-private/validate-document-fields.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaService } from "@warp-drive-mirror/core/types";
+import type { CollectionResourceDocument, SingleResourceDocument } from "@warp-drive-mirror/core/types/spec/json-api-raw";
+export declare function validateDocumentFields(schema: SchemaService, jsonApiDoc: SingleResourceDocument | CollectionResourceDocument): void;

package/dist/unpkg/dev/declarations/-private/validator/1.1/7.1_top-level-document-members.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/unpkg/dev/declarations/-private/validator/1.1/7.2_resource-objects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/unpkg/dev/declarations/-private/validator/1.1/links.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/unpkg/dev/declarations/-private/validator/index.d.ts

@@ -0,0 +1,4 @@
+import type { CacheCapabilitiesManager } from "@warp-drive-mirror/core/types";
+import type { StructuredDocument } from "@warp-drive-mirror/core/types/request";
+import type { ResourceDocument } from "@warp-drive-mirror/core/types/spec/document";
+export declare function validateDocument(capabilities: CacheCapabilitiesManager, doc: StructuredDocument<ResourceDocument>): void;

package/dist/unpkg/dev/declarations/-private/validator/utils.d.ts

@@ -0,0 +1,75 @@
+import type { FuseResult } from "fuse.js";
+import Fuse from "fuse.js";
+import jsonToAst from "json-to-ast";
+import type { CacheCapabilitiesManager, SchemaService } from "@warp-drive-mirror/core/types";
+import type { StructuredDataDocument, StructuredDocument, StructuredErrorDocument } from "@warp-drive-mirror/core/types/request";
+import type { FieldSchema } from "@warp-drive-mirror/core/types/schema/fields";
+import type { ResourceDataDocument, ResourceDocument, ResourceErrorDocument, ResourceMetaDocument } from "@warp-drive-mirror/core/types/spec/document";
+export declare function inspectType(obj: unknown): string;
+export declare function isSimpleObject(obj: unknown): obj is Record<string, unknown>;
+export declare const RELATIONSHIP_FIELD_KINDS: string[];
+export type PathLike = Array<string | number>;
+interface ErrorReport {
+	path: PathLike;
+	message: string;
+	loc: {
+		start: {
+			line: number;
+			column: number;
+			offset: number;
+		};
+		end: {
+			line: number;
+			column: number;
+			offset: number;
+		};
+	};
+	type: "error" | "warning" | "info";
+	kind: "key" | "value";
+}
+export declare class Reporter {
+	capabilities: CacheCapabilitiesManager;
+	contextDocument: StructuredDocument<ResourceDocument>;
+	errors: ErrorReport[];
+	ast: ReturnType<typeof jsonToAst>;
+	jsonStr: string;
+	strict: {
+		linkage: boolean;
+		unknownType: boolean;
+		unknownAttribute: boolean;
+		unknownRelationship: boolean;
+	};
+	constructor(capabilities: CacheCapabilitiesManager, doc: StructuredDocument<ResourceDocument>);
+	_typeFilter: Fuse<string> | undefined;
+	searchTypes(type: string): FuseResult<string>[];
+	_fieldFilters: Map<string, Fuse<string>>;
+	searchFields(type: string, field: string): FuseResult<string>[];
+	get schema(): SchemaService;
+	getLocation(path: PathLike, kind: "key" | "value"): {
+		start: {
+			line: number;
+			column: number;
+			offset: number;
+		};
+		end: {
+			line: number;
+			column: number;
+			offset: number;
+		};
+	};
+	error(path: PathLike, message: string, kind?: "key" | "value"): void;
+	warn(path: PathLike, message: string, kind?: "key" | "value"): void;
+	info(path: PathLike, message: string, kind?: "key" | "value"): void;
+	hasExtension(extensionName: string): boolean;
+	getExtension(extensionName: string): ReporterFn | undefined;
+	report(colorize?: boolean): void;
+}
+type ReporterFn = (reporter: Reporter, path: PathLike) => void;
+export declare function isMetaDocument(doc: StructuredDocument<ResourceDocument>): doc is StructuredDataDocument<ResourceMetaDocument>;
+export declare function isErrorDocument(doc: StructuredDocument<ResourceDocument>): doc is StructuredErrorDocument<ResourceErrorDocument>;
+export declare function isPushedDocument(doc: unknown): doc is {
+	content: ResourceDataDocument;
+};
+export declare function logPotentialMatches(matches: FuseResult<string>[], kind: string): string;
+export declare function getRemoteField(fields: Map<string, FieldSchema>, key: string): FieldSchema | undefined;
+export {};

package/dist/unpkg/dev/declarations/index.d.ts

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