@warp-drive/core 5.7.0-alpha.13 → 5.7.0-alpha.15

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

@@ -1,21 +1,21 @@
-import type { StableDocumentIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
+import type { RequestKey, ResourceKey } 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;
+	(cacheKey: ResourceKey, notificationType: "attributes" | "relationships", key?: string): void;
+	(cacheKey: ResourceKey, notificationType: "errors" | "meta" | "identity" | "state"): void;
+	(cacheKey: ResourceKey, notificationType: CacheOperation): void;
 }
 export interface ResourceOperationCallback {
 	// resource updates
-	(identifier: StableRecordIdentifier, notificationType: CacheOperation): void;
+	(cacheKey: ResourceKey, notificationType: CacheOperation): void;
 }
 export interface DocumentOperationCallback {
 	// document updates
-	(identifier: StableDocumentIdentifier, notificationType: DocumentCacheOperation): void;
+	(cacheKey: RequestKey, notificationType: DocumentCacheOperation): void;
 }
 /**
 * The NotificationManager provides the ability to subscribe to
@@ -42,34 +42,33 @@ export default class NotificationManager {
 	private _onFlushCB?;
 	constructor(store: Store);
 	/**
-	* Subscribe to changes for a given resource identifier, resource addition/removal, or document addition/removal.
+	* Subscribe to changes for a given ResourceKey, RequestKey, or addition/removal of any resource
+	* or document.
 	*
 	* ```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;
+	*   (cacheKey: ResourceKey, notificationType: 'attributes' | 'relationships', key?: string): void;
+	*   (cacheKey: ResourceKey, notificationType: 'errors' | 'meta' | 'identity' | 'state'): void;
+	*   (cacheKey: ResourceKey, notificationType: NotificationType, key?: string): void;
 	* }
 	* export interface ResourceOperationCallback {
 	*   // resource updates
-	*   (identifier: StableRecordIdentifier, notificationType: CacheOperation): void;
+	*   (cacheKey: ResourceKey, notificationType: CacheOperation): void;
 	* }
 	* export interface DocumentOperationCallback {
 	*   // document updates
-	*   (identifier: StableDocumentIdentifier, notificationType: CacheOperation): void;
+	*   (cacheKey: RequestKey, 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
+	* @return 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;
+	subscribe(cacheKey: ResourceKey, callback: NotificationCallback): UnsubscribeToken;
+	subscribe(cacheKey: "resource", callback: ResourceOperationCallback): UnsubscribeToken;
+	subscribe(cacheKey: "document" | RequestKey, callback: DocumentOperationCallback): UnsubscribeToken;
 	/**
 	* remove a previous subscription
 	*
@@ -81,18 +80,15 @@ export default class NotificationManager {
 	*
 	* @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;
+	notify(cacheKey: ResourceKey, value: "attributes" | "relationships", key?: string | null): boolean;
+	notify(cacheKey: ResourceKey, value: "errors" | "meta" | "identity" | "state", key?: null): boolean;
+	notify(cacheKey: ResourceKey, value: CacheOperation, key?: null): boolean;
+	notify(cacheKey: RequestKey, value: DocumentCacheOperation, key?: null): 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,8 +1,10 @@
 import type { LocalRelationshipOperation } from "../../../types/graph.js";
-import type { StableDocumentIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
+import type { ResourceKey, RequestKey } 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 { LegacyLiveArray } from "../record-arrays/legacy-live-array.js";
+import { type LegacyQueryArray } from "../record-arrays/legacy-query.js";
+import { type ReactiveResourceArray } from "../record-arrays/resource-array.js";
 import type { Store } from "../store-service.js";
 import type { UnsubscribeToken } from "./notification-manager.js";
 /**
@@ -38,13 +40,23 @@ import type { UnsubscribeToken } from "./notification-manager.js";
 * 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">;
+interface LegacyQueryInit {
+	type: string;
+	query: ImmutableRequestInfo | Record<string, unknown>;
+}
+interface AnonymousRequestCollectionInit {
+	source: ResourceKey[];
+}
+interface RequestCollectionInit {
+	source: ResourceKey[];
+	requestKey: RequestKey;
+}
+type ChangeSet = Map<ResourceKey, "add" | "del">;
 /**
 @class RecordArrayManager
 @internal
@@ -53,20 +65,61 @@ 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>>;
+	/**
+	*
+	*/
+	_set: Map<ReactiveResourceArray, Set<ResourceKey>>;
+	/**
+	* LiveArray (peekAll/findAll) array instances
+	* keyed by their ResourceType.
+	*/
+	_live: Map<string, LegacyLiveArray>;
+	/**
+	*
+	*/
+	_managed: Set<ReactiveResourceArray>;
+	/**
+	* Buffered changes to apply keyed by the array to
+	* which to apply them to.
+	*/
+	_pending: Map<ReactiveResourceArray, ChangeSet>;
+	/**
+	* An inverse map from ResourceKey to the list
+	* of arrays it can be found in, useful for fast updates
+	* when state changes to a resource occur.
+	*/
+	_identifiers: Map<ResourceKey, Set<ReactiveResourceArray>>;
+	/**
+	* When we do not yet have a LiveArray, this keeps track of
+	* the added/removed identifiers to enable us to more efficiently
+	* produce the LiveArray later.
+	*
+	* It's possible that using a Set and only storing additions instead of
+	* additions and deletes would be more efficient.
+	*/
 	_staged: Map<string, ChangeSet>;
 	_subscription: UnsubscribeToken;
 	_documentSubscription: UnsubscribeToken;
-	_keyedArrays: Map<string, Collection>;
-	_visibilitySet: Map<StableRecordIdentifier, boolean>;
+	/**
+	* KeyedArrays are arrays associated to a specific RequestKey.
+	*/
+	_keyedArrays: Map<string, ReactiveResourceArray>;
+	/**
+	* The visibility set tracks whether a given identifier should
+	* be shown in RecordArrays. It is used to dedupe added/removed
+	* and state change events.
+	*
+	* As a Map, it grows to be very large - there may be ways to
+	* reduce its size by instead migrating to it functioning as
+	* an exclusion list. Any entry not in the list would be considered
+	* visible.
+	*/
+	_visibilitySet: Map<ResourceKey, boolean>;
 	constructor(options: {
 		store: Store;
 	});
-	_syncArray(array: IdentifierArray | Collection): void;
+	private _subscribeToResourceChanges;
+	_syncArray(array: ReactiveResourceArray): void;
 	mutate(mutation: LocalRelationshipOperation): void;
 	/**
 	Get the `RecordArray` for a modelName, which contains all loaded records of
@@ -76,22 +129,20 @@ export declare class RecordArrayManager {
 	@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;
+	liveArrayFor(type: string): LegacyLiveArray;
+	getCollection(config: LegacyQueryInit): LegacyQueryArray;
+	getCollection(config: AnonymousRequestCollectionInit): ReactiveResourceArray;
+	getCollection(config: RequestCollectionInit): ReactiveResourceArray;
+	dirtyArray(array: ReactiveResourceArray, delta: number, shouldSyncFromCache: boolean): void;
+	_getPendingFor(identifier: ResourceKey, includeManaged: boolean, isRemove?: boolean): Map<ReactiveResourceArray, ChangeSet> | void;
+	populateManagedArray(array: ReactiveResourceArray, identifiers: ResourceKey[], payload: CollectionResourceDocument | null): void;
+	identifierAdded(identifier: ResourceKey): void;
+	identifierRemoved(identifier: ResourceKey): void;
+	identifierChanged(identifier: ResourceKey): void;
+	pause(): void;
+	resume(): void;
 	clear(isClear?: boolean): void;
 	destroy(): void;
 }
-export declare function disassociateIdentifier(ArraysCache: Map<StableRecordIdentifier, Set<Collection>>, array: Collection, identifier: StableRecordIdentifier): void;
+export declare function disassociateIdentifier(ArraysCache: Map<ResourceKey, Set<ReactiveResourceArray>>, array: ReactiveResourceArray, identifier: ResourceKey): void;
 export {};

package/declarations/store/-private/network/request-cache.d.ts

@@ -1,4 +1,4 @@
-import type { StableRecordIdentifier } from "../../../types/identifier.js";
+import type { ResourceKey } from "../../../types/identifier.js";
 import type { FindRecordOptions } from "../../-types/q/store.js";
 import type { Store } from "../store-service.js";
 declare const Touching: "___(unique) Symbol(Touching)";
@@ -6,7 +6,7 @@ export declare const RequestPromise: "___(unique) Symbol(RequestPromise)";
 export interface Operation {
 	op: string;
 	options: FindRecordOptions | undefined;
-	recordIdentifier: StableRecordIdentifier;
+	recordIdentifier: ResourceKey;
 }
 export interface FindRecordQuery extends Operation {
 	op: "findRecord";
@@ -30,7 +30,7 @@ export interface Response {
 	data: unknown;
 }
 interface InternalRequest extends RequestCacheRequestState {
-	[Touching]: StableRecordIdentifier[];
+	[Touching]: ResourceKey[];
 	[RequestPromise]?: Promise<unknown>;
 }
 export type RequestSubscription = (requestState: RequestCacheRequestState) => void;
@@ -43,14 +43,14 @@ export type RequestSubscription = (requestState: RequestCacheRequestState) => vo
 */
 export declare class RequestStateService {
 	/** @internal */
-	_pending: Map<StableRecordIdentifier, InternalRequest[]>;
+	_pending: Map<ResourceKey, InternalRequest[]>;
 	private _done;
 	private _subscriptions;
 	private _toFlush;
 	private _store;
 	constructor(store: Store);
 	/** @internal */
-	_clearEntries(identifier: StableRecordIdentifier): void;
+	_clearEntries(identifier: ResourceKey): void;
 	/** @internal */
 	_enqueue<T>(promise: Promise<T>, queryRequest: Request): Promise<T>;
 	private _triggerSubscriptions;
@@ -83,25 +83,25 @@ export declare class RequestStateService {
 	* design.
 	*
 	* @public
-	* @param {StableRecordIdentifier} identifier
+	* @param {ResourceKey} identifier
 	* @param {(state: RequestCacheRequestState) => void} callback
 	*/
-	subscribeForRecord(identifier: StableRecordIdentifier, callback: RequestSubscription): void;
+	subscribeForRecord(identifier: ResourceKey, callback: RequestSubscription): void;
 	/**
 	* Retrieve all active requests for a given resource identity.
 	*
 	* @public
-	* @param {StableRecordIdentifier} identifier
+	* @param {ResourceKey} identifier
 	* @return {RequestCacheRequestState[]} an array of request states for any pending requests for the given identifier
 	*/
-	getPendingRequestsForRecord(identifier: StableRecordIdentifier): RequestCacheRequestState[];
+	getPendingRequestsForRecord(identifier: ResourceKey): RequestCacheRequestState[];
 	/**
 	* Retrieve the last completed request for a given resource identity.
 	*
 	* @public
-	* @param {StableRecordIdentifier} identifier
+	* @param {ResourceKey} identifier
 	* @return {RequestCacheRequestState | null} the state of the most recent request for the given identifier
 	*/
-	getLastRequestForRecord(identifier: StableRecordIdentifier): RequestCacheRequestState | null;
+	getLastRequestForRecord(identifier: ResourceKey): RequestCacheRequestState | null;
 }
 export {};

package/declarations/store/-private/new-core-tmp/expensive-subscription.d.ts

@@ -0,0 +1,24 @@
+import type { RequestKey } from "../../../types/identifier.js";
+import type { Store } from "../store-service.js";
+/**
+* Creates an {@link ExpensiveSubscription} for the {@link RequestKey}
+* if one does not already exist and adds a watcher to it.
+*
+* Returns a cleanup function. This should be called on-mount by a component
+* that wants to subscribe to a request and cleanup should be called on dismount.
+*
+* ::: warning ⚠️ Avoid Using If Your App Supports Fine-grained Reactivity
+* This mechanism should never be used by frameworks or libraries
+* that support fine-grained reactivity.
+* :::
+*
+* `ExpensiveSubscription` is a mechanism for non-reactive
+* frameworks such as `react` to integrate with WarpDrive, for instance
+* by treating a request as an [external store](https://react.dev/reference/react/useSyncExternalStore)
+*
+* `ExpensiveSubscription` is expensive *because* it doubles the number
+* of notification callbacks required for each resource contained in
+* the request being subscribed to. The more requests in-use, the more
+* this cost adds up.
+*/
+export declare function getExpensiveRequestSubscription(store: Store, requestKey: RequestKey, callback: () => void): () => void;

package/declarations/store/-private/new-core-tmp/reactivity/signal.d.ts

@@ -7,6 +7,7 @@ import type { SignalStore, WarpDriveSignal } from "./internal.js";
 * @internal
 */
 export declare function entangleSignal<T extends object>(signals: SignalStore, obj: T, key: string | symbol, initialValue: unknown): WarpDriveSignal;
+export declare function createSignalDescriptor(key: string | symbol, intialValue: unknown): PropertyDescriptor;
 /**
 * define an enumerable signal property.
 *

package/declarations/store/-private/new-core-tmp/request-state.d.ts

@@ -195,7 +195,7 @@ export interface CancelledRequest<
 * interface Future<T> extends Promise<T>> {
 *   getStream(): Promise<ReadableStream>;
 *   abort(): void;
-*   lid: StableDocumentIdentifier | null;
+*   lid: RequestKey | null;
 * }
 * ```
 *

package/declarations/store/-private/record-arrays/-utils.d.ts

@@ -0,0 +1,82 @@
+import type { BaseFinderOptions } from "../../../types.js";
+import type { LocalRelationshipOperation } from "../../../types/graph.js";
+import type { ResourceKey } from "../../../types/identifier.js";
+import type { Store } from "../store-service.js";
+import type { NativeProxy } from "./native-proxy-type-fix.js";
+import type { ReactiveResourceArray } from "./resource-array.js";
+/**
+* LegacyArrays have the capability of updating via `array.update()`
+* and saving each contained record individually via `array.save()`
+*/
+export interface LegacyArray<T = unknown> extends ReactiveResourceArray<T> {
+	/**
+	The flag to signal a `RecordArray` is currently loading data.
+	Example
+	```javascript
+	let people = store.peekAll('person');
+	people.isUpdating; // false
+	people.update();
+	people.isUpdating; // true
+	```
+	*/
+	isUpdating: boolean;
+	/** @internal */
+	_updatingPromise: Promise<LegacyArray<T>> | null;
+	/**
+	Used to get the latest version of all of the records in this array
+	from the adapter.
+	
+	Example
+	
+	```javascript
+	let people = store.peekAll('person');
+	people.isUpdating; // false
+	
+	people.update().then(function() {
+	people.isUpdating; // false
+	});
+	
+	people.isUpdating; // true
+	```
+	
+	@public
+	*/
+	update(this: LegacyArray<T>): Promise<LegacyArray<T>>;
+	/**
+	Saves all of the records in the `RecordArray`.
+	
+	Example
+	
+	```js
+	let messages = store.peekAll('message');
+	messages.forEach(function(message) {
+	message.hasBeenSeen = true;
+	});
+	messages.save();
+	```
+	
+	@public
+	*/
+	save(this: LegacyArray<T>): Promise<LegacyArray<T>>;
+}
+export declare function upgradeThis(obj: unknown): asserts obj is LegacyArray;
+export declare function update(this: ReactiveResourceArray): Promise<ReactiveResourceArray>;
+export declare function save(this: ReactiveResourceArray): Promise<ReactiveResourceArray>;
+export type KeyType = string | symbol | number;
+export declare function isArrayGetter<T>(prop: KeyType): prop is keyof Array<T>;
+export declare function isArraySetter<T>(prop: KeyType): prop is keyof Array<T>;
+export declare function convertToInt(prop: KeyType): number | null;
+export type ForEachCB<T> = (record: T, index: number, context: typeof NativeProxy<ResourceKey[], T[]>) => void;
+export declare function safeForEach<T>(instance: typeof NativeProxy<ResourceKey[], T[]>, arr: ResourceKey[], store: Store, callback: ForEachCB<T>, target: unknown): typeof NativeProxy<ResourceKey[], T[]>;
+type PromiseTo<T> = Omit<Promise<T>, typeof Symbol.toStringTag>;
+type PromiseManyArray<T> = {
+	length: number;
+	content: ReactiveResourceArray<T> | null;
+	promise: Promise<ReactiveResourceArray<T>> | null;
+} & PromiseTo<ReactiveResourceArray<T>>;
+export interface MinimumManager {
+	_syncArray(array: ReactiveResourceArray): void;
+	mutate?(mutation: LocalRelationshipOperation): void;
+	reloadHasMany?<T>(key: string, options?: BaseFinderOptions): Promise<ReactiveResourceArray> | PromiseManyArray<T>;
+}
+export {};

package/declarations/store/-private/record-arrays/legacy-live-array.d.ts

@@ -0,0 +1,89 @@
+import type { ResourceKey } from "../../../types/identifier.js";
+import type { TypeFromInstanceOrString } from "../../../types/record.js";
+import type { Store } from "../store-service.js";
+import type { LegacyArray, MinimumManager } from "./-utils.js";
+/**
+* LiveArrays contain all the known records for a given `ResourceType`.
+*
+* ### Basic Example
+*
+* For instance, if an application were to have a `'user'` type:
+*
+* ```ts
+* const usersLiveArray = store.peekAll('user');
+* ```
+*
+* ---
+*
+*  
+*
+* ### LiveArrays are Arrays
+*
+* LiveArrays have all array APIs, and will report `true`
+* for both `liveArray instanceof Array` and `Array.isArray(liveArray)`
+*
+* ---
+*
+*  
+*
+* ### Reactive
+*
+* The array is "live" as it will reactively update any time new
+* users are added to the store's cache.
+*
+* There is only one LiveArray instance per ResourceType, and it
+* can be accessed either via {@link Store.peekAll} or {@link Store.findAll}
+*
+* ```ts
+* const users = await store.findAll('user');
+* const peekedUsers = store.peekAll('user');
+* peekedUsers === users; // true
+* ```
+*
+* ---
+*
+*  
+*
+* ### New Records
+*
+* Records in the `"new"` state (created locally on the client
+* but not yet saved) appear in LiveArrays if they are in LegacyMode.
+*
+* PolarisMode records in the `"new"` state do not appear in LiveArrays.
+*
+* ---
+*
+*  
+*
+* ### Polymorphism
+*
+* LiveArrays are not polymorphic. If your application has an abstract
+* type "car" with concrete types "ferrari" and "bmw", then "ferrari"
+* and "bmw" will have populated LiveArrays, but the LiveArray for "car"
+* would be empty.
+*
+* @legacy we recommend againt using LiveArrays. Use {@link Store.request} instead
+*/
+export interface LegacyLiveArray<T = unknown> extends LegacyArray<T> {
+	isLoaded: boolean;
+	/** @internal */
+	DEPRECATED_CLASS_NAME: string;
+	modelName: TypeFromInstanceOrString<T>;
+}
+/**
+* The options for {@link createLegacyLiveArray}
+*
+* @internal
+*/
+export interface LegacyLiveArrayCreateOptions {
+	store: Store;
+	manager: MinimumManager;
+	source: ResourceKey[];
+	type: string;
+}
+/**
+* Creates a {@link LegacyLiveArray}
+*
+* @internal
+*/
+export declare function createLegacyLiveArray(options: LegacyLiveArrayCreateOptions): LegacyLiveArray;