@warp-drive/core 5.6.0-alpha.17 → 5.6.0-alpha.5

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

@@ -1,443 +0,0 @@
-import type { Cache, ChangedAttributesHash, RelationshipDiff } from "../../../types/cache.js";
-import type { Change } from "../../../types/cache/change.js";
-import type { MergeOperation } from "../../../types/cache/operations.js";
-import type { CollectionRelationship, ResourceRelationship } from "../../../types/cache/relationship.js";
-import type { LocalRelationshipOperation } from "../../../types/graph.js";
-import type { StableDocumentIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
-import type { Value } from "../../../types/json/raw.js";
-import type { StructuredDataDocument, StructuredDocument } from "../../../types/request.js";
-import type { 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 {
-	#private;
-	version: "2";
-	constructor(cache: Cache);
-	// Cache Management
-	// ================
-	/**
-	* 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.
-	*
-	* Note: currently the only valid operation is a MergeOperation
-	* which occurs when a collision of identifiers is detected.
-	*
-	* @public
-	* @param op the operation to perform
-	* @return {void}
-	*/
-	patch(op: MergeOperation): 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 {StableRecordIdentifier | StableDocumentIdentifier} identifier
-	* @return {ResourceDocument | ResourceBlob | null} the known resource data
-	*/
-	peek(identifier: StableRecordIdentifier): unknown;
-	peek(identifier: StableDocumentIdentifier): ResourceDocument | null;
-	peekRemoteState(identifier: StableRecordIdentifier): unknown;
-	peekRemoteState(identifier: StableDocumentIdentifier): ResourceDocument | null;
-	/**
-	* Peek the Cache for the existing request data associated with
-	* a cacheable request
-	*
-	* @param {StableDocumentIdentifier}
-	* @return {StableDocumentIdentifier | null}
-	* @public
-	*/
-	peekRequest(identifier: StableDocumentIdentifier): StructuredDocument<ResourceDocument> | null;
-	/**
-	* Push resource data from a remote source into the cache for this identifier
-	*
-	* @public
-	* @param identifier
-	* @param data
-	* @param hasRecord
-	* @return {void | string[]} if `hasRecord` is true then calculated key changes should be returned
-	*/
-	upsert(identifier: StableRecordIdentifier, data: unknown, hasRecord: boolean): void | string[];
-	// Cache Forking Support
-	// =====================
-	/**
-	* 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 `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: StableRecordIdentifier | StableDocumentIdentifier;
-	*  op: 'upsert' | 'remove';
-	*  patch?: unknown;
-	* }
-	* ```
-	*
-	* @public
-	*/
-	diff(): Promise<Change[]>;
-	// 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
-	*/
-	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>;
-	// Cache
-	// =====
-	// Resource Support
-	// ================
-	/**
-	* [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
-	* @param identifier
-	* @param options
-	*/
-	clientDidCreate(identifier: StableRecordIdentifier, options?: Record<string, unknown>): Record<string, unknown>;
-	/**
-	* [LIFECYCLE] Signals to the cache that a resource
-	* will be part of a save transaction.
-	*
-	* @public
-	* @param identifier
-	*/
-	willCommit(identifier: StableRecordIdentifier, context: StoreRequestContext): void;
-	/**
-	* [LIFECYCLE] Signals to the cache that a resource
-	* was successfully updated as part of a save transaction.
-	*
-	* @public
-	* @param identifier
-	* @param data
-	*/
-	didCommit(identifier: StableRecordIdentifier, result: StructuredDataDocument<unknown>): SingleResourceDataDocument;
-	/**
-	* [LIFECYCLE] Signals to the cache that a resource
-	* was update via a save transaction failed.
-	*
-	* @public
-	* @param identifier
-	* @param errors
-	*/
-	commitWasRejected(identifier: StableRecordIdentifier, errors?: ApiError[]): void;
-	/**
-	* [LIFECYCLE] Signals to the cache that all data for a resource
-	* should be cleared.
-	*
-	* @public
-	* @param identifier
-	*/
-	unloadRecord(identifier: StableRecordIdentifier): void;
-	// Granular Resource Data APIs
-	// ===========================
-	/**
-	* Retrieve the data for an attribute from the cache
-	*
-	* @public
-	* @param identifier
-	* @param propertyName
-	* @return {unknown}
-	*/
-	getAttr(identifier: StableRecordIdentifier, propertyName: string): Value | undefined;
-	/**
-	* Retrieve the remote state for an attribute from the cache
-	*
-	* @public
-	* @param identifier
-	* @param propertyName
-	* @return {unknown}
-	*/
-	getRemoteAttr(identifier: StableRecordIdentifier, propertyName: string): Value | undefined;
-	/**
-	* Mutate the data for an attribute in the cache
-	*
-	* @public
-	* @param identifier
-	* @param propertyName
-	* @param value
-	*/
-	setAttr(identifier: StableRecordIdentifier, propertyName: string, value: Value): void;
-	/**
-	* Query the cache for the changed attributes of a resource.
-	*
-	* @public
-	* @param identifier
-	* @return
-	*/
-	changedAttrs(identifier: StableRecordIdentifier): ChangedAttributesHash;
-	/**
-	* Query the cache for whether any mutated attributes exist
-	*
-	* @public
-	* @param identifier
-	* @return {Boolean}
-	*/
-	hasChangedAttrs(identifier: StableRecordIdentifier): boolean;
-	/**
-	* Tell the cache to discard any uncommitted mutations to attributes
-	*
-	* @public
-	* @param identifier
-	* @return the names of attributes that were restored
-	*/
-	rollbackAttrs(identifier: StableRecordIdentifier): string[];
-	// Relationships
-	// =============
-	/**
-	* 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>}
-	*/
-	changedRelationships(identifier: StableRecordIdentifier): Map<string, RelationshipDiff>;
-	/**
-	* Query the cache for whether any mutated attributes exist
-	*
-	* @public
-	* @param {StableRecordIdentifier} identifier
-	* @return {Boolean}
-	*/
-	hasChangedRelationships(identifier: StableRecordIdentifier): 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
-	* @param {StableRecordIdentifier} identifier
-	* @return {String[]} the names of relationships that were restored
-	*/
-	rollbackRelationships(identifier: StableRecordIdentifier): string[];
-	/**
-	* Query the cache for the current state of a relationship property
-	*
-	* @public
-	* @param identifier
-	* @param propertyName
-	* @return resource relationship object
-	*/
-	getRelationship(identifier: StableRecordIdentifier, propertyName: string): ResourceRelationship | CollectionRelationship;
-	/**
-	* Query the cache for the remote state of a relationship property
-	*
-	* @public
-	* @param identifier
-	* @param propertyName
-	* @return resource relationship object
-	*/
-	getRemoteRelationship(identifier: StableRecordIdentifier, propertyName: string): ResourceRelationship | CollectionRelationship;
-	// Resource State
-	// ===============
-	/**
-	* Update the cache state for the given resource to be marked as locally deleted,
-	* or remove such a mark.
-	*
-	* @public
-	* @param identifier
-	* @param isDeleted
-	*/
-	setIsDeleted(identifier: StableRecordIdentifier, isDeleted: boolean): void;
-	/**
-	* Query the cache for any validation errors applicable to the given resource.
-	*
-	* @public
-	* @param identifier
-	* @return
-	*/
-	getErrors(identifier: StableRecordIdentifier): ApiError[];
-	/**
-	* Query the cache for whether a given resource has any available data
-	*
-	* @public
-	* @param identifier
-	* @return {Boolean}
-	*/
-	isEmpty(identifier: StableRecordIdentifier): boolean;
-	/**
-	* Query the cache for whether a given resource was created locally and not
-	* yet persisted.
-	*
-	* @public
-	* @param identifier
-	* @return {Boolean}
-	*/
-	isNew(identifier: StableRecordIdentifier): boolean;
-	/**
-	* Query the cache for whether a given resource is marked as deleted (but not
-	* necessarily persisted yet).
-	*
-	* @public
-	* @param identifier
-	* @return {Boolean}
-	*/
-	isDeleted(identifier: StableRecordIdentifier): boolean;
-	/**
-	* Query the cache for whether a given resource has been deleted and that deletion
-	* has also been persisted.
-	*
-	* @public
-	* @param identifier
-	* @return {Boolean}
-	*/
-	isDeletionCommitted(identifier: StableRecordIdentifier): boolean;
-}

package/declarations/store/-private/managers/notification-manager.d.ts

@@ -1,98 +0,0 @@
-import type { StableDocumentIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
-import type { Store } from "../store-service.js";
-export type UnsubscribeToken = object;
-export type CacheOperation = "added" | "removed" | "updated" | "state";
-export type DocumentCacheOperation = "invalidated" | "added" | "removed" | "updated" | "state";
-export type NotificationType = "attributes" | "relationships" | "identity" | "errors" | "meta" | CacheOperation;
-export interface NotificationCallback {
-	(identifier: StableRecordIdentifier, notificationType: "attributes" | "relationships", key?: string): void;
-	(identifier: StableRecordIdentifier, notificationType: "errors" | "meta" | "identity" | "state"): void;
-	(identifier: StableRecordIdentifier, notificationType: CacheOperation): void;
-}
-export interface ResourceOperationCallback {
-	// resource updates
-	(identifier: StableRecordIdentifier, notificationType: CacheOperation): void;
-}
-export interface DocumentOperationCallback {
-	// document updates
-	(identifier: StableDocumentIdentifier, notificationType: DocumentCacheOperation): void;
-}
-/**
-* The NotificationManager provides the ability to subscribe to
-* changes to Cache state.
-*
-* This Feature is what allows WarpDrive to create subscriptions that
-* work with any framework or change-notification system.
-*
-* @hideconstructor
-* @public
-*/
-export default class NotificationManager {
-	/** @internal */
-	private store;
-	/** @internal */
-	private isDestroyed;
-	/** @internal */
-	private _buffered;
-	/** @internal */
-	private _cache;
-	/** @internal */
-	private _hasFlush;
-	/** @internal */
-	private _onFlushCB?;
-	constructor(store: Store);
-	/**
-	* Subscribe to changes for a given resource identifier, resource addition/removal, or document addition/removal.
-	*
-	* ```ts
-	* export type CacheOperation = 'added' | 'removed' | 'updated' | 'state';
-	*
-	* export interface NotificationCallback {
-	*   (identifier: StableRecordIdentifier, notificationType: 'attributes' | 'relationships', key?: string): void;
-	*   (identifier: StableRecordIdentifier, notificationType: 'errors' | 'meta' | 'identity' | 'state'): void;
-	*   (identifier: StableRecordIdentifier, notificationType: NotificationType, key?: string): void;
-	* }
-	* export interface ResourceOperationCallback {
-	*   // resource updates
-	*   (identifier: StableRecordIdentifier, notificationType: CacheOperation): void;
-	* }
-	* export interface DocumentOperationCallback {
-	*   // document updates
-	*   (identifier: StableDocumentIdentifier, notificationType: CacheOperation): void;
-	* }
-	* ```
-	*
-	* @public
-	* @param {StableDocumentIdentifier | StableRecordIdentifier | 'resource' | 'document'} identifier
-	* @param {NotificationCallback | ResourceOperationCallback | DocumentOperationCallback} callback
-	* @return {UnsubscribeToken} an opaque token to be used with unsubscribe
-	*/
-	subscribe(identifier: StableRecordIdentifier, callback: NotificationCallback): UnsubscribeToken;
-	subscribe(identifier: "resource", callback: ResourceOperationCallback): UnsubscribeToken;
-	subscribe(identifier: "document" | StableDocumentIdentifier, callback: DocumentOperationCallback): UnsubscribeToken;
-	/**
-	* remove a previous subscription
-	*
-	* @public
-	*/
-	unsubscribe(token: UnsubscribeToken): void;
-	/**
-	* Custom Caches and Application Code should not call this method directly.
-	*
-	* @private
-	*/
-	notify(identifier: StableRecordIdentifier, value: "attributes" | "relationships", key?: string): boolean;
-	notify(identifier: StableRecordIdentifier, value: "errors" | "meta" | "identity" | "state"): boolean;
-	notify(identifier: StableRecordIdentifier, value: CacheOperation): boolean;
-	notify(identifier: StableDocumentIdentifier, value: DocumentCacheOperation): boolean;
-	/** @internal */
-	_onNextFlush(cb: () => void): void;
-	private _scheduleNotify;
-	/** @internal */
-	_flush(): void;
-	private _flushNotification;
-	private _flushNotification;
-	private _flushNotification;
-	/** @internal */
-	destroy(): void;
-}

package/declarations/store/-private/managers/record-array-manager.d.ts

@@ -1,97 +0,0 @@
-import type { LocalRelationshipOperation } from "../../../types/graph.js";
-import type { StableDocumentIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
-import type { ImmutableRequestInfo } from "../../../types/request.js";
-import type { CollectionResourceDocument } from "../../../types/spec/json-api-raw.js";
-import { Collection, IdentifierArray } from "../record-arrays/identifier-array.js";
-import type { Store } from "../store-service.js";
-import type { UnsubscribeToken } from "./notification-manager.js";
-/**
-* This is a clever optimization.
-*
-* clever optimizations rarely stand the test of time, so if you're
-* ever curious or think something better is possible please benchmark
-* and discuss. The benchmark for this at the time of writing is in
-* `scripts/benchmark-push.js`
-*
-* This approach turns out to be 150x faster in Chrome and node than
-* simply using push or concat. It's highly susceptible to the specifics
-* of the batch size, and may require tuning.
-*
-* Clever optimizations should always come with a `why`. This optimization
-* exists for two reasons.
-*
-* 1) array.push(...objects) and Array.prototype.push.apply(arr, objects)
-*   are susceptible to stack overflows. The size of objects at which this
-*   occurs varies by environment, browser, and current stack depth and memory
-*   pressure; however, it occurs in all browsers in fairly pristine conditions
-*   somewhere around 125k to 200k elements. Since WarpDrive regularly encounters
-*   arrays larger than this in size, we cannot use push.
-*
-* 2) `array.concat` or simply setting the array to a new reference is often an
-*   easier approach; however, native Proxy to an array cannot swap it's target array
-*   and attempts at juggling multiple array sources have proven to be victim to a number
-*   of browser implementation bugs. Should these bugs be addressed then we could
-*   simplify to using `concat`, however, do note this is currently 150x faster
-*   than concat, and due to the overloaded signature of concat will likely always
-*   be faster.
-*
-* Sincerely,
-*   - runspired (Chris Thoburn) 08/21/2022
-*
-* @function fastPush
-* @internal
-* @param target the array to push into
-* @param source the items to push into target
-*/
-export declare function fastPush<T>(target: T[], source: T[]): void;
-type ChangeSet = Map<StableRecordIdentifier, "add" | "del">;
-/**
-@class RecordArrayManager
-@internal
-*/
-export declare class RecordArrayManager {
-	store: Store;
-	isDestroying: boolean;
-	isDestroyed: boolean;
-	_set: Map<IdentifierArray, Set<StableRecordIdentifier>>;
-	_live: Map<string, IdentifierArray>;
-	_managed: Set<IdentifierArray>;
-	_pending: Map<IdentifierArray, ChangeSet>;
-	_identifiers: Map<StableRecordIdentifier, Set<Collection>>;
-	_staged: Map<string, ChangeSet>;
-	_subscription: UnsubscribeToken;
-	_documentSubscription: UnsubscribeToken;
-	_keyedArrays: Map<string, Collection>;
-	_visibilitySet: Map<StableRecordIdentifier, boolean>;
-	constructor(options: {
-		store: Store;
-	});
-	_syncArray(array: IdentifierArray | Collection): void;
-	mutate(mutation: LocalRelationshipOperation): void;
-	/**
-	Get the `RecordArray` for a modelName, which contains all loaded records of
-	given modelName.
-	
-	@internal
-	@param {String} modelName
-	@return {RecordArray}
-	*/
-	liveArrayFor(type: string): IdentifierArray;
-	getCollection(config: {
-		type?: string;
-		query?: ImmutableRequestInfo | Record<string, unknown>;
-		identifiers?: StableRecordIdentifier[];
-		doc?: CollectionResourceDocument;
-		identifier?: StableDocumentIdentifier | null;
-	}): Collection;
-	dirtyArray(array: IdentifierArray, delta: number, shouldSyncFromCache: boolean): void;
-	_getPendingFor(identifier: StableRecordIdentifier, includeManaged: boolean, isRemove?: boolean): Map<IdentifierArray, ChangeSet> | void;
-	populateManagedArray(array: Collection, identifiers: StableRecordIdentifier[], payload: CollectionResourceDocument | null): void;
-	identifierAdded(identifier: StableRecordIdentifier): void;
-	identifierRemoved(identifier: StableRecordIdentifier): void;
-	identifierChanged(identifier: StableRecordIdentifier): void;
-	clear(isClear?: boolean): void;
-	destroy(): void;
-}
-export declare function disassociateIdentifier(ArraysCache: Map<StableRecordIdentifier, Set<Collection>>, array: Collection, identifier: StableRecordIdentifier): void;
-export {};