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

package/dist/active-record.js.map

@@ -1 +1 @@
-{"version":3,"file":"active-record.js","names":["recordIdentifierFor","buildBaseURL","pluralize","underscore","copyForwardUrlOptions","macroCondition","getGlobalConfig","isExisting","identifier","id","type","deleteRecord","record","options","WarpDrive","env","DEBUG","test","Error","urlOptions","op","resourcePath","url","headers","Headers","append","method","data","records","createRecord","updateRecord","patch"],"sources":["../src/-private/active-record/find-record.ts","../src/-private/active-record/query.ts","../src/-private/active-record/save-record.ts"],"sourcesContent":["import type { ReactiveDataDocument } from '@warp-drive-mirror/core/reactive';\nimport type { TypeFromInstance } from '@warp-drive-mirror/core/types/record';\nimport type {\n  FindRecordOptions,\n  FindRecordRequestOptions,\n  RemotelyAccessibleIdentifier,\n} from '@warp-drive-mirror/core/types/request';\nimport type { Meta } from '@warp-drive-mirror/core/types/spec/json-api-raw';\n\nimport { buildBaseURL, buildQueryParams, type FindRecordUrlOptions } from '../../index.ts';\nimport { pluralize, underscore } from '../../string.ts';\nimport { copyForwardUrlOptions, extractCacheOptions } from '../builder-utils.ts';\n\n/**\n * Builds request options to fetch a single resource by a known id or identifier\n * configured for the url and header expectations of most ActiveRecord APIs.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { findRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const data = await store.request(findRecord('person', '1'));\n * ```\n *\n * **With Options**\n *\n * ```ts\n * import { findRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = findRecord('person', '1', { include: ['pets', 'friends'] });\n * const data = await store.request(options);\n * ```\n *\n * **With an Identifier**\n *\n * ```ts\n * import { findRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = findRecord({ type: 'person', id: '1' }, { include: ['pets', 'friends'] });\n * const data = await store.request(options);\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing and underscoring the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { findRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = findRecord('person', '1', { include: ['pets', 'friends'] }, { namespace: 'api/v2' });\n * const data = await store.request(options);\n * ```\n *\n * @public\n * @param identifier\n * @param options\n */\nexport function findRecord<T, M extends Meta | undefined = Meta | undefined, E extends object = object>(\n  identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>,\n  options?: FindRecordOptions\n): FindRecordRequestOptions<ReactiveDataDocument<T, M, E>, T>;\nexport function findRecord(\n  identifier: RemotelyAccessibleIdentifier,\n  options?: FindRecordOptions\n): FindRecordRequestOptions;\nexport function findRecord<T, M extends Meta | undefined = Meta | undefined, E extends object = object>(\n  type: TypeFromInstance<T>,\n  id: string,\n  options?: FindRecordOptions\n): FindRecordRequestOptions<ReactiveDataDocument<T, M, E>, T>;\nexport function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;\nexport function findRecord(\n  arg1: string | RemotelyAccessibleIdentifier,\n  arg2: string | FindRecordOptions | undefined,\n  arg3?: FindRecordOptions\n): FindRecordRequestOptions {\n  const identifier: RemotelyAccessibleIdentifier = typeof arg1 === 'string' ? { type: arg1, id: arg2 as string } : arg1;\n  const options = ((typeof arg1 === 'string' ? arg3 : arg2) || {}) as FindRecordOptions;\n  const cacheOptions = extractCacheOptions(options);\n  const urlOptions: FindRecordUrlOptions = {\n    identifier,\n    op: 'findRecord',\n    resourcePath: pluralize(underscore(identifier.type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n\n  return {\n    url: options.include?.length\n      ? `${url}?${buildQueryParams({ include: options.include }, options.urlParamsSettings)}`\n      : url,\n    method: 'GET',\n    headers,\n    cacheOptions,\n    op: 'findRecord',\n    records: [identifier],\n  };\n}\n\n/** @deprecated use {@link ReactiveDataDocument} instead */\nexport type FindRecordResultDocument<\n  T,\n  M extends Meta | undefined = Meta | undefined,\n  E extends object = object,\n> = ReactiveDataDocument<T, M, E>;\n","import type { ReactiveDataDocument } from '@warp-drive-mirror/core/reactive';\nimport type { QueryParamsSource } from '@warp-drive-mirror/core/types/params';\nimport type { TypeFromInstance } from '@warp-drive-mirror/core/types/record';\nimport type { ConstrainedRequestOptions, QueryRequestOptions } from '@warp-drive-mirror/core/types/request';\nimport type { Meta } from '@warp-drive-mirror/core/types/spec/json-api-raw';\n\nimport { buildBaseURL, buildQueryParams, type QueryUrlOptions } from '../../index.ts';\nimport { pluralize, underscore } from '../../string';\nimport { copyForwardUrlOptions, extractCacheOptions } from '../builder-utils.ts';\n\n/**\n * Builds request options to query for resources, usually by a primary\n * type, configured for the url and header expectations of most ActiveRecord APIs.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { query } from '@warp-drive-mirror/utilities/active-record';\n *\n * const data = await store.request(query('person'));\n * ```\n *\n * **With Query Params**\n *\n * ```ts\n * import { query } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = query('person', { include: ['pets', 'friends'] });\n * const data = await store.request(options);\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing and underscoring the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { query } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = query('person', { include: ['pets', 'friends'] }, { reload: true });\n * const data = await store.request(options);\n * ```\n *\n * @public\n * @param identifier\n * @param query\n * @param options\n */\nexport function query<T, M extends Meta | undefined = Meta | undefined, E extends object = object>(\n  type: TypeFromInstance<T>,\n  query?: QueryParamsSource,\n  options?: ConstrainedRequestOptions\n): QueryRequestOptions<ReactiveDataDocument<T[], M, E>>;\nexport function query(\n  type: string,\n  query?: QueryParamsSource,\n  options?: ConstrainedRequestOptions\n): QueryRequestOptions;\nexport function query(\n  type: string,\n  // oxlint-disable-next-line no-shadow\n  query: QueryParamsSource = {},\n  options: ConstrainedRequestOptions = {}\n): QueryRequestOptions {\n  const cacheOptions = extractCacheOptions(options);\n  const urlOptions: QueryUrlOptions = {\n    identifier: { type },\n    op: 'query',\n    resourcePath: pluralize(underscore(type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n  const queryString = buildQueryParams(query, options.urlParamsSettings);\n\n  return {\n    url: queryString ? `${url}?${queryString}` : url,\n    method: 'GET',\n    headers,\n    cacheOptions,\n    op: 'query',\n  };\n}\n","import { recordIdentifierFor } from '@warp-drive-mirror/core';\nimport { assert } from '@warp-drive-mirror/core/build-config/macros';\nimport type { ReactiveDataDocument } from '@warp-drive-mirror/core/reactive';\nimport type { PersistedResourceKey, ResourceKey } from '@warp-drive-mirror/core/types/identifier';\nimport type { TypedRecordInstance } from '@warp-drive-mirror/core/types/record';\nimport type {\n  ConstrainedRequestOptions,\n  CreateRequestOptions,\n  DeleteRequestOptions,\n  UpdateRequestOptions,\n} from '@warp-drive-mirror/core/types/request';\nimport type { Meta } from '@warp-drive-mirror/core/types/spec/json-api-raw';\n\nimport {\n  buildBaseURL,\n  type CreateRecordUrlOptions,\n  type DeleteRecordUrlOptions,\n  type UpdateRecordUrlOptions,\n} from '../../index.ts';\nimport { pluralize, underscore } from '../../string';\nimport { copyForwardUrlOptions } from '../builder-utils.ts';\n\nfunction isExisting(identifier: ResourceKey): identifier is PersistedResourceKey {\n  return 'id' in identifier && identifier.id !== null && 'type' in identifier && identifier.type !== null;\n}\n\n/**\n * Builds request options to delete record for resources,\n * configured for the url, method and header expectations of ActiveRecord APIs.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { deleteRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.peekRecord('person', '1');\n *\n * // mark record as deleted\n * store.deleteRecord(person);\n *\n * // persist deletion\n * const data = await store.request(deleteRecord(person));\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { deleteRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.peekRecord('person', '1');\n *\n * // mark record as deleted\n * store.deleteRecord(person);\n *\n * // persist deletion\n * const options = deleteRecord(person, { namespace: 'api/v1' });\n * const data = await store.request(options);\n * ```\n *\n * @public\n * @param record\n * @param options\n */\nexport function deleteRecord<T>(record: T, options?: ConstrainedRequestOptions): DeleteRequestOptions<T>;\nexport function deleteRecord(record: unknown, options?: ConstrainedRequestOptions): DeleteRequestOptions;\nexport function deleteRecord(record: unknown, options: ConstrainedRequestOptions = {}): DeleteRequestOptions {\n  const identifier = recordIdentifierFor(record);\n  assert(`Expected to be given a record instance`, identifier);\n  assert(`Cannot delete a record that does not have an associated type and id.`, isExisting(identifier));\n\n  const urlOptions: DeleteRecordUrlOptions = {\n    identifier: identifier,\n    op: 'deleteRecord',\n    resourcePath: pluralize(underscore(identifier.type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n\n  return {\n    url,\n    method: 'DELETE',\n    headers,\n    op: 'deleteRecord',\n    data: {\n      record: identifier,\n    },\n    records: [identifier],\n  };\n}\n\n/**\n * Builds request options to create new record for resources,\n * configured for the url, method and header expectations of most ActiveRecord APIs.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { createRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.createRecord('person', { name: 'Ted' });\n * const data = await store.request(createRecord(person));\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { createRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.createRecord('person', { name: 'Ted' });\n * const options = createRecord(person, { namespace: 'api/v1' });\n * const data = await store.request(options);\n * ```\n *\n * @public\n * @param record\n * @param options\n */\nexport function createRecord<T>(record: T, options?: ConstrainedRequestOptions): CreateRequestOptions<T>;\nexport function createRecord(record: unknown, options?: ConstrainedRequestOptions): CreateRequestOptions;\nexport function createRecord(record: unknown, options: ConstrainedRequestOptions = {}): CreateRequestOptions {\n  const identifier = recordIdentifierFor(record);\n  assert(`Expected to be given a record instance`, identifier);\n\n  const urlOptions: CreateRecordUrlOptions = {\n    identifier: identifier,\n    op: 'createRecord',\n    resourcePath: pluralize(underscore(identifier.type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n\n  return {\n    url,\n    method: 'POST',\n    headers,\n    op: 'createRecord',\n    data: {\n      record: identifier,\n    },\n    records: [identifier],\n  };\n}\n\n/**\n * Builds request options to update existing record for resources,\n * configured for the url, method and header expectations of most ActiveRecord APIs.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { updateRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.peekRecord('person', '1');\n * person.name = 'Chris';\n * const data = await store.request(updateRecord(person));\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `patch` - Allows caller to specify whether to use a PATCH request instead of a PUT request, defaults to `false`.\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { updateRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.peekRecord('person', '1');\n * person.name = 'Chris';\n * const options = updateRecord(person, { patch: true });\n * const data = await store.request(options);\n * ```\n *\n * @public\n * @param record\n * @param options\n */\nexport function updateRecord<\n  T extends TypedRecordInstance,\n  RT extends TypedRecordInstance = T,\n  M extends Meta | undefined = Meta | undefined,\n  E extends object = object,\n>(\n  record: T,\n  options?: ConstrainedRequestOptions & { patch?: boolean }\n): UpdateRequestOptions<ReactiveDataDocument<RT, M, E>, T>;\nexport function updateRecord(\n  record: unknown,\n  options?: ConstrainedRequestOptions & { patch?: boolean }\n): UpdateRequestOptions;\nexport function updateRecord(\n  record: unknown,\n  options: ConstrainedRequestOptions & { patch?: boolean } = {}\n): UpdateRequestOptions {\n  const identifier = recordIdentifierFor(record);\n  assert(`Expected to be given a record instance`, identifier);\n  assert(`Cannot update a record that does not have an associated type and id.`, isExisting(identifier));\n\n  const urlOptions: UpdateRecordUrlOptions = {\n    identifier: identifier,\n    op: 'updateRecord',\n    resourcePath: pluralize(underscore(identifier.type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n\n  return {\n    url,\n    method: options.patch ? 'PATCH' : 'PUT',\n    headers,\n    op: 'updateRecord',\n    data: {\n      record: identifier,\n    },\n    records: [identifier],\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"active-record.js","names":["recordIdentifierFor","buildBaseURL","pluralize","underscore","copyForwardUrlOptions","macroCondition","getGlobalConfig","isExisting","identifier","id","type","deleteRecord","record","options","WarpDrive","env","DEBUG","test","Error","urlOptions","op","resourcePath","url","headers","Headers","append","method","data","records","createRecord","updateRecord","patch"],"sources":["../src/-private/active-record/find-record.ts","../src/-private/active-record/query.ts","../src/-private/active-record/save-record.ts"],"sourcesContent":["import type { ReactiveDataDocument } from '@warp-drive-mirror/core/reactive';\nimport type { TypeFromInstance } from '@warp-drive-mirror/core/types/record';\nimport type {\n  FindRecordOptions,\n  FindRecordRequestOptions,\n  RemotelyAccessibleIdentifier,\n} from '@warp-drive-mirror/core/types/request';\nimport type { Meta } from '@warp-drive-mirror/core/types/spec/json-api-raw';\n\nimport { buildBaseURL, buildQueryParams, type FindRecordUrlOptions } from '../../index.ts';\nimport { pluralize, underscore } from '../../string.ts';\nimport { copyForwardUrlOptions, extractCacheOptions } from '../builder-utils.ts';\n\n/**\n * Builds request options to fetch a single resource by a known id or identifier\n * configured for the url and header expectations of most ActiveRecord APIs.\n *\n * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and\n * when to use one.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { findRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const data = await store.request(findRecord('person', '1'));\n * ```\n *\n * **With Options**\n *\n * ```ts\n * import { findRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = findRecord('person', '1', { include: ['pets', 'friends'] });\n * const data = await store.request(options);\n * ```\n *\n * **With an Identifier**\n *\n * ```ts\n * import { findRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = findRecord({ type: 'person', id: '1' }, { include: ['pets', 'friends'] });\n * const data = await store.request(options);\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing and underscoring the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { findRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = findRecord('person', '1', { include: ['pets', 'friends'] }, { namespace: 'api/v2' });\n * const data = await store.request(options);\n * ```\n *\n * @summary Builds a `GET` request for one resource by type and id, using ActiveRecord-style pluralized, underscored\n * URLs.\n * @public\n * @param identifier\n * @param options\n */\nexport function findRecord<T, M extends Meta | undefined = Meta | undefined, E extends object = object>(\n  identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>,\n  options?: FindRecordOptions\n): FindRecordRequestOptions<ReactiveDataDocument<T, M, E>, T>;\nexport function findRecord(\n  identifier: RemotelyAccessibleIdentifier,\n  options?: FindRecordOptions\n): FindRecordRequestOptions;\nexport function findRecord<T, M extends Meta | undefined = Meta | undefined, E extends object = object>(\n  type: TypeFromInstance<T>,\n  id: string,\n  options?: FindRecordOptions\n): FindRecordRequestOptions<ReactiveDataDocument<T, M, E>, T>;\nexport function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;\nexport function findRecord(\n  arg1: string | RemotelyAccessibleIdentifier,\n  arg2: string | FindRecordOptions | undefined,\n  arg3?: FindRecordOptions\n): FindRecordRequestOptions {\n  const identifier: RemotelyAccessibleIdentifier = typeof arg1 === 'string' ? { type: arg1, id: arg2 as string } : arg1;\n  const options = ((typeof arg1 === 'string' ? arg3 : arg2) || {}) as FindRecordOptions;\n  const cacheOptions = extractCacheOptions(options);\n  const urlOptions: FindRecordUrlOptions = {\n    identifier,\n    op: 'findRecord',\n    resourcePath: pluralize(underscore(identifier.type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n\n  return {\n    url: options.include?.length\n      ? `${url}?${buildQueryParams({ include: options.include }, options.urlParamsSettings)}`\n      : url,\n    method: 'GET',\n    headers,\n    cacheOptions,\n    op: 'findRecord',\n    records: [identifier],\n  };\n}\n\n/** @deprecated use {@link ReactiveDataDocument} instead */\nexport type FindRecordResultDocument<\n  T,\n  M extends Meta | undefined = Meta | undefined,\n  E extends object = object,\n> = ReactiveDataDocument<T, M, E>;\n","import type { ReactiveDataDocument } from '@warp-drive-mirror/core/reactive';\nimport type { QueryParamsSource } from '@warp-drive-mirror/core/types/params';\nimport type { TypeFromInstance } from '@warp-drive-mirror/core/types/record';\nimport type { ConstrainedRequestOptions, QueryRequestOptions } from '@warp-drive-mirror/core/types/request';\nimport type { Meta } from '@warp-drive-mirror/core/types/spec/json-api-raw';\n\nimport { buildBaseURL, buildQueryParams, type QueryUrlOptions } from '../../index.ts';\nimport { pluralize, underscore } from '../../string';\nimport { copyForwardUrlOptions, extractCacheOptions } from '../builder-utils.ts';\n\n/**\n * Builds request options to query for resources, usually by a primary\n * type, configured for the url and header expectations of most ActiveRecord APIs.\n *\n * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and\n * when to use one.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { query } from '@warp-drive-mirror/utilities/active-record';\n *\n * const data = await store.request(query('person'));\n * ```\n *\n * **With Query Params**\n *\n * ```ts\n * import { query } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = query('person', { include: ['pets', 'friends'] });\n * const data = await store.request(options);\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing and underscoring the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { query } from '@warp-drive-mirror/utilities/active-record';\n *\n * const options = query('person', { include: ['pets', 'friends'] }, { reload: true });\n * const data = await store.request(options);\n * ```\n *\n * @summary Builds a `GET` request that queries a resource type with query params, using ActiveRecord-style URLs.\n * @public\n * @param identifier\n * @param query\n * @param options\n */\nexport function query<T, M extends Meta | undefined = Meta | undefined, E extends object = object>(\n  type: TypeFromInstance<T>,\n  query?: QueryParamsSource,\n  options?: ConstrainedRequestOptions\n): QueryRequestOptions<ReactiveDataDocument<T[], M, E>>;\nexport function query(\n  type: string,\n  query?: QueryParamsSource,\n  options?: ConstrainedRequestOptions\n): QueryRequestOptions;\nexport function query(\n  type: string,\n  // oxlint-disable-next-line no-shadow\n  query: QueryParamsSource = {},\n  options: ConstrainedRequestOptions = {}\n): QueryRequestOptions {\n  const cacheOptions = extractCacheOptions(options);\n  const urlOptions: QueryUrlOptions = {\n    identifier: { type },\n    op: 'query',\n    resourcePath: pluralize(underscore(type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n  const queryString = buildQueryParams(query, options.urlParamsSettings);\n\n  return {\n    url: queryString ? `${url}?${queryString}` : url,\n    method: 'GET',\n    headers,\n    cacheOptions,\n    op: 'query',\n  };\n}\n","import { recordIdentifierFor } from '@warp-drive-mirror/core';\nimport { assert } from '@warp-drive-mirror/core/build-config/macros';\nimport type { ReactiveDataDocument } from '@warp-drive-mirror/core/reactive';\nimport type { PersistedResourceKey, ResourceKey } from '@warp-drive-mirror/core/types/identifier';\nimport type { TypedRecordInstance } from '@warp-drive-mirror/core/types/record';\nimport type {\n  ConstrainedRequestOptions,\n  CreateRequestOptions,\n  DeleteRequestOptions,\n  UpdateRequestOptions,\n} from '@warp-drive-mirror/core/types/request';\nimport type { Meta } from '@warp-drive-mirror/core/types/spec/json-api-raw';\n\nimport {\n  buildBaseURL,\n  type CreateRecordUrlOptions,\n  type DeleteRecordUrlOptions,\n  type UpdateRecordUrlOptions,\n} from '../../index.ts';\nimport { pluralize, underscore } from '../../string';\nimport { copyForwardUrlOptions } from '../builder-utils.ts';\n\nfunction isExisting(identifier: ResourceKey): identifier is PersistedResourceKey {\n  return 'id' in identifier && identifier.id !== null && 'type' in identifier && identifier.type !== null;\n}\n\n/**\n * Builds request options to delete record for resources,\n * configured for the url, method and header expectations of ActiveRecord APIs.\n *\n * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and\n * when to use one.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { deleteRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.peekRecord('person', '1');\n *\n * // mark record as deleted\n * store.deleteRecord(person);\n *\n * // persist deletion\n * const data = await store.request(deleteRecord(person));\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { deleteRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.peekRecord('person', '1');\n *\n * // mark record as deleted\n * store.deleteRecord(person);\n *\n * // persist deletion\n * const options = deleteRecord(person, { namespace: 'api/v1' });\n * const data = await store.request(options);\n * ```\n *\n * @summary Builds a `DELETE` request that persists deletion of an existing record, using ActiveRecord-style URLs.\n * @public\n * @param record\n * @param options\n */\nexport function deleteRecord<T>(record: T, options?: ConstrainedRequestOptions): DeleteRequestOptions<T>;\nexport function deleteRecord(record: unknown, options?: ConstrainedRequestOptions): DeleteRequestOptions;\nexport function deleteRecord(record: unknown, options: ConstrainedRequestOptions = {}): DeleteRequestOptions {\n  const identifier = recordIdentifierFor(record);\n  assert(`Expected to be given a record instance`, identifier);\n  assert(`Cannot delete a record that does not have an associated type and id.`, isExisting(identifier));\n\n  const urlOptions: DeleteRecordUrlOptions = {\n    identifier: identifier,\n    op: 'deleteRecord',\n    resourcePath: pluralize(underscore(identifier.type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n\n  return {\n    url,\n    method: 'DELETE',\n    headers,\n    op: 'deleteRecord',\n    data: {\n      record: identifier,\n    },\n    records: [identifier],\n  };\n}\n\n/**\n * Builds request options to create new record for resources,\n * configured for the url, method and header expectations of most ActiveRecord APIs.\n *\n * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and\n * when to use one.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { createRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.createRecord('person', { name: 'Ted' });\n * const data = await store.request(createRecord(person));\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { createRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.createRecord('person', { name: 'Ted' });\n * const options = createRecord(person, { namespace: 'api/v1' });\n * const data = await store.request(options);\n * ```\n *\n * @summary Builds a `POST` request that saves a newly created record, using ActiveRecord-style URLs.\n * @public\n * @param record\n * @param options\n */\nexport function createRecord<T>(record: T, options?: ConstrainedRequestOptions): CreateRequestOptions<T>;\nexport function createRecord(record: unknown, options?: ConstrainedRequestOptions): CreateRequestOptions;\nexport function createRecord(record: unknown, options: ConstrainedRequestOptions = {}): CreateRequestOptions {\n  const identifier = recordIdentifierFor(record);\n  assert(`Expected to be given a record instance`, identifier);\n\n  const urlOptions: CreateRecordUrlOptions = {\n    identifier: identifier,\n    op: 'createRecord',\n    resourcePath: pluralize(underscore(identifier.type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n\n  return {\n    url,\n    method: 'POST',\n    headers,\n    op: 'createRecord',\n    data: {\n      record: identifier,\n    },\n    records: [identifier],\n  };\n}\n\n/**\n * Builds request options to update existing record for resources,\n * configured for the url, method and header expectations of most ActiveRecord APIs.\n *\n * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and\n * when to use one.\n *\n * **Basic Usage**\n *\n * ```ts\n * import { updateRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.peekRecord('person', '1');\n * person.name = 'Chris';\n * const data = await store.request(updateRecord(person));\n * ```\n *\n * **Supplying Options to Modify the Request Behavior**\n *\n * The following options are supported:\n *\n * - `patch` - Allows caller to specify whether to use a PATCH request instead of a PUT request, defaults to `false`.\n * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.\n * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.\n * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type\n * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this\n *      option will delegate to the store's CachePolicy, defaulting to `false` if none is configured.\n * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the\n *      promise with the cached value, not supplying this option will delegate to the store's CachePolicy,\n *      defaulting to `false` if none is configured.\n * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)\n *\n * ```ts\n * import { updateRecord } from '@warp-drive-mirror/utilities/active-record';\n *\n * const person = store.peekRecord('person', '1');\n * person.name = 'Chris';\n * const options = updateRecord(person, { patch: true });\n * const data = await store.request(options);\n * ```\n *\n * @summary Builds a `PUT` (or `PATCH`) request that saves changes to an existing record, using ActiveRecord-style URLs.\n * @public\n * @param record\n * @param options\n */\nexport function updateRecord<\n  T extends TypedRecordInstance,\n  RT extends TypedRecordInstance = T,\n  M extends Meta | undefined = Meta | undefined,\n  E extends object = object,\n>(\n  record: T,\n  options?: ConstrainedRequestOptions & { patch?: boolean }\n): UpdateRequestOptions<ReactiveDataDocument<RT, M, E>, T>;\nexport function updateRecord(\n  record: unknown,\n  options?: ConstrainedRequestOptions & { patch?: boolean }\n): UpdateRequestOptions;\nexport function updateRecord(\n  record: unknown,\n  options: ConstrainedRequestOptions & { patch?: boolean } = {}\n): UpdateRequestOptions {\n  const identifier = recordIdentifierFor(record);\n  assert(`Expected to be given a record instance`, identifier);\n  assert(`Cannot update a record that does not have an associated type and id.`, isExisting(identifier));\n\n  const urlOptions: UpdateRecordUrlOptions = {\n    identifier: identifier,\n    op: 'updateRecord',\n    resourcePath: pluralize(underscore(identifier.type)),\n  };\n\n  copyForwardUrlOptions(urlOptions, options);\n\n  const url = buildBaseURL(urlOptions);\n  const headers = new Headers();\n  headers.append('Accept', 'application/json;charset=utf-8');\n\n  return {\n    url,\n    method: options.patch ? 'PATCH' : 'PUT',\n    headers,\n    op: 'updateRecord',\n    data: {\n      record: identifier,\n    },\n    records: [identifier],\n  };\n}\n"],"mappings":";;;;;;;AAuFA,SAAgB,WACd,MACA,MACA,MAC0B;CAC1B,MAAM,aAA2C,OAAO,SAAS,WAAW;EAAE,MAAM;EAAM,IAAI;CAAe,IAAI;CACjH,MAAM,WAAY,OAAO,SAAS,WAAW,OAAO,SAAS,CAAC;CAC9D,MAAM,eAAe,oBAAoB,OAAO;CAChD,MAAM,aAAmC;EACvC;EACA,IAAI;EACJ,cAAc,UAAU,WAAW,WAAW,IAAI,CAAC;CACrD;CAEA,sBAAsB,YAAY,OAAO;CAEzC,MAAM,MAAM,aAAa,UAAU;CACnC,MAAM,UAAU,IAAI,QAAQ;CAC5B,QAAQ,OAAO,UAAU,gCAAgC;CAEzD,OAAO;EACL,KAAK,QAAQ,SAAS,SAClB,GAAG,IAAI,GAAG,iBAAiB,EAAE,SAAS,QAAQ,QAAQ,GAAG,QAAQ,iBAAiB,MAClF;EACJ,QAAQ;EACR;EACA;EACA,IAAI;EACJ,SAAS,CAAC,UAAU;CACtB;AACF;;;;AC9CA,SAAgB,MACd,MAEA,QAA2B,CAAC,GAC5B,UAAqC,CAAC,GACjB;CACrB,MAAM,eAAe,oBAAoB,OAAO;CAChD,MAAM,aAA8B;EAClC,YAAY,EAAE,KAAK;EACnB,IAAI;EACJ,cAAc,UAAU,WAAW,IAAI,CAAC;CAC1C;CAEA,sBAAsB,YAAY,OAAO;CAEzC,MAAM,MAAM,aAAa,UAAU;CACnC,MAAM,UAAU,IAAI,QAAQ;CAC5B,QAAQ,OAAO,UAAU,gCAAgC;CACzD,MAAM,cAAc,iBAAiB,OAAO,QAAQ,iBAAiB;CAErE,OAAO;EACL,KAAK,cAAc,GAAG,IAAI,GAAG,gBAAgB;EAC7C,QAAQ;EACR;EACA;EACA,IAAI;CACN;AACF;;;;AC5EA,SAASO,WAAWC,YAA6D;CAC/E,OAAO,QAAQA,cAAcA,WAAWC,OAAO,QAAQ,UAAUD,cAAcA,WAAWE,SAAS;AACrG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgBC,aAAaC,QAAiBC,UAAqC,CAAC,GAAyB;CAC3G,MAAML,aAAaR,oBAAoBY,MAAM;CAC7CP,eAAAC,gBAAA,CAAA,CAAAQ,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,wCAAwC;CAAA,EAAA,CAAEV,UAAU;CAC3DH,eAAAC,gBAAA,CAAA,CAAAQ,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,sEAAsE;CAAA,EAAA,CAAEX,WAAWC,UAAU,CAAC;CAErG,MAAMW,aAAqC;EAC7BX;EACZY,IAAI;EACJC,cAAcnB,UAAUC,WAAWK,WAAWE,IAAI,CAAC;CACrD;CAEAN,sBAAsBe,YAAYN,OAAO;CAEzC,MAAMS,MAAMrB,aAAakB,UAAU;CACnC,MAAMI,UAAU,IAAIC,QAAQ;CAC5BD,QAAQE,OAAO,UAAU,gCAAgC;CAEzD,OAAO;EACLH;EACAI,QAAQ;EACRH;EACAH,IAAI;EACJO,MAAM,EACJf,QAAQJ,WACV;EACAoB,SAAS,CAACpB,UAAU;CACtB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,SAAgBqB,aAAajB,QAAiBC,UAAqC,CAAC,GAAyB;CAC3G,MAAML,aAAaR,oBAAoBY,MAAM;CAC7CP,eAAAC,gBAAA,CAAA,CAAAQ,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,wCAAwC;CAAA,EAAA,CAAEV,UAAU;CAE3D,MAAMW,aAAqC;EAC7BX;EACZY,IAAI;EACJC,cAAcnB,UAAUC,WAAWK,WAAWE,IAAI,CAAC;CACrD;CAEAN,sBAAsBe,YAAYN,OAAO;CAEzC,MAAMS,MAAMrB,aAAakB,UAAU;CACnC,MAAMI,UAAU,IAAIC,QAAQ;CAC5BD,QAAQE,OAAO,UAAU,gCAAgC;CAEzD,OAAO;EACLH;EACAI,QAAQ;EACRH;EACAH,IAAI;EACJO,MAAM,EACJf,QAAQJ,WACV;EACAoB,SAAS,CAACpB,UAAU;CACtB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgBsB,aACdlB,QACAC,UAA2D,CAAC,GACtC;CACtB,MAAML,aAAaR,oBAAoBY,MAAM;CAC7CP,eAAAC,gBAAA,CAAA,CAAAQ,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,wCAAwC;CAAA,EAAA,CAAEV,UAAU;CAC3DH,eAAAC,gBAAA,CAAA,CAAAQ,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,sEAAsE;CAAA,EAAA,CAAEX,WAAWC,UAAU,CAAC;CAErG,MAAMW,aAAqC;EAC7BX;EACZY,IAAI;EACJC,cAAcnB,UAAUC,WAAWK,WAAWE,IAAI,CAAC;CACrD;CAEAN,sBAAsBe,YAAYN,OAAO;CAEzC,MAAMS,MAAMrB,aAAakB,UAAU;CACnC,MAAMI,UAAU,IAAIC,QAAQ;CAC5BD,QAAQE,OAAO,UAAU,gCAAgC;CAEzD,OAAO;EACLH;EACAI,QAAQb,QAAQkB,QAAQ,UAAU;EAClCR;EACAH,IAAI;EACJO,MAAM,EACJf,QAAQJ,WACV;EACAoB,SAAS,CAACpB,UAAU;CACtB;AACF"}

package/dist/derivations.d.ts

@@ -13,6 +13,8 @@ interface ConcatDerivation {
  *
  * Generally you should not need to import and use this function directly.
  *
+ * @summary Derivation registered as `concat` that joins a record's listed `fields` into one string with an optional
+ * `separator`.
  * @example
  * {
  *   name: 'fullName',

package/dist/derivations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derivations.d.ts","names":[],"sources":["../src/derivations.ts"],"mappings":";;;UAGU;GAEN,QAAQ;;KACR,SAAS,gCACT;GAED;;;;;;;;;;;;;;;;;;;qBAoBU,QAAQ"}
+{"version":3,"file":"derivations.d.ts","names":[],"sources":["../src/derivations.ts"],"mappings":";;;UAQU;GAEN,QAAQ;;KACR,SAAS,gCACT;GAED;;;;;;;;;;;;;;;;;;;;;qBAsBU,QAAQ"}

package/dist/derivations.js

@@ -2,11 +2,17 @@ import { Type } from "@warp-drive-mirror/core/types/symbols";
 
 //#region src/derivations.ts
 /**
+* @module
+* @summary The `concat` derivation, which joins a record's listed fields into one string with an optional separator.
+*/
+/**
 * A derivation for use by {@link ReactiveResource} that joins the given fields
 * with the optional separator (or '' if no separator is provided).
 *
 * Generally you should not need to import and use this function directly.
 *
+* @summary Derivation registered as `concat` that joins a record's listed `fields` into one string with an optional
+* `separator`.
 * @example
 * {
 *   name: 'fullName',

package/dist/derivations.js.map

@@ -1 +1 @@
-{"version":3,"file":"derivations.js","names":["Type","concat","record","options","_prop","Error","opts","fields","map","field","join","separator"],"sources":["../src/derivations.ts"],"sourcesContent":["import type { ReactiveResource } from '@warp-drive-mirror/core/reactive';\nimport { Type } from '@warp-drive-mirror/core/types/symbols';\n\ninterface ConcatDerivation {\n  (\n    record: ReactiveResource & { [key: string]: unknown },\n    options: Record<string, unknown> | null,\n    _prop: string\n  ): string;\n  [Type]: 'concat';\n}\n\n/**\n * A derivation for use by {@link ReactiveResource} that joins the given fields\n * with the optional separator (or '' if no separator is provided).\n *\n * Generally you should not need to import and use this function directly.\n *\n * @example\n * {\n *   name: 'fullName',\n *   kind: 'derived',\n *   type: 'concat',\n *   options: {\n *     fields: ['firstName', 'lastName'],\n *     separator: ' ',\n *   },\n * }\n */\nexport const concat: ConcatDerivation = (\n  record: ReactiveResource & { [key: string]: unknown },\n  options: Record<string, unknown> | null,\n  _prop: string\n) => {\n  if (!options) {\n    throw new Error(`options is required`);\n  }\n  // SAFETY: we cast internally to a more specific type, for our own use\n  // SAFETY: but provide the more general signature to the schema service\n  const opts = options as { fields: string[]; separator?: string };\n  return opts.fields.map((field) => record[field]).join(opts.separator ?? '');\n};\nconcat[Type] = 'concat';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA6BA,MAAaC,UACXC,QACAC,SACAC,UACG;CACH,IAAI,CAACD,SACH,MAAM,IAAIE,MAAM,qBAAqB;CAIvC,MAAMC,OAAOH;CACb,OAAOG,KAAKC,OAAOC,KAAKC,UAAUP,OAAOO,MAAM,CAAC,CAACC,KAAKJ,KAAKK,aAAa,EAAE;AAC5E;AACAV,OAAOD,QAAQ"}
+{"version":3,"file":"derivations.js","names":["Type","concat","record","options","_prop","Error","opts","fields","map","field","join","separator"],"sources":["../src/derivations.ts"],"sourcesContent":["/**\n * @module\n * @summary The `concat` derivation, which joins a record's listed fields into one string with an optional separator.\n */\n\nimport type { ReactiveResource } from '@warp-drive-mirror/core/reactive';\nimport { Type } from '@warp-drive-mirror/core/types/symbols';\n\ninterface ConcatDerivation {\n  (\n    record: ReactiveResource & { [key: string]: unknown },\n    options: Record<string, unknown> | null,\n    _prop: string\n  ): string;\n  [Type]: 'concat';\n}\n\n/**\n * A derivation for use by {@link ReactiveResource} that joins the given fields\n * with the optional separator (or '' if no separator is provided).\n *\n * Generally you should not need to import and use this function directly.\n *\n * @summary Derivation registered as `concat` that joins a record's listed `fields` into one string with an optional\n * `separator`.\n * @example\n * {\n *   name: 'fullName',\n *   kind: 'derived',\n *   type: 'concat',\n *   options: {\n *     fields: ['firstName', 'lastName'],\n *     separator: ' ',\n *   },\n * }\n */\nexport const concat: ConcatDerivation = (\n  record: ReactiveResource & { [key: string]: unknown },\n  options: Record<string, unknown> | null,\n  _prop: string\n) => {\n  if (!options) {\n    throw new Error(`options is required`);\n  }\n  // SAFETY: we cast internally to a more specific type, for our own use\n  // SAFETY: but provide the more general signature to the schema service\n  const opts = options as { fields: string[]; separator?: string };\n  return opts.fields.map((field) => record[field]).join(opts.separator ?? '');\n};\nconcat[Type] = 'concat';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,MAAaC,UACXC,QACAC,SACAC,UACG;CACH,IAAI,CAACD,SACH,MAAM,IAAIE,MAAM,qBAAqB;CAIvC,MAAMC,OAAOH;CACb,OAAOG,KAAKC,OAAOC,KAAKC,UAAUP,OAAOO,MAAM,CAAC,CAACC,KAAKJ,KAAKK,aAAa,EAAE;AAC5E;AACAV,OAAOD,QAAQ"}

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 };