@warp-drive/core 5.8.0-alpha.30 → 5.8.0-alpha.34

package/dist/unpkg/prod/declarations/store/-private/managers/cache-key-manager.d.ts

@@ -0,0 +1,304 @@
+import { type PersistedResourceKey, type RequestKey, type ResourceKey } from "../../../types/identifier.js";
+import type { RequestInfo } from "../../../types/request.js";
+import type { ExistingResourceIdentifierObject, ResourceIdentifierObject } from "../../../types/spec/json-api-raw.js";
+import type { ForgetMethod, GenerationMethod, KeyInfo, KeyInfoMethod, ResetMethod, UpdateMethod } from "../../-types/q/identifier.js";
+type TypeFromIdentifier<T> = T extends {
+	type: infer U;
+} ? U : string;
+type NarrowIdentifierIfPossible<T> = T extends ExistingResourceIdentifierObject ? PersistedResourceKey<TypeFromIdentifier<T>> : ResourceKey;
+export declare function isResourceKey(identifier: unknown): identifier is ResourceKey;
+export declare function isRequestKey(identifier: unknown): identifier is RequestKey;
+interface KeyOptions {
+	lid: IdentifierMap;
+	id: IdentifierMap;
+}
+type TypeMap = {
+	[key: string]: KeyOptions;
+};
+type IdentifierMap = Map<string, ResourceKey>;
+type StableCache = {
+	resources: IdentifierMap;
+	documents: Map<string, RequestKey>;
+	resourcesByType: TypeMap;
+	polymorphicLidBackMap: Map<string, string[]>;
+};
+export type MergeMethod = (targetIdentifier: ResourceKey, matchedIdentifier: ResourceKey, resourceData: unknown) => ResourceKey;
+/**
+Configures how unique identifier lid strings are generated by @ember-data/store.
+
+This configuration MUST occur prior to the store instance being created.
+
+Takes a method which can expect to receive various data as its first argument
+and the name of a bucket as its second argument.
+
+Currently there are two buckets, 'record' and 'document'.
+
+### Resource (`Record`) Identity
+
+If the bucket is `record` the method must return a unique (to at-least
+the given bucket) string identifier for the given data as a string to be
+used as the `lid` of an `Identifier` token.
+
+This method will only be called by either `getOrCreateRecordIdentifier` or
+`createIdentifierForNewRecord` when an identifier for the supplied data
+is not already known via `lid` or `type + id` combo and one needs to be
+generated or retrieved from a proprietary cache.
+
+`data` will be the same data argument provided to `getOrCreateRecordIdentifier`
+and in the `createIdentifierForNewRecord` case will be an object with
+only `type` as a key.
+
+```ts
+import { setIdentifierGenerationMethod } from '@warp-drive/core';
+
+export function initialize(applicationInstance) {
+// note how `count` here is now scoped to the application instance
+// for our generation method by being inside the closure provided
+// by the initialize function
+let count = 0;
+
+setIdentifierGenerationMethod((resource, bucket) => {
+return resource.lid || `my-key-${count++}`;
+});
+}
+
+export default {
+name: 'configure-ember-data-identifiers',
+initialize
+};
+```
+
+### Document Identity
+
+If the bucket is `document` the method will receive the associated
+immutable `request` passed to `store.request` as its first argument
+and should return a unique string for the given request if the document
+should be cached, and `null` if it should not be cached.
+
+Note, the request result will still be passed to the cache via `Cache.put`,
+but caches should take this as a signal that the document should not itself
+be cached, while its contents may still be used to update other cache state.
+
+The presence of `cacheOptions.key` on the request will take precedence
+for the document cache key, and this method will not be called if it is
+present.
+
+The default method implementation for this bucket is to return `null`
+for all requests whose method is not `GET`, and to return the `url` for
+those where it is.
+
+This means that queries via `POST` MUST provide `cacheOptions.key` or
+implement this hook.
+
+⚠️ Caution: Requests that do not have a `method` assigned are assumed to be `GET`
+
+@public
+*/
+export declare function setIdentifierGenerationMethod(method: GenerationMethod | null): void;
+/**
+Configure a callback for when the identifier cache encounters new resource
+data for an existing resource.
+
+This configuration MUST occur prior to the store instance being created.
+
+```js
+import { setIdentifierUpdateMethod } from '@warp-drive/core';
+```
+
+Takes a method which can expect to receive an existing `Identifier` alongside
+some new data to consider as a second argument. This is an opportunity
+for secondary lookup tables and caches associated with the identifier
+to be amended.
+
+This method is called everytime `updateRecordIdentifier` is called and
+with the same arguments. It provides the opportunity to update secondary
+lookup tables for existing identifiers.
+
+It will always be called after an identifier created with `createIdentifierForNewRecord`
+has been committed, or after an update to the `record` a `RecordIdentifier`
+is assigned to has been committed. Committed here meaning that the server
+has acknowledged the update (for instance after a call to `.save()`)
+
+If `id` has not previously existed, it will be assigned to the `Identifier`
+prior to this `UpdateMethod` being called; however, calls to the parent method
+`updateRecordIdentifier` that attempt to change the `id` or calling update
+without providing an `id` when one is missing will throw an error.
+
+@public
+*/
+export declare function setIdentifierUpdateMethod(method: UpdateMethod | null): void;
+/**
+Configure a callback for when the identifier cache is going to release an identifier.
+
+This configuration MUST occur prior to the store instance being created.
+
+```js
+import { setIdentifierForgetMethod } from '@warp-drive/core';
+```
+
+Takes method which can expect to receive an existing `Identifier` that should be eliminated
+from any secondary lookup tables or caches that the user has populated for it.
+
+@public
+*/
+export declare function setIdentifierForgetMethod(method: ForgetMethod | null): void;
+/**
+Configure a callback for when the identifier cache is being torn down.
+
+This configuration MUST occur prior to the store instance being created.
+
+```js
+import { setIdentifierResetMethod } from '@warp-drive/core';
+```
+
+Takes a method which can expect to be called when the parent application is destroyed.
+
+If you have properly used a WeakMap to encapsulate the state of your customization
+to the application instance, you may not need to implement the `resetMethod`.
+
+@public
+*/
+export declare function setIdentifierResetMethod(method: ResetMethod | null): void;
+/**
+Configure a callback for when the identifier cache is generating a new
+ResourceKey for a resource.
+
+This method controls the `type` and `id` that will be assigned to the
+`ResourceKey` that is created.
+
+This configuration MUST occur prior to the store instance being created.
+
+```js
+import { setKeyInfoForResource } from '@warp-drive/core';
+```
+
+@public
+*/
+export declare function setKeyInfoForResource(method: KeyInfoMethod | null): void;
+/**
+* Each instance of {@link Store} receives a unique instance of a CacheKeyManager.
+*
+* This cache is responsible for assigning or retrieving the unique identify
+* for arbitrary resource data encountered by the store. Data representing
+* a unique resource or record should always be represented by the same
+* identifier.
+*
+* It can be configured by consuming applications.
+*
+* @hideconstructor
+* @public
+*/
+export declare class CacheKeyManager {
+	constructor();
+	/**
+	* allows us to peek without generating when needed
+	* useful for the "create" case when we need to see if
+	* we are accidentally overwritting something
+	*
+	* @private
+	*/
+	peekResourceKey(resource: ResourceIdentifierObject): ResourceKey | undefined;
+	/**
+	* Peeks the {@link RequestKey} for the given {@link RequestInfo}, but will not
+	* create one if none has been previously generated.
+	*
+	* @public
+	*/
+	peekRequestKey(request: RequestInfo): RequestKey | null;
+	/**
+	* Returns the {@link RequestKey} for the given {@link RequestInfo} if the request is
+	* considered cacheable. For cacheable requests, this method will create
+	* a RequestKey if none is found.
+	*
+	* A `null` response indicates the request cannot/will not be cached,
+	* generally this means either
+	*
+	* - {@link RequestInfo.cacheOptions.key} is not present on the `RequestInfo`
+	* - the request's method is `GET` but it has no `url`
+	*
+	* Generally you should not seek to cache requests that are not idempotent
+	* or have side effects, such as mutations that create, update or delete
+	* a resource.
+	*
+	* @public
+	*/
+	getOrCreateDocumentIdentifier(request: RequestInfo): RequestKey | null;
+	/**
+	Returns the {@link ResourceKey} for the given Resource, creates one if it does not yet exist.
+	
+	Specifically this means that we:
+	
+	- validate the `id` `type` and `lid` combo against known identifiers
+	- return an object with an `lid` that is stable (repeated calls with the same
+	`id` + `type` or `lid` will return the same `lid` value)
+	- this referential stability of the object itself is guaranteed
+	
+	@public
+	*/
+	getOrCreateRecordIdentifier<T>(resource: T): NarrowIdentifierIfPossible<T>;
+	/**
+	Returns a new Identifier for the supplied data. Call this method to generate
+	an identifier when a new resource is being created local to the client and
+	potentially does not have an `id`.
+	
+	Delegates generation to the user supplied `GenerateMethod` if one has been provided
+	with the signature `generateMethod({ type }, 'record')`.
+	
+	@public
+	*/
+	createIdentifierForNewRecord(data: {
+		type: string;
+		id?: string | null;
+		lid?: string;
+	}): ResourceKey;
+	/**
+	Provides the opportunity to update secondary lookup tables for existing identifiers
+	Called after an identifier created with `createIdentifierForNewRecord` has been
+	committed.
+	
+	Assigned `id` to an `Identifier` if `id` has not previously existed; however,
+	attempting to change the `id` or calling update without providing an `id` when
+	one is missing will throw an error.
+	
+	- sets `id` (if `id` was previously `null`)
+	- `lid` and `type` MUST NOT be altered post creation
+	
+	If a merge occurs, it is possible the returned identifier does not match the originally
+	provided identifier. In this case the abandoned identifier will go through the usual
+	`forgetRecordIdentifier` codepaths.
+	
+	@public
+	*/
+	updateRecordIdentifier(identifierObject: ResourceKey, data: unknown): ResourceKey;
+	/**
+	Provides the opportunity to eliminate an identifier from secondary lookup tables
+	as well as eliminates it from ember-data's own lookup tables and book keeping.
+	
+	Useful when a record has been deleted and the deletion has been persisted and
+	we do not care about the record anymore. Especially useful when an `id` of a
+	deleted record might be reused later for a new record.
+	
+	@public
+	*/
+	forgetRecordIdentifier(identifierObject: ResourceKey): void;
+}
+/**
+* This type exists for internal use only for
+* where intimate contracts still exist either for
+* the Test Suite or for Legacy code.
+*
+* @private
+*/
+export interface PrivateCacheKeyManager extends CacheKeyManager {
+	_cache: StableCache;
+	/**
+	* Internal hook to allow management of merge conflicts with identifiers.
+	*
+	* we allow late binding of this private internal merge so that
+	* the cache can insert itself here to handle elimination of duplicates
+	*/
+	__configureMerge(method: MergeMethod | null): void;
+	_mergeRecordIdentifiers(keyInfo: KeyInfo, identifier: ResourceKey, existingIdentifier: ResourceKey, data: unknown): ResourceKey;
+	destroy(): void;
+}
+export {};

package/dist/unpkg/prod/declarations/store/-private/managers/cache-manager.d.ts

@@ -0,0 +1,380 @@
+import type { Cache, ChangedAttributesHash, RelationshipDiff } from "../../../types/cache.js";
+import type { Change } from "../../../types/cache/change.js";
+import type { Operation } from "../../../types/cache/operations.js";
+import type { CollectionRelationship, ResourceRelationship } from "../../../types/cache/relationship.js";
+import type { LocalRelationshipOperation } from "../../../types/graph.js";
+import type { RequestKey, ResourceKey } from "../../../types/identifier.js";
+import type { Value } from "../../../types/json/raw.js";
+import type { StructuredDataDocument, StructuredDocument } from "../../../types/request.js";
+import type { CollectionResourceDataDocument, ResourceDocument, SingleResourceDataDocument } from "../../../types/spec/document.js";
+import type { ApiError } from "../../../types/spec/error.js";
+import type { StoreRequestContext } from "../cache-handler/handler.js";
+/**
+* The CacheManager wraps a Cache enforcing that only
+* the public API surface area is exposed.
+*
+* Hence, it is the value of `Store.cache`, wrapping
+* the cache instance returned by `Store.createCache`.
+*
+* It handles translating between cache versions when
+* necessary, for instance when a Store is configured
+* to use both a v1 and a v2 cache depending on some
+* heuristic.
+*
+* Starting with the v2 spec, the cache is designed such
+* that it must be implemented as a singleton.
+*
+* @class CacheManager
+* @public
+*/
+export declare class CacheManager implements Cache {
+	version: "2";
+	constructor(cache: Cache);
+	/**
+	* Cache the response to a request
+	*
+	* Unlike `store.push` which has UPSERT
+	* semantics, `put` has `replace` semantics similar to
+	* the `http` method `PUT`
+	*
+	* the individually cacheable
+	* e resource data it may contain
+	* should upsert, but the document data surrounding it should
+	* fully replace any existing information
+	*
+	* Note that in order to support inserting arbitrary data
+	* to the cache that did not originate from a request `put`
+	* should expect to sometimes encounter a document with only
+	* a `content` member and therefor must not assume the existence
+	* of `request` and `response` on the document.
+	*
+	* @param {StructuredDocument} doc
+	* @return {ResourceDocument}
+	* @public
+	*/
+	put<T>(doc: StructuredDocument<T> | {
+		content: T;
+	}): ResourceDocument;
+	/**
+	* Perform an operation on the cache to update the remote state.
+	*
+	* @public
+	* @param op the operation to perform
+	* @return {void}
+	*/
+	patch(op: Operation | Operation[]): void;
+	/**
+	* Update resource data with a local mutation. Currently supports operations
+	* on relationships only.
+	*
+	* @public
+	* @param mutation
+	*/
+	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 retaining 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.
+	*
+	* @public
+	* @param {ResourceKey | RequestKey} cacheKey
+	* @return {ResourceDocument | ResourceBlob | null} the known resource data
+	*/
+	peek(cacheKey: ResourceKey): unknown;
+	peek(cacheKey: RequestKey): ResourceDocument | null;
+	peekRemoteState(cacheKey: ResourceKey): unknown;
+	peekRemoteState(cacheKey: RequestKey): ResourceDocument | null;
+	/**
+	* Peek the Cache for the existing request data associated with
+	* a cacheable request
+	*
+	* @param {RequestKey}
+	* @return {RequestKey | null}
+	* @public
+	*/
+	peekRequest(key: RequestKey): StructuredDocument<ResourceDocument> | null;
+	/**
+	* Push resource data from a remote source into the cache for this ResourceKey
+	*
+	* @public
+	* @return if `hasRecord` is true then calculated key changes should be returned
+	*/
+	upsert(key: ResourceKey, data: unknown, hasRecord: 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.
+	*
+	* @public
+	* @return {Promise<Cache>}
+	*/
+	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.
+	*
+	* @param {Cache} cache
+	* @public
+	* @return {Promise<void>}
+	*/
+	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 `ResourceKey` 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 {
+	*  key: ResourceKey | RequestKey;
+	*  op: 'upsert' | 'remove';
+	*  patch?: unknown;
+	* }
+	* ```
+	*
+	* @public
+	*/
+	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`.
+	*
+	* @return {Promise<ReadableStream>}
+	* @public
+	*/
+	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.
+	*
+	* @param {ReadableStream} stream
+	* @return {Promise<void>}
+	* @public
+	*/
+	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.
+	*
+	* @public
+	*/
+	clientDidCreate(key: ResourceKey, options?: Record<string, unknown>): Record<string, unknown>;
+	/**
+	* [LIFECYCLE] Signals to the cache that a resource
+	* will be part of a save transaction.
+	*
+	* @public
+	* @param key
+	*/
+	willCommit(key: ResourceKey | ResourceKey[], context: StoreRequestContext): void;
+	/**
+	* [LIFECYCLE] Signals to the cache that a resource
+	* was successfully updated as part of a save transaction.
+	*
+	* @public
+	*/
+	didCommit(key: ResourceKey, result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(key: ResourceKey[], result: StructuredDataDocument<SingleResourceDataDocument> | null): SingleResourceDataDocument;
+	didCommit(key: ResourceKey[], result: StructuredDataDocument<CollectionResourceDataDocument> | null): CollectionResourceDataDocument;
+	/**
+	* [LIFECYCLE] Signals to the cache that a resource
+	* was update via a save transaction failed.
+	*
+	* @public
+	*/
+	commitWasRejected(key: ResourceKey | ResourceKey[], errors?: ApiError[]): void;
+	/**
+	* [LIFECYCLE] Signals to the cache that all data for a resource
+	* should be cleared.
+	*
+	* @public
+	*/
+	unloadRecord(key: ResourceKey): void;
+	/**
+	* Retrieve the data for an attribute from the cache
+	*
+	* @public
+	*/
+	getAttr(key: ResourceKey, propertyName: string): Value | undefined;
+	/**
+	* Retrieve the remote state for an attribute from the cache
+	*
+	* @public
+	*/
+	getRemoteAttr(key: ResourceKey, propertyName: string): Value | undefined;
+	/**
+	* Mutate the data for an attribute in the cache
+	*
+	* @public
+	*/
+	setAttr(key: ResourceKey, propertyName: string, value: Value): void;
+	/**
+	* Query the cache for the changed attributes of a resource.
+	*
+	* @public
+	*/
+	changedAttrs(key: ResourceKey): ChangedAttributesHash;
+	/**
+	* Query the cache for whether any mutated attributes exist
+	*
+	* @public
+	*/
+	hasChangedAttrs(key: ResourceKey): boolean;
+	/**
+	* Tell the cache to discard any uncommitted mutations to attributes
+	*
+	* @public
+	* @return the names of attributes that were restored
+	*/
+	rollbackAttrs(key: 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;
+	};
+	```
+	*
+	* @public
+	*/
+	changedRelationships(key: ResourceKey): Map<string, RelationshipDiff>;
+	/**
+	* Query the cache for whether any mutated attributes exist
+	*
+	* @public
+	*/
+	hasChangedRelationships(key: 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
+	*
+	* @public
+	* @return the names of relationships that were restored
+	*/
+	rollbackRelationships(key: ResourceKey): string[];
+	/**
+	* Query the cache for the current state of a relationship property
+	*
+	* @public
+	* @return resource relationship object
+	*/
+	getRelationship(key: ResourceKey, propertyName: string): ResourceRelationship | CollectionRelationship;
+	/**
+	* Query the cache for the remote state of a relationship property
+	*
+	* @public
+	* @return resource relationship object
+	*/
+	getRemoteRelationship(key: ResourceKey, propertyName: string): ResourceRelationship | CollectionRelationship;
+	/**
+	* Update the cache state for the given resource to be marked as locally deleted,
+	* or remove such a mark.
+	*
+	* @public
+	*/
+	setIsDeleted(key: ResourceKey, isDeleted: boolean): void;
+	/**
+	* Query the cache for any validation errors applicable to the given resource.
+	*
+	* @public
+	*/
+	getErrors(key: ResourceKey): ApiError[];
+	/**
+	* Query the cache for whether a given resource has any available data
+	*
+	* @public
+	*/
+	isEmpty(key: ResourceKey): boolean;
+	/**
+	* Query the cache for whether a given resource was created locally and not
+	* yet persisted.
+	*
+	* @public
+	*/
+	isNew(key: ResourceKey): boolean;
+	/**
+	* Query the cache for whether a given resource is marked as deleted (but not
+	* necessarily persisted yet).
+	*
+	* @public
+	*/
+	isDeleted(key: ResourceKey): boolean;
+	/**
+	* Query the cache for whether a given resource has been deleted and that deletion
+	* has also been persisted.
+	*
+	* @public
+	*/
+	isDeletionCommitted(key: ResourceKey): boolean;
+}