@warp-drive/core 5.6.0-alpha.14 → 5.6.0-alpha.17

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

@@ -0,0 +1,261 @@
+import type { RequestManager, Store, StoreRequestInput } from "../../../index.js";
+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;
+	isOnline: boolean;
+	retry: () => Promise<void>;
+}
+type AutorefreshBehaviorType = "online" | "interval" | "invalid";
+type AutorefreshBehaviorCombos = boolean | AutorefreshBehaviorType | `${AutorefreshBehaviorType},${AutorefreshBehaviorType}` | `${AutorefreshBehaviorType},${AutorefreshBehaviorType},${AutorefreshBehaviorType}`;
+type ContentFeatures<RT> = {
+	isOnline: boolean;
+	isHidden: boolean;
+	isRefreshing: boolean;
+	refresh: () => Promise<void>;
+	reload: () => Promise<void>;
+	abort?: () => void;
+	latestRequest?: Future<RT>;
+};
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export interface SubscriptionArgs<
+	RT,
+	T,
+	E
+> {
+	/**
+	* The request to monitor. This should be a `Future` instance returned
+	* by either the `store.request` or `store.requestManager.request` methods.
+	*
+	*/
+	request?: Future<RT>;
+	/**
+	* 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>;
+	/**
+	* The autorefresh behavior for the request. This can be a boolean, or any
+	* combination of the following values: `'online'`, `'interval'`, `'invalid'`.
+	*
+	* - `'online'`: Refresh the request when the browser comes back online
+	* - `'interval'`: Refresh the request at a specified interval
+	* - `'invalid'`: Refresh the request when the store emits an invalidation
+	*
+	* If `true`, this is equivalent to `'online,invalid'`.
+	*
+	* Defaults to `false`.
+	*
+	*/
+	autorefresh?: AutorefreshBehaviorCombos;
+	/**
+	* The number of milliseconds to wait before refreshing the request when the
+	* browser comes back online or the network becomes available.
+	*
+	* This also controls the interval at which the request will be refreshed if
+	* the `interval` autorefresh type is enabled.
+	*
+	* Defaults to `30_000` (30 seconds).
+	*
+	*/
+	autorefreshThreshold?: number;
+	/**
+	* The behavior of the request initiated by autorefresh. This can be one of
+	* the following values:
+	*
+	* - `'refresh'`: Refresh the request in the background
+	* - `'reload'`: Force a reload of the request
+	* - `'policy'` (**default**): Let the store's configured CachePolicy decide whether to
+	*    reload, refresh, or do nothing.
+	*
+	* Defaults to `'policy'`.
+	*
+	*/
+	autorefreshBehavior?: "refresh" | "reload" | "policy";
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export interface RequestSubscription<
+	RT,
+	T,
+	E
+> {
+	/**
+	* The method to call when the component this subscription is attached to
+	* unmounts.
+	*/
+	[DISPOSE](): void;
+}
+/**
+* A reactive class
+*
+* @hideconstructor
+*/
+export declare class RequestSubscription<
+	RT,
+	T,
+	E
+> {
+	/**
+	* Whether the browser reports that the network is online.
+	*/
+	isOnline: boolean;
+	/**
+	* Whether the browser reports that the tab is hidden.
+	*/
+	isHidden: boolean;
+	/**
+	* Whether the component is currently refreshing the request.
+	*/
+	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
+	*/
+	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;
+	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.
+	*/
+	retry: () => Promise<void>;
+	/**
+	* Refresh the request, updating it in the background.
+	*/
+	refresh: () => Promise<void>;
+	/**
+	* features to yield to the error slot of a component
+	*/
+	get errorFeatures(): ErrorFeatures;
+	/**
+	* 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 result(): RT;
+}
+export declare function createRequestSubscription<
+	RT,
+	T,
+	E
+>(store: Store | RequestManager, args: SubscriptionArgs<RT, T, E>): RequestSubscription<RT, T, E>;
+export {};

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

@@ -1,141 +1,147 @@
-import type { BaseFinderOptions } from '../../../types';
-import type { LocalRelationshipOperation } from '../../../types/graph.ts';
-import type { StableDocumentIdentifier, StableRecordIdentifier } from '../../../types/identifier.ts';
-import type { TypeFromInstanceOrString } from '../../../types/record.ts';
-import type { ImmutableRequestInfo } from '../../../types/request.ts';
-import type { Links, PaginationLinks } from '../../../types/spec/json-api-raw.ts';
-import type { RecordArrayManager } from '../managers/record-array-manager.ts';
-import type { WarpDriveSignal } from '../new-core-tmp/reactivity/internal.ts';
-import { ARRAY_SIGNAL } from '../new-core-tmp/reactivity/internal.ts';
-import type { Store } from '../store-service.ts';
-import { NativeProxy } from './native-proxy-type-fix.ts';
+import type { BaseFinderOptions } from "../../../types.js";
+import type { LocalRelationshipOperation } from "../../../types/graph.js";
+import type { StableDocumentIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
+import type { TypeFromInstanceOrString } from "../../../types/record.js";
+import type { ImmutableRequestInfo } from "../../../types/request.js";
+import type { LegacyHasManyField, LinksModeHasManyField } from "../../../types/schema/fields.js";
+import type { Links, PaginationLinks } from "../../../types/spec/json-api-raw.js";
+import type { RecordArrayManager } from "../managers/record-array-manager.js";
+import type { WarpDriveSignal } from "../new-core-tmp/reactivity/internal.js";
+import { ARRAY_SIGNAL } from "../new-core-tmp/reactivity/internal.js";
+import type { Store } from "../store-service.js";
+import { NativeProxy } from "./native-proxy-type-fix.js";
 export declare const SOURCE: "___(unique) Symbol(#source)";
 export declare const MUTATE: "___(unique) Symbol(#update)";
 declare const IS_COLLECTION: "___(unique) Symbol(IS_COLLECTION)";
 export type IdentifierArrayCreateOptions<T = unknown> = {
-    identifiers: StableRecordIdentifier<TypeFromInstanceOrString<T>>[];
-    type?: TypeFromInstanceOrString<T>;
-    store: Store;
-    allowMutation: boolean;
-    manager: MinimumManager;
-    links?: Links | PaginationLinks | null;
-    meta?: Record<string, unknown> | null;
-    identifier?: StableDocumentIdentifier | null;
+	identifiers: StableRecordIdentifier<TypeFromInstanceOrString<T>>[];
+	type?: TypeFromInstanceOrString<T>;
+	store: Store;
+	allowMutation: boolean;
+	manager: MinimumManager;
+	field?: LegacyHasManyField | LinksModeHasManyField;
+	links?: Links | PaginationLinks | null;
+	meta?: Record<string, unknown> | null;
+	identifier?: StableDocumentIdentifier | null;
+	[MUTATE]?(target: StableRecordIdentifier[], receiver: typeof NativeProxy<StableRecordIdentifier[], T[]>, prop: string, args: unknown[], _SIGNAL: WarpDriveSignal): unknown;
 };
 type PromiseTo<T> = Omit<Promise<T>, typeof Symbol.toStringTag>;
 type PromiseManyArray<T> = {
-    length: number;
-    content: IdentifierArray<T> | null;
-    promise: Promise<IdentifierArray<T>> | null;
+	length: number;
+	content: IdentifierArray<T> | null;
+	promise: Promise<IdentifierArray<T>> | null;
 } & PromiseTo<IdentifierArray<T>>;
 export type MinimumManager = {
-    _syncArray: (array: IdentifierArray) => void;
-    mutate?(mutation: LocalRelationshipOperation): void;
-    reloadHasMany?<T>(key: string, options?: BaseFinderOptions): Promise<IdentifierArray<T>> | PromiseManyArray<T>;
+	_syncArray: (array: IdentifierArray) => void;
+	mutate?(mutation: LocalRelationshipOperation): void;
+	reloadHasMany?<T>(key: string, options?: BaseFinderOptions): Promise<IdentifierArray<T>> | PromiseManyArray<T>;
 };
 /**
-  A record array is an array that contains records of a certain type (or modelName).
-  The record array materializes records as needed when they are retrieved for the first
-  time. You should not create record arrays yourself. Instead, an instance of
-  `RecordArray` or its subclasses will be returned by your application's store
-  in response to queries.
+A record array is an array that contains records of a certain type (or modelName).
+The record array materializes records as needed when they are retrieved for the first
+time. You should not create record arrays yourself. Instead, an instance of
+`RecordArray` or its subclasses will be returned by your application's store
+in response to queries.
 
-  This class should not be imported and instantiated by consuming applications.
+This class should not be imported and instantiated by consuming applications.
 
-  @class RecordArray
-  @public
+@class RecordArray
+@public
 */
-export interface IdentifierArray<T = unknown> extends Omit<Array<T>, '[]'> {
-    [MUTATE]?(target: StableRecordIdentifier[], receiver: typeof NativeProxy<StableRecordIdentifier[], T[]>, prop: string, args: unknown[], _SIGNAL: WarpDriveSignal): unknown;
+export interface IdentifierArray<T = unknown> extends Omit<Array<T>, "[]"> {
+	[IS_COLLECTION]: boolean;
+	[ARRAY_SIGNAL]: WarpDriveSignal;
+	[SOURCE]: StableRecordIdentifier[];
 }
 export declare class IdentifierArray<T = unknown> {
-    DEPRECATED_CLASS_NAME: string;
-    /**
-      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
-      ```
-      @property isUpdating
-      @public
-      @type Boolean
-    */
-    isUpdating: boolean;
-    isLoaded: boolean;
-    isDestroying: boolean;
-    isDestroyed: boolean;
-    _updatingPromise: Promise<IdentifierArray<T>> | null;
-    readonly identifier: StableDocumentIdentifier | null;
-    [IS_COLLECTION]: boolean;
-    [ARRAY_SIGNAL]: WarpDriveSignal;
-    [SOURCE]: StableRecordIdentifier[];
-    links: Links | PaginationLinks | null;
-    meta: Record<string, unknown> | null;
-    modelName?: TypeFromInstanceOrString<T>;
-    /**
-      The store that created this record array.
-  
-      @property store
-      @private
-      @type Store
-      */
-    store: Store;
-    _manager: MinimumManager;
-    destroy(clear: boolean): void;
-    constructor(options: IdentifierArrayCreateOptions<T>);
-    /**
-      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(): Promise<IdentifierArray<T>>;
-    _update(): Promise<IdentifierArray<T>>;
-    /**
-      Saves all of the records in the `RecordArray`.
-  
-      Example
-  
-      ```javascript
-      let messages = store.peekAll('message');
-      messages.forEach(function(message) {
-        message.hasBeenSeen = true;
-      });
-      messages.save();
-      ```
-  
-      @public
-      @return {Promise<IdentifierArray>} promise
-    */
-    save(): Promise<IdentifierArray>;
+	DEPRECATED_CLASS_NAME: string;
+	/**
+	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
+	```
+	@property isUpdating
+	@public
+	@type Boolean
+	*/
+	isUpdating: boolean;
+	isLoaded: boolean;
+	isDestroying: boolean;
+	isDestroyed: boolean;
+	_updatingPromise: Promise<IdentifierArray<T>> | null;
+	readonly identifier: StableDocumentIdentifier | null;
+	links: Links | PaginationLinks | null;
+	meta: Record<string, unknown> | null;
+	modelName?: TypeFromInstanceOrString<T>;
+	/**
+	The store that created this record array.
+	
+	@property store
+	@private
+	@type Store
+	*/
+	store: Store;
+	_manager: MinimumManager;
+	destroy(clear: boolean): void;
+	constructor(options: IdentifierArrayCreateOptions<T>);
+	/**
+	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(): Promise<IdentifierArray<T>>;
+	/*
+	Update this Array and return a promise which resolves once the update
+	is finished.
+	*/
+	_update(): Promise<IdentifierArray<T>>;
+	// TODO deprecate
+	/**
+	Saves all of the records in the `RecordArray`.
+	
+	Example
+	
+	```javascript
+	let messages = store.peekAll('message');
+	messages.forEach(function(message) {
+	message.hasBeenSeen = true;
+	});
+	messages.save();
+	```
+	
+	@public
+	@return {Promise<IdentifierArray>} promise
+	*/
+	save(): Promise<IdentifierArray>;
 }
 export type CollectionCreateOptions = IdentifierArrayCreateOptions & {
-    manager: RecordArrayManager;
-    query: ImmutableRequestInfo | Record<string, unknown> | null;
-    isLoaded: boolean;
+	manager: RecordArrayManager;
+	query: ImmutableRequestInfo | Record<string, unknown> | null;
+	isLoaded: boolean;
 };
 export declare class Collection<T = unknown> extends IdentifierArray<T> {
-    query: ImmutableRequestInfo | Record<string, unknown> | null;
-    _manager: RecordArrayManager;
-    constructor(options: CollectionCreateOptions);
-    _update(): Promise<Collection<T>>;
-    destroy(clear: boolean): void;
+	query: ImmutableRequestInfo | Record<string, unknown> | null;
+	_manager: RecordArrayManager;
+	constructor(options: CollectionCreateOptions);
+	_update(): Promise<Collection<T>>;
+	destroy(clear: boolean): void;
 }
 export {};
-//# sourceMappingURL=identifier-array.d.ts.map