@warp-drive/utilities 5.9.0-alpha.9 → 5.9.0-beta.1

package/declarations/handlers.d.ts

@@ -1,10 +1,283 @@
+import { RequestContext, StructuredDataDocument } from "@warp-drive/core/types/request";
+import { Future, Handler, NextFn } from "@warp-drive/core/request";
+//#region src/-private/handlers/auto-compress.d.ts
 /**
-* A selection of pre-built request handlers for handling common
-* request scenarios.
-*
-* @module
-*/
-export { AutoCompress, SupportsRequestStreams } from "./-private/handlers/auto-compress.js";
-export { Gate } from "./-private/handlers/gated.js";
-export { MetaDocHandler } from "./-private/handlers/meta-doc.js";
-export { addTraceHeader, TAB_ASSIGNED, TAB_ID, assertInvalidUrlLength, MAX_URL_LENGTH } from "./-private/handlers/utils.js";
+ * Whether the browser supports `ReadableStream` as a request body
+ * in a `POST` request.
+ *
+ * @group Constants
+ */
+declare const SupportsRequestStreams: boolean;
+interface Constraints {
+  /**
+   * The minimum size at which to compress blobs
+   *
+   * @default 1000
+   */
+  Blob?: number;
+  /**
+   * The minimum size at which to compress array buffers
+   *
+   * @default 1000
+   */
+  ArrayBuffer?: number;
+  /**
+   * The minimum size at which to compress typed arrays
+   *
+   * @default 1000
+   */
+  TypedArray?: number;
+  /**
+   * The minimum size at which to compress data views
+   *
+   * @default 1000
+   */
+  DataView?: number;
+  /**
+   * The minimum size at which to compress strings
+   *
+   * @default 1000
+   */
+  String?: number;
+}
+/**
+ * Options for configuring the AutoCompress handler.
+ *
+ */
+interface CompressionOptions {
+  /**
+   * The compression format to use. Must be a valid
+   * compression format supported by [CompressionStream](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)
+   *
+   * The default is `gzip`.
+   *
+   */
+  format?: CompressionFormat;
+  /**
+   * Some browsers support `ReadableStream` as a request body. This option
+   * enables passing the compression stream as the request body instead of
+   * the final compressed body when the browser supports doing so.
+   *
+   * This comes with several caveats:
+   *
+   * - the request will be put into `duplex: 'half'` mode. This should be
+   *   transparent to you, but it is worth noting.
+   * - the request mode cannot be `no-cors` as requests with a `ReadableStream`
+   *   have no content length and thus are a new form of request that triggers
+   *   cors requirements and a preflight request.
+   * - http/1.x is not supported.
+   *
+   * For additional reading about the restrictions of using `ReadableStream`
+   * as a request body, see the [Chromium Documentation](https://developer.chrome.com/docs/capabilities/web-apis/fetch-streaming-requests#restrictions)
+   *
+   * Streaming can be enabled per-request in browsers which support it by
+   * setting `request.options.allowStreaming` to `true`.
+   *
+   * Streaming can be forced even when the browser does not support it by setting
+   * `request.options.forceStreaming` to `true`. This is useful if later handlers
+   * in the chain can handle the request body as a stream.
+   *
+   * @default false
+   */
+  allowStreaming?: boolean;
+  /**
+   * If `true`, the request will be forced into streaming mode even
+   * if the browser does not support it. This is useful if later handlers
+   * in the chain can handle the request body as a stream.
+   *
+   * @default false
+   */
+  forceStreaming?: boolean;
+  /**
+   * The constraints for the request body. This is used to determine
+   * whether to compress the request body or not.
+   *
+   * The defaults are:
+   *
+   * ```ts
+   * {
+   *   Blob: 1000, // blob.size
+   *   ArrayBuffer: 1000, // buffer.byteLength
+   *   TypedArray: 1000, // array.byteLength
+   *   DataView: 1000, // view.byteLength
+   *   String: 1000, // string.length
+   * }
+   * ```
+   *
+   * The following body types are never compressed unless explicitly
+   * configured by the request:
+   * - `FormData`
+   * - `URLSearchParams`
+   * - `ReadableStream`
+   *
+   * A request.options.compress value of `false` will disable
+   * compression for a request body of any type. While a value of
+   * `true` will enable compression for the request.
+   *
+   * An undefined value will use the default, a value of `0` will
+   * enable compression for all values, and a value of `-1` will
+   * disable compression.
+   *
+   */
+  constraints?: Constraints;
+}
+/**
+ * A request handler that automatically compresses the request body
+ * if the request body is a string, array buffer, blob, or form data.
+ *
+ * This uses the [CompressionStream API](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)
+ *
+ * The compression format as well as the kinds of data to compress can be
+ * configured using the `format` and `constraints` options.
+ *
+ * ```diff
+ * +import { AutoCompress } from '@ember-data/request-utils/handlers';
+ * import Fetch from '@ember-data/request/fetch';
+ * import RequestManager from '@ember-data/request';
+ * import Store from '@ember-data/store';
+ *
+ * class AppStore extends Store {
+ *   requestManager = new RequestManager()
+ *     .use([
+ * +       new AutoCompress(),
+ *        Fetch
+ *     ]);
+ * }
+ * ```
+ *
+ * @group Handlers
+ * @public
+ * @since 5.5.0
+ */
+declare class AutoCompress implements Handler {
+  /**
+   * The resolved options this handler was configured with, with all
+   * defaults (including `constraints` defaults) applied.
+   */
+  options: Required<CompressionOptions> & {
+    /**
+     * The resolved size constraints used to decide whether to compress a given request body.
+     */
+    constraints: Required<Constraints>;
+  };
+  constructor(options?: CompressionOptions);
+  request<T>({ request }: RequestContext, next: NextFn<T>): Promise<T> | Future<T>;
+}
+//#endregion
+//#region src/-private/handlers/gated.d.ts
+/**
+ * If CheckFn returns true, the wrapped handler will be used.
+ * If CheckFn returns false, the wrapped handler will be skipped.
+ */
+type CheckFn = (context: RequestContext) => boolean;
+/**
+ *
+ * @group Handlers
+ * @public
+ */
+declare class Gate implements Handler {
+  /**
+   * The wrapped handler to invoke when {@link Gate.checkFn | checkFn} returns `true`.
+   */
+  handler: Handler;
+  /**
+   * The predicate used to decide whether {@link Gate.handler | handler} should run for a given request.
+   */
+  checkFn: CheckFn;
+  constructor(handler: Handler, checkFn: CheckFn);
+  request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T>;
+}
+//#endregion
+//#region src/-private/handlers/meta-doc.d.ts
+/**
+ * MetaDocHandler processes requests that are marked as meta requests.
+ *
+ * It treats the response body as "entirely meta" transforming
+ *
+ * ```ts
+ * {
+ *   some: "key",
+ *   another: "thing"
+ * }
+ * ```
+ *
+ * into
+ *
+ * ```ts
+ * {
+ * 	 meta: {
+ *     some: "key",
+ *     another: "thing"
+ *   }
+ * }
+ * ```
+ *
+ * To activate this handler, a request should specify
+ *
+ * ```ts
+ * options.isMetaRequest = true
+ * ```
+ *
+ * For instance
+ *
+ * ```ts
+ * store.request({
+ *   url: '/example',
+ *   options: {
+ *     isMetaRequest: true
+ *   }
+ * });
+ * ```
+ *
+ * Errors are not processed by this handler, so if the request fails and the error response
+ * is not in {json:api} format additional processing may be needed.
+ *
+ * @group Handlers
+ */
+declare const MetaDocHandler: Handler;
+//#endregion
+//#region src/-private/handlers/utils.d.ts
+/**
+ * A unique identifier for the current browser tab
+ * useful for observability/tracing and deduping
+ * across multiple tabs.
+ *
+ * @group Constants
+ */
+declare const TAB_ID: string;
+/**
+ * The epoch seconds at which the tab id was generated
+ *
+ * @group Constants
+ */
+declare const TAB_ASSIGNED: number;
+/**
+ * Adds the `X-Amzn-Trace-Id` header to support observability
+ * tooling around request routing.
+ *
+ * This makes use of the {@link TAB_ID} and {@link TAB_ASSIGNED}
+ * to enable tracking the browser tab of origin across multiple requests.
+ *
+ * Follows the template: `Root=1-${now}-${uuidv4};TabId=1-${epochSeconds}-${tab-uuid}`
+ *
+ * @group Utility Functions
+ */
+declare function addTraceHeader(headers: Headers): Headers;
+/**
+ * Source: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html
+ * As of 2024-12-05 the maximum URL length is 8192 bytes.
+ *
+ * @group Constants
+ */
+declare const MAX_URL_LENGTH = 8192;
+/**
+ * This assertion takes a URL and throws an error if the URL is longer than the maximum URL length.
+ *
+ * See also {@link MAX_URL_LENGTH}
+ *
+ * @group Utility Functions
+ */
+declare function assertInvalidUrlLength(url: string | undefined): void;
+//#endregion
+export { AutoCompress, Gate, MAX_URL_LENGTH, MetaDocHandler, SupportsRequestStreams, TAB_ASSIGNED, TAB_ID, addTraceHeader, assertInvalidUrlLength };
+//# sourceMappingURL=handlers.d.ts.map

package/declarations/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","names":[],"sources":["../src/-private/handlers/auto-compress.ts","../src/-private/handlers/gated.ts","../src/-private/handlers/meta-doc.ts","../src/-private/handlers/utils.ts"],"mappings":";;;;;;;;;cAca;UAgBH;;;;;;EAMR;;;;;;EAMA;;;;;;EAMA;;;;;;EAMA;;;;;;EAMA;;;;;;UAOQ;;;;;;;;EAQR,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BT;;;;;;;;EASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCA,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAwCH,wBAAwB;;;;;EAKnC,SAAiB,SAAS;;;;IAIxB,aAAa,SAAS;;EAGxB,YAAY,UAAS;EAUrB,QAAQ,KAAK,WAAW,gBAAgB,MAAM,OAAO,KAAK,QAAQ,KAAK,OAAO;;;;;;;;KCxM3E,WAAW,SAAS;;;;;;cAOZ,gBAAgB;;;;EAI3B,SAAiB;;;;EAIjB,SAAiB;EAEjB,YAAY,SAAS,SAAS,SAAS;EAKvC,QAAQ,aAAa,SAAS,gBAAgB,MAAM,OAAO,KAAK,QAAQ,IAAI,uBAAuB,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCoBrG,gBAAgB;;;;;;;;;;cCdhB;;;;;;cAMA;;;;;;;;;;;;iBAaG,eAAe,SAAS,UAAU;;;;;;;cAarC;;;;;;;;iBASG,uBAAuB"}