@warp-drive/core 5.7.0-alpha.2 → 5.7.0-alpha.20

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

@@ -1,5 +1,6 @@
 import type { Future } from "../../../request.js";
 import type { ImmutableRequestInfo, ResponseInfo, StructuredErrorDocument } from "../../../types/request.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type { PendingPromise, RejectedPromise, ResolvedPromise } from "./promise-state.js";
 /**
 * Lazily consumes the stream of a request, providing a number of
@@ -69,17 +70,14 @@ export interface PendingRequest extends PendingPromise {
 * Extends the {@link ResolvedPromise} interface.
 *
 */
-export interface ResolvedRequest<
-	RT,
-	T
-> extends ResolvedPromise<RT> {
+export interface ResolvedRequest<RT> extends ResolvedPromise<RT> {
 	/**
 	* Whether the request is cancelled.
 	*
 	*/
 	isCancelled: false;
 	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT, T> | null;
+	request: ImmutableRequestInfo<RT> | null;
 	response: Response | ResponseInfo | null;
 }
 /**
@@ -92,7 +90,6 @@ export interface ResolvedRequest<
 */
 export interface RejectedRequest<
 	RT,
-	T,
 	E extends StructuredErrorDocument = StructuredErrorDocument
 > extends RejectedPromise<E> {
 	/**
@@ -101,7 +98,7 @@ export interface RejectedRequest<
 	*/
 	isCancelled: false;
 	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT, T> | null;
+	request: ImmutableRequestInfo<RT> | null;
 	response: Response | ResponseInfo | null;
 }
 /**
@@ -112,7 +109,6 @@ export interface RejectedRequest<
 */
 export interface CancelledRequest<
 	RT,
-	T,
 	E extends StructuredErrorDocument = StructuredErrorDocument
 > {
 	/**
@@ -175,33 +171,33 @@ export interface CancelledRequest<
 	*/
 	isCancelled: true;
 	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT, T> | null;
+	request: ImmutableRequestInfo<RT> | null;
 	response: Response | ResponseInfo | null;
 }
 /**
-* RequestState extends the concept of PromiseState to provide a reactive
-* wrapper for a request `Future` which allows you write declarative code
+* RequestState extends the concept of {@link PromiseState} to provide a reactive
+* wrapper for a request {@link Future} which allows you write declarative code
 * around a Future's control flow.
 *
 * It is useful in both Template and JavaScript contexts, allowing you
 * to quickly derive behaviors and data from pending, error and success
 * states.
 *
-* The key difference between a Promise and a Future is that Futures provide
-* access to a stream of their content, the identity of the request (if any)
-* as well as the ability to attempt to abort the request.
+* The key difference between a {@link Promise} and a Future is that Futures provide
+* access to a {@link ReadableStream | stream} of their content, the {@link RequestKey} of the request (if any)
+* as well as the ability to attempt to {@link Future.abort | abort} the request.
 *
 * ```ts
 * interface Future<T> extends Promise<T>> {
 *   getStream(): Promise<ReadableStream>;
 *   abort(): void;
-*   lid: StableDocumentIdentifier | null;
+*   lid: RequestKey | null;
 * }
 * ```
 *
 * These additional APIs allow us to craft even richer state experiences.
 *
-* To get the state of a request, use `getRequestState`.
+* To get the state of a request, use {@link getRequestState}.
 *
 * See also:
 * - {@link PendingRequest}
@@ -212,14 +208,12 @@ export interface CancelledRequest<
 */
 export type RequestCacheRequestState<
 	RT = unknown,
-	T = unknown,
 	E extends StructuredErrorDocument = StructuredErrorDocument
-> = PendingRequest | ResolvedRequest<RT, T> | RejectedRequest<RT, T, E> | CancelledRequest<RT, T, E>;
+> = PendingRequest | ResolvedRequest<RT> | RejectedRequest<RT, E> | CancelledRequest<RT, E>;
 export declare function createRequestState<
 	RT,
-	T,
 	E
->(future: Future<RT>): Readonly<RequestCacheRequestState<RT, T, StructuredErrorDocument<E>>>;
+>(future: Future<RT>): Readonly<RequestCacheRequestState<RT, StructuredErrorDocument<E>>>;
 /**
 * `getRequestState` can be used in both JavaScript and Template contexts.
 *
@@ -272,6 +266,5 @@ export declare function createRequestState<
 */
 export declare function getRequestState<
 	RT,
-	T,
 	E
->(future: Future<RT>): Readonly<RequestCacheRequestState<RT, T, StructuredErrorDocument<E>>>;
+>(future: Future<RT>): Readonly<RequestCacheRequestState<RT, StructuredErrorDocument<E>>>;

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

@@ -22,7 +22,6 @@ type ContentFeatures<RT> = {
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface SubscriptionArgs<
 	RT,
-	T,
 	E
 > {
 	/**
@@ -37,7 +36,7 @@ export interface SubscriptionArgs<
 	* like the component to also initiate the request.
 	*
 	*/
-	query?: StoreRequestInput<RT, T>;
+	query?: StoreRequestInput<RT>;
 	/**
 	* The autorefresh behavior for the request. This can be a boolean, or any
 	* combination of the following values: `'online'`, `'interval'`, `'invalid'`.
@@ -80,7 +79,6 @@ export interface SubscriptionArgs<
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface RequestSubscription<
 	RT,
-	T,
 	E
 > {
 	/**
@@ -96,7 +94,6 @@ export interface RequestSubscription<
 */
 export declare class RequestSubscription<
 	RT,
-	T,
 	E
 > {
 	/**
@@ -183,7 +180,7 @@ export declare class RequestSubscription<
 	private _args;
 	/** @internal */
 	store: Store | RequestManager;
-	constructor(store: Store | RequestManager, args: SubscriptionArgs<RT, T, E>);
+	constructor(store: Store | RequestManager, args: SubscriptionArgs<RT, E>);
 	/**
 	* @internal
 	*/
@@ -250,12 +247,11 @@ export declare class RequestSubscription<
 	*/
 	get _request(): Future<RT>;
 	get request(): Future<RT>;
-	get reqState(): RequestState<RT, T, StructuredErrorDocument<E>>;
+	get reqState(): RequestState<RT, StructuredErrorDocument<E>>;
 	get result(): RT;
 }
 export declare function createRequestSubscription<
 	RT,
-	T,
 	E
->(store: Store | RequestManager, args: SubscriptionArgs<RT, T, E>): RequestSubscription<RT, T, E>;
+>(store: Store | RequestManager, args: SubscriptionArgs<RT, E>): RequestSubscription<RT, E>;
 export {};

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;

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, ResourceKey } 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: ResourceKey;
+	links: Links | PaginationLinks | null;
+	meta: Meta | null;
+}
+/**
+* Creates a {@link LegacyManyArray}
+*
+* @internal
+*/
+export declare function createLegacyManyArray<T>(options: LegacyManyArrayCreateOptions): LegacyManyArray<T>;

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

@@ -0,0 +1,103 @@
+import type { ImmutableRequestInfo } from "../../../types/request.js";
+import type { Links, Meta, PaginationLinks } from "../../../types/spec/json-api-raw.js";
+import type { LegacyLiveArray, LegacyLiveArrayCreateOptions } from "./legacy-live-array.js";
+/**
+* QueryArrays contain the primary records returned when querying
+* for records by `ResourceType`.
+*
+* ### Basic Example
+*
+* For instance, if an application were to have a `'user'` type:
+*
+* ```ts
+* const users = await store.query('user', { name: 'Chris' });
+* ```
+*
+* ---
+*
+*  
+*
+* ### QueryArrays are Arrays
+*
+* QueryArrays have all array APIs, and will report `true`
+* for both `queryArray instanceof Array` and `Array.isArray(queryArray)`
+*
+* However, any mutation of the array will throw an error.
+*
+* ---
+*
+*  
+*
+* ### Reactive
+*
+* If a record in a QueryArray is deleted and unloaded, it will be
+* automatically removed from the array.
+*
+* ---
+*
+*  
+*
+* ### Immutable
+*
+* Records cannot be directly added to or removed from a QueryArray.
+*
+* ---
+*
+*  
+*
+* ### Polymorphism
+*
+* QueryArrays are not intended to be polymorphic. If your application has
+* an abstract type "car" with concrete types "ferrari" and "bmw", a query
+* which returns primary data containing both ferraris and bmws will *likely*
+* work, but it is not guaranteed.
+*
+* In contrast, the {@link ReactiveResourceArray} returned when using {@link Store.request}
+* is guaranteed to work with polymorphic responses.
+*
+* ---
+*
+*  
+*
+* ### Memory Leaks
+*
+* QueryArrays are meant to be long lived. They can be refreshed using
+* `array.update()`, and destroyed via `array.destroy()`.
+*
+* Unlike most Reactive state in WarpDrive, applications must choose to call
+* `destroy` when the `QueryArray` is no longer needed, else the array instance
+* will be retained until either the application or the store which created it
+* are destroyed. Destroying a QueryArray does not remove its records
+* from the cache, but it does remove the array as well as the overhead it requires
+* from the store for book-keeping.
+*
+* @legacy we recommend againt using QueryArrays. Use {@link Store.request} instead
+*/
+export interface LegacyQueryArray<T = unknown> extends LegacyLiveArray<T> {
+	query: ImmutableRequestInfo | Record<string, unknown> | null;
+	destroy(): void;
+	links: PaginationLinks | Links | null;
+	meta: Meta | null;
+}
+/**
+* The options for {@link createLegacyQueryArray}
+*
+* See also {@link LegacyLiveArrayCreateOptions} which
+* this extends.
+*
+* @internal
+*/
+export interface LegacyQueryArrayCreateOptions extends LegacyLiveArrayCreateOptions {
+	query: ImmutableRequestInfo | Record<string, unknown> | null;
+	isLoaded: boolean;
+	links: PaginationLinks | Links | null;
+	meta: Meta | null;
+}
+/**
+* Creates a {@link LegacyQueryArray}
+*
+* Options: {@link LegacyQueryArrayCreateOptions}
+*
+* @internal
+*/
+export declare function createLegacyQueryArray<T = unknown>(options: LegacyQueryArrayCreateOptions): LegacyQueryArray<T>;