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

package/declarations/reactive/-private/symbols.d.ts

@@ -25,7 +25,6 @@
 // Note that none of these symbols are part of the public API, these are used for
 // debugging DX and as a safe way to provide an intimate contract on public objects.
 export declare const SOURCE: "___(unique) Symbol(SOURCE)";
-export declare const MUTATE: "___(unique) Symbol(MUTATE)";
 export declare const Destroy: "___(unique) Symbol(Destroy)";
 export declare const Checkout: "___(unique) Symbol(Checkout)";
 export declare const Context: "___(unique) Symbol(Context)";

package/declarations/request/-private/fetch.d.ts

@@ -1,6 +1,6 @@
 import { type Context } from "./context.js";
-import type { HttpErrorProps } from "./utils.js";
-export type { HttpErrorProps };
+import type { FetchError } from "./utils.js";
+export type { FetchError };
 interface FastbootRequest extends Request {
 	protocol: string;
 	host: string;

package/declarations/request/-private/utils.d.ts

@@ -3,12 +3,54 @@ import { ContextOwner } from "./context.js";
 import type { DeferredFuture, Future, GodContext, Handler } from "./types.js";
 export declare const IS_CACHE_HANDLER: "___(unique) Symbol(IS_CACHE_HANDLER)";
 export declare function curryFuture<T>(owner: ContextOwner, inbound: Future<T>, outbound: DeferredFuture<T>): Future<T>;
-export interface HttpErrorProps extends DOMException {
+/**
+* Additional properties exposed on errors thrown by the
+* {@link Fetch | Fetch Handler}.
+*
+* In the case of an Abort or system/browser level issue,
+* this extends {@link DOMException}.
+*
+* Else it extends from {@link AggregateError} if the
+* response includes an array of errors, falling back
+* to {@link Error} as its base.
+*/
+export interface FetchError extends DOMException {
+	/**
+	* Alias for {@link FetchError.status | status}.
+	*
+	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/status)
+	*/
 	code: number;
+	/**
+	* The name associated to the {@link FetchError.status | status code}.
+	*
+	* Typically this will be of the formula `StatusTextError` for instance
+	* a 404 status with status text of `Not Found` would have the name
+	* `NotFoundError`.
+	*/
 	name: string;
+	/**
+	* The http status code associated to the returned error.
+	*
+	* Browser/System level network errors will often have an error code of `0` or `5`.
+	* Aborted requests will have an error code of `20`.
+	*
+	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/status)
+	*/
 	status: number;
+	/**
+	* The Status Text associated to the {@link FetchError.status | status code}
+	* for the error.
+	*
+	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/statusText)
+	*
+	*/
 	statusText: string;
-	isRequestError: boolean;
+	/**
+	* A property signifying that an Error uses the {@link FetchError}
+	* interface.
+	*/
+	isRequestError: true;
 }
 export declare function enhanceReason(reason?: string): DOMException;
 export declare function handleOutcome<T>(owner: ContextOwner, inbound: Promise<T | StructuredDataDocument<T>>, outbound: DeferredFuture<T>): Future<T>;

package/declarations/store/-private/cache-handler/types.d.ts

@@ -71,7 +71,7 @@ export interface CachePolicy {
 	* so that request subscriptions can reload when needed.
 	*
 	* ```ts
-	* store.notifications.notify(identifier, 'invalidated');
+	* store.notifications.notify(identifier, 'invalidated', null);
 	* ```
 	*
 	* This allows anything subscribed to the request to be notified of the change

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

@@ -81,18 +81,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(identifier: StableRecordIdentifier, value: "attributes" | "relationships", key?: string | null): boolean;
+	notify(identifier: StableRecordIdentifier, value: "errors" | "meta" | "identity" | "state", key?: null): boolean;
+	notify(identifier: StableRecordIdentifier, value: CacheOperation, key?: null): boolean;
+	notify(identifier: StableDocumentIdentifier, 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

@@ -2,7 +2,9 @@ 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 { 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,12 +40,22 @@ 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;
+interface LegacyQueryInit {
+	type: string;
+	query: ImmutableRequestInfo | Record<string, unknown>;
+}
+interface AnonymousRequestCollectionInit {
+	source: StableRecordIdentifier[];
+}
+interface RequestCollectionInit {
+	source: StableRecordIdentifier[];
+	requestKey: StableDocumentIdentifier;
+}
 type ChangeSet = Map<StableRecordIdentifier, "add" | "del">;
 /**
 @class RecordArrayManager
@@ -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<StableRecordIdentifier>>;
+	/**
+	* 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 StableRecordIdentifier to the list
+	* of arrays it can be found in, useful for fast updates
+	* when state changes to a resource occur.
+	*/
+	_identifiers: Map<StableRecordIdentifier, 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>;
+	/**
+	* 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<StableRecordIdentifier, 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;
+	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: StableRecordIdentifier, includeManaged: boolean, isRemove?: boolean): Map<ReactiveResourceArray, ChangeSet> | void;
+	populateManagedArray(array: ReactiveResourceArray, identifiers: StableRecordIdentifier[], payload: CollectionResourceDocument | null): void;
 	identifierAdded(identifier: StableRecordIdentifier): void;
 	identifierRemoved(identifier: StableRecordIdentifier): void;
 	identifierChanged(identifier: StableRecordIdentifier): 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<StableRecordIdentifier, Set<ReactiveResourceArray>>, array: ReactiveResourceArray, identifier: StableRecordIdentifier): void;
 export {};

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/record-arrays/-utils.d.ts

@@ -0,0 +1,82 @@
+import type { BaseFinderOptions } from "../../../types.js";
+import type { LocalRelationshipOperation } from "../../../types/graph.js";
+import type { StableRecordIdentifier } 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<StableRecordIdentifier[], T[]>) => void;
+export declare function safeForEach<T>(instance: typeof NativeProxy<StableRecordIdentifier[], T[]>, arr: StableRecordIdentifier[], store: Store, callback: ForEachCB<T>, target: unknown): typeof NativeProxy<StableRecordIdentifier[], 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 { StableRecordIdentifier } 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: StableRecordIdentifier[];
+	type: string;
+}
+/**
+* Creates a {@link LegacyLiveArray}
+*
+* @internal
+*/
+export declare function createLegacyLiveArray(options: LegacyLiveArrayCreateOptions): LegacyLiveArray;

package/declarations/store/-private/record-arrays/{many-array.d.ts → legacy-many-array.d.ts}

@@ -1,28 +1,10 @@
-import type { BaseFinderOptions, ModelSchema, StableRecordIdentifier } from "../../../types.js";
-import type { Cache } from "../../../types/cache.js";
-import type { TypedRecordInstance, TypeFromInstance, TypeFromInstanceOrString } from "../../../types/record.js";
+import type { BaseFinderOptions, StableRecordIdentifier } from "../../../types.js";
+import type { TypedRecordInstance, TypeFromInstance } from "../../../types/record.js";
 import type { LegacyHasManyField, LinksModeHasManyField } from "../../../types/schema/fields.js";
-import type { Links, PaginationLinks } from "../../../types/spec/json-api-raw.js";
-import type { CreateRecordProperties, Store } from "../store-service.js";
-import type { MinimumManager } from "./identifier-array.js";
-import { IdentifierArray } from "./identifier-array.js";
-export interface ManyArrayCreateArgs<T> {
-	identifiers: StableRecordIdentifier<TypeFromInstanceOrString<T>>[];
-	type: TypeFromInstanceOrString<T>;
-	store: Store;
-	allowMutation: boolean;
-	manager: MinimumManager;
-	field?: LegacyHasManyField | LinksModeHasManyField;
-	identifier: StableRecordIdentifier;
-	cache: Cache;
-	meta: Record<string, unknown> | null;
-	links: Links | PaginationLinks | null;
-	key: string;
-	isPolymorphic: boolean;
-	isAsync: boolean;
-	_inverseIsAsync: boolean;
-	isLoaded: boolean;
-}
+import type { Links, Meta, PaginationLinks } from "../../../types/spec/json-api-raw.js";
+import type { CreateRecordProperties } from "../store-service.js";
+import type { LegacyLiveArrayCreateOptions } from "./legacy-live-array.js";
+import { type ReactiveResourceArray } from "./resource-array.js";
 /**
 A `ManyArray` is a `MutableArray` that represents the contents of a has-many
 relationship.
@@ -63,83 +45,25 @@ the has-many.
 We call the record to which a relationship belongs-to the
 relationship's _owner_.
 
-@class ManyArray
 @public
 */
-export declare class RelatedCollection<T = unknown> extends IdentifierArray<T> {
+export interface LegacyManyArray<T = unknown> extends ReactiveResourceArray<T> {
+	meta: Meta | null;
+	links: Links | PaginationLinks | null;
+	/** @internal */
+	isPolymorphic: boolean;
+	/** @internal */
 	isAsync: boolean;
+	/** @internal */
+	key: string;
+	/** @internal */
+	modelName: T extends TypedRecordInstance ? TypeFromInstance<T> : string;
 	/**
 	The loading state of this array
-	
-	@property isLoaded
-	@type {Boolean}
 	@public
 	*/
 	isLoaded: boolean;
-	/**
-	`true` if the relationship is polymorphic, `false` otherwise.
-	
-	@property isPolymorphic
-	@type {Boolean}
-	@private
-	*/
-	isPolymorphic: boolean;
-	_inverseIsAsync: boolean;
-	/**
-	Metadata associated with the request for async hasMany relationships.
-	
-	Example
-	
-	Given that the server returns the following JSON payload when fetching a
-	hasMany relationship:
-	
-	```js
-	{
-	"comments": [{
-	"id": 1,
-	"comment": "This is the first comment",
-	}, {
-	// ...
-	}],
-	
-	"meta": {
-	"page": 1,
-	"total": 5
-	}
-	}
-	```
-	
-	You can then access the meta data via the `meta` property:
-	
-	```js
-	let comments = await post.comments;
-	let meta = comments.meta;
-	
-	// meta.page => 1
-	// meta.total => 5
-	```
-	
-	@property meta
-	@type {Object | null}
-	@public
-	*/
-	meta: Record<string, unknown> | null;
-	/**
-	* Retrieve the links for this relationship
-	*
-	@property links
-	@type {Object | null}
-	@public
-	*/
-	links: Links | PaginationLinks | null;
-	identifier: StableRecordIdentifier;
-	cache: Cache;
-	_manager: MinimumManager;
-	store: Store;
-	key: string;
-	type: ModelSchema;
-	modelName: T extends TypedRecordInstance ? TypeFromInstance<T> : string;
-	constructor(options: ManyArrayCreateArgs<T>);
+	/** @internal */
 	notify(): void;
 	/**
 	Reloads all of the records in the manyArray. If the manyArray
@@ -162,13 +86,11 @@ export declare class RelatedCollection<T = unknown> extends IdentifierArray<T> {
 	
 	@public
 	*/
-	reload(options?: BaseFinderOptions): Promise<this>;
+	reload(options?: BaseFinderOptions): Promise<LegacyManyArray<T>>;
 	/**
-	Create a child record within the owner
+	Create a child record and associated it to the collection
 	
 	@public
-	@param {Object} hash
-	@return {Model} record
 	*/
 	createRecord(hash: CreateRecordProperties<T>): T;
 	/**
@@ -178,7 +100,7 @@ export declare class RelatedCollection<T = unknown> extends IdentifierArray<T> {
 	
 	Example
 	
-	```javascript
+	```js
 	const { content: { data: inbox } } = await store.request(findRecord({ type: 'inbox', id: '1' }));
 	
 	let messages = await inbox.messages;
@@ -189,9 +111,29 @@ export declare class RelatedCollection<T = unknown> extends IdentifierArray<T> {
 	```
 	
 	@public
-	@return {PromiseArray} promise
 	*/
-	save: () => Promise<IdentifierArray<T>>;
+	save: () => Promise<LegacyManyArray<T>>;
 	/** @internal */
-	destroy(): void;
+	destroy: () => void;
+}
+/**
+* The options for {@link createLegacyManyArray}
+*
+* @internal
+*/
+export interface LegacyManyArrayCreateOptions extends LegacyLiveArrayCreateOptions {
+	isLoaded: boolean;
+	editable: boolean;
+	isAsync: boolean;
+	isPolymorphic: boolean;
+	field: LegacyHasManyField | LinksModeHasManyField;
+	identifier: StableRecordIdentifier;
+	links: Links | PaginationLinks | null;
+	meta: Meta | null;
 }
+/**
+* Creates a {@link LegacyManyArray}
+*
+* @internal
+*/
+export declare function createLegacyManyArray<T>(options: LegacyManyArrayCreateOptions): LegacyManyArray<T>;