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

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

@@ -1,135 +1,162 @@
-import type { StableDocumentIdentifier } from '../../types/identifier';
-import type { RequestInfo } from '../../types/request';
-import type { CacheHandler, Future, GenericCreateArgs, Handler, ManagedRequestPriority } from './types';
-import { IS_CACHE_HANDLER } from './utils';
+import type { StableDocumentIdentifier } from "../../types/identifier.js";
+import type { RequestInfo } from "../../types/request.js";
+import type { CacheHandler, Future, GenericCreateArgs, Handler, ManagedRequestPriority } from "./types.js";
+import { IS_CACHE_HANDLER } from "./utils.js";
 /**
- * ```js
- * import RequestManager from '@ember-data/request';
- * ```
- *
- * A RequestManager provides a request/response flow in which configured
- * handlers are successively given the opportunity to handle, modify, or
- * pass-along a request.
- *
- * ```ts
- * interface RequestManager {
- *   request<T>(req: RequestInfo): Future<T>;
- * }
- * ```
- *
- * For example:
- *
- * ```ts
- * import RequestManager from '@ember-data/request';
- * import Fetch from '@ember-data/request/fetch';
- * import Auth from 'ember-simple-auth/ember-data-handler';
- * import Config from './config';
- *
- * const { apiUrl } = Config;
- *
- * // ... create manager
- * const manager = new RequestManager().use([Auth, Fetch]);
- *
- * // ... execute a request
- * const response = await manager.request({
- *   url: `${apiUrl}/users`
- * });
- * ```
- *
- * ### Futures
- *
- * The return value of `manager.request` is a `Future`, which allows
- * access to limited information about the request while it is still
- * pending and fulfills with the final state when the request completes.
- *
- * A `Future` is cancellable via `abort`.
- *
- * Handlers may optionally expose a `ReadableStream` to the `Future` for
- * streaming data; however, when doing so the future should not resolve
- * until the response stream is fully read.
- *
- * ```ts
- * interface Future<T> extends Promise<StructuredDocument<T>> {
- *   abort(): void;
- *
- *   async getStream(): ReadableStream | null;
- * }
- * ```
- *
- * ### StructuredDocuments
- *
- * A Future resolves with a `StructuredDataDocument` or rejects with a `StructuredErrorDocument`.
- *
- * ```ts
- * interface StructuredDataDocument<T> {
- *   request: ImmutableRequestInfo;
- *   response: ImmutableResponseInfo;
- *   content: T;
- * }
- * interface StructuredErrorDocument extends Error {
- *   request: ImmutableRequestInfo;
- *   response: ImmutableResponseInfo;
- *   error: string | object;
- * }
- * type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;
- * ```
- *
- * @class RequestManager
- * @public
- */
+* ## Import
+*
+* ```js
+* import { RequestManager } from '@warp-drive/core';
+* ```
+*
+* For complete usage guide see the [RequestManager Documentation](/guides/).
+*
+* ## How It Works
+*
+* ```ts
+* interface RequestManager {
+*   request<T>(req: RequestInfo): Future<T>;
+* }
+* ```
+*
+* A RequestManager provides a request/response flow in which configured
+* handlers are successively given the opportunity to handle, modify, or
+* pass-along a request.
+*
+* <img src="/images/handlers-all-labeled.gif" alt="RequestManager Flow Animation" width="100%" />
+*
+* For example:
+*
+* ::: code-group
+*
+* ```ts [Setup.ts]
+* import { RequestManager, Fetch } from '@warp-drive/core';
+* import { AutoCompress } from '@warp-drive/utilities/handlers';
+* import Auth from 'ember-simple-auth/handler';
+*
+* // ... create manager
+* const manager = new RequestManager()
+*    .use([Auth, new AutoCompress(), Fetch]); // [!code focus]
+* ```
+*
+* ```ts [Usage.ts]
+* import Config from './config';
+*
+* const { apiUrl } = Config;
+*
+* // ... execute a request
+* const response = await manager.request({
+*   url: `${apiUrl}/users`
+* });
+* ```
+*
+* :::
+*
+* ### Futures
+*
+* The return value of `manager.request` is a `Future`, which allows
+* access to limited information about the request while it is still
+* pending and fulfills with the final state when the request completes.
+*
+* A `Future` is cancellable via `abort`.
+*
+* Handlers may optionally expose a `ReadableStream` to the `Future` for
+* streaming data; however, when doing so the future should not resolve
+* until the response stream is fully read.
+*
+* ```ts
+* interface Future<T> extends Promise<StructuredDocument<T>> {
+*   abort(): void;
+*
+*   async getStream(): ReadableStream | null;
+* }
+* ```
+*
+* ### StructuredDocuments
+*
+* A Future resolves with a `StructuredDataDocument` or rejects with a `StructuredErrorDocument`.
+*
+* ```ts
+* interface StructuredDataDocument<T> {
+*   request: ImmutableRequestInfo;
+*   response: ImmutableResponseInfo;
+*   content: T;
+* }
+* interface StructuredErrorDocument extends Error {
+*   request: ImmutableRequestInfo;
+*   response: ImmutableResponseInfo;
+*   error: string | object;
+* }
+* type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;
+* ```
+*
+* @class RequestManager
+* @public
+*/
 export declare class RequestManager {
-    #private;
-    _hasCacheHandler: boolean;
-    /**
-     * A map of pending requests from request.id to their
-     * associated CacheHandler promise.
-     *
-     * This queue is managed by the CacheHandler
-     *
-     * @internal
-     */
-    _pending: Map<number, Promise<unknown>>;
-    _deduped: Map<StableDocumentIdentifier, {
-        priority: ManagedRequestPriority;
-        promise: Promise<unknown>;
-    }>;
-    constructor(options?: GenericCreateArgs);
-    /**
-     * Register a handler to use for primary cache intercept.
-     *
-     * Only one such handler may exist. If using the same
-     * RequestManager as the Store instance the Store
-     * registers itself as a Cache handler.
-     *
-     * @public
-     * @param {Handler[]} cacheHandler
-     * @return {ThisType}
-     */
-    useCache(cacheHandler: CacheHandler & {
-        [IS_CACHE_HANDLER]?: true;
-    }): this;
-    /**
-     * Register handler(s) to use when a request is issued.
-     *
-     * Handlers will be invoked in the order they are registered.
-     * Each Handler is given the opportunity to handle the request,
-     * curry the request, or pass along a modified request.
-     *
-     * @public
-     * @param {Handler[]} newHandlers
-     * @return {ThisType}
-     */
-    use(newHandlers: Handler[]): this;
-    /**
-     * Issue a Request.
-     *
-     * Returns a Future that fulfills with a StructuredDocument
-     *
-     * @public
-     * @param {RequestInfo} request
-     * @return {Future}
-     */
-    request<RT, T = unknown>(request: RequestInfo<RT, T>): Future<RT>;
-    static create(options?: GenericCreateArgs): RequestManager;
+	#private;
+	/** @internal */
+	_hasCacheHandler: boolean;
+	/**
+	* A map of pending requests from request.id to their
+	* associated CacheHandler promise.
+	*
+	* This queue is managed by the CacheHandler
+	*
+	* @internal
+	*/
+	_pending: Map<number, Promise<unknown>>;
+	/** @internal */
+	_deduped: Map<StableDocumentIdentifier, {
+		priority: ManagedRequestPriority;
+		promise: Promise<unknown>;
+	}>;
+	constructor(options?: GenericCreateArgs);
+	/**
+	* Register a handler to use for primary cache intercept.
+	*
+	* Only one such handler may exist. If using the same
+	* RequestManager as the Store instance the Store
+	* registers itself as a Cache handler.
+	*
+	* @public
+	*/
+	useCache(cacheHandler: CacheHandler & {
+		[IS_CACHE_HANDLER]?: true;
+	}): this;
+	/**
+	* Register handler(s) to use when a request is issued.
+	*
+	* Handlers will be invoked in the order they are registered.
+	* Each Handler is given the opportunity to handle the request,
+	* curry the request, or pass along a modified request.
+	*
+	* @public
+	* @param {Handler[]} newHandlers
+	* @return {ThisType}
+	*/
+	use(newHandlers: Handler[]): this;
+	/**
+	* Issue a Request.
+	*
+	* Returns a Future that fulfills with a StructuredDocument
+	*
+	* @public
+	* @param {RequestInfo} request
+	* @return {Future}
+	*/
+	request<
+		RT,
+		T = unknown
+	>(request: RequestInfo<RT, T>): Future<RT>;
+	/**
+	* This method exists so that the RequestManager can be created
+	* can be created by container/factory systems that expect to
+	* call a static `create` method to instantiate the class.
+	*
+	* Using `new RequestManager()` directly is preferred.
+	*
+	* @private
+	*/
+	static create(options?: GenericCreateArgs): RequestManager;
 }
-//# sourceMappingURL=manager.d.ts.map

package/declarations/request/-private/promise-cache.d.ts

@@ -1,20 +1,28 @@
-export type CacheResult<T = unknown, E = unknown> = {
-    isError: true;
-    result: E;
+export type CacheResult<
+	T = unknown,
+	E = unknown
+> = {
+	isError: true;
+	result: E;
 } | {
-    isError: false;
-    result: T;
+	isError: false;
+	result: T;
 };
-export type Awaitable<T = unknown, E = unknown> = {
-    then: (onFulfilled: (value: T) => unknown, onRejected: (reason: E) => unknown) => unknown;
-    catch: (onRejected: (reason: E) => unknown) => unknown;
-    finally: (onFinally: () => unknown) => unknown;
+export type Awaitable<
+	T = unknown,
+	E = unknown
+> = {
+	then: (onFulfilled: (value: T) => unknown, onRejected: (reason: E) => unknown) => unknown;
+	catch: (onRejected: (reason: E) => unknown) => unknown;
+	finally: (onFinally: () => unknown) => unknown;
 };
-export declare const PromiseCache: WeakMap<Awaitable<unknown, unknown>, CacheResult<unknown, unknown>>;
-export declare const RequestMap: Map<number, CacheResult<unknown, unknown>>;
+export declare const PromiseCache: WeakMap<Awaitable, CacheResult>;
+export declare const RequestMap: Map<number, CacheResult>;
 export declare function setRequestResult(requestId: number, result: CacheResult): void;
 export declare function clearRequestResult(requestId: number): void;
 export declare function getRequestResult(requestId: number): CacheResult | undefined;
 export declare function setPromiseResult(promise: Promise<unknown> | Awaitable, result: CacheResult): void;
-export declare function getPromiseResult<T, E>(promise: Promise<T> | Awaitable<T, E>): CacheResult<T, E> | undefined;
-//# sourceMappingURL=promise-cache.d.ts.map
+export declare function getPromiseResult<
+	T,
+	E
+>(promise: Promise<T> | Awaitable<T, E>): CacheResult<T, E> | undefined;

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

@@ -1,89 +1,91 @@
-import type { StableDocumentIdentifier } from '../../types/identifier';
-import type { IS_FUTURE, RequestContext, RequestInfo, ResponseInfo, StructuredDataDocument } from '../../types/request';
+/* eslint-disable no-irregular-whitespace */
+import type { StableDocumentIdentifier } from "../../types/identifier.js";
+import type { IS_FUTURE, RequestContext, RequestInfo, ResponseInfo, StructuredDataDocument } from "../../types/request.js";
 export interface GodContext {
-    controller: AbortController;
-    response: ResponseInfo | null;
-    stream: ReadableStream | Promise<ReadableStream | null> | null;
-    hasRequestedStream: boolean;
-    id: number;
-    identifier: StableDocumentIdentifier | null;
+	controller: AbortController;
+	response: ResponseInfo | null;
+	stream: ReadableStream | Promise<ReadableStream | null> | null;
+	hasRequestedStream: boolean;
+	id: number;
+	identifier: StableDocumentIdentifier | null;
 }
 export type Deferred<T> = {
-    resolve(v: T): void;
-    reject(v: unknown): void;
-    promise: Promise<T>;
+	resolve(v: T): void;
+	reject(v: unknown): void;
+	promise: Promise<T>;
 };
 export type ManagedRequestPriority = {
-    blocking: boolean;
+	blocking: boolean;
 };
 export type DeferredStream = {
-    resolve(v: ReadableStream | null): void;
-    reject(v: unknown): void;
-    promise: Promise<ReadableStream | null> & {
-        sizeHint?: number;
-    };
+	resolve(v: ReadableStream | null): void;
+	reject(v: unknown): void;
+	promise: Promise<ReadableStream | null> & {
+		sizeHint?: number;
+	};
 };
 /**
- * A Future is a Promise which resolves to a StructuredDocument
- * while providing the ability to `abort` the underlying request,
- * `getStream` the response before the outer promise resolves;
- *
- * @class Future
- * @public
- */
+* A Future is a {@link Promise} which resolves to a {@link StructuredDataDocument | 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>> {
-    [IS_FUTURE]: true;
-    /**
-     * Cancel this request by firing the AbortController's signal.
-     *
-     * @param {String} [reason] optional reason for aborting the request
-     * @public
-     * @return {void}
-     */
-    abort(reason?: string): void;
-    /**
-     * Get the response stream, if any, once made available.
-     *
-     * @public
-     * @return {Promise<ReadableStream | null>}
-     */
-    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
-     * @public
-     * @return {void}
-     */
-    onFinalize(cb: () => void): void;
-    /**
-     * The identifier of the associated request, if any, as
-     * assigned by the CacheHandler.
-     *
-     * @property lid
-     * @type {StableDocumentIdentifier | null}
-     * @public
-     */
-    lid: StableDocumentIdentifier | null;
-    /**
-     * The id of the associated request, if any, as assigned
-     * by the RequestManager
-     *
-     * @property id
-     * @type {Number}
-     * @public
-     */
-    id: number;
+	[IS_FUTURE]: true;
+	/**
+	* Cancel this request by firing the {@link AbortController}'s signal.
+	*
+	* @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.
+	*
+	* @public
+	* @return {Promise<ReadableStream | null>}
+	*/
+	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
+	* @public
+	* @return {void}
+	*/
+	onFinalize(cb: () => void): void;
+	/**
+	* The identifier of the associated request, if any, as
+	* assigned by the CacheHandler.
+	*
+	* @property lid
+	* @type {StableDocumentIdentifier | null}
+	* @public
+	*/
+	lid: StableDocumentIdentifier | null;
+	/**
+	* The id of the associated request, if any, as assigned
+	* by the RequestManager
+	*
+	* @property id
+	* @type {Number}
+	* @public
+	*/
+	id: number;
 }
 export type DeferredFuture<T> = {
-    resolve(v: StructuredDataDocument<T>): void;
-    reject(v: unknown): void;
-    promise: Future<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
+* 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.
 
@@ -97,7 +99,7 @@ that it can then compose how it sees fit with its own response.
 type NextFn<P> = (req: RequestInfo) => Future<P>;
 
 interface Handler {
-  async request<T>(context: RequestContext, next: NextFn<P>): T;
+async request<T>(context: RequestContext, next: NextFn<P>): T;
 }
 ```
 
@@ -105,10 +107,10 @@ interface Handler {
 
 ```ts
 interface RequestContext<T> {
-  readonly request: RequestInfo;
+readonly request: RequestInfo;
 
-  setStream(stream: ReadableStream | Promise<ReadableStream>): void;
-  setResponse(response: Response | ResponseInfo): void;
+setStream(stream: ReadableStream | Promise<ReadableStream>): void;
+setResponse(response: Response | ResponseInfo): void;
 }
 ```
 
@@ -121,13 +123,13 @@ 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);
+async request(context) {
+const response = await fetch(context.request);
+context.setResponse(reponse);
+context.setStream(response.clone().body);
 
-    return response.json();
-  }
+return response.json();
+}
 }
 ```
 
@@ -138,13 +140,13 @@ const FetchHandler = {
 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.
+- 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.
 
 ----
 
@@ -184,52 +186,51 @@ Request handlers are registered by configuring the manager via `use`
 
 ```ts
 const manager = new RequestManager()
-  .use([Handler1, Handler2]);
+.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.
 
 
- @class (Interface) Handler
- @public
+@class (Interface) Handler
+@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
-     * @param context
-     * @param next
-     */
-    request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T>;
+	/**
+	* Method to implement to handle requests. Receives the request
+	* context and a nextFn to call to pass-along the request to
+	* other handlers.
+	*
+	* @public
+	* @param context
+	* @param next
+	*/
+	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T>;
 }
 /**
- * The CacheHandler is identical to other handlers ecxept 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)`.
- *
- * @class (Interface) CacheHandler
- * @public
- */
+* The CacheHandler is identical to other handlers ecxept 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)`.
+*
+* @class (Interface) 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
-     * @param context
-     * @param next
-     */
-    request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> | T;
+	/**
+	* Method to implement to handle requests. Receives the request
+	* context and a nextFn to call to pass-along the request to
+	* other handlers.
+	*
+	* @public
+	* @param context
+	* @param next
+	*/
+	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> | T;
 }
 export interface RequestResponse<T> {
-    result: T;
+	result: T;
 }
 export type GenericCreateArgs = Record<string | symbol, unknown>;
-//# sourceMappingURL=types.d.ts.map