@warp-drive/core 5.6.0-alpha.5 → 5.6.0-beta.1

package/declarations/store/-private/network/request-cache.d.ts

@@ -0,0 +1,107 @@
+import type { StableRecordIdentifier } from "../../../types/identifier.js";
+import type { FindRecordOptions } from "../../-types/q/store.js";
+import type { Store } from "../store-service.js";
+declare const Touching: "___(unique) Symbol(Touching)";
+export declare const RequestPromise: "___(unique) Symbol(RequestPromise)";
+export interface Operation {
+	op: string;
+	options: FindRecordOptions | undefined;
+	recordIdentifier: StableRecordIdentifier;
+}
+export interface FindRecordQuery extends Operation {
+	op: "findRecord";
+}
+export interface SaveRecordMutation extends Operation {
+	op: "saveRecord";
+}
+export interface Request {
+	data: Operation[];
+	options?: Record<string, unknown>;
+}
+export type RequestStates = "pending" | "fulfilled" | "rejected";
+export interface RequestCacheRequestState {
+	state: RequestStates;
+	type: "query" | "mutation";
+	request: Request;
+	response?: Response;
+}
+export interface Response {
+	// rawData: unknown;
+	data: unknown;
+}
+interface InternalRequest extends RequestCacheRequestState {
+	[Touching]: StableRecordIdentifier[];
+	[RequestPromise]?: Promise<unknown>;
+}
+export type RequestSubscription = (requestState: RequestCacheRequestState) => void;
+/**
+* The RequestStateService is used to track the state of requests
+* for fetching or updating known resource identifies that are inflight.
+*
+* @hideconstructor
+* @public
+*/
+export declare class RequestStateService {
+	/** @internal */
+	_pending: Map<StableRecordIdentifier, InternalRequest[]>;
+	private _done;
+	private _subscriptions;
+	private _toFlush;
+	private _store;
+	constructor(store: Store);
+	/** @internal */
+	_clearEntries(identifier: StableRecordIdentifier): void;
+	/** @internal */
+	_enqueue<T>(promise: Promise<T>, queryRequest: Request): Promise<T>;
+	private _triggerSubscriptions;
+	private _flush;
+	private _flushRequest;
+	private _dequeue;
+	private _addDone;
+	/**
+	* Subscribe to requests for a given resource identity.
+	*
+	* The callback will receive the current state of the request.
+	*
+	* ```ts
+	* interface RequestState {
+	*   state: 'pending' | 'fulfilled' | 'rejected';
+	*   type: 'query' | 'mutation';
+	*   request: Request;
+	*   response?: { data: unknown };
+	* }
+	* ```
+	*
+	* Note: It should be considered dangerous to use this API for more than simple
+	* state derivation or debugging. The `request` and `response` properties are poorly
+	* spec'd and may change unexpectedly when shifting what Handlers are in use or how
+	* requests are issued from the Store.
+	*
+	* We expect to revisit this API in the near future as we continue to refine the
+	* RequestManager ergonomics, as a simpler but more powerful direct integration
+	* with the RequestManager for these purposes is likely to be a better long-term
+	* design.
+	*
+	* @public
+	* @param {StableRecordIdentifier} identifier
+	* @param {(state: RequestCacheRequestState) => void} callback
+	*/
+	subscribeForRecord(identifier: StableRecordIdentifier, callback: RequestSubscription): void;
+	/**
+	* Retrieve all active requests for a given resource identity.
+	*
+	* @public
+	* @param {StableRecordIdentifier} identifier
+	* @return {RequestCacheRequestState[]} an array of request states for any pending requests for the given identifier
+	*/
+	getPendingRequestsForRecord(identifier: StableRecordIdentifier): RequestCacheRequestState[];
+	/**
+	* Retrieve the last completed request for a given resource identity.
+	*
+	* @public
+	* @param {StableRecordIdentifier} identifier
+	* @return {RequestCacheRequestState | null} the state of the most recent request for the given identifier
+	*/
+	getLastRequestForRecord(identifier: StableRecordIdentifier): RequestCacheRequestState | null;
+}
+export {};

package/declarations/store/-private/new-core-tmp/promise-state.d.ts

@@ -0,0 +1,263 @@
+import type { Awaitable } from "../../../request.js";
+/**
+* The state of a promise in the "pending"
+* state. This is the default initial state.
+*
+*/
+export interface PendingPromise {
+	/**
+	* The status of the promise.
+	*
+	*/
+	status: "pending";
+	/**
+	* Whether the promise is pending.
+	*
+	*/
+	isPending: true;
+	/**
+	* Whether the promise is pending.
+	*
+	* @deprecated use `isPending` instead
+	*/
+	isLoading: true;
+	/**
+	* Whether the promise has resolved
+	* successfully.
+	*
+	*/
+	isSuccess: false;
+	/**
+	* Whether the promise has rejected
+	* with an error.
+	*
+	*/
+	isError: false;
+	/**
+	* Once the promise has resolved, this will
+	* be the value the promise resolved to.
+	*
+	*/
+	value: null;
+	/**
+	* Once the promise has resolved, this will
+	* be the value the promise resolved to.
+	*
+	* @deprecated use `value` instead
+	*/
+	result: null;
+	/**
+	* Once the promise has rejected, this will
+	* be the error the promise rejected with.
+	*
+	*
+	* @deprecated use `reason` instead
+	*/
+	error: null;
+	/**
+	* Once the promise has rejected, this will
+	* be the error the promise rejected with.
+	*
+	*/
+	reason: null;
+}
+/**
+* The state of a promise in the "fulfilled" state.
+* This is the state of a promise that has resolved
+* successfully.
+*
+*/
+export interface ResolvedPromise<T> {
+	/**
+	* The status of the promise.
+	*
+	*/
+	status: "fulfilled";
+	/**
+	* Whether the promise is pending.
+	*
+	*/
+	isPending: false;
+	/**
+	* Whether the promise is pending.
+	*
+	* @deprecated use `isPending` instead
+	*/
+	isLoading: false;
+	/**
+	* Whether the promise has resolved
+	* successfully.
+	*
+	*/
+	isSuccess: true;
+	/**
+	* Whether the promise has rejected
+	* with an error.
+	*
+	*/
+	isError: false;
+	/**
+	* Once the promise has resolved, this will
+	* be the value the promise resolved to.
+	*
+	*/
+	value: T;
+	/**
+	* Once the promise has resolved, this will
+	* be the value the promise resolved to.
+	*
+	* @deprecated use `value` instead
+	*/
+	result: T;
+	/**
+	* Once the promise has rejected, this will
+	* be the error the promise rejected with.
+	*
+	*
+	* @deprecated use `reason` instead
+	*/
+	error: null;
+	/**
+	* Once the promise has rejected, this will
+	* be the error the promise rejected with.
+	*
+	*/
+	reason: null;
+}
+/**
+* The state of a promise in the "rejected" state.
+* This is the state of a promise that has rejected
+* with an error.
+*
+*/
+export interface RejectedPromise<E> {
+	/**
+	* The status of the promise.
+	*
+	*/
+	status: "rejected";
+	/**
+	* Whether the promise is pending.
+	*
+	*/
+	isPending: false;
+	/**
+	* Whether the promise is pending.
+	*
+	* @deprecated use `isPending` instead
+	*/
+	isLoading: false;
+	/**
+	* Whether the promise has resolved
+	* successfully.
+	*
+	*/
+	isSuccess: false;
+	/**
+	* Whether the promise has rejected
+	* with an error.
+	*
+	*/
+	isError: true;
+	/**
+	* Once the promise has resolved, this will
+	* be the value the promise resolved to.
+	*
+	*/
+	value: null;
+	/**
+	* Once the promise has resolved, this will
+	* be the value the promise resolved to.
+	*
+	* @deprecated use `value` instead
+	*/
+	result: null;
+	/**
+	* Once the promise has rejected, this will
+	* be the error the promise rejected with.
+	*
+	*
+	* @deprecated use `reason` instead
+	*/
+	error: E;
+	/**
+	* Once the promise has rejected, this will
+	* be the error the promise rejected with.
+	*
+	*/
+	reason: E;
+}
+/**
+* The state of a promise. This is the type that is returned
+* from `getPromiseState`.
+*
+* See also:
+* - {@link PendingPromise}
+* - {@link ResolvedPromise}
+* - {@link RejectedPromise}
+*
+*/
+export type PromiseState<
+	T = unknown,
+	E = unknown
+> = PendingPromise | ResolvedPromise<T> | RejectedPromise<E>;
+export declare function createPromiseState<
+	T,
+	E
+>(promise: Promise<T> | Awaitable<T, E>): Readonly<PromiseState<T, E>>;
+/**
+* Returns a reactive state-machine for the provided promise or awaitable.
+*
+* Repeat calls to `getPromiseState` with the same promise will return the same state object
+* making is safe and easy to use in templates and JavaScript code to produce reactive
+* behaviors around promises.
+*
+* `getPromiseState` can be used in both JavaScript and Template contexts.
+*
+* ```ts
+* import { getPromiseState } from '@warp-drive/ember';
+*
+* const state = getPromiseState(promise);
+* ```
+*
+* For instance, we could write a getter on a component that updates whenever
+* the promise state advances or the promise changes, by combining the function
+* with the use of `@cached`
+*
+* ```ts
+* class Component {
+*   @cached
+*   get title() {
+*     const state = getPromiseState(this.args.request);
+*     if (state.isPending) {
+*       return 'loading...';
+*     }
+*     if (state.isError) { return null; }
+*     return state.result.title;
+*   }
+* }
+* ```
+*
+* Or in a template as a helper:
+*
+* ```gjs
+* import { getPromiseState } from '@warp-drive/ember';
+*
+* <template>
+*   {{#let (getPromiseState @request) as |state|}}
+*     {{#if state.isPending}} <Spinner />
+*     {{else if state.isError}} <ErrorForm @error={{state.error}} />
+*     {{else}}
+*       <h1>{{state.result.title}}</h1>
+*     {{/if}}
+*   {{/let}}
+* </template>
+* ```
+*
+* If looking to use in a template, consider also the `<Await />` component.
+*
+*/
+export declare function getPromiseState<
+	T = unknown,
+	E = unknown
+>(promise: Promise<T> | Awaitable<T, E>): Readonly<PromiseState<T, E>>;

package/declarations/store/-private/new-core-tmp/reactivity/configure.d.ts

@@ -0,0 +1,176 @@
+export declare const ARRAY_SIGNAL: "___(unique) Symbol(#[])";
+export declare const OBJECT_SIGNAL: "___(unique) Symbol(#{})";
+/**
+* Requirements:
+*
+* Signal:
+*
+* - signal: a way of creating a reference that we can dirty when we desire to notify
+*         - @signal: a way of creating an accessor on an object that subscribes to a signal on access
+*                    and notifies the signal on set, or of upgrading a descriptor to be such an accessor
+*         - defineSignal: a way of creating a signal on an object
+*         - notifySignal: a way of notifying the underlying signal that it has been dirtied
+*         - peekSignal: a way of inspecting the signal without notifying it
+*
+*  - gate: a memoized getter function that re-runs when on access if its signal is dirty
+*          conceptually, a gate is a tightly coupled signal and memo
+*         - @gate: a way of creating a gate on an object or upgrading a descriptor with a getter
+*                  to be a gate
+*         - defineGate: a way of creating a gate on an object
+*         - notifySignal: a way of notifying the signal for a gate that it has been dirtied
+*
+* - memo:
+*        - @memo: a way of creating a memoized getter on an object or upgrading a descriptor with a getter
+*                 to be a memo
+*        - defineMemo: a way of creating a memo on an object
+*
+* - signalStore: storage bucket for signals associated to an object
+*        - withSignalStore: a way of pre-creating a signal store on an object
+*
+*
+* @internal
+*/
+/**
+* An Opaque type that represents a framework specific or TC39 signal.
+*
+* It may be an array of signals or a single signal.
+*
+* @internal
+*/
+export type SignalRef = unknown;
+/**
+* The hooks which MUST be configured in order to use reactive arrays,
+* resources and documents with framework specfic signals or TC39 signals.
+*
+* Support for multiple frameworks simultaneously can be done via
+* this abstraction by returning multiple signals from the `createSignal`
+* method, and consuming the correct one via the correct framework via
+* the `consumeSignal` and `notifySignal` methods.
+*
+* Unlike many signals implementations, WarpDrive does not wrap values as
+* signals directly, but instead uses signals to alert the reactive layer
+* to changes in the underlying cache. E.g. a signal is associated to a value,
+* but does not serve as the cache for that value directly. We refer to this as
+* a "gate", the pattern has also been called "side-signals".
+*
+* A no-op implementation is allowed, though it may lead to performance issues
+* in locations that use createMemo as no memoization would be done. This is
+* typically desirable only when integrating with a framework that does its own
+* memoization and does not integrate with any signals-like primitive. For these
+* scenarios you may also be interested in integrating with the {@link NotificationManager}
+* more directly.
+*
+* @public
+*/
+export interface SignalHooks<T = SignalRef> {
+	/**
+	* Create a signal for the given key associated to the given object.
+	*
+	* This method does *not* need to cache the signal, it will only be
+	* called once for a given object and key. However, if your framework
+	* will look for a signal cache on the object in a given location or may
+	* have created its own signal on the object for some reason it may be
+	* useful to ensure such cache is properly updated.
+	*/
+	createSignal: (obj: object, key: string | symbol) => T;
+	/**
+	* Consume (mark as acccessed) a signal previously created via createSignal.
+	*/
+	consumeSignal: (signal: T) => void;
+	/**
+	* Alert a signal previously created via createSignal that its associated value has changed.
+	*/
+	notifySignal: (signal: T) => void;
+	/**
+	* Take the given function and wrap it in signals-based memoization. Analagous
+	* to a Computed in the TC39 spec.
+	*
+	* Should return a function which when run provides the latest value of the original
+	* function.
+	*/
+	createMemo: <F>(obj: object, key: string | symbol, fn: () => F) => () => F;
+	/**
+	* If the signals implementation allows synchronous flushing of watchers, and
+	* has scheduled such a flush (e.g. watchers will run before the current calling
+	* context yields) this should return "true".
+	*
+	* This is generally something that should return false for anything but the few
+	* frameworks that extensively handle their own reactivity => render scheduling.
+	*
+	* For an example, see EmberJS's backburner scheduler which functioned as a microtask
+	* polyfill.
+	*/
+	willSyncFlushWatchers: () => boolean;
+	/**
+	* An optional method that allows wrapping key promises within WarpDrive
+	* for things like test-waiters.
+	*/
+	waitFor?: <K>(promise: Promise<K>) => Promise<K>;
+}
+/**
+* Contains information a {@link SignalHooks} implementation may want
+* to use, such as the specialized key used for the signal
+* representing an array's contents / length.
+*
+* ```ts
+* interface HooksOptions {
+*   wellknown: {
+*     Array: symbol | string;
+*   }
+* }
+* ```
+*
+* @public
+*/
+export interface HooksOptions {
+	/**
+	* A list of specialized symbols/strings
+	* used by WarpDrive to encapsulate key
+	* reactivity concerns.
+	*/
+	wellknown: {
+		/**
+		* The key used when the signal provides reactivity for the
+		* `length` or "contents" of an array.
+		*
+		* Arrays only use a single signal for all accesses, regardless
+		* of index, property or method: this one.
+		*/
+		Array: symbol | string;
+	};
+}
+/**
+* Configures the signals implementation to use. Supports multiple
+* implementations simultaneously.
+*
+* See {@link HooksOptions} for the options passed to the provided function
+* when called.
+*
+* See {@link SignalHooks} for the implementation the callback function should
+* return.
+*
+* @public
+* @param buildConfig - a function that takes options and returns a configuration object
+*/
+export declare function setupSignals<T>(buildConfig: (options: HooksOptions) => SignalHooks<T>): void;
+/**
+* Internal method for consuming the configured `createSignal` hook
+*
+* @internal
+*/
+export declare function createSignal(obj: object, key: string | symbol): SignalRef;
+/**
+* Internal method for consuming the configured `consumeSignal` hook
+*
+* @internal
+*/
+export declare function consumeSignal(signal: SignalRef): void;
+/**
+* Internal method for consuming the configured `notifySignal` hook
+*
+* @internal
+*/
+export declare function notifySignal(signal: SignalRef): void;
+export declare function createMemo<T>(object: object, key: string | symbol, fn: () => T): () => T;
+export declare function willSyncFlushWatchers(): boolean;
+export declare function waitFor<K>(promise: Promise<K>): Promise<K>;

package/declarations/store/-private/new-core-tmp/reactivity/internal.d.ts

@@ -0,0 +1,169 @@
+import { ARRAY_SIGNAL, OBJECT_SIGNAL, type SignalRef } from "./configure.js";
+export type { SignalRef };
+export { ARRAY_SIGNAL, OBJECT_SIGNAL };
+/**
+* A WarpDriveSignal is a wrapper around a framework specific or TC39 signal
+* that enables us to store and manage the signal in a universal way.
+*
+* WarpDrive uses signals to manage three separate concepts:
+*
+* - as a `storage` for a value local to the object that we want to be reactive
+*   (see `@local` schema field for an example)
+* - as a `gate` for a memoized getter that we want to act as a reactive property
+*   but whose value is computed/pulled from a non-reactive source elsewhere
+*   and whose latest value is stored in the signal
+*   (see `field` schema field for an example)
+* - as a `gate` with a manually managed value updated on pull when `isStale` is true
+*
+*
+* It offers
+*
+* - a non-reactive way to access/update the current value
+* - a non-reactive way to mark the signal as dirtied
+* - a non-reactive way to store content for why the signal was dirtied
+* - access to the underlying Signal(s) in-use
+*
+* For debugging:
+* - the "key" or "name" of the signal
+* - the "object identity" or "context" to which the signal is attached
+*
+* @internal
+*/
+export interface WarpDriveSignal {
+	/**
+	* The "key" or "name" of the signal.
+	* This is usually (but not always) the name of a property
+	* on the object to which the signal is attached.
+	*
+	* This is used for debugging purposes.
+	* It is not used for any other purpose.
+	*
+	* @internal
+	*/
+	key: string | symbol;
+	/**
+	* The "object identity" or "context" to which the
+	* signal is attached.
+	*
+	* This is used for debugging purposes.
+	* It is not used for any other purpose.
+	*
+	* @internal
+	*/
+	context: object;
+	/**
+	* The underlying signal(s) in-use.
+	*
+	* Generally, this is a single signal.
+	*
+	* In some cases multiple signals need to be condensed,
+	* such as to support legacy Ember Array APIs or to
+	* support reactive-objects shared between the code of
+	* multiple frameworks.
+	*
+	* In such cases, this value may be an array.
+	*
+	* e.g. (pseudo-code for Ember):
+	*
+	* setupSignals({
+	*   createSignal: (obj, key, initialValue) => {
+	*     if (isArraySignal(key)) {
+	*       return [
+	*         tagForProperty(obj, key),
+	*         tagForProperty(obj, '[]'),
+	*         tagForProperty(obj, 'length'),
+	*       ];
+	*     }
+	*     return tagForProperty(obj, key);
+	*   },
+	*
+	*   consumeSignal: (signal) => {
+	*     if (Array.isArray(signal)) {
+	*       signal.forEach((s) => consumeTag(s));
+	*     } else {
+	*       consumeTag(signal);
+	*     }
+	*   },
+	*
+	*   dirtySignal: (signal) => {
+	*     if (Array.isArray(signal)) {
+	*       signal.forEach((s) => dirtyTag(s));
+	*     } else {
+	*       dirtyTag(signal);
+	*     }
+	*   },
+	* });
+	*
+	* @internal
+	*/
+	signal: SignalRef;
+	/**
+	* The last "value" computed for this signal when
+	* a signal is also used for storage.
+	*
+	* @internal
+	*/
+	value: unknown;
+	/**
+	* Whether ths signal is known to have been dirtied.
+	* This is useful *both* when manually managing the
+	* `value` cache and when using the signal as a
+	* "gate"
+	*
+	* @internal
+	*/
+	isStale: boolean;
+}
+/**
+* We attach signals to their context object via
+* a Map attached to the object via this symbol.
+*
+* This allows us to store multiple signals
+* on the same object with smaller memory
+* overhead and no WeakMap lookups.
+*
+* Performance sensitive objects should
+* pre-warm their shape by assigning this
+* during initialization.
+*
+* ```ts
+* initializeSignalStore(obj);
+* ```
+*
+* @internal
+*/
+export declare const Signals: "___(unique) Symbol(Signals)";
+export type SignalStore = Map<string | symbol, WarpDriveSignal>;
+/**
+* A type util to recast the object as having a signal store.
+*
+* @internal
+*/
+export declare function upgradeWithSignals<T extends object>(obj: T): asserts obj is T & {
+	[Signals]: SignalStore;
+};
+/**
+* A util that will create a signal store on the object
+* if it does not already exist and returns the associated
+* signal store.
+*
+* @internal
+*/
+export declare function withSignalStore<T extends object>(obj: T): SignalStore;
+/**
+* A util that will create a signal store on the object
+* if it does not already exist.
+*
+* Useful for pre-warming the shape of an object to ensure
+* a key-transition to add it is not required later.
+*
+* @internal
+*/
+export declare function initializeSignalStore<T extends object>(obj: T): asserts obj is T & {
+	[Signals]: SignalStore;
+};
+export declare function createInternalSignal(signals: SignalStore, obj: object, key: string | symbol, initialValue: unknown): WarpDriveSignal;
+export declare function getOrCreateInternalSignal(signals: SignalStore, obj: object, key: string | symbol, initialValue: unknown): WarpDriveSignal;
+export declare function peekInternalSignal(signals: SignalStore | undefined, key: string | symbol): WarpDriveSignal | undefined;
+export declare function consumeInternalSignal(signal: WarpDriveSignal): void;
+export declare function notifyInternalSignal(signal: WarpDriveSignal | undefined): void;