@warp-drive/core 5.6.0-alpha.11

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

@@ -0,0 +1,428 @@
+import type { Cache, ChangedAttributesHash, RelationshipDiff } from '../../../types/cache.ts';
+import type { Change } from '../../../types/cache/change.ts';
+import type { MergeOperation } from '../../../types/cache/operations.ts';
+import type { CollectionRelationship, ResourceRelationship } from '../../../types/cache/relationship.ts';
+import type { LocalRelationshipOperation } from '../../../types/graph.ts';
+import type { StableDocumentIdentifier, StableRecordIdentifier } from '../../../types/identifier.ts';
+import type { Value } from '../../../types/json/raw.ts';
+import type { StructuredDataDocument, StructuredDocument } from '../../../types/request.ts';
+import type { ResourceDocument, SingleResourceDataDocument } from '../../../types/spec/document.ts';
+import type { ApiError } from '../../../types/spec/error.ts';
+import type { StoreRequestContext } from '../cache-handler/handler.ts';
+/**
+ * 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 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[];
+    /**
+     * 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[]>;
+    /**
+     * 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
+     * @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;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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;
+}
+//# sourceMappingURL=cache-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../../../../src/store/-private/managers/cache-manager.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,93 @@
+import type { StableDocumentIdentifier, StableRecordIdentifier } from '../../../types/identifier.ts';
+import type { Store } from '../store-service.ts';
+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 {
+    (identifier: StableRecordIdentifier, notificationType: CacheOperation): void;
+}
+export interface DocumentOperationCallback {
+    (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.
+ *
+ * @class NotificationManager
+ * @public
+ */
+export default class NotificationManager {
+    store: Store;
+    isDestroyed: boolean;
+    _buffered: Map<StableDocumentIdentifier | StableRecordIdentifier, [string, string | undefined][]>;
+    _cache: Map<StableDocumentIdentifier | StableRecordIdentifier | 'resource' | 'document', Array<NotificationCallback | ResourceOperationCallback | DocumentOperationCallback>>;
+    _hasFlush: boolean;
+    _onFlushCB?: () => void;
+    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
+     * @param {UnsubscribeToken} token
+     */
+    unsubscribe(token: UnsubscribeToken): void;
+    /**
+     * Custom Caches and Application Code should not call this method directly.
+     *
+     * @param identifier
+     * @param value
+     * @param key
+     * @return {Boolean} whether a notification was delivered to any subscribers
+     * @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;
+    _onNextFlush(cb: () => void): void;
+    _scheduleNotify(): boolean;
+    _flush(): void;
+    _flushNotification(identifier: StableRecordIdentifier, value: 'attributes' | 'relationships', key?: string): boolean;
+    _flushNotification(identifier: StableRecordIdentifier, value: 'errors' | 'meta' | 'identity' | 'state'): boolean;
+    _flushNotification(identifier: StableRecordIdentifier | StableDocumentIdentifier, value: CacheOperation): boolean;
+    destroy(): void;
+}
+//# sourceMappingURL=notification-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notification-manager.d.ts","sourceRoot":"","sources":["../../../../src/store/-private/managers/notification-manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAIrG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAQ/F,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,eAAe,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,cAAc,CAAC;AAEhH,MAAM,WAAW,oBAAoB;IACnC,CAAC,UAAU,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,YAAY,GAAG,eAAe,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3G,CAAC,UAAU,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC;IACvG,CAAC,UAAU,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,cAAc,GAAG,IAAI,CAAC;CAE9E;AAED,MAAM,WAAW,yBAAyB;IAExC,CAAC,UAAU,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,cAAc,GAAG,IAAI,CAAC;CAC9E;AAED,MAAM,WAAW,yBAAyB;IAExC,CAAC,UAAU,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACxF;AA6CD;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,GAAG,CAAC,wBAAwB,GAAG,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;IAClG,MAAM,EAAE,GAAG,CACjB,wBAAwB,GAAG,sBAAsB,GAAG,UAAU,GAAG,UAAU,EAC3E,KAAK,CAAC,oBAAoB,GAAG,yBAAyB,GAAG,yBAAyB,CAAC,CACpF,CAAC;IACM,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;gBAEpB,KAAK,EAAE,KAAK;IAQxB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,UAAU,EAAE,sBAAsB,EAAE,QAAQ,EAAE,oBAAoB,GAAG,gBAAgB;IAC/F,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,yBAAyB,GAAG,gBAAgB;IACxF,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,wBAAwB,EAAE,QAAQ,EAAE,yBAAyB,GAAG,gBAAgB;IA4BnH;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,gBAAgB;IAMnC;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,EAAE,sBAAsB,EAAE,KAAK,EAAE,YAAY,GAAG,eAAe,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO;IACxG,MAAM,CAAC,UAAU,EAAE,sBAAsB,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO;IACpG,MAAM,CAAC,UAAU,EAAE,sBAAsB,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO;IAC1E,MAAM,CAAC,UAAU,EAAE,wBAAwB,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO;IAmEpF,YAAY,CAAC,EAAE,EAAE,MAAM,IAAI;IAI3B,eAAe,IAAI,OAAO;IAkB1B,MAAM;IAiBN,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,EAAE,KAAK,EAAE,YAAY,GAAG,eAAe,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO;IACpH,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO;IAChH,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,wBAAwB,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO;IAyCjH,OAAO;CAIR"}

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

@@ -0,0 +1,98 @@
+import type { LocalRelationshipOperation } from '../../../types/graph.ts';
+import type { StableDocumentIdentifier, StableRecordIdentifier } from '../../../types/identifier.ts';
+import type { ImmutableRequestInfo } from '../../../types/request.ts';
+import type { CollectionResourceDocument } from '../../../types/spec/json-api-raw.ts';
+import { Collection, IdentifierArray } from '../record-arrays/identifier-array.ts';
+import type { Store } from '../store-service.ts';
+import type { UnsubscribeToken } from './notification-manager.ts';
+/**
+ * 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 {};
+//# sourceMappingURL=record-array-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-array-manager.d.ts","sourceRoot":"","sources":["../../../../src/store/-private/managers/record-array-manager.ts"],"names":[],"mappings":"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"}