@warp-drive-mirror/core 5.9.0-alpha.2 → 5.9.0-alpha.21

package/declarations/signals/reactivity/internal.d.ts

@@ -1,154 +0,0 @@
-import { ARRAY_SIGNAL, OBJECT_SIGNAL, type SignalRef } from "./configure.js";
-export type { SignalRef };
-export { ARRAY_SIGNAL, OBJECT_SIGNAL };
-interface Initializer {
-	value: () => unknown;
-}
-export declare function makeInitializer(fn: () => unknown): Initializer;
-/**
-* 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
-*
-* @private
-*/
-export interface WarpDriveSignal {
-	/**
-	* 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);
-	*     }
-	*   },
-	* });
-	*
-	* @private
-	*/
-	signal: SignalRef;
-	/**
-	* The last "value" computed for this signal when
-	* a signal is also used for storage.
-	*
-	* @private
-	*/
-	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"
-	*
-	* @private
-	*/
-	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);
-* ```
-*
-* @private
-*/
-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.
-*
-* @private
-*/
-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.
-*
-* @private
-*/
-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.
-*
-* @private
-*/
-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 createInternalMemo<T>(signals: SignalStore, object: object, key: string | symbol, fn: () => T): () => T;
-export declare function consumeInternalMemo<T>(fn: () => T): T;
-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;

package/declarations/signals/reactivity/signal.d.ts

@@ -1,56 +0,0 @@
-import type { SignalStore, WarpDriveSignal } from "./internal.js";
-/**
-* Creates a signal for the key/object pairing and subscribes to the signal.
-*
-* Use when you need to ensure a signal exists and is subscribed to.
-*
-* @private
-*/
-export declare function entangleSignal<T extends object>(signals: SignalStore, obj: T, key: string | symbol, initialValue: unknown): WarpDriveSignal;
-export declare function entangleInitiallyStaleSignal<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.
-*
-* Akin to Object.defineProperty.
-*
-* The signal will be lazily created when accessed and scoped to the
-* instance of the object.
-*
-* @private
-*/
-export declare function defineSignal<T extends object>(obj: T, key: string, v?: unknown): void;
-/**
-* Define a non-enumerable signal property.
-*
-* @private
-*/
-export declare function defineNonEnumerableSignal<T extends object>(obj: T, key: string, v?: unknown): void;
-interface DecoratorPropertyDescriptor extends PropertyDescriptor {
-	initializer?: () => unknown;
-}
-/**
-* Decorator version of creating a signal.
-*/
-export declare function signal<
-	T extends object,
-	K extends keyof T & string
->(target: T, key: K, descriptor?: DecoratorPropertyDescriptor): void;
-/**
-* Decorator version of creating a memoized getter
-*/
-export declare function memoized<
-	T extends object,
-	K extends keyof T & string
->(target: T, key: K, descriptor: PropertyDescriptor): PropertyDescriptor;
-/**
-* Decorator version of creating a gate.
-*
-* @private
-*/
-export declare function gate<
-	T extends object,
-	K extends keyof T & string
->(_target: T, key: K, desc: PropertyDescriptor): PropertyDescriptor;
-export declare function defineGate<T extends object>(obj: T, key: string, desc: PropertyDescriptor): void;
-export {};

package/declarations/signals/request-state.d.ts

@@ -1,372 +0,0 @@
-import type { Future } from "../request.js";
-import type { ImmutableRequestInfo, ResponseInfo, StructuredErrorDocument } from "../types/request.js";
-import type { PendingPromise, RejectedPromise, ResolvedPromise } from "./promise-state.js";
-/**
-* Lazily consumes the stream of a request, providing a number of
-* reactive properties that can be used to build UIs that respond
-* to the progress of a request.
-*
-* @hideconstructor
-*/
-export declare class RequestLoadingState {
-	promise: Promise<void> | null;
-	get isPending(): boolean;
-	get sizeHint(): number;
-	get stream(): ReadableStream | null;
-	get isStarted(): boolean;
-	get bytesLoaded(): number;
-	get startTime(): number;
-	get endTime(): number;
-	get lastPacketTime(): number;
-	get isComplete(): boolean;
-	get isCancelled(): boolean;
-	get isErrored(): boolean;
-	get error(): Error | null;
-	get elapsedTime(): number;
-	get completedRatio(): number;
-	get remainingRatio(): number;
-	get duration(): number;
-	get speed(): number;
-	constructor(future: Future<unknown>);
-	abort: () => void;
-}
-/**
-* The state of a request in the "pending"
-* state. This is the default initial state.
-*
-* Extends the {@link PendingPromise} interface.
-*
-*/
-export interface PendingRequest extends PendingPromise {
-	/**
-	* Whether the request is cancelled.
-	*
-	*/
-	isCancelled: false;
-	loadingState: RequestLoadingState;
-	request: null;
-	response: null;
-}
-/**
-* The state of a request in the "fulfilled" state.
-* This is the state of a request that has resolved
-* successfully.
-*
-* Extends the {@link ResolvedPromise} interface.
-*
-*/
-export interface ResolvedRequest<RT> extends ResolvedPromise<RT> {
-	/**
-	* Retries the request with high (blocking) priority. This is the
-	* same as having passed `cacheOptions.reload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	reload(): Future<RT>;
-	/**
-	* Retries the request with low (non-blocking) priority. This is the
-	* same as having passed `cacheOptions.backgroundReload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	refresh(usePolicy?: boolean): Future<RT>;
-	/**
-	* Whether the request is cancelled.
-	*
-	*/
-	isCancelled: false;
-	/**
-	* A lazily created {@link RequestLoadingState} instance
-	* which provides a number of reactive properties that can be used
-	* to build UIs that respond to the progress of a request.
-	*/
-	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT> | null;
-	response: Response | ResponseInfo | null;
-}
-/**
-* The state of a request in the "rejected" state.
-* This is the state of a request that has rejected
-* with an error.
-*
-* Extends the {@link RejectedPromise} interface.
-*
-*/
-export interface RejectedRequest<
-	RT,
-	E extends StructuredErrorDocument = StructuredErrorDocument
-> extends RejectedPromise<E> {
-	/**
-	* Retries the request with high (blocking) priority. This is the
-	* same as having passed `cacheOptions.reload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	reload(): Future<RT>;
-	/**
-	* Retries the request with low (non-blocking) priority. This is the
-	* same as having passed `cacheOptions.backgroundReload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	refresh(usePolicy?: boolean): Future<RT>;
-	/**
-	* Whether the request is cancelled.
-	*
-	*/
-	isCancelled: false;
-	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT> | null;
-	response: Response | ResponseInfo | null;
-}
-/**
-* The state of a request in the "cancelled" state.
-* This is the state of a promise that has been
-* cancelled.
-*
-*/
-export interface CancelledRequest<
-	RT,
-	E extends StructuredErrorDocument = StructuredErrorDocument
-> {
-	/**
-	* Retries the request with high (blocking) priority. This is the
-	* same as having passed `cacheOptions.reload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	reload(): Future<RT>;
-	/**
-	* Retries the request with low (non-blocking) priority. This is the
-	* same as having passed `cacheOptions.backgroundReload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	refresh(usePolicy?: boolean): Future<RT>;
-	/**
-	* The status of the request.
-	*
-	*/
-	status: "cancelled";
-	/**
-	* Whether the request is pending.
-	*
-	*/
-	isPending: false;
-	/**
-	* Whether the request is pending.
-	*
-	*/
-	isLoading: false;
-	/**
-	* Whether the request has resolved
-	* successfully.
-	*
-	*/
-	isSuccess: false;
-	/**
-	* Whether the request has rejected
-	* with an error.
-	*
-	*/
-	isError: true;
-	/**
-	* Once the request has resolved, this will
-	* be the value the request resolved to.
-	*
-	*/
-	value: null;
-	/**
-	* Once the request has resolved, this will
-	* be the value the request resolved to.
-	*
-	* @deprecated use `value` instead
-	*/
-	result: null;
-	/**
-	* Once the request has rejected, this will
-	* be the error the request rejected with.
-	*
-	*
-	* @deprecated use `reason` instead
-	*/
-	error: E;
-	/**
-	* Once the request has rejected, this will
-	* be the error the request rejected with.
-	*
-	*/
-	reason: E;
-	/**
-	* Whether the request is cancelled.
-	*
-	*/
-	isCancelled: true;
-	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT> | null;
-	response: Response | ResponseInfo | null;
-}
-export interface PrivateRequestState {
-	_loadingState?: RequestLoadingState;
-	_request: Future<unknown>;
-}
-/**
-* 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 {@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: RequestKey | null;
-* }
-* ```
-*
-* These additional APIs allow us to craft even richer state experiences.
-*
-* To get the state of a request, use {@link getRequestState}.
-*
-* See also:
-* - {@link PendingRequest}
-* - {@link ResolvedRequest}
-* - {@link RejectedRequest}
-* - {@link CancelledRequest}
-*
-*/
-export type RequestState<
-	RT = unknown,
-	E extends StructuredErrorDocument = StructuredErrorDocument
-> = PendingRequest | ResolvedRequest<RT> | RejectedRequest<RT, E> | CancelledRequest<RT, E>;
-export declare function createRequestState<
-	RT,
-	E
->(future: Future<RT>): Readonly<RequestState<RT, StructuredErrorDocument<E>>>;
-/**
-* `getRequestState` can be used in both JavaScript and Template contexts.
-*
-* ```ts
-* import { getRequestState } from '@warp-drive-mirror/ember';
-*
-* const state = getRequestState(future);
-* ```
-*
-* For instance, we could write a getter on a component that updates whenever
-* the request state advances or the future changes, by combining the function
-* with the use of `@cached`
-*
-* ```ts
-* class Component {
-*   @cached
-*   get title() {
-*     const state = getRequestState(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 { getRequestState } from '@warp-drive-mirror/ember';
-*
-* <template>
-*   {{#let (getRequestState @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 `<Request />` component
-* which offers a number of additional capabilities for requests *beyond* what
-* `RequestState` provides.
-*
-*/
-export declare function getRequestState<
-	RT,
-	E
->(future: Future<RT>): Readonly<RequestState<RT, StructuredErrorDocument<E>>>;