@warp-drive/core 5.7.0-alpha.9 → 5.7.0-beta.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/legacy-many-array.d.ts

@@ -0,0 +1,133 @@
+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, 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.
+
+The `ManyArray` is instantiated lazily the first time the relationship is
+requested.
+
+This class is not intended to be directly instantiated by consuming applications.
+
+### Inverses
+
+Often, the relationships in Ember Data applications will have
+an inverse. For example, imagine the following models are
+defined:
+
+```js [app/models/post.js]
+import Model, { hasMany } from '@ember-data/model';
+
+export default class PostModel extends Model {
+@hasMany('comment') comments;
+}
+```
+
+```js [app/models/comment.js]
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class CommentModel extends Model {
+@belongsTo('post') post;
+}
+```
+
+If you created a new instance of `Post` and added
+a `Comment` record to its `comments` has-many
+relationship, you would expect the comment's `post`
+property to be set to the post that contained
+the has-many.
+
+We call the record to which a relationship belongs-to the
+relationship's _owner_.
+
+@public
+*/
+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
+	@public
+	*/
+	isLoaded: boolean;
+	/**
+	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
+	relationship.
+	
+	If the ManyArray holds the result of a `store.query()` reload will
+	re-run the original query.
+	
+	Example
+	
+	```javascript
+	let user = store.peekRecord('user', '1')
+	await login(user);
+	
+	let permissions = await user.permissions;
+	await permissions.reload();
+	```
+	
+	@public
+	*/
+	reload(options?: BaseFinderOptions): Promise<LegacyManyArray<T>>;
+	/**
+	Create a child record and associated it to the collection
+	
+	@public
+	*/
+	createRecord(hash: CreateRecordProperties<T>): T;
+	/**
+	Saves all of the records in the `ManyArray`.
+	
+	Note: this API can only be used in legacy mode with a configured Adapter.
+	
+	Example
+	
+	```js
+	const { content: { data: inbox } } = await store.request(findRecord({ type: 'inbox', id: '1' }));
+	
+	let messages = await inbox.messages;
+	messages.forEach((message) => {
+	message.isRead = true;
+	});
+	messages.save();
+	```
+	
+	@public
+	*/
+	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;
+}