@warp-drive/core 5.7.0-alpha.3 → 5.7.0-alpha.30

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

@@ -0,0 +1,24 @@
+import type { RequestKey } from "../../../types/identifier.js";
+import type { Store } from "../store-service.js";
+/**
+* Creates an {@link ExpensiveSubscription} for the {@link RequestKey}
+* if one does not already exist and adds a watcher to it.
+*
+* Returns a cleanup function. This should be called on-mount by a component
+* that wants to subscribe to a request and cleanup should be called on dismount.
+*
+* ::: warning ⚠️ Avoid Using If Your App Supports Fine-grained Reactivity
+* This mechanism should never be used by frameworks or libraries
+* that support fine-grained reactivity.
+* :::
+*
+* `ExpensiveSubscription` is a mechanism for non-reactive
+* frameworks such as `react` to integrate with WarpDrive, for instance
+* by treating a request as an [external store](https://react.dev/reference/react/useSyncExternalStore)
+*
+* `ExpensiveSubscription` is expensive *because* it doubles the number
+* of notification callbacks required for each resource contained in
+* the request being subscribed to. The more requests in-use, the more
+* this cost adds up.
+*/
+export declare function getExpensiveRequestSubscription(store: Store, requestKey: RequestKey, callback: () => void): () => void;

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

@@ -1,44 +1,6 @@
 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.
 *
@@ -156,19 +118,19 @@ export declare function setupSignals<T>(buildConfig: (options: HooksOptions) =>
 /**
 * Internal method for consuming the configured `createSignal` hook
 *
-* @internal
+* @private
 */
 export declare function createSignal(obj: object, key: string | symbol): SignalRef;
 /**
 * Internal method for consuming the configured `consumeSignal` hook
 *
-* @internal
+* @private
 */
 export declare function consumeSignal(signal: SignalRef): void;
 /**
 * Internal method for consuming the configured `notifySignal` hook
 *
-* @internal
+* @private
 */
 export declare function notifySignal(signal: SignalRef): void;
 export declare function createMemo<T>(object: object, key: string | symbol, fn: () => T): () => T;

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

@@ -1,6 +1,10 @@
 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.
@@ -27,30 +31,9 @@ export { ARRAY_SIGNAL, OBJECT_SIGNAL };
 * - the "key" or "name" of the signal
 * - the "object identity" or "context" to which the signal is attached
 *
-* @internal
+* @private
 */
 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.
 	*
@@ -94,14 +77,14 @@ export interface WarpDriveSignal {
 	*   },
 	* });
 	*
-	* @internal
+	* @private
 	*/
 	signal: SignalRef;
 	/**
 	* The last "value" computed for this signal when
 	* a signal is also used for storage.
 	*
-	* @internal
+	* @private
 	*/
 	value: unknown;
 	/**
@@ -110,7 +93,7 @@ export interface WarpDriveSignal {
 	* `value` cache and when using the signal as a
 	* "gate"
 	*
-	* @internal
+	* @private
 	*/
 	isStale: boolean;
 }
@@ -130,14 +113,14 @@ export interface WarpDriveSignal {
 * initializeSignalStore(obj);
 * ```
 *
-* @internal
+* @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.
 *
-* @internal
+* @private
 */
 export declare function upgradeWithSignals<T extends object>(obj: T): asserts obj is T & {
 	[Signals]: SignalStore;
@@ -147,7 +130,7 @@ export declare function upgradeWithSignals<T extends object>(obj: T): asserts ob
 * if it does not already exist and returns the associated
 * signal store.
 *
-* @internal
+* @private
 */
 export declare function withSignalStore<T extends object>(obj: T): SignalStore;
 /**
@@ -157,7 +140,7 @@ export declare function withSignalStore<T extends object>(obj: T): SignalStore;
 * Useful for pre-warming the shape of an object to ensure
 * a key-transition to add it is not required later.
 *
-* @internal
+* @private
 */
 export declare function initializeSignalStore<T extends object>(obj: T): asserts obj is T & {
 	[Signals]: SignalStore;

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

@@ -4,9 +4,10 @@ import type { SignalStore, WarpDriveSignal } from "./internal.js";
 *
 * Use when you need to ensure a signal exists and is subscribed to.
 *
-* @internal
+* @private
 */
 export declare function entangleSignal<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.
 *
@@ -15,21 +16,40 @@ export declare function entangleSignal<T extends object>(signals: SignalStore, o
 * The signal will be lazily created when accessed and scoped to the
 * instance of the object.
 *
-* @internal
+* @private
 */
 export declare function defineSignal<T extends object>(obj: T, key: string, v?: unknown): void;
 /**
 * Define a non-enumerable signal property.
 *
-* @internal
+* @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/store/-private/new-core-tmp/request-state.d.ts

@@ -1,11 +1,13 @@
 import type { Future } from "../../../request.js";
 import type { ImmutableRequestInfo, ResponseInfo, StructuredErrorDocument } from "../../../types/request.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 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 {
 	private _sizeHint;
@@ -69,17 +71,55 @@ export interface PendingRequest extends PendingPromise {
 * Extends the {@link ResolvedPromise} interface.
 *
 */
-export interface ResolvedRequest<
-	RT,
-	T
-> extends ResolvedPromise<RT> {
+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, T> | null;
+	request: ImmutableRequestInfo<RT> | null;
 	response: Response | ResponseInfo | null;
 }
 /**
@@ -92,16 +132,51 @@ export interface ResolvedRequest<
 */
 export interface RejectedRequest<
 	RT,
-	T,
 	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, T> | null;
+	request: ImmutableRequestInfo<RT> | null;
 	response: Response | ResponseInfo | null;
 }
 /**
@@ -112,9 +187,44 @@ export interface RejectedRequest<
 */
 export interface CancelledRequest<
 	RT,
-	T,
 	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.
 	*
@@ -175,33 +285,33 @@ export interface CancelledRequest<
 	*/
 	isCancelled: true;
 	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT, T> | null;
+	request: ImmutableRequestInfo<RT> | null;
 	response: Response | ResponseInfo | null;
 }
 /**
-* RequestState extends the concept of PromiseState to provide a reactive
-* wrapper for a request `Future` which allows you write declarative code
+* 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 Promise and a Future is that Futures provide
-* access to a stream of their content, the identity of the request (if any)
-* as well as the ability to attempt to abort the request.
+* 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: StableDocumentIdentifier | null;
+*   lid: RequestKey | null;
 * }
 * ```
 *
 * These additional APIs allow us to craft even richer state experiences.
 *
-* To get the state of a request, use `getRequestState`.
+* To get the state of a request, use {@link getRequestState}.
 *
 * See also:
 * - {@link PendingRequest}
@@ -212,14 +322,12 @@ export interface CancelledRequest<
 */
 export type RequestCacheRequestState<
 	RT = unknown,
-	T = unknown,
 	E extends StructuredErrorDocument = StructuredErrorDocument
-> = PendingRequest | ResolvedRequest<RT, T> | RejectedRequest<RT, T, E> | CancelledRequest<RT, T, E>;
+> = PendingRequest | ResolvedRequest<RT> | RejectedRequest<RT, E> | CancelledRequest<RT, E>;
 export declare function createRequestState<
 	RT,
-	T,
 	E
->(future: Future<RT>): Readonly<RequestCacheRequestState<RT, T, StructuredErrorDocument<E>>>;
+>(future: Future<RT>): Readonly<RequestCacheRequestState<RT, StructuredErrorDocument<E>>>;
 /**
 * `getRequestState` can be used in both JavaScript and Template contexts.
 *
@@ -272,6 +380,5 @@ export declare function createRequestState<
 */
 export declare function getRequestState<
 	RT,
-	T,
 	E
->(future: Future<RT>): Readonly<RequestCacheRequestState<RT, T, StructuredErrorDocument<E>>>;
+>(future: Future<RT>): Readonly<RequestCacheRequestState<RT, StructuredErrorDocument<E>>>;