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

package/declarations/request/-private/types.d.ts

@@ -1,234 +0,0 @@
-import type { Store } from "../../store/-private.js";
-import type { RequestKey } from "../../types/identifier.js";
-import type { RequestContext, RequestInfo, ResponseInfo, StructuredDataDocument } from "../../types/request.js";
-import type { RequestManager } from "./manager.js";
-export interface GodContext {
-	controller: AbortController;
-	response: ResponseInfo | null;
-	stream: ReadableStream | Promise<ReadableStream | null> | null;
-	hasRequestedStream: boolean;
-	id: number;
-	identifier: RequestKey | null;
-	requester: RequestManager | Store;
-}
-export type Deferred<T> = {
-	resolve(v: T): void;
-	reject(v: unknown): void;
-	promise: Promise<T>;
-};
-export type ManagedRequestPriority = {
-	blocking: boolean;
-};
-export type DeferredStream = {
-	resolve(v: ReadableStream | null): void;
-	reject(v: unknown): void;
-	promise: Promise<ReadableStream | null> & {
-		sizeHint?: number;
-	};
-};
-/**
-* A Future is a {@link Promise} which resolves or rejects with a {@link StructuredDocument}
-* while providing the ability to {@link Future.abort | abort} the underlying request, and
-* {@link Future.getStream | access the response stream} before the outer promise resolves;
-*
-* @public
-*/
-export interface Future<T> extends Promise<StructuredDataDocument<T>> {
-	/**
-	* Cancel this request by firing the {@link AbortController}'s signal.
-	*
-	* This method can be used as an action or event handler as its
-	* context is bound to the Future instance.
-	*
-	* @privateRemarks
-	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/abort)
-	*
-	* @param reason optional reason for aborting the request
-	* @public
-	*/
-	abort(reason?: string): void;
-	/**
-	* Get the response stream, if any, once made available.
-	*
-	* This method can be used as an action or event handler as its
-	* context is bound to the Future instance.
-	*
-	* @public
-	*/
-	getStream(): Promise<ReadableStream | null>;
-	/**
-	*  Run a callback when this request completes. Use sparingly,
-	*  mostly useful for instrumentation and infrastructure.
-	*
-	* @param cb the callback to run
-	*/
-	onFinalize(cb: () => void): void;
-	/**
-	* The identifier of the associated request, if any, as
-	* assigned by the CacheHandler.
-	*/
-	lid: RequestKey | null;
-	/**
-	* The id of the associated request, if any, as assigned
-	* by the RequestManager
-	*
-	* This is not unique across Manager instances and cannot
-	* be used to identify or dedupe requests.
-	*/
-	id: number;
-	/**
-	* The RequestManager or Store that initiated this request.
-	*
-	* @private
-	*/
-	requester: RequestManager | Store;
-}
-export type DeferredFuture<T> = {
-	resolve(v: StructuredDataDocument<T>): void;
-	reject(v: unknown): void;
-	promise: Future<T>;
-};
-export type NextFn<P = unknown> = (req: RequestInfo) => Future<P>;
-/**
-* Requests are fulfilled by handlers. A handler receives the request context
-as well as a `next` function with which to pass along a request to the next
-handler if it so chooses.
-
-A handler may be any object with a `request` method. This allows both stateful and non-stateful
-handlers to be utilized.
-
-If a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`
-that it can then compose how it sees fit with its own response.
-
-```ts
-type NextFn<P> = (req: RequestInfo) => Future<P>;
-
-interface Handler {
-async request<T>(context: RequestContext, next: NextFn<P>): T;
-}
-```
-
-`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.
-
-```ts
-interface RequestContext<T> {
-readonly request: RequestInfo;
-
-setStream(stream: ReadableStream | Promise<ReadableStream>): void;
-setResponse(response: Response | ResponseInfo): void;
-}
-```
-
-A basic `fetch` handler with support for streaming content updates while
-the download is still underway might look like the following, where we use
-[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.
-
-A more efficient handler might read from the response stream, building up the
-response content before passing along the chunk downstream.
-
-```ts
-const FetchHandler = {
-async request(context) {
-const response = await fetch(context.request);
-context.setResponse(reponse);
-context.setStream(response.clone().body);
-
-return response.json();
-}
-}
-```
-
-### Stream Currying
-
-`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.
-
-For context, it helps to understand a few of the use-cases that RequestManager
-is intended to allow.
-
-- to manage and return streaming content (such as video files)
-- to fulfill a request from multiple sources or by splitting one request into multiple requests
-- for instance one API call for a user and another for the user's friends
-- or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB etc.) and the rest from another source (a different API, a WebWorker, etc.)
-- to coalesce multiple requests
-- to decorate a request with additional info
-- e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.
-
-----
-
-`await fetch(<req>)` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application
-code *while chunks are still being received by the browser*.
-
-When an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.
-
-The `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.
-
-Each handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method
-has not been called by the time that the handler's request method has resolved.
-
-Handlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.
-
-```ts
-context.setStream(future.getStream());
-```
-
-Handlers that either call `next` multiple times or otherwise have reason to create multiple  fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.
-
-Of course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.
-
-### Automatic Currying of Stream and Response
-
-In order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next(<req>)).content;`.
-
-Similarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.
-
-Finally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next(<req>)`.
-
-In the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.
-
-### Handler Order
-
-Request handlers are registered by configuring the manager via `use`
-
-```ts
-const manager = new RequestManager()
-.use([Handler1, Handler2]);
-```
-
-Handlers will be invoked in the order they are registered ("fifo", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.
-
-@public
-*/
-export interface Handler {
-	/**
-	* Method to implement to handle requests. Receives the request
-	* context and a nextFn to call to pass-along the request to
-	* other handlers.
-	*
-	* @public
-	*/
-	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T>;
-}
-/**
-* The CacheHandler is identical to other handlers except that it
-* is allowed to return a value synchronously. This is useful for
-* features like reducing microtask queueing when de-duping.
-*
-* A RequestManager may only have one CacheHandler, registered via
-* `manager.useCache(CacheHandler)`.
-*
-* @public
-*/
-export interface CacheHandler {
-	/**
-	* Method to implement to handle requests. Receives the request
-	* context and a nextFn to call to pass-along the request to
-	* other handlers.
-	*
-	* @public
-	*/
-	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> | T;
-}
-export interface RequestResponse<T> {
-	result: T;
-}
-export type GenericCreateArgs = Record<string | symbol, unknown>;

package/declarations/request/-private/utils.d.ts

@@ -1,57 +0,0 @@
-import type { RequestInfo, StructuredDataDocument } from "../../types/request.js";
-import { ContextOwner } from "./context.js";
-import type { DeferredFuture, Future, GodContext, Handler } from "./types.js";
-export declare const IS_CACHE_HANDLER: "___(unique) Symbol(IS_CACHE_HANDLER)";
-export declare function curryFuture<T>(owner: ContextOwner, inbound: Future<T>, outbound: DeferredFuture<T>): Future<T>;
-/**
-* Additional properties exposed on errors thrown by the
-* {@link Fetch | Fetch Handler}.
-*
-* In the case of an Abort or system/browser level issue,
-* this extends {@link DOMException}.
-*
-* Else it extends from {@link AggregateError} if the
-* response includes an array of errors, falling back
-* to {@link Error} as its base.
-*/
-export interface FetchError extends DOMException {
-	/**
-	* Alias for {@link FetchError.status | status}.
-	*
-	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/status)
-	*/
-	code: number;
-	/**
-	* The name associated to the {@link FetchError.status | status code}.
-	*
-	* Typically this will be of the formula `StatusTextError` for instance
-	* a 404 status with status text of `Not Found` would have the name
-	* `NotFoundError`.
-	*/
-	name: string;
-	/**
-	* The http status code associated to the returned error.
-	*
-	* Browser/System level network errors will often have an error code of `0` or `5`.
-	* Aborted requests will have an error code of `20`.
-	*
-	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/status)
-	*/
-	status: number;
-	/**
-	* The Status Text associated to the {@link FetchError.status | status code}
-	* for the error.
-	*
-	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/statusText)
-	*
-	*/
-	statusText: string;
-	/**
-	* A property signifying that an Error uses the {@link FetchError}
-	* interface.
-	*/
-	isRequestError: true;
-}
-export declare function enhanceReason(reason?: string): DOMException;
-export declare function handleOutcome<T>(owner: ContextOwner, inbound: Promise<T | StructuredDataDocument<T>>, outbound: DeferredFuture<T>): Future<T>;
-export declare function executeNextHandler<T>(wares: Readonly<Handler[]>, request: RequestInfo, i: number, god: GodContext): Future<T>;

package/declarations/signals/-private.d.ts

@@ -1,6 +0,0 @@
-export { DISPOSE, createRequestSubscription, type RequestArgs, type SubscriptionArgs, type RequestComponentArgs, type RequestSubscription, type ContentFeatures, type RecoveryFeatures, type AutorefreshBehaviorCombos, type AutorefreshBehaviorType } from "./request-subscription.js";
-export { getRequestState, type RequestLoadingState, type RequestState } from "./request-state.js";
-export { getPromiseState, type PromiseState, type ResolvedPromise, type RejectedPromise, type PendingPromise } from "./promise-state.js";
-export { setupSignals, type HooksOptions, type SignalHooks, waitFor, willSyncFlushWatchers } from "./reactivity/configure.js";
-export { signal, memoized, gate, entangleSignal, entangleInitiallyStaleSignal, defineSignal, defineGate, defineNonEnumerableSignal, createSignalDescriptor } from "./reactivity/signal.js";
-export { type SignalStore, ARRAY_SIGNAL, OBJECT_SIGNAL, Signals, type WarpDriveSignal, peekInternalSignal, createInternalMemo, withSignalStore, notifyInternalSignal, consumeInternalSignal, getOrCreateInternalSignal, createInternalSignal } from "./reactivity/internal.js";

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

@@ -1,264 +0,0 @@
-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-mirror/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-mirror/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.
-*
-* See also {@link PromiseState}
-*/
-export declare function getPromiseState<
-	T = unknown,
-	E = unknown
->(promise: Promise<T> | Awaitable<T, E>): Readonly<PromiseState<T, E>>;

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

@@ -1,138 +0,0 @@
-export declare const ARRAY_SIGNAL: "___(unique) Symbol(#[])";
-export declare const OBJECT_SIGNAL: "___(unique) Symbol(#{})";
-/**
-* 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
-*
-* @private
-*/
-export declare function createSignal(obj: object, key: string | symbol): SignalRef;
-/**
-* Internal method for consuming the configured `consumeSignal` hook
-*
-* @private
-*/
-export declare function consumeSignal(signal: SignalRef): void;
-/**
-* Internal method for consuming the configured `notifySignal` hook
-*
-* @private
-*/
-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>;