@warp-drive-mirror/utilities 5.10.0-alpha.12 → 5.10.0-alpha.13

package/dist/handlers.d.ts

@@ -5,6 +5,8 @@ import { Future, Handler, NextFn } from "@warp-drive-mirror/core/request";
  * Whether the browser supports `ReadableStream` as a request body
  * in a `POST` request.
  *
+ * @summary Whether the current browser can send a `ReadableStream` as a `fetch` request body, detected once at
+ * module load.
  * @group Constants
  */
 export declare const SupportsRequestStreams: boolean;
@@ -145,6 +147,8 @@ interface CompressionOptions {
  * }
  * ```
  *
+ * @summary Request handler that compresses large `POST`, `PUT`, `PATCH`, and `DELETE` bodies with `CompressionStream`,
+ * optionally streaming them.
  * @group Handlers
  * @public
  * @since 5.5.0
@@ -172,6 +176,8 @@ export declare class AutoCompress implements Handler {
 type CheckFn = (context: RequestContext) => boolean;
 /**
  *
+ * @summary Request handler that wraps another handler and runs it only when a check function returns true for the
+ * request.
  * @group Handlers
  * @public
  */
@@ -232,6 +238,7 @@ export declare class Gate implements Handler {
  * 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.
  *
+ * @summary Request handler that wraps the whole response body in `meta` for requests with `options.isMetaRequest` set.
  * @group Handlers
  */
 export declare const MetaDocHandler: Handler;
@@ -242,12 +249,15 @@ export declare const MetaDocHandler: Handler;
  * useful for observability/tracing and deduping
  * across multiple tabs.
  *
+ * @summary Random UUID identifying the current browser tab, kept in `sessionStorage` across reloads, for request
+ * tracing.
  * @group Constants
  */
 export declare const TAB_ID: string;
 /**
  * The epoch seconds at which the tab id was generated
  *
+ * @summary Epoch seconds recorded when this module loaded, paired with `TAB_ID` in trace headers.
  * @group Constants
  */
 export declare const TAB_ASSIGNED: number;
@@ -260,6 +270,8 @@ export declare const TAB_ASSIGNED: number;
  *
  * Follows the template: `Root=1-${now}-${uuidv4};TabId=1-${epochSeconds}-${tab-uuid}`
  *
+ * @summary Sets an `X-Amzn-Trace-Id` header carrying a per-request id and the tab id, so requests can be traced to
+ * their browser tab.
  * @group Utility Functions
  */
 export declare function addTraceHeader(headers: Headers): Headers;
@@ -267,6 +279,7 @@ export 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.
  *
+ * @summary The 8192-byte URL length limit, taken from AWS CloudFront, that `assertInvalidUrlLength` checks against.
  * @group Constants
  */
 export declare const MAX_URL_LENGTH = 8192;
@@ -275,6 +288,8 @@ export declare const MAX_URL_LENGTH = 8192;
  *
  * See also {@link MAX_URL_LENGTH}
  *
+ * @summary Dev-mode assertion that throws when a URL is longer than `MAX_URL_LENGTH`, suggesting a `POST` or `QUERY`
+ * request instead.
  * @group Utility Functions
  */
 export declare function assertInvalidUrlLength(url: string | undefined): void;

package/dist/handlers.d.ts.map

@@ -1 +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":";;;;;;;;;qBAca;UAgBH;;;;;;EAMR;;;;;;EAMA;;;;;;EAMA;;;;;;EAMA;;;;;;EAMA;;;;;;UAOQ;;;;;;;;EAQR,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BT;;;;;;;;EASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCA,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAwCH,wBAAwB;;;;;EAKnC,SAAiB,SAAS;;;;IAIxB,aAAa,SAAS;;EAGxB,YAAY,UAAS;EAUrB,QAAQ,KAAK,WAAW,gBAAgB,MAAM,OAAO,KAAK,QAAQ,KAAK,OAAO;;;;;;;;KCxM3E,WAAW,SAAS;;;;;;qBAOZ,gBAAgB;;;;EAI3B,SAAiB;;;;EAIjB,SAAiB;EAEjB,YAAY,SAAS,SAAS,SAAS;EAKvC,QAAQ,aAAa,SAAS,gBAAgB,MAAM,OAAO,KAAK,QAAQ,IAAI,uBAAuB,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBCoBrG,gBAAgB;;;;;;;;;;qBCdhB;;;;;;qBAMA;;;;;;;;;;;;wBAaG,eAAe,SAAS,UAAU;;;;;;;qBAarC;;;;;;;;wBASG,uBAAuB"}
+{"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":";;;;;;;;;;;qBAgBa;UAgBH;;;;;;EAMR;;;;;;EAMA;;;;;;EAMA;;;;;;EAMA;;;;;;EAMA;;;;;;UAOQ;;;;;;;;EAQR,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BT;;;;;;;;EASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCA,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA0CH,wBAAwB;;;;;EAKnC,SAAiB,SAAS;;;;IAIxB,aAAa,SAAS;;EAGxB,YAAY,UAAS;EAUrB,QAAQ,KAAK,WAAW,gBAAgB,MAAM,OAAO,KAAK,QAAQ,KAAK,OAAO;;;;;;;;KC5M3E,WAAW,SAAS;;;;;;;;qBASZ,gBAAgB;;;;EAI3B,SAAiB;;;;EAIjB,SAAiB;EAEjB,YAAY,SAAS,SAAS,SAAS;EAKvC,QAAQ,aAAa,SAAS,gBAAgB,MAAM,OAAO,KAAK,QAAQ,IAAI,uBAAuB,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBCmBrG,gBAAgB;;;;;;;;;;;;qBCbhB;;;;;;;qBAOA;;;;;;;;;;;;;;wBAeG,eAAe,SAAS,UAAU;;;;;;;;qBAcrC;;;;;;;;;;wBAWG,uBAAuB"}

package/dist/handlers.js

@@ -8,6 +8,8 @@ function isCompressibleMethod(method) {
 * Whether the browser supports `ReadableStream` as a request body
 * in a `POST` request.
 *
+* @summary Whether the current browser can send a `ReadableStream` as a `fetch` request body, detected once at
+* module load.
 * @group Constants
 */
 const SupportsRequestStreams = (() => {
@@ -58,6 +60,8 @@ const TypedArray = Object.getPrototypeOf(Uint8Array);
 * }
 * ```
 *
+* @summary Request handler that compresses large `POST`, `PUT`, `PATCH`, and `DELETE` bodies with `CompressionStream`,
+* optionally streaming them.
 * @group Handlers
 * @public
 * @since 5.5.0
@@ -127,6 +131,8 @@ function encodingForFormat(format) {
 */
 /**
 *
+* @summary Request handler that wraps another handler and runs it only when a check function returns true for the
+* request.
 * @group Handlers
 * @public
 */
@@ -192,6 +198,7 @@ var Gate = class {
 * 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.
 *
+* @summary Request handler that wraps the whole response body in `meta` for requests with `options.isMetaRequest` set.
 * @group Handlers
 */
 const MetaDocHandler = { request(context, next) {
@@ -224,12 +231,15 @@ function getTabId() {
 * useful for observability/tracing and deduping
 * across multiple tabs.
 *
+* @summary Random UUID identifying the current browser tab, kept in `sessionStorage` across reloads, for request
+* tracing.
 * @group Constants
 */
 const TAB_ID = getTabId();
 /**
 * The epoch seconds at which the tab id was generated
 *
+* @summary Epoch seconds recorded when this module loaded, paired with `TAB_ID` in trace headers.
 * @group Constants
 */
 const TAB_ASSIGNED = Math.floor(Date.now() / 1e3);
@@ -242,6 +252,8 @@ const TAB_ASSIGNED = Math.floor(Date.now() / 1e3);
 *
 * Follows the template: `Root=1-${now}-${uuidv4};TabId=1-${epochSeconds}-${tab-uuid}`
 *
+* @summary Sets an `X-Amzn-Trace-Id` header carrying a per-request id and the tab id, so requests can be traced to
+* their browser tab.
 * @group Utility Functions
 */
 function addTraceHeader(headers) {
@@ -253,6 +265,7 @@ function addTraceHeader(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.
 *
+* @summary The 8192-byte URL length limit, taken from AWS CloudFront, that `assertInvalidUrlLength` checks against.
 * @group Constants
 */
 const MAX_URL_LENGTH = 8192;
@@ -261,6 +274,8 @@ const MAX_URL_LENGTH = 8192;
 *
 * See also {@link MAX_URL_LENGTH}
 *
+* @summary Dev-mode assertion that throws when a URL is longer than `MAX_URL_LENGTH`, suggesting a `POST` or `QUERY`
+* request instead.
 * @group Utility Functions
 */
 function assertInvalidUrlLength(url) {

package/dist/handlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.js","names":["isCompressibleMethod","method","SupportsRequestStreams","duplexAccessed","hasContentType","Request","body","ReadableStream","duplex","headers","has","DEFAULT_CONSTRAINTS","Blob","ArrayBuffer","TypedArray","DataView","String","Object","getPrototypeOf","Uint8Array","AutoCompress","constructor","options","opts","format","constraints","assign","allowStreaming","forceStreaming","request","next","shouldCompress","compress","canCompress","length","size","byteLength","response","Response","stream","pipeThrough","CompressionStream","Headers","set","encodingForFormat","req","resp","blob","then","type","macroCondition","getGlobalConfig","WarpDrive","env","DEBUG","test","Error","Gate","constructor","handler","checkFn","request","context","next","FastBoot","globalThis","addEventListener","sessionStorage","setItem","getTabId","crypto","randomUUID","tabId","getItem","tabClosed","newTabId","TAB_ID","TAB_ASSIGNED","Math","floor","Date","now","addTraceHeader","headers","set","MAX_URL_LENGTH","assertInvalidUrlLength","url","macroCondition","getGlobalConfig","WarpDrive","env","DEBUG","test","Error","length"],"sources":["../src/-private/handlers/auto-compress.ts","../src/-private/handlers/gated.ts","../src/-private/handlers/meta-doc.ts","../src/-private/handlers/utils.ts"],"sourcesContent":["import { assert } from '@warp-drive-mirror/core/build-config/macros';\nimport type { Future, Handler, NextFn } from '@warp-drive-mirror/core/request';\nimport type { HTTPMethod, RequestContext } from '@warp-drive-mirror/core/types/request';\n\nfunction isCompressibleMethod(method?: HTTPMethod): boolean {\n  return method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE';\n}\n\n/**\n * Whether the browser supports `ReadableStream` as a request body\n * in a `POST` request.\n *\n * @group Constants\n */\nexport const SupportsRequestStreams: boolean = (() => {\n  let duplexAccessed = false;\n\n  const hasContentType = new Request('', {\n    body: new ReadableStream(),\n    method: 'POST',\n    // @ts-expect-error untyped\n    get duplex() {\n      duplexAccessed = true;\n      return 'half';\n    },\n  }).headers.has('Content-Type');\n\n  return duplexAccessed && !hasContentType;\n})();\n\ninterface Constraints {\n  /**\n   * The minimum size at which to compress blobs\n   *\n   * @default 1000\n   */\n  Blob?: number;\n  /**\n   * The minimum size at which to compress array buffers\n   *\n   * @default 1000\n   */\n  ArrayBuffer?: number;\n  /**\n   * The minimum size at which to compress typed arrays\n   *\n   * @default 1000\n   */\n  TypedArray?: number;\n  /**\n   * The minimum size at which to compress data views\n   *\n   * @default 1000\n   */\n  DataView?: number;\n  /**\n   * The minimum size at which to compress strings\n   *\n   * @default 1000\n   */\n  String?: number;\n}\n\n/**\n * Options for configuring the AutoCompress handler.\n *\n */\ninterface CompressionOptions {\n  /**\n   * The compression format to use. Must be a valid\n   * compression format supported by [CompressionStream](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)\n   *\n   * The default is `gzip`.\n   *\n   */\n  format?: CompressionFormat;\n\n  /**\n   * Some browsers support `ReadableStream` as a request body. This option\n   * enables passing the compression stream as the request body instead of\n   * the final compressed body when the browser supports doing so.\n   *\n   * This comes with several caveats:\n   *\n   * - the request will be put into `duplex: 'half'` mode. This should be\n   *   transparent to you, but it is worth noting.\n   * - the request mode cannot be `no-cors` as requests with a `ReadableStream`\n   *   have no content length and thus are a new form of request that triggers\n   *   cors requirements and a preflight request.\n   * - http/1.x is not supported.\n   *\n   * For additional reading about the restrictions of using `ReadableStream`\n   * as a request body, see the [Chromium Documentation](https://developer.chrome.com/docs/capabilities/web-apis/fetch-streaming-requests#restrictions)\n   *\n   * Streaming can be enabled per-request in browsers which support it by\n   * setting `request.options.allowStreaming` to `true`.\n   *\n   * Streaming can be forced even when the browser does not support it by setting\n   * `request.options.forceStreaming` to `true`. This is useful if later handlers\n   * in the chain can handle the request body as a stream.\n   *\n   * @default false\n   */\n  allowStreaming?: boolean;\n\n  /**\n   * If `true`, the request will be forced into streaming mode even\n   * if the browser does not support it. This is useful if later handlers\n   * in the chain can handle the request body as a stream.\n   *\n   * @default false\n   */\n  forceStreaming?: boolean;\n\n  /**\n   * The constraints for the request body. This is used to determine\n   * whether to compress the request body or not.\n   *\n   * The defaults are:\n   *\n   * ```ts\n   * {\n   *   Blob: 1000, // blob.size\n   *   ArrayBuffer: 1000, // buffer.byteLength\n   *   TypedArray: 1000, // array.byteLength\n   *   DataView: 1000, // view.byteLength\n   *   String: 1000, // string.length\n   * }\n   * ```\n   *\n   * The following body types are never compressed unless explicitly\n   * configured by the request:\n   * - `FormData`\n   * - `URLSearchParams`\n   * - `ReadableStream`\n   *\n   * A request.options.compress value of `false` will disable\n   * compression for a request body of any type. While a value of\n   * `true` will enable compression for the request.\n   *\n   * An undefined value will use the default, a value of `0` will\n   * enable compression for all values, and a value of `-1` will\n   * disable compression.\n   *\n   */\n  constraints?: Constraints;\n}\n\nconst DEFAULT_CONSTRAINTS = {\n  Blob: 1000,\n  ArrayBuffer: 1000,\n  TypedArray: 1000,\n  DataView: 1000,\n  String: 1000,\n};\nconst TypedArray = Object.getPrototypeOf(Uint8Array) as typeof Uint8Array;\n\n/**\n * A request handler that automatically compresses the request body\n * if the request body is a string, array buffer, blob, or form data.\n *\n * This uses the [CompressionStream API](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)\n *\n * The compression format as well as the kinds of data to compress can be\n * configured using the `format` and `constraints` options.\n *\n * ```diff\n * +import { AutoCompress } from '@ember-data-mirror/request-utils/handlers';\n * import Fetch from '@ember-data-mirror/request/fetch';\n * import RequestManager from '@ember-data-mirror/request';\n * import Store from '@ember-data-mirror/store';\n *\n * class AppStore extends Store {\n *   requestManager = new RequestManager()\n *     .use([\n * +       new AutoCompress(),\n *        Fetch\n *     ]);\n * }\n * ```\n *\n * @group Handlers\n * @public\n * @since 5.5.0\n */\nexport class AutoCompress implements Handler {\n  /**\n   * The resolved options this handler was configured with, with all\n   * defaults (including `constraints` defaults) applied.\n   */\n  declare options: Required<CompressionOptions> & {\n    /**\n     * The resolved size constraints used to decide whether to compress a given request body.\n     */\n    constraints: Required<Constraints>;\n  };\n\n  constructor(options: CompressionOptions = {}) {\n    const opts = {\n      format: options.format ?? 'gzip',\n      constraints: Object.assign({}, DEFAULT_CONSTRAINTS, options.constraints),\n      allowStreaming: options.allowStreaming ?? false,\n      forceStreaming: options.forceStreaming ?? false,\n    };\n    this.options = opts;\n  }\n\n  request<T>({ request }: RequestContext, next: NextFn<T>): Promise<T> | Future<T> {\n    const { constraints } = this.options;\n    const { body } = request;\n\n    const shouldCompress =\n      !!body &&\n      isCompressibleMethod(request.method) &&\n      request.options?.compress !== false &&\n      // prettier-ignore\n      (request.options?.compress ? true\n      : typeof body === 'string' || body instanceof String ? canCompress('String', constraints, body.length)\n      : body instanceof Blob ? canCompress('Blob', constraints, body.size)\n      : body instanceof ArrayBuffer ? canCompress('ArrayBuffer', constraints, body.byteLength)\n      : body instanceof DataView ? canCompress('DataView', constraints, body.byteLength)\n      : body instanceof TypedArray ? canCompress('TypedArray', constraints, body.byteLength)\n      : false);\n\n    if (!shouldCompress) return next(request);\n\n    // A convenient way to convert all of the supported body types to a readable\n    // stream is to use a `Response` object body\n    const response = new Response(request.body);\n    const stream = response.body?.pipeThrough(new CompressionStream(this.options.format));\n    const headers = new Headers(request.headers);\n    headers.set('Content-Encoding', encodingForFormat(this.options.format));\n\n    //\n    // For browsers that support it, `fetch` can receive a `ReadableStream` as\n    // the body, so all we need to do is to create a new `ReadableStream` and\n    // compress it on the fly\n    //\n    const forceStreaming = request.options?.forceStreaming ?? this.options.forceStreaming;\n    const allowStreaming = request.options?.allowStreaming ?? this.options.allowStreaming;\n    if (forceStreaming || (SupportsRequestStreams && allowStreaming)) {\n      const req = Object.assign({}, request, {\n        body: stream,\n        headers,\n      });\n      if (SupportsRequestStreams) {\n        // @ts-expect-error untyped\n        req.duplex = 'half';\n      }\n\n      return next(req);\n\n      //\n      // For non-chromium browsers, we have to \"pull\" the stream to get the final\n      // bytes and supply the final byte array as the new request body.\n      //\n    }\n\n    // we need to pull the stream to get the final bytes\n    const resp = new Response(stream);\n    return resp.blob().then((blob) => {\n      const req = Object.assign({}, request, {\n        body: blob,\n        headers,\n      });\n      return next(req);\n    }) as Promise<T>;\n  }\n}\n\nfunction canCompress(type: keyof Constraints, constraints: Required<Constraints>, size: number): boolean {\n  // if we have a value of 0, we can compress anything\n  if (constraints[type] === 0) return true;\n  if (constraints[type] === -1) return false;\n  return size >= constraints[type];\n}\n\nfunction encodingForFormat(format: CompressionFormat): string {\n  switch (format) {\n    case 'gzip':\n    case 'deflate':\n    case 'deflate-raw':\n      return format;\n    default:\n      assert(`Unsupported compression format: ${format as unknown as string}`);\n      // @ts-expect-error - unreachable code is reachable in production\n      return format;\n  }\n}\n","import type { Future, Handler, NextFn } from '@warp-drive-mirror/core/request';\nimport type { RequestContext, StructuredDataDocument } from '@warp-drive-mirror/core/types/request';\n\n/**\n * If CheckFn returns true, the wrapped handler will be used.\n * If CheckFn returns false, the wrapped handler will be skipped.\n */\ntype CheckFn = (context: RequestContext) => boolean;\n\n/**\n *\n * @group Handlers\n * @public\n */\nexport class Gate implements Handler {\n  /**\n   * The wrapped handler to invoke when {@link Gate.checkFn | checkFn} returns `true`.\n   */\n  declare handler: Handler;\n  /**\n   * The predicate used to decide whether {@link Gate.handler | handler} should run for a given request.\n   */\n  declare checkFn: CheckFn;\n\n  constructor(handler: Handler, checkFn: CheckFn) {\n    this.handler = handler;\n    this.checkFn = checkFn;\n  }\n\n  request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> {\n    if (this.checkFn(context)) {\n      return this.handler.request(context, next);\n    }\n    return next(context.request);\n  }\n}\n","import type { StoreRequestContext } from '@warp-drive-mirror/core';\nimport type { Handler, NextFn } from '@warp-drive-mirror/core/request';\nimport type { StructuredDataDocument } from '@warp-drive-mirror/core/types/request';\n\n/**\n * MetaDocHandler processes requests that are marked as meta requests.\n *\n * It treats the response body as \"entirely meta\" transforming\n *\n * ```ts\n * {\n *   some: \"key\",\n *   another: \"thing\"\n * }\n * ```\n *\n * into\n *\n * ```ts\n * {\n * \t meta: {\n *     some: \"key\",\n *     another: \"thing\"\n *   }\n * }\n * ```\n *\n * To activate this handler, a request should specify\n *\n * ```ts\n * options.isMetaRequest = true\n * ```\n *\n * For instance\n *\n * ```ts\n * store.request({\n *   url: '/example',\n *   options: {\n *     isMetaRequest: true\n *   }\n * });\n * ```\n *\n * Errors are not processed by this handler, so if the request fails and the error response\n * is not in {json:api} format additional processing may be needed.\n *\n * @group Handlers\n */\nexport const MetaDocHandler: Handler = {\n  request<T>(context: StoreRequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T> | Awaited<T>> {\n    if (!context.request.options?.isMetaRequest) {\n      return next(context.request);\n    }\n\n    return next(context.request).then((response) => {\n      return processResponse<T>(response);\n    });\n  },\n};\n\nfunction processResponse<T>(response: StructuredDataDocument<T>): T {\n  return {\n    meta: response.content,\n  } as T;\n}\n","import { assert } from '@warp-drive-mirror/core/build-config/macros';\n\nif (typeof FastBoot === 'undefined') {\n  globalThis.addEventListener('beforeunload', function () {\n    sessionStorage.setItem('tab-closed', 'true');\n  });\n}\n\nfunction getTabId() {\n  if (typeof sessionStorage === 'undefined') {\n    return crypto.randomUUID();\n  }\n\n  const tabId = sessionStorage.getItem('tab-id');\n  if (tabId) {\n    const tabClosed = sessionStorage.getItem('tab-closed');\n    if (tabClosed === 'true') {\n      return tabId;\n    }\n\n    // fall through to generate a new tab id\n  }\n\n  const newTabId = crypto.randomUUID();\n  sessionStorage.setItem('tab-id', newTabId);\n  return newTabId;\n}\n\n/**\n * A unique identifier for the current browser tab\n * useful for observability/tracing and deduping\n * across multiple tabs.\n *\n * @group Constants\n */\nexport const TAB_ID: string = getTabId();\n/**\n * The epoch seconds at which the tab id was generated\n *\n * @group Constants\n */\nexport const TAB_ASSIGNED: number = Math.floor(Date.now() / 1000);\n\n/**\n * Adds the `X-Amzn-Trace-Id` header to support observability\n * tooling around request routing.\n *\n * This makes use of the {@link TAB_ID} and {@link TAB_ASSIGNED}\n * to enable tracking the browser tab of origin across multiple requests.\n *\n * Follows the template: `Root=1-${now}-${uuidv4};TabId=1-${epochSeconds}-${tab-uuid}`\n *\n * @group Utility Functions\n */\nexport function addTraceHeader(headers: Headers): Headers {\n  const now = Math.floor(Date.now() / 1000);\n  headers.set('X-Amzn-Trace-Id', `Root=1-${now}-${crypto.randomUUID()};TabId=1-${TAB_ASSIGNED}-${TAB_ID}`);\n\n  return headers;\n}\n\n/**\n * Source: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html\n * As of 2024-12-05 the maximum URL length is 8192 bytes.\n *\n * @group Constants\n */\nexport const MAX_URL_LENGTH = 8192;\n\n/**\n * This assertion takes a URL and throws an error if the URL is longer than the maximum URL length.\n *\n * See also {@link MAX_URL_LENGTH}\n *\n * @group Utility Functions\n */\nexport function assertInvalidUrlLength(url: string | undefined): void {\n  assert(\n    `URL length ${url?.length} exceeds the maximum URL length of ${MAX_URL_LENGTH} bytes.\\n\\nConsider converting this request query a \\`/query\\` endpoint instead of a GET, or upgrade the current endpoint to be able to receive a POST request directly (ideally specifying the header HTTP-Method-Override: QUERY)\\n\\nThe Invalid URL is:\\n\\n${url}`,\n    !url || url.length <= MAX_URL_LENGTH\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"handlers.js","names":["isCompressibleMethod","method","SupportsRequestStreams","duplexAccessed","hasContentType","Request","body","ReadableStream","duplex","headers","has","DEFAULT_CONSTRAINTS","Blob","ArrayBuffer","TypedArray","DataView","String","Object","getPrototypeOf","Uint8Array","AutoCompress","constructor","options","opts","format","constraints","assign","allowStreaming","forceStreaming","request","next","shouldCompress","compress","canCompress","length","size","byteLength","response","Response","stream","pipeThrough","CompressionStream","Headers","set","encodingForFormat","req","resp","blob","then","type","macroCondition","getGlobalConfig","WarpDrive","env","DEBUG","test","Error","Gate","constructor","handler","checkFn","request","context","next","FastBoot","globalThis","addEventListener","sessionStorage","setItem","getTabId","crypto","randomUUID","tabId","getItem","tabClosed","newTabId","TAB_ID","TAB_ASSIGNED","Math","floor","Date","now","addTraceHeader","headers","set","MAX_URL_LENGTH","assertInvalidUrlLength","url","macroCondition","getGlobalConfig","WarpDrive","env","DEBUG","test","Error","length"],"sources":["../src/-private/handlers/auto-compress.ts","../src/-private/handlers/gated.ts","../src/-private/handlers/meta-doc.ts","../src/-private/handlers/utils.ts"],"sourcesContent":["import { assert } from '@warp-drive-mirror/core/build-config/macros';\nimport type { Future, Handler, NextFn } from '@warp-drive-mirror/core/request';\nimport type { HTTPMethod, RequestContext } from '@warp-drive-mirror/core/types/request';\n\nfunction isCompressibleMethod(method?: HTTPMethod): boolean {\n  return method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE';\n}\n\n/**\n * Whether the browser supports `ReadableStream` as a request body\n * in a `POST` request.\n *\n * @summary Whether the current browser can send a `ReadableStream` as a `fetch` request body, detected once at\n * module load.\n * @group Constants\n */\nexport const SupportsRequestStreams: boolean = (() => {\n  let duplexAccessed = false;\n\n  const hasContentType = new Request('', {\n    body: new ReadableStream(),\n    method: 'POST',\n    // @ts-expect-error untyped\n    get duplex() {\n      duplexAccessed = true;\n      return 'half';\n    },\n  }).headers.has('Content-Type');\n\n  return duplexAccessed && !hasContentType;\n})();\n\ninterface Constraints {\n  /**\n   * The minimum size at which to compress blobs\n   *\n   * @default 1000\n   */\n  Blob?: number;\n  /**\n   * The minimum size at which to compress array buffers\n   *\n   * @default 1000\n   */\n  ArrayBuffer?: number;\n  /**\n   * The minimum size at which to compress typed arrays\n   *\n   * @default 1000\n   */\n  TypedArray?: number;\n  /**\n   * The minimum size at which to compress data views\n   *\n   * @default 1000\n   */\n  DataView?: number;\n  /**\n   * The minimum size at which to compress strings\n   *\n   * @default 1000\n   */\n  String?: number;\n}\n\n/**\n * Options for configuring the AutoCompress handler.\n *\n */\ninterface CompressionOptions {\n  /**\n   * The compression format to use. Must be a valid\n   * compression format supported by [CompressionStream](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)\n   *\n   * The default is `gzip`.\n   *\n   */\n  format?: CompressionFormat;\n\n  /**\n   * Some browsers support `ReadableStream` as a request body. This option\n   * enables passing the compression stream as the request body instead of\n   * the final compressed body when the browser supports doing so.\n   *\n   * This comes with several caveats:\n   *\n   * - the request will be put into `duplex: 'half'` mode. This should be\n   *   transparent to you, but it is worth noting.\n   * - the request mode cannot be `no-cors` as requests with a `ReadableStream`\n   *   have no content length and thus are a new form of request that triggers\n   *   cors requirements and a preflight request.\n   * - http/1.x is not supported.\n   *\n   * For additional reading about the restrictions of using `ReadableStream`\n   * as a request body, see the [Chromium Documentation](https://developer.chrome.com/docs/capabilities/web-apis/fetch-streaming-requests#restrictions)\n   *\n   * Streaming can be enabled per-request in browsers which support it by\n   * setting `request.options.allowStreaming` to `true`.\n   *\n   * Streaming can be forced even when the browser does not support it by setting\n   * `request.options.forceStreaming` to `true`. This is useful if later handlers\n   * in the chain can handle the request body as a stream.\n   *\n   * @default false\n   */\n  allowStreaming?: boolean;\n\n  /**\n   * If `true`, the request will be forced into streaming mode even\n   * if the browser does not support it. This is useful if later handlers\n   * in the chain can handle the request body as a stream.\n   *\n   * @default false\n   */\n  forceStreaming?: boolean;\n\n  /**\n   * The constraints for the request body. This is used to determine\n   * whether to compress the request body or not.\n   *\n   * The defaults are:\n   *\n   * ```ts\n   * {\n   *   Blob: 1000, // blob.size\n   *   ArrayBuffer: 1000, // buffer.byteLength\n   *   TypedArray: 1000, // array.byteLength\n   *   DataView: 1000, // view.byteLength\n   *   String: 1000, // string.length\n   * }\n   * ```\n   *\n   * The following body types are never compressed unless explicitly\n   * configured by the request:\n   * - `FormData`\n   * - `URLSearchParams`\n   * - `ReadableStream`\n   *\n   * A request.options.compress value of `false` will disable\n   * compression for a request body of any type. While a value of\n   * `true` will enable compression for the request.\n   *\n   * An undefined value will use the default, a value of `0` will\n   * enable compression for all values, and a value of `-1` will\n   * disable compression.\n   *\n   */\n  constraints?: Constraints;\n}\n\nconst DEFAULT_CONSTRAINTS = {\n  Blob: 1000,\n  ArrayBuffer: 1000,\n  TypedArray: 1000,\n  DataView: 1000,\n  String: 1000,\n};\nconst TypedArray = Object.getPrototypeOf(Uint8Array) as typeof Uint8Array;\n\n/**\n * A request handler that automatically compresses the request body\n * if the request body is a string, array buffer, blob, or form data.\n *\n * This uses the [CompressionStream API](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)\n *\n * The compression format as well as the kinds of data to compress can be\n * configured using the `format` and `constraints` options.\n *\n * ```diff\n * +import { AutoCompress } from '@ember-data-mirror/request-utils/handlers';\n * import Fetch from '@ember-data-mirror/request/fetch';\n * import RequestManager from '@ember-data-mirror/request';\n * import Store from '@ember-data-mirror/store';\n *\n * class AppStore extends Store {\n *   requestManager = new RequestManager()\n *     .use([\n * +       new AutoCompress(),\n *        Fetch\n *     ]);\n * }\n * ```\n *\n * @summary Request handler that compresses large `POST`, `PUT`, `PATCH`, and `DELETE` bodies with `CompressionStream`,\n * optionally streaming them.\n * @group Handlers\n * @public\n * @since 5.5.0\n */\nexport class AutoCompress implements Handler {\n  /**\n   * The resolved options this handler was configured with, with all\n   * defaults (including `constraints` defaults) applied.\n   */\n  declare options: Required<CompressionOptions> & {\n    /**\n     * The resolved size constraints used to decide whether to compress a given request body.\n     */\n    constraints: Required<Constraints>;\n  };\n\n  constructor(options: CompressionOptions = {}) {\n    const opts = {\n      format: options.format ?? 'gzip',\n      constraints: Object.assign({}, DEFAULT_CONSTRAINTS, options.constraints),\n      allowStreaming: options.allowStreaming ?? false,\n      forceStreaming: options.forceStreaming ?? false,\n    };\n    this.options = opts;\n  }\n\n  request<T>({ request }: RequestContext, next: NextFn<T>): Promise<T> | Future<T> {\n    const { constraints } = this.options;\n    const { body } = request;\n\n    const shouldCompress =\n      !!body &&\n      isCompressibleMethod(request.method) &&\n      request.options?.compress !== false &&\n      // prettier-ignore\n      (request.options?.compress ? true\n      : typeof body === 'string' || body instanceof String ? canCompress('String', constraints, body.length)\n      : body instanceof Blob ? canCompress('Blob', constraints, body.size)\n      : body instanceof ArrayBuffer ? canCompress('ArrayBuffer', constraints, body.byteLength)\n      : body instanceof DataView ? canCompress('DataView', constraints, body.byteLength)\n      : body instanceof TypedArray ? canCompress('TypedArray', constraints, body.byteLength)\n      : false);\n\n    if (!shouldCompress) return next(request);\n\n    // A convenient way to convert all of the supported body types to a readable\n    // stream is to use a `Response` object body\n    const response = new Response(request.body);\n    const stream = response.body?.pipeThrough(new CompressionStream(this.options.format));\n    const headers = new Headers(request.headers);\n    headers.set('Content-Encoding', encodingForFormat(this.options.format));\n\n    //\n    // For browsers that support it, `fetch` can receive a `ReadableStream` as\n    // the body, so all we need to do is to create a new `ReadableStream` and\n    // compress it on the fly\n    //\n    const forceStreaming = request.options?.forceStreaming ?? this.options.forceStreaming;\n    const allowStreaming = request.options?.allowStreaming ?? this.options.allowStreaming;\n    if (forceStreaming || (SupportsRequestStreams && allowStreaming)) {\n      const req = Object.assign({}, request, {\n        body: stream,\n        headers,\n      });\n      if (SupportsRequestStreams) {\n        // @ts-expect-error untyped\n        req.duplex = 'half';\n      }\n\n      return next(req);\n\n      //\n      // For non-chromium browsers, we have to \"pull\" the stream to get the final\n      // bytes and supply the final byte array as the new request body.\n      //\n    }\n\n    // we need to pull the stream to get the final bytes\n    const resp = new Response(stream);\n    return resp.blob().then((blob) => {\n      const req = Object.assign({}, request, {\n        body: blob,\n        headers,\n      });\n      return next(req);\n    }) as Promise<T>;\n  }\n}\n\nfunction canCompress(type: keyof Constraints, constraints: Required<Constraints>, size: number): boolean {\n  // if we have a value of 0, we can compress anything\n  if (constraints[type] === 0) return true;\n  if (constraints[type] === -1) return false;\n  return size >= constraints[type];\n}\n\nfunction encodingForFormat(format: CompressionFormat): string {\n  switch (format) {\n    case 'gzip':\n    case 'deflate':\n    case 'deflate-raw':\n      return format;\n    default:\n      assert(`Unsupported compression format: ${format as unknown as string}`);\n      // @ts-expect-error - unreachable code is reachable in production\n      return format;\n  }\n}\n","import type { Future, Handler, NextFn } from '@warp-drive-mirror/core/request';\nimport type { RequestContext, StructuredDataDocument } from '@warp-drive-mirror/core/types/request';\n\n/**\n * If CheckFn returns true, the wrapped handler will be used.\n * If CheckFn returns false, the wrapped handler will be skipped.\n */\ntype CheckFn = (context: RequestContext) => boolean;\n\n/**\n *\n * @summary Request handler that wraps another handler and runs it only when a check function returns true for the\n * request.\n * @group Handlers\n * @public\n */\nexport class Gate implements Handler {\n  /**\n   * The wrapped handler to invoke when {@link Gate.checkFn | checkFn} returns `true`.\n   */\n  declare handler: Handler;\n  /**\n   * The predicate used to decide whether {@link Gate.handler | handler} should run for a given request.\n   */\n  declare checkFn: CheckFn;\n\n  constructor(handler: Handler, checkFn: CheckFn) {\n    this.handler = handler;\n    this.checkFn = checkFn;\n  }\n\n  request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> {\n    if (this.checkFn(context)) {\n      return this.handler.request(context, next);\n    }\n    return next(context.request);\n  }\n}\n","import type { StoreRequestContext } from '@warp-drive-mirror/core';\nimport type { Handler, NextFn } from '@warp-drive-mirror/core/request';\nimport type { StructuredDataDocument } from '@warp-drive-mirror/core/types/request';\n\n/**\n * MetaDocHandler processes requests that are marked as meta requests.\n *\n * It treats the response body as \"entirely meta\" transforming\n *\n * ```ts\n * {\n *   some: \"key\",\n *   another: \"thing\"\n * }\n * ```\n *\n * into\n *\n * ```ts\n * {\n * \t meta: {\n *     some: \"key\",\n *     another: \"thing\"\n *   }\n * }\n * ```\n *\n * To activate this handler, a request should specify\n *\n * ```ts\n * options.isMetaRequest = true\n * ```\n *\n * For instance\n *\n * ```ts\n * store.request({\n *   url: '/example',\n *   options: {\n *     isMetaRequest: true\n *   }\n * });\n * ```\n *\n * Errors are not processed by this handler, so if the request fails and the error response\n * is not in {json:api} format additional processing may be needed.\n *\n * @summary Request handler that wraps the whole response body in `meta` for requests with `options.isMetaRequest` set.\n * @group Handlers\n */\nexport const MetaDocHandler: Handler = {\n  request<T>(context: StoreRequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T> | Awaited<T>> {\n    if (!context.request.options?.isMetaRequest) {\n      return next(context.request);\n    }\n\n    return next(context.request).then((response) => {\n      return processResponse<T>(response);\n    });\n  },\n};\n\nfunction processResponse<T>(response: StructuredDataDocument<T>): T {\n  return {\n    meta: response.content,\n  } as T;\n}\n","import { assert } from '@warp-drive-mirror/core/build-config/macros';\n\nif (typeof FastBoot === 'undefined') {\n  globalThis.addEventListener('beforeunload', function () {\n    sessionStorage.setItem('tab-closed', 'true');\n  });\n}\n\nfunction getTabId() {\n  if (typeof sessionStorage === 'undefined') {\n    return crypto.randomUUID();\n  }\n\n  const tabId = sessionStorage.getItem('tab-id');\n  if (tabId) {\n    const tabClosed = sessionStorage.getItem('tab-closed');\n    if (tabClosed === 'true') {\n      return tabId;\n    }\n\n    // fall through to generate a new tab id\n  }\n\n  const newTabId = crypto.randomUUID();\n  sessionStorage.setItem('tab-id', newTabId);\n  return newTabId;\n}\n\n/**\n * A unique identifier for the current browser tab\n * useful for observability/tracing and deduping\n * across multiple tabs.\n *\n * @summary Random UUID identifying the current browser tab, kept in `sessionStorage` across reloads, for request\n * tracing.\n * @group Constants\n */\nexport const TAB_ID: string = getTabId();\n/**\n * The epoch seconds at which the tab id was generated\n *\n * @summary Epoch seconds recorded when this module loaded, paired with `TAB_ID` in trace headers.\n * @group Constants\n */\nexport const TAB_ASSIGNED: number = Math.floor(Date.now() / 1000);\n\n/**\n * Adds the `X-Amzn-Trace-Id` header to support observability\n * tooling around request routing.\n *\n * This makes use of the {@link TAB_ID} and {@link TAB_ASSIGNED}\n * to enable tracking the browser tab of origin across multiple requests.\n *\n * Follows the template: `Root=1-${now}-${uuidv4};TabId=1-${epochSeconds}-${tab-uuid}`\n *\n * @summary Sets an `X-Amzn-Trace-Id` header carrying a per-request id and the tab id, so requests can be traced to\n * their browser tab.\n * @group Utility Functions\n */\nexport function addTraceHeader(headers: Headers): Headers {\n  const now = Math.floor(Date.now() / 1000);\n  headers.set('X-Amzn-Trace-Id', `Root=1-${now}-${crypto.randomUUID()};TabId=1-${TAB_ASSIGNED}-${TAB_ID}`);\n\n  return headers;\n}\n\n/**\n * Source: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html\n * As of 2024-12-05 the maximum URL length is 8192 bytes.\n *\n * @summary The 8192-byte URL length limit, taken from AWS CloudFront, that `assertInvalidUrlLength` checks against.\n * @group Constants\n */\nexport const MAX_URL_LENGTH = 8192;\n\n/**\n * This assertion takes a URL and throws an error if the URL is longer than the maximum URL length.\n *\n * See also {@link MAX_URL_LENGTH}\n *\n * @summary Dev-mode assertion that throws when a URL is longer than `MAX_URL_LENGTH`, suggesting a `POST` or `QUERY`\n * request instead.\n * @group Utility Functions\n */\nexport function assertInvalidUrlLength(url: string | undefined): void {\n  assert(\n    `URL length ${url?.length} exceeds the maximum URL length of ${MAX_URL_LENGTH} bytes.\\n\\nConsider converting this request query a \\`/query\\` endpoint instead of a GET, or upgrade the current endpoint to be able to receive a POST request directly (ideally specifying the header HTTP-Method-Override: QUERY)\\n\\nThe Invalid URL is:\\n\\n${url}`,\n    !url || url.length <= MAX_URL_LENGTH\n  );\n}\n"],"mappings":"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"}

package/dist/{index-D6QIwzqm.d.ts → index-Ds06tKwC.d.ts}

@@ -4,6 +4,7 @@ import { QueryParamsSerializationOptions, QueryParamsSource, Serializable } from
  * The global configuration used by {@link buildBaseURL} when a call does
  * not provide its own `host`/`namespace`. Set via {@link setBuildURLConfig}.
  *
+ * @summary The global `host` and `namespace` that `buildBaseURL` prefixes onto URLs when a call does not pass its own.
  * @public
  */
 interface BuildURLConfig {
@@ -23,6 +24,10 @@ interface BuildURLConfig {
  * These values may still be overridden by passing
  * them to buildBaseURL directly.
  *
+ * The [Basic Usage](/guides/the-manual/cookbook/basic-usage#step-2-configure-some-request-defaults)
+ * guide sets these defaults through the `@warp-drive-mirror/utilities/json-api` version of this function,
+ * which also sets this global configuration.
+ *
  * This method may be called as many times as needed.
  * host values of `''` or `'/'` are equivalent.
  *
@@ -49,12 +54,14 @@ interface BuildURLConfig {
  * });
  * ```
  *
+ * @summary Sets the app-wide default `host` and `namespace` used by `buildBaseURL` and the request builders.
  * @public
  */
 declare function setBuildURLConfig(config: BuildURLConfig): void;
 /**
  * {@link buildBaseURL} options for a `findRecord` request.
  *
+ * @summary Options passed to `buildBaseURL` to build the URL for fetching one resource by type and id.
  * @public
  */
 interface FindRecordUrlOptions {
@@ -91,6 +98,7 @@ interface FindRecordUrlOptions {
 /**
  * {@link buildBaseURL} options for a `query` request.
  *
+ * @summary Options passed to `buildBaseURL` to build the URL for querying a collection of one resource type.
  * @public
  */
 interface QueryUrlOptions {
@@ -123,6 +131,8 @@ interface QueryUrlOptions {
 /**
  * {@link buildBaseURL} options for a `findMany` request.
  *
+ * @summary Options passed to `buildBaseURL` to build the URL for fetching several resources, pathed by the first
+ * identifier's type.
  * @public
  */
 interface FindManyUrlOptions {
@@ -159,6 +169,8 @@ interface FindManyUrlOptions {
 /**
  * {@link buildBaseURL} options for a `findRelatedCollection` request.
  *
+ * @summary Options passed to `buildBaseURL` to build the URL for a record's has-many relationship, ending in the
+ * field name.
  * @public
  */
 interface FindRelatedCollectionUrlOptions {
@@ -199,6 +211,8 @@ interface FindRelatedCollectionUrlOptions {
 /**
  * {@link buildBaseURL} options for a `findRelatedRecord` request.
  *
+ * @summary Options passed to `buildBaseURL` to build the URL for a record's belongs-to relationship, ending in the
+ * field name.
  * @public
  */
 interface FindRelatedResourceUrlOptions {
@@ -239,6 +253,7 @@ interface FindRelatedResourceUrlOptions {
 /**
  * {@link buildBaseURL} options for a `createRecord` request.
  *
+ * @summary Options passed to `buildBaseURL` to build the collection URL a new record of a given type is saved to.
  * @public
  */
 interface CreateRecordUrlOptions {
@@ -271,6 +286,7 @@ interface CreateRecordUrlOptions {
 /**
  * {@link buildBaseURL} options for an `updateRecord` request.
  *
+ * @summary Options passed to `buildBaseURL` to build the URL for saving changes to an existing record by type and id.
  * @public
  */
 interface UpdateRecordUrlOptions {
@@ -307,6 +323,7 @@ interface UpdateRecordUrlOptions {
 /**
  * {@link buildBaseURL} options for a `deleteRecord` request.
  *
+ * @summary Options passed to `buildBaseURL` to build the URL for deleting an existing record by type and id.
  * @public
  */
 interface DeleteRecordUrlOptions {
@@ -344,6 +361,7 @@ interface DeleteRecordUrlOptions {
  * {@link buildBaseURL} options for building a URL directly from a `resourcePath`
  * without an associated request operation.
  *
+ * @summary Options passed to `buildBaseURL` to build a URL from an explicit `resourcePath` with no request `op`.
  * @public
  */
 interface GenericUrlOptions {
@@ -373,6 +391,7 @@ interface GenericUrlOptions {
  * - {@link DeleteRecordUrlOptions}
  * - {@link GenericUrlOptions}
  *
+ * @summary Any of the option shapes `buildBaseURL` accepts, one per request `op` plus a generic `resourcePath` form.
  * @public
  */
 type UrlOptions = FindRecordUrlOptions | QueryUrlOptions | FindManyUrlOptions | FindRelatedCollectionUrlOptions | FindRelatedResourceUrlOptions | CreateRecordUrlOptions | UpdateRecordUrlOptions | DeleteRecordUrlOptions | GenericUrlOptions;
@@ -381,6 +400,9 @@ type UrlOptions = FindRecordUrlOptions | QueryUrlOptions | FindManyUrlOptions |
  * Does not include support for building query params (see `buildQueryParams`)
  * so that it may be composed cleanly with other query-params strategies.
  *
+ * See the [Builders](/guides/the-manual/requests/builders) guide for writing your own request
+ * builders.
+ *
  * Usage:
  *
  * ```ts
@@ -410,6 +432,7 @@ type UrlOptions = FindRecordUrlOptions | QueryUrlOptions | FindManyUrlOptions |
  *   - 'findRecord' 'query' 'findMany' 'findRelatedCollection' 'findRelatedRecord'` 'createRecord' 'updateRecord' 'deleteRecord'
  * - Depending on the value of `op`, `identifier` or `identifiers` will be required.
  *
+ * @summary Joins host, namespace, resource path, id, and relationship field into a request URL without query params.
  * @public
  */
 declare function buildBaseURL(urlOptions: UrlOptions): string;
@@ -417,6 +440,11 @@ declare function buildBaseURL(urlOptions: UrlOptions): string;
  * filter out keys of an object that have falsy values or point to empty arrays
  * returning a new object with only those keys that have truthy values / non-empty arrays
  *
+ * See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for
+ * why builders need stable query params.
+ *
+ * @summary Returns a copy of an object without keys whose values are `undefined`, `null`, empty strings, or empty
+ * arrays.
  * @public
  * @param source object to filter keys with empty values from
  * @return A new object with the keys that contained empty values removed
@@ -426,6 +454,9 @@ declare function filterEmpty(source: Record<string, Serializable>): Record<strin
  * Sorts query params by both key and value returning a new URLSearchParams
  * object with the keys inserted in sorted order.
  *
+ * See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for
+ * why builders need stable query params.
+ *
  * Treats `included` specially, splicing it into an array if it is a string and sorting the array.
  *
  * The `params` given are never mutated: neither the object itself nor any array
@@ -440,6 +471,8 @@ declare function filterEmpty(source: Record<string, Serializable>): Record<strin
  * 'repeat': appends the key for every value e.g. `&ids=1&ids=2`
  * 'comma' (default): appends the key once with a comma separated list of values e.g. `&ids=1,2`
  *
+ * @summary Builds a `URLSearchParams` with keys and array values sorted, so equivalent queries produce identical
+ * params.
  * @public
  * @return A {@link URLSearchParams} with keys inserted in sorted order
  */
@@ -447,6 +480,9 @@ declare function sortQueryParams(params: QueryParamsSource, options?: QueryParam
 /**
  * Sorts query params by both key and value, returning a query params string
  *
+ * See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for
+ * why builders need stable query params.
+ *
  * Treats `included` specially, splicing it into an array if it is a string and sorting the array.
  *
  * The `params` given are never mutated: neither the object itself nor any array
@@ -461,10 +497,12 @@ declare function sortQueryParams(params: QueryParamsSource, options?: QueryParam
  * 'repeat': appends the key for every value e.g. `ids=1&ids=2`
  * 'comma' (default): appends the key once with a comma separated list of values e.g. `ids=1,2`
  *
+ * @summary Serializes query params into a string with keys and array values sorted, so equivalent queries share one
+ * URL.
  * @public
  * @return A sorted query params string without the leading `?`
  */
 declare function buildQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): string;
 //#endregion
 export { FindRecordUrlOptions as a, GenericUrlOptions as c, UrlOptions as d, buildBaseURL as f, sortQueryParams as g, setBuildURLConfig as h, FindManyUrlOptions as i, QueryUrlOptions as l, filterEmpty as m, CreateRecordUrlOptions as n, FindRelatedCollectionUrlOptions as o, buildQueryParams as p, DeleteRecordUrlOptions as r, FindRelatedResourceUrlOptions as s, BuildURLConfig as t, UpdateRecordUrlOptions as u };
-//# sourceMappingURL=index-D6QIwzqm.d.ts.map
+//# sourceMappingURL=index-Ds06tKwC.d.ts.map

package/dist/index-Ds06tKwC.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-Ds06tKwC.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;UAqBiB;;;;EAIf;;;;EAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgDc,kBAAkB,QAAQ;;;;;;;UA8BzB;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;;UASe;;;;EAIf;;;;EAIA;;;;IAIE;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;;;UAUe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;;;UASe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;EAIA;;;;;;;;;UAUe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;EAIA;;;;;;;;UASe;;;;EAIf;;;;EAIA;;;;IAIE;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;;UASe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;;UASe;;;;EAIf;;;;EAIA;;;;IAIE;;;;IAIA;;;;;EAKF;;;;EAIA;;;;EAIA;;;;;;;;;UAUe;;;;EAIf;;;;EAIA;;;;EAIA;;;;;;;;;;;;;;;;;;KAmBU,aACR,uBACA,kBACA,qBACA,kCACA,gCACA,yBACA,yBACA,yBACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyEY,aAAa,YAAY;;;;;;;;;;;;;;iBAiIzB,YAAY,QAAQ,eAAe,gBAAgB,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwClE,gBAAgB,QAAQ,mBAAmB,UAAU,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwFvF,iBAAiB,QAAQ,mBAAmB,UAAU"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { a as FindRecordUrlOptions, c as GenericUrlOptions, d as UrlOptions, f as buildBaseURL, g as sortQueryParams, h as setBuildURLConfig, i as FindManyUrlOptions, l as QueryUrlOptions, m as filterEmpty, n as CreateRecordUrlOptions, o as FindRelatedCollectionUrlOptions, p as buildQueryParams, r as DeleteRecordUrlOptions, s as FindRelatedResourceUrlOptions, t as BuildURLConfig, u as UpdateRecordUrlOptions } from "./index-D6QIwzqm.js";
+import { a as FindRecordUrlOptions, c as GenericUrlOptions, d as UrlOptions, f as buildBaseURL, g as sortQueryParams, h as setBuildURLConfig, i as FindManyUrlOptions, l as QueryUrlOptions, m as filterEmpty, n as CreateRecordUrlOptions, o as FindRelatedCollectionUrlOptions, p as buildQueryParams, r as DeleteRecordUrlOptions, s as FindRelatedResourceUrlOptions, t as BuildURLConfig, u as UpdateRecordUrlOptions } from "./index-Ds06tKwC.js";
 export { BuildURLConfig, CreateRecordUrlOptions, DeleteRecordUrlOptions, FindManyUrlOptions, FindRecordUrlOptions, FindRelatedCollectionUrlOptions, FindRelatedResourceUrlOptions, GenericUrlOptions, QueryUrlOptions, UpdateRecordUrlOptions, UrlOptions, buildBaseURL, buildQueryParams, filterEmpty, setBuildURLConfig, sortQueryParams };

package/dist/index.js

@@ -3,6 +3,7 @@ import { getGlobalConfig, macroCondition } from "@embroider/macros";
 
 //#region src/index.ts
 /**
+* @summary Helpers for building request URLs and sorted query strings, with a configurable global host and namespace.
 * @module
 * @mergeModuleWith <project>
 */
@@ -10,6 +11,7 @@ import { getGlobalConfig, macroCondition } from "@embroider/macros";
 * The global configuration used by {@link buildBaseURL} when a call does
 * not provide its own `host`/`namespace`. Set via {@link setBuildURLConfig}.
 *
+* @summary The global `host` and `namespace` that `buildBaseURL` prefixes onto URLs when a call does not pass its own.
 * @public
 */
 const CONFIG = getOrSetGlobal("CONFIG", {
@@ -23,6 +25,10 @@ const CONFIG = getOrSetGlobal("CONFIG", {
 * These values may still be overridden by passing
 * them to buildBaseURL directly.
 *
+* The [Basic Usage](/guides/the-manual/cookbook/basic-usage#step-2-configure-some-request-defaults)
+* guide sets these defaults through the `@warp-drive-mirror/utilities/json-api` version of this function,
+* which also sets this global configuration.
+*
 * This method may be called as many times as needed.
 * host values of `''` or `'/'` are equivalent.
 *
@@ -49,6 +55,7 @@ const CONFIG = getOrSetGlobal("CONFIG", {
 * });
 * ```
 *
+* @summary Sets the app-wide default `host` and `namespace` used by `buildBaseURL` and the request builders.
 * @public
 */
 function setBuildURLConfig(config) {
@@ -73,47 +80,59 @@ function setBuildURLConfig(config) {
 /**
 * {@link buildBaseURL} options for a `findRecord` request.
 *
+* @summary Options passed to `buildBaseURL` to build the URL for fetching one resource by type and id.
 * @public
 */
 /**
 * {@link buildBaseURL} options for a `query` request.
 *
+* @summary Options passed to `buildBaseURL` to build the URL for querying a collection of one resource type.
 * @public
 */
 /**
 * {@link buildBaseURL} options for a `findMany` request.
 *
+* @summary Options passed to `buildBaseURL` to build the URL for fetching several resources, pathed by the first
+* identifier's type.
 * @public
 */
 /**
 * {@link buildBaseURL} options for a `findRelatedCollection` request.
 *
+* @summary Options passed to `buildBaseURL` to build the URL for a record's has-many relationship, ending in the
+* field name.
 * @public
 */
 /**
 * {@link buildBaseURL} options for a `findRelatedRecord` request.
 *
+* @summary Options passed to `buildBaseURL` to build the URL for a record's belongs-to relationship, ending in the
+* field name.
 * @public
 */
 /**
 * {@link buildBaseURL} options for a `createRecord` request.
 *
+* @summary Options passed to `buildBaseURL` to build the collection URL a new record of a given type is saved to.
 * @public
 */
 /**
 * {@link buildBaseURL} options for an `updateRecord` request.
 *
+* @summary Options passed to `buildBaseURL` to build the URL for saving changes to an existing record by type and id.
 * @public
 */
 /**
 * {@link buildBaseURL} options for a `deleteRecord` request.
 *
+* @summary Options passed to `buildBaseURL` to build the URL for deleting an existing record by type and id.
 * @public
 */
 /**
 * {@link buildBaseURL} options for building a URL directly from a `resourcePath`
 * without an associated request operation.
 *
+* @summary Options passed to `buildBaseURL` to build a URL from an explicit `resourcePath` with no request `op`.
 * @public
 */
 /**
@@ -129,6 +148,7 @@ function setBuildURLConfig(config) {
 * - {@link DeleteRecordUrlOptions}
 * - {@link GenericUrlOptions}
 *
+* @summary Any of the option shapes `buildBaseURL` accepts, one per request `op` plus a generic `resourcePath` form.
 * @public
 */
 const OPERATIONS_WITH_PRIMARY_RECORDS = /* @__PURE__ */ new Set([
@@ -155,6 +175,9 @@ function resourcePathForType(options) {
 * Does not include support for building query params (see `buildQueryParams`)
 * so that it may be composed cleanly with other query-params strategies.
 *
+* See the [Builders](/guides/the-manual/requests/builders) guide for writing your own request
+* builders.
+*
 * Usage:
 *
 * ```ts
@@ -184,6 +207,7 @@ function resourcePathForType(options) {
 *   - 'findRecord' 'query' 'findMany' 'findRelatedCollection' 'findRelatedRecord'` 'createRecord' 'updateRecord' 'deleteRecord'
 * - Depending on the value of `op`, `identifier` or `identifiers` will be required.
 *
+* @summary Joins host, namespace, resource path, id, and relationship field into a request URL without query params.
 * @public
 */
 function buildBaseURL(urlOptions) {
@@ -285,6 +309,11 @@ function handleInclude(include) {
 * filter out keys of an object that have falsy values or point to empty arrays
 * returning a new object with only those keys that have truthy values / non-empty arrays
 *
+* See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for
+* why builders need stable query params.
+*
+* @summary Returns a copy of an object without keys whose values are `undefined`, `null`, empty strings, or empty
+* arrays.
 * @public
 * @param source object to filter keys with empty values from
 * @return A new object with the keys that contained empty values removed
@@ -303,6 +332,9 @@ function filterEmpty(source) {
 * Sorts query params by both key and value returning a new URLSearchParams
 * object with the keys inserted in sorted order.
 *
+* See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for
+* why builders need stable query params.
+*
 * Treats `included` specially, splicing it into an array if it is a string and sorting the array.
 *
 * The `params` given are never mutated: neither the object itself nor any array
@@ -317,6 +349,8 @@ function filterEmpty(source) {
 * 'repeat': appends the key for every value e.g. `&ids=1&ids=2`
 * 'comma' (default): appends the key once with a comma separated list of values e.g. `&ids=1,2`
 *
+* @summary Builds a `URLSearchParams` with keys and array values sorted, so equivalent queries produce identical
+* params.
 * @public
 * @return A {@link URLSearchParams} with keys inserted in sorted order
 */
@@ -365,6 +399,9 @@ function sortQueryParams(params, options) {
 /**
 * Sorts query params by both key and value, returning a query params string
 *
+* See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for
+* why builders need stable query params.
+*
 * Treats `included` specially, splicing it into an array if it is a string and sorting the array.
 *
 * The `params` given are never mutated: neither the object itself nor any array
@@ -379,6 +416,8 @@ function sortQueryParams(params, options) {
 * 'repeat': appends the key for every value e.g. `ids=1&ids=2`
 * 'comma' (default): appends the key once with a comma separated list of values e.g. `ids=1,2`
 *
+* @summary Serializes query params into a string with keys and array values sorted, so equivalent queries share one
+* URL.
 * @public
 * @return A sorted query params string without the leading `?`
 */