@warp-drive-mirror/core 5.7.0-alpha.9 → 5.7.0

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

@@ -3,14 +3,22 @@ import type { Future } from "../../../request.js";
 import type { StructuredErrorDocument } from "../../../types/request.js";
 import type { RequestState } from "../../-private.js";
 export declare const DISPOSE: "(symbol) dispose";
-interface ErrorFeatures {
-	isHidden: boolean;
+export type AutorefreshBehaviorType = "online" | "interval" | "invalid";
+export type AutorefreshBehaviorCombos = boolean | AutorefreshBehaviorType | `${AutorefreshBehaviorType},${AutorefreshBehaviorType}` | `${AutorefreshBehaviorType},${AutorefreshBehaviorType},${AutorefreshBehaviorType}`;
+/**
+* Utilities to assist in recovering from the error.
+*/
+export interface RecoveryFeatures {
 	isOnline: boolean;
+	isHidden: boolean;
 	retry: () => Promise<void>;
 }
-type AutorefreshBehaviorType = "online" | "interval" | "invalid";
-type AutorefreshBehaviorCombos = boolean | AutorefreshBehaviorType | `${AutorefreshBehaviorType},${AutorefreshBehaviorType}` | `${AutorefreshBehaviorType},${AutorefreshBehaviorType},${AutorefreshBehaviorType}`;
-type ContentFeatures<RT> = {
+/** @deprecated use {@link RecoveryFeatures} */
+export type ErrorFeatures = RecoveryFeatures;
+/**
+* Utilities for keeping the request fresh
+*/
+export interface ContentFeatures<RT> {
 	isOnline: boolean;
 	isHidden: boolean;
 	isRefreshing: boolean;
@@ -18,11 +26,24 @@ type ContentFeatures<RT> = {
 	reload: () => Promise<void>;
 	abort?: () => void;
 	latestRequest?: Future<RT>;
-};
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+}
+export interface RequestArgs<
+	RT,
+	E
+> extends SubscriptionArgs<RT, E> {
+	subscription?: RequestSubscription<RT, E>;
+	/**
+	* The store instance to use for making requests. If contexts are available,
+	* the component will default to using the `store` on the context.
+	*
+	* This is required if the store is not available via context or should be
+	* different from the store provided via context.
+	*
+	*/
+	store?: Store | RequestManager;
+}
 export interface SubscriptionArgs<
 	RT,
-	T,
 	E
 > {
 	/**
@@ -30,14 +51,14 @@ export interface SubscriptionArgs<
 	* by either the `store.request` or `store.requestManager.request` methods.
 	*
 	*/
-	request?: Future<RT>;
+	request?: Future<RT> | undefined | null;
 	/**
 	* A query to use for the request. This should be an object that can be
 	* passed to `store.request`. Use this in place of `@request` if you would
 	* like the component to also initiate the request.
 	*
 	*/
-	query?: StoreRequestInput<RT, T>;
+	query?: StoreRequestInput<RT> | undefined | null;
 	/**
 	* The autorefresh behavior for the request. This can be a boolean, or any
 	* combination of the following values: `'online'`, `'interval'`, `'invalid'`.
@@ -77,10 +98,22 @@ export interface SubscriptionArgs<
 	*/
 	autorefreshBehavior?: "refresh" | "reload" | "policy";
 }
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export interface RequestComponentArgs<
+	RT,
+	E
+> extends SubscriptionArgs<RT, E> {
+	/**
+	* The store instance to use for making requests. If contexts are available,
+	* the component will default to using the `store` on the context.
+	*
+	* This is required if the store is not available via context or should be
+	* different from the store provided via context.
+	*
+	*/
+	store?: Store | RequestManager;
+}
 export interface RequestSubscription<
 	RT,
-	T,
 	E
 > {
 	/**
@@ -96,7 +129,6 @@ export interface RequestSubscription<
 */
 export declare class RequestSubscription<
 	RT,
-	T,
 	E
 > {
 	/**
@@ -112,123 +144,13 @@ export declare class RequestSubscription<
 	*/
 	isRefreshing: boolean;
 	/**
-	* The most recent blocking request that was made, typically
-	* the result of a reload.
-	*
-	* This will never be the original request passed as an arg to
-	* the component.
-	*
-	* @internal
-	*/
-	private _localRequest;
-	/**
-	* The most recent request that was made, typically due to either a
-	* reload or a refresh.
-	*
-	* This will never be the original request passed as an arg to
-	* the component.
-	*
-	* @internal
-	*/
-	private _latestRequest;
-	/**
-	* The time at which the network was reported as offline.
-	*
-	* @internal
-	*/
-	private _unavailableStart;
-	/** @internal */
-	private _intervalStart;
-	/** @internal */
-	private _nextInterval;
-	/** @internal */
-	private _invalidated;
-	/** @internal */
-	private _isUpdating;
-	/** @internal */
-	private isDestroyed;
-	/**
-	* The event listener for network status changes,
-	* cached to use the reference for removal.
-	*
-	* @internal
+	* The Store this subscription subscribes to or the RequestManager
+	* which issues this request.
 	*/
-	private _onlineChanged;
-	/**
-	* The event listener for visibility status changes,
-	* cached to use the reference for removal.
-	*
-	* @internal
-	*/
-	private _backgroundChanged;
-	/**
-	* The last request passed as an arg to the component,
-	* cached for comparison.
-	*
-	* @internal
-	*/
-	private _originalRequest;
-	/**
-	* The last query passed as an arg to the component,
-	* cached for comparison.
-	*
-	* @internal
-	*/
-	private _originalQuery;
-	/** @internal */
-	private _subscription;
-	/** @internal */
-	private _subscribedTo;
-	/** @internal */
-	private _args;
-	/** @internal */
 	store: Store | RequestManager;
-	constructor(store: Store | RequestManager, args: SubscriptionArgs<RT, T, E>);
-	/**
-	* @internal
-	*/
-	private _beginPolling;
+	constructor(store: Store | RequestManager, args: SubscriptionArgs<RT, E>);
 	get isIdle(): boolean;
 	get autorefreshTypes(): Set<AutorefreshBehaviorType>;
-	// we only run this function on component creation
-	// and when an update is triggered, so it does not
-	// react to changes in the autorefreshThreshold
-	// or autorefresh args.
-	//
-	// if we need to react to those changes, we can
-	// use a modifier or internal component or some
-	// such to trigger a re-run of this function.
-	private _scheduleInterval;
-	private _clearInterval;
-	/**
-	* @internal
-	*/
-	private _updateSubscriptions;
-	/**
-	* @internal
-	*/
-	private _removeSubscriptions;
-	/**
-	* Install the event listeners for network and visibility changes.
-	* This is only done in browser environments with a global `window`.
-	*
-	* @internal
-	*/
-	private _installListeners;
-	/**
-	* If the network is online and the tab is visible, either reload or refresh the request
-	* based on the component's configuration and the requested update mode.
-	*
-	* Valid modes are:
-	*
-	* - `'reload'`: Force a reload of the request.
-	* - `'refresh'`: Refresh the request in the background.
-	* - `'policy'`: Make the request, letting the store's configured CachePolicy decide whether to reload, refresh, or do nothing.
-	* - `undefined`: Make the request using the component's autorefreshBehavior setting if the autorefreshThreshold has passed.
-	*
-	* @internal
-	*/
-	private _maybeUpdate;
 	/**
 	* Retry the request, reloading it from the server.
 	*/
@@ -240,22 +162,16 @@ export declare class RequestSubscription<
 	/**
 	* features to yield to the error slot of a component
 	*/
-	get errorFeatures(): ErrorFeatures;
+	get errorFeatures(): RecoveryFeatures;
 	/**
 	* features to yield to the content slot of a component
 	*/
 	get contentFeatures(): ContentFeatures<RT>;
-	/**
-	* @internal
-	*/
-	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>;
-export {};
+>(store: Store | RequestManager, args: SubscriptionArgs<RT, E>): RequestSubscription<RT, E>;

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

@@ -0,0 +1,80 @@
+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;
+	/**
+	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,81 @@
+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;
+	modelName: TypeFromInstanceOrString<T>;
+}
+/**
+* The options for {@link createLegacyLiveArray}
+*
+* @private
+*/
+export interface LegacyLiveArrayCreateOptions {
+	store: Store;
+	manager: MinimumManager;
+	source: ResourceKey[];
+	type: string;
+}

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,85 +45,21 @@ 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> {
-	isAsync: boolean;
+export interface LegacyManyArray<T = unknown> extends ReactiveResourceArray<T> {
+	meta: Meta | null;
+	links: Links | PaginationLinks | null;
+	/** @private */
+	key: string;
+	/** @private */
+	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>);
-	notify(): void;
-	/**
 	Reloads all of the records in the manyArray. If the manyArray
 	holds a relationship that was originally fetched using a links url
 	WarpDrive will revisit the original links url to repopulate the
@@ -162,13 +80,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 +94,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 +105,29 @@ export declare class RelatedCollection<T = unknown> extends IdentifierArray<T> {
 	```
 	
 	@public
-	@return {PromiseArray} promise
 	*/
-	save: () => Promise<IdentifierArray<T>>;
-	/** @internal */
-	destroy(): void;
+	save: () => Promise<LegacyManyArray<T>>;
+	/** @private */
+	destroy: () => void;
+}
+/**
+* The options for {@link createLegacyManyArray}
+*
+* @private
+*/
+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}
+*
+* @private
+*/
+export declare function createLegacyManyArray<T>(options: LegacyManyArrayCreateOptions): LegacyManyArray<T>;

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

@@ -0,0 +1,81 @@
+import type { ImmutableRequestInfo } from "../../../types/request.js";
+import type { Links, Meta, PaginationLinks } from "../../../types/spec/json-api-raw.js";
+import type { LegacyLiveArray } 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;
+}