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

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["getOrSetGlobal","macroCondition","getGlobalConfig","CONFIG","host","namespace","setBuildURLConfig","config","WarpDrive","env","DEBUG","test","Error","endsWith","startsWith","OPERATIONS_WITH_PRIMARY_RECORDS","Set","isOperationWithPrimaryRecord","options","has","op","hasResourcePath","resourcePath","length","resourcePathForType","identifiers","type","identifier","buildBaseURL","urlOptions","Object","assign","Array","isArray","every","i","id","idPath","encodeURIComponent","fieldPath","String","join","includes","hasHost","url","filter","Boolean","DEFAULT_QUERY_PARAMS_SERIALIZATION_OPTIONS","arrayFormat","handleInclude","include","split","filterEmpty","source","result","key","value","undefined","sortQueryParams","params","opts","paramsIsObject","URLSearchParams","urlParams","dictionaryParams","forEach","hasExisting","existingValue","push","sortedKeys","keys","sort","sortedValue","toSorted","v","append","buildQueryParams","toString"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @module\n * @mergeModuleWith <project>\n */\n\nimport { assert } from '@warp-drive/core/build-config/macros';\nimport { getOrSetGlobal } from '@warp-drive/core/types/-private';\nimport type { QueryParamsSerializationOptions, QueryParamsSource, Serializable } from '@warp-drive/core/types/params';\n\n// prevents the final constructed object from needing to add\n// host and namespace which are provided by the final consuming\n// class to the prototype which can result in overwrite errors\n\n/**\n * The global configuration used by {@link buildBaseURL} when a call does\n * not provide its own `host`/`namespace`. Set via {@link setBuildURLConfig}.\n *\n * @public\n */\nexport interface BuildURLConfig {\n  /**\n   * The scheme, domain and port (if any) to prefix built URLs with, e.g. `'https://api.example.com'`.\n   */\n  host: string | null;\n  /**\n   * The path segment to insert between `host` and the resource path, e.g. `'api/v1'`.\n   */\n  namespace: string | null;\n}\n\nconst CONFIG: BuildURLConfig = getOrSetGlobal('CONFIG', {\n  host: '',\n  namespace: '',\n});\n\n/**\n * Sets the global configuration for `buildBaseURL`\n * for host and namespace values for the application.\n *\n * These values may still be overridden by passing\n * them to buildBaseURL directly.\n *\n * This method may be called as many times as needed.\n * host values of `''` or `'/'` are equivalent.\n *\n * Except for the value of `/` as host, host should not\n * end with `/`.\n *\n * namespace should not start or end with a `/`.\n *\n * ```ts\n * type BuildURLConfig = {\n *   host: string;\n *   namespace: string'\n * }\n * ```\n *\n * Example:\n *\n * ```ts\n * import { setBuildURLConfig } from '@warp-drive/utilities';\n *\n * setBuildURLConfig({\n *   host: 'https://api.example.com',\n *   namespace: 'api/v1'\n * });\n * ```\n *\n * @public\n */\nexport function setBuildURLConfig(config: BuildURLConfig): void {\n  assert(`setBuildURLConfig: You must pass a config object`, config);\n  assert(\n    `setBuildURLConfig: You must pass a config object with a 'host' or 'namespace' property`,\n    'host' in config || 'namespace' in config\n  );\n\n  CONFIG.host = config.host || '';\n  CONFIG.namespace = config.namespace || '';\n\n  assert(\n    `buildBaseURL: host must NOT end with '/', received '${CONFIG.host}'`,\n    CONFIG.host === '/' || !CONFIG.host.endsWith('/')\n  );\n  assert(\n    `buildBaseURL: namespace must NOT start with '/', received '${CONFIG.namespace}'`,\n    !CONFIG.namespace.startsWith('/')\n  );\n  assert(\n    `buildBaseURL: namespace must NOT end with '/', received '${CONFIG.namespace}'`,\n    !CONFIG.namespace.endsWith('/')\n  );\n}\n\n/**\n * {@link buildBaseURL} options for a `findRecord` request.\n *\n * @public\n */\nexport interface FindRecordUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'findRecord';\n  /**\n   * The type and id of the record to find.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `query` request.\n *\n * @public\n */\nexport interface QueryUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'query';\n  /**\n   * The type of the records to query.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `findMany` request.\n *\n * @public\n */\nexport interface FindManyUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'findMany';\n  /**\n   * The type and id of each record to find.\n   */\n  identifiers: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  }[];\n  /**\n   * The path segment for the resource, defaults to the first identifier's `type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n/**\n * {@link buildBaseURL} options for a `findRelatedCollection` request.\n *\n * @public\n */\nexport interface FindRelatedCollectionUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'findRelatedCollection';\n  /**\n   * The type and id of the record whose relationship is being fetched.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The relationship field name, appended to the resource path.\n   */\n  fieldPath: string;\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `findRelatedRecord` request.\n *\n * @public\n */\nexport interface FindRelatedResourceUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'findRelatedRecord';\n  /**\n   * The type and id of the record whose relationship is being fetched.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The relationship field name, appended to the resource path.\n   */\n  fieldPath: string;\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `createRecord` request.\n *\n * @public\n */\nexport interface CreateRecordUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'createRecord';\n  /**\n   * The type of the record being created.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for an `updateRecord` request.\n *\n * @public\n */\nexport interface UpdateRecordUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'updateRecord';\n  /**\n   * The type and id of the record being updated.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `deleteRecord` request.\n *\n * @public\n */\nexport interface DeleteRecordUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'deleteRecord';\n  /**\n   * The type and id of the record being deleted.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for building a URL directly from a `resourcePath`\n * without an associated request operation.\n *\n * @public\n */\nexport interface GenericUrlOptions {\n  /**\n   * The path segment for the resource.\n   */\n  resourcePath: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * The union of all `op`-specific option shapes accepted by {@link buildBaseURL}, one of:\n *\n * - {@link FindRecordUrlOptions}\n * - {@link QueryUrlOptions}\n * - {@link FindManyUrlOptions}\n * - {@link FindRelatedCollectionUrlOptions}\n * - {@link FindRelatedResourceUrlOptions}\n * - {@link CreateRecordUrlOptions}\n * - {@link UpdateRecordUrlOptions}\n * - {@link DeleteRecordUrlOptions}\n * - {@link GenericUrlOptions}\n *\n * @public\n */\nexport type UrlOptions =\n  | FindRecordUrlOptions\n  | QueryUrlOptions\n  | FindManyUrlOptions\n  | FindRelatedCollectionUrlOptions\n  | FindRelatedResourceUrlOptions\n  | CreateRecordUrlOptions\n  | UpdateRecordUrlOptions\n  | DeleteRecordUrlOptions\n  | GenericUrlOptions;\n\nconst OPERATIONS_WITH_PRIMARY_RECORDS = new Set([\n  'findRecord',\n  'findRelatedRecord',\n  'findRelatedCollection',\n  'updateRecord',\n  'deleteRecord',\n]);\n\nfunction isOperationWithPrimaryRecord(\n  options: UrlOptions\n): options is\n  | FindRecordUrlOptions\n  | FindRelatedCollectionUrlOptions\n  | FindRelatedResourceUrlOptions\n  | UpdateRecordUrlOptions\n  | DeleteRecordUrlOptions {\n  return 'op' in options && OPERATIONS_WITH_PRIMARY_RECORDS.has(options.op);\n}\n\nfunction hasResourcePath(options: UrlOptions): options is GenericUrlOptions {\n  return 'resourcePath' in options && typeof options.resourcePath === 'string' && options.resourcePath.length > 0;\n}\n\nfunction resourcePathForType(options: UrlOptions): string {\n  assert(\n    `resourcePathForType: You must pass a valid op as part of options`,\n    'op' in options && typeof options.op === 'string'\n  );\n  return options.op === 'findMany' ? options.identifiers[0].type : options.identifier.type;\n}\n\n/**\n * Builds a URL for a request based on the provided options.\n * Does not include support for building query params (see `buildQueryParams`)\n * so that it may be composed cleanly with other query-params strategies.\n *\n * Usage:\n *\n * ```ts\n * import { buildBaseURL } from '@warp-drive/utilities';\n *\n * const url = buildBaseURL({\n *   host: 'https://api.example.com',\n *   namespace: 'api/v1',\n *   resourcePath: 'emberDevelopers',\n *   op: 'query',\n *   identifier: { type: 'ember-developer' }\n * });\n *\n * // => 'https://api.example.com/api/v1/emberDevelopers'\n * ```\n *\n * On the surface this may seem like a lot of work to do something simple, but\n * it is designed to be composable with other utilities and interfaces that the\n * average product engineer will never need to see or use.\n *\n * A few notes:\n *\n * - `resourcePath` is optional, but if it is not provided, `identifier.type` will be used.\n * - `host` and `namespace` are optional, but if they are not provided, the values globally\n *    configured via `setBuildURLConfig` will be used.\n * - `op` is required and must be one of the following:\n *   - 'findRecord' 'query' 'findMany' 'findRelatedCollection' 'findRelatedRecord'` 'createRecord' 'updateRecord' 'deleteRecord'\n * - Depending on the value of `op`, `identifier` or `identifiers` will be required.\n *\n * @public\n */\nexport function buildBaseURL(urlOptions: UrlOptions): string {\n  const options = Object.assign(\n    {\n      host: CONFIG.host,\n      namespace: CONFIG.namespace,\n    },\n    urlOptions\n  );\n  assert(\n    `buildBaseURL: You must pass \\`op\\` as part of options`,\n    hasResourcePath(options) || (typeof options.op === 'string' && options.op.length > 0)\n  );\n  assert(\n    `buildBaseURL: You must pass \\`identifier\\` as part of options`,\n    hasResourcePath(options) ||\n      options.op === 'findMany' ||\n      (options.identifier && typeof options.identifier === 'object')\n  );\n  assert(\n    `buildBaseURL: You must pass \\`identifiers\\` as part of options`,\n    hasResourcePath(options) ||\n      options.op !== 'findMany' ||\n      (options.identifiers &&\n        Array.isArray(options.identifiers) &&\n        options.identifiers.length > 0 &&\n        options.identifiers.every((i) => i && typeof i === 'object'))\n  );\n  assert(\n    `buildBaseURL: You must pass valid \\`identifier\\` as part of options, expected 'id'`,\n    hasResourcePath(options) ||\n      !isOperationWithPrimaryRecord(options) ||\n      (typeof options.identifier.id === 'string' && options.identifier.id.length > 0)\n  );\n  assert(\n    `buildBaseURL: You must pass \\`identifiers\\` as part of options`,\n    hasResourcePath(options) ||\n      options.op !== 'findMany' ||\n      options.identifiers.every((i) => typeof i.id === 'string' && i.id.length > 0)\n  );\n  assert(\n    `buildBaseURL: You must pass valid \\`identifier\\` as part of options, expected 'type'`,\n    hasResourcePath(options) ||\n      options.op === 'findMany' ||\n      (typeof options.identifier.type === 'string' && options.identifier.type.length > 0)\n  );\n  assert(\n    `buildBaseURL: You must pass valid \\`identifiers\\` as part of options, expected 'type'`,\n    hasResourcePath(options) ||\n      options.op !== 'findMany' ||\n      (typeof options.identifiers[0].type === 'string' && options.identifiers[0].type.length > 0)\n  );\n\n  // prettier-ignore\n  const idPath: string =\n      isOperationWithPrimaryRecord(options) ? encodeURIComponent(options.identifier.id)\n      : '';\n  const resourcePath = options.resourcePath || resourcePathForType(options);\n  const { host, namespace } = options;\n  const fieldPath = 'fieldPath' in options ? options.fieldPath : '';\n\n  assert(\n    `buildBaseURL: You tried to build a url for a ${String(\n      'op' in options ? options.op + ' ' : ''\n    )}request to ${resourcePath} but resourcePath must be set or op must be one of \"${[\n      'findRecord',\n      'findRelatedRecord',\n      'findRelatedCollection',\n      'updateRecord',\n      'deleteRecord',\n      'createRecord',\n      'query',\n      'findMany',\n    ].join('\",\"')}\".`,\n    hasResourcePath(options) ||\n      [\n        'findRecord',\n        'query',\n        'findMany',\n        'findRelatedCollection',\n        'findRelatedRecord',\n        'createRecord',\n        'updateRecord',\n        'deleteRecord',\n      ].includes(options.op)\n  );\n\n  assert(`buildBaseURL: host must NOT end with '/', received '${host}'`, host === '/' || !host.endsWith('/'));\n  assert(`buildBaseURL: namespace must NOT start with '/', received '${namespace}'`, !namespace.startsWith('/'));\n  assert(`buildBaseURL: namespace must NOT end with '/', received '${namespace}'`, !namespace.endsWith('/'));\n  assert(\n    `buildBaseURL: resourcePath must NOT start with '/', received '${resourcePath}'`,\n    !resourcePath.startsWith('/')\n  );\n  assert(`buildBaseURL: resourcePath must NOT end with '/', received '${resourcePath}'`, !resourcePath.endsWith('/'));\n  assert(`buildBaseURL: fieldPath must NOT start with '/', received '${fieldPath}'`, !fieldPath.startsWith('/'));\n  assert(`buildBaseURL: fieldPath must NOT end with '/', received '${fieldPath}'`, !fieldPath.endsWith('/'));\n  assert(`buildBaseURL: idPath must NOT start with '/', received '${idPath}'`, !idPath.startsWith('/'));\n  assert(`buildBaseURL: idPath must NOT end with '/', received '${idPath}'`, !idPath.endsWith('/'));\n\n  const hasHost = host !== '' && host !== '/';\n  const url = [hasHost ? host : '', namespace, resourcePath, idPath, fieldPath].filter(Boolean).join('/');\n  return hasHost ? url : `/${url}`;\n}\n\nconst DEFAULT_QUERY_PARAMS_SERIALIZATION_OPTIONS: QueryParamsSerializationOptions = {\n  arrayFormat: 'comma',\n};\n\nfunction handleInclude(include: string | string[]): string[] {\n  assert(\n    `Expected include to be a string or array, got ${typeof include}`,\n    typeof include === 'string' || Array.isArray(include)\n  );\n  return typeof include === 'string' ? include.split(',') : include;\n}\n\n/**\n * filter out keys of an object that have falsy values or point to empty arrays\n * returning a new object with only those keys that have truthy values / non-empty arrays\n *\n * @public\n * @param source object to filter keys with empty values from\n * @return A new object with the keys that contained empty values removed\n */\nexport function filterEmpty(source: Record<string, Serializable>): Record<string, Serializable> {\n  const result: Record<string, Serializable> = {};\n  for (const key in source) {\n    const value = source[key];\n    // Allow `0` and `false` but filter falsy values that indicate \"empty\"\n    if (value !== undefined && value !== null && value !== '') {\n      if (!Array.isArray(value) || value.length > 0) {\n        result[key] = source[key];\n      }\n    }\n  }\n  return result;\n}\n\n/**\n * Sorts query params by both key and value returning a new URLSearchParams\n * object with the keys inserted in sorted order.\n *\n * Treats `included` specially, splicing it into an array if it is a string and sorting the array.\n *\n * The `params` given are never mutated: neither the object itself nor any array\n * value it holds is reordered or replaced, so passing state that is also\n * rendered (a tracked array of filter values, for instance) is safe.\n *\n * Options:\n * - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'\n *\n * 'bracket': appends [] to the key for every value e.g. `&ids[]=1&ids[]=2`\n * 'indices': appends [i] to the key for every value e.g. `&ids[0]=1&ids[1]=2`\n * 'repeat': appends the key for every value e.g. `&ids=1&ids=2`\n * 'comma' (default): appends the key once with a comma separated list of values e.g. `&ids=1,2`\n *\n * @public\n * @return A {@link URLSearchParams} with keys inserted in sorted order\n */\nexport function sortQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): URLSearchParams {\n  const opts = Object.assign({}, DEFAULT_QUERY_PARAMS_SERIALIZATION_OPTIONS, options);\n  const paramsIsObject = !(params instanceof URLSearchParams);\n  const urlParams = new URLSearchParams();\n  // shallow copy so that normalizing `include` below does not write back onto\n  // the caller's object. Array values are still shared with the caller, so\n  // everything downstream must sort copies rather than sorting in place.\n  const dictionaryParams: Record<string, Serializable> = paramsIsObject ? Object.assign({}, params) : {};\n\n  if (!paramsIsObject) {\n    params.forEach((value, key) => {\n      const hasExisting = key in dictionaryParams;\n      if (!hasExisting) {\n        dictionaryParams[key] = value;\n      } else {\n        const existingValue = dictionaryParams[key];\n        if (Array.isArray(existingValue)) {\n          existingValue.push(value);\n        } else {\n          dictionaryParams[key] = [existingValue, value];\n        }\n      }\n    });\n  }\n\n  if ('include' in dictionaryParams) {\n    dictionaryParams.include = handleInclude(dictionaryParams.include as string | string[]);\n  }\n\n  const sortedKeys = Object.keys(dictionaryParams).sort();\n  sortedKeys.forEach((key) => {\n    const value = dictionaryParams[key];\n    if (Array.isArray(value)) {\n      const sortedValue = value.toSorted();\n      switch (opts.arrayFormat) {\n        case 'indices':\n          sortedValue.forEach((v, i) => {\n            urlParams.append(`${key}[${i}]`, String(v));\n          });\n          return;\n        case 'bracket':\n          sortedValue.forEach((v) => {\n            urlParams.append(`${key}[]`, String(v));\n          });\n          return;\n        case 'repeat':\n          sortedValue.forEach((v) => {\n            urlParams.append(key, String(v));\n          });\n          return;\n        case 'comma':\n        default:\n          urlParams.append(key, sortedValue.join(','));\n          return;\n      }\n    } else {\n      urlParams.append(key, String(value));\n    }\n  });\n\n  return urlParams;\n}\n\n/**\n * Sorts query params by both key and value, returning a query params string\n *\n * Treats `included` specially, splicing it into an array if it is a string and sorting the array.\n *\n * The `params` given are never mutated: neither the object itself nor any array\n * value it holds is reordered or replaced, so passing state that is also\n * rendered (a tracked array of filter values, for instance) is safe.\n *\n * Options:\n * - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'\n *\n * 'bracket': appends [] to the key for every value e.g. `ids[]=1&ids[]=2`\n * 'indices': appends [i] to the key for every value e.g. `ids[0]=1&ids[1]=2`\n * 'repeat': appends the key for every value e.g. `ids=1&ids=2`\n * 'comma' (default): appends the key once with a comma separated list of values e.g. `ids=1,2`\n *\n * @public\n * @return A sorted query params string without the leading `?`\n */\nexport function buildQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): string {\n  return sortQueryParams(params, options).toString();\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["getOrSetGlobal","macroCondition","getGlobalConfig","CONFIG","host","namespace","setBuildURLConfig","config","WarpDrive","env","DEBUG","test","Error","endsWith","startsWith","OPERATIONS_WITH_PRIMARY_RECORDS","Set","isOperationWithPrimaryRecord","options","has","op","hasResourcePath","resourcePath","length","resourcePathForType","identifiers","type","identifier","buildBaseURL","urlOptions","Object","assign","Array","isArray","every","i","id","idPath","encodeURIComponent","fieldPath","String","join","includes","hasHost","url","filter","Boolean","DEFAULT_QUERY_PARAMS_SERIALIZATION_OPTIONS","arrayFormat","handleInclude","include","split","filterEmpty","source","result","key","value","undefined","sortQueryParams","params","opts","paramsIsObject","URLSearchParams","urlParams","dictionaryParams","forEach","hasExisting","existingValue","push","sortedKeys","keys","sort","sortedValue","toSorted","v","append","buildQueryParams","toString"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @summary Helpers for building request URLs and sorted query strings, with a configurable global host and namespace.\n * @module\n * @mergeModuleWith <project>\n */\n\nimport { assert } from '@warp-drive/core/build-config/macros';\nimport { getOrSetGlobal } from '@warp-drive/core/types/-private';\nimport type { QueryParamsSerializationOptions, QueryParamsSource, Serializable } from '@warp-drive/core/types/params';\n\n// prevents the final constructed object from needing to add\n// host and namespace which are provided by the final consuming\n// class to the prototype which can result in overwrite errors\n\n/**\n * The global configuration used by {@link buildBaseURL} when a call does\n * not provide its own `host`/`namespace`. Set via {@link setBuildURLConfig}.\n *\n * @summary The global `host` and `namespace` that `buildBaseURL` prefixes onto URLs when a call does not pass its own.\n * @public\n */\nexport interface BuildURLConfig {\n  /**\n   * The scheme, domain and port (if any) to prefix built URLs with, e.g. `'https://api.example.com'`.\n   */\n  host: string | null;\n  /**\n   * The path segment to insert between `host` and the resource path, e.g. `'api/v1'`.\n   */\n  namespace: string | null;\n}\n\nconst CONFIG: BuildURLConfig = getOrSetGlobal('CONFIG', {\n  host: '',\n  namespace: '',\n});\n\n/**\n * Sets the global configuration for `buildBaseURL`\n * for host and namespace values for the application.\n *\n * These values may still be overridden by passing\n * them to buildBaseURL directly.\n *\n * The [Basic Usage](/guides/the-manual/cookbook/basic-usage#step-2-configure-some-request-defaults)\n * guide sets these defaults through the `@warp-drive/utilities/json-api` version of this function,\n * which also sets this global configuration.\n *\n * This method may be called as many times as needed.\n * host values of `''` or `'/'` are equivalent.\n *\n * Except for the value of `/` as host, host should not\n * end with `/`.\n *\n * namespace should not start or end with a `/`.\n *\n * ```ts\n * type BuildURLConfig = {\n *   host: string;\n *   namespace: string'\n * }\n * ```\n *\n * Example:\n *\n * ```ts\n * import { setBuildURLConfig } from '@warp-drive/utilities';\n *\n * setBuildURLConfig({\n *   host: 'https://api.example.com',\n *   namespace: 'api/v1'\n * });\n * ```\n *\n * @summary Sets the app-wide default `host` and `namespace` used by `buildBaseURL` and the request builders.\n * @public\n */\nexport function setBuildURLConfig(config: BuildURLConfig): void {\n  assert(`setBuildURLConfig: You must pass a config object`, config);\n  assert(\n    `setBuildURLConfig: You must pass a config object with a 'host' or 'namespace' property`,\n    'host' in config || 'namespace' in config\n  );\n\n  CONFIG.host = config.host || '';\n  CONFIG.namespace = config.namespace || '';\n\n  assert(\n    `buildBaseURL: host must NOT end with '/', received '${CONFIG.host}'`,\n    CONFIG.host === '/' || !CONFIG.host.endsWith('/')\n  );\n  assert(\n    `buildBaseURL: namespace must NOT start with '/', received '${CONFIG.namespace}'`,\n    !CONFIG.namespace.startsWith('/')\n  );\n  assert(\n    `buildBaseURL: namespace must NOT end with '/', received '${CONFIG.namespace}'`,\n    !CONFIG.namespace.endsWith('/')\n  );\n}\n\n/**\n * {@link buildBaseURL} options for a `findRecord` request.\n *\n * @summary Options passed to `buildBaseURL` to build the URL for fetching one resource by type and id.\n * @public\n */\nexport interface FindRecordUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'findRecord';\n  /**\n   * The type and id of the record to find.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `query` request.\n *\n * @summary Options passed to `buildBaseURL` to build the URL for querying a collection of one resource type.\n * @public\n */\nexport interface QueryUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'query';\n  /**\n   * The type of the records to query.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `findMany` request.\n *\n * @summary Options passed to `buildBaseURL` to build the URL for fetching several resources, pathed by the first\n * identifier's type.\n * @public\n */\nexport interface FindManyUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'findMany';\n  /**\n   * The type and id of each record to find.\n   */\n  identifiers: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  }[];\n  /**\n   * The path segment for the resource, defaults to the first identifier's `type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n/**\n * {@link buildBaseURL} options for a `findRelatedCollection` request.\n *\n * @summary Options passed to `buildBaseURL` to build the URL for a record's has-many relationship, ending in the\n * field name.\n * @public\n */\nexport interface FindRelatedCollectionUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'findRelatedCollection';\n  /**\n   * The type and id of the record whose relationship is being fetched.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The relationship field name, appended to the resource path.\n   */\n  fieldPath: string;\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `findRelatedRecord` request.\n *\n * @summary Options passed to `buildBaseURL` to build the URL for a record's belongs-to relationship, ending in the\n * field name.\n * @public\n */\nexport interface FindRelatedResourceUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'findRelatedRecord';\n  /**\n   * The type and id of the record whose relationship is being fetched.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The relationship field name, appended to the resource path.\n   */\n  fieldPath: string;\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `createRecord` request.\n *\n * @summary Options passed to `buildBaseURL` to build the collection URL a new record of a given type is saved to.\n * @public\n */\nexport interface CreateRecordUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'createRecord';\n  /**\n   * The type of the record being created.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for an `updateRecord` request.\n *\n * @summary Options passed to `buildBaseURL` to build the URL for saving changes to an existing record by type and id.\n * @public\n */\nexport interface UpdateRecordUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'updateRecord';\n  /**\n   * The type and id of the record being updated.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for a `deleteRecord` request.\n *\n * @summary Options passed to `buildBaseURL` to build the URL for deleting an existing record by type and id.\n * @public\n */\nexport interface DeleteRecordUrlOptions {\n  /**\n   * The request operation this URL is for.\n   */\n  op: 'deleteRecord';\n  /**\n   * The type and id of the record being deleted.\n   */\n  identifier: {\n    /**\n     * The resource type.\n     */\n    type: string;\n    /**\n     * The resource id.\n     */\n    id: string;\n  };\n  /**\n   * The path segment for the resource, defaults to `identifier.type` if not provided.\n   */\n  resourcePath?: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * {@link buildBaseURL} options for building a URL directly from a `resourcePath`\n * without an associated request operation.\n *\n * @summary Options passed to `buildBaseURL` to build a URL from an explicit `resourcePath` with no request `op`.\n * @public\n */\nexport interface GenericUrlOptions {\n  /**\n   * The path segment for the resource.\n   */\n  resourcePath: string;\n  /**\n   * Overrides the globally configured host for this call only.\n   */\n  host?: string;\n  /**\n   * Overrides the globally configured namespace for this call only.\n   */\n  namespace?: string;\n}\n\n/**\n * The union of all `op`-specific option shapes accepted by {@link buildBaseURL}, one of:\n *\n * - {@link FindRecordUrlOptions}\n * - {@link QueryUrlOptions}\n * - {@link FindManyUrlOptions}\n * - {@link FindRelatedCollectionUrlOptions}\n * - {@link FindRelatedResourceUrlOptions}\n * - {@link CreateRecordUrlOptions}\n * - {@link UpdateRecordUrlOptions}\n * - {@link DeleteRecordUrlOptions}\n * - {@link GenericUrlOptions}\n *\n * @summary Any of the option shapes `buildBaseURL` accepts, one per request `op` plus a generic `resourcePath` form.\n * @public\n */\nexport type UrlOptions =\n  | FindRecordUrlOptions\n  | QueryUrlOptions\n  | FindManyUrlOptions\n  | FindRelatedCollectionUrlOptions\n  | FindRelatedResourceUrlOptions\n  | CreateRecordUrlOptions\n  | UpdateRecordUrlOptions\n  | DeleteRecordUrlOptions\n  | GenericUrlOptions;\n\nconst OPERATIONS_WITH_PRIMARY_RECORDS = new Set([\n  'findRecord',\n  'findRelatedRecord',\n  'findRelatedCollection',\n  'updateRecord',\n  'deleteRecord',\n]);\n\nfunction isOperationWithPrimaryRecord(\n  options: UrlOptions\n): options is\n  | FindRecordUrlOptions\n  | FindRelatedCollectionUrlOptions\n  | FindRelatedResourceUrlOptions\n  | UpdateRecordUrlOptions\n  | DeleteRecordUrlOptions {\n  return 'op' in options && OPERATIONS_WITH_PRIMARY_RECORDS.has(options.op);\n}\n\nfunction hasResourcePath(options: UrlOptions): options is GenericUrlOptions {\n  return 'resourcePath' in options && typeof options.resourcePath === 'string' && options.resourcePath.length > 0;\n}\n\nfunction resourcePathForType(options: UrlOptions): string {\n  assert(\n    `resourcePathForType: You must pass a valid op as part of options`,\n    'op' in options && typeof options.op === 'string'\n  );\n  return options.op === 'findMany' ? options.identifiers[0].type : options.identifier.type;\n}\n\n/**\n * Builds a URL for a request based on the provided options.\n * Does not include support for building query params (see `buildQueryParams`)\n * so that it may be composed cleanly with other query-params strategies.\n *\n * See the [Builders](/guides/the-manual/requests/builders) guide for writing your own request\n * builders.\n *\n * Usage:\n *\n * ```ts\n * import { buildBaseURL } from '@warp-drive/utilities';\n *\n * const url = buildBaseURL({\n *   host: 'https://api.example.com',\n *   namespace: 'api/v1',\n *   resourcePath: 'emberDevelopers',\n *   op: 'query',\n *   identifier: { type: 'ember-developer' }\n * });\n *\n * // => 'https://api.example.com/api/v1/emberDevelopers'\n * ```\n *\n * On the surface this may seem like a lot of work to do something simple, but\n * it is designed to be composable with other utilities and interfaces that the\n * average product engineer will never need to see or use.\n *\n * A few notes:\n *\n * - `resourcePath` is optional, but if it is not provided, `identifier.type` will be used.\n * - `host` and `namespace` are optional, but if they are not provided, the values globally\n *    configured via `setBuildURLConfig` will be used.\n * - `op` is required and must be one of the following:\n *   - 'findRecord' 'query' 'findMany' 'findRelatedCollection' 'findRelatedRecord'` 'createRecord' 'updateRecord' 'deleteRecord'\n * - Depending on the value of `op`, `identifier` or `identifiers` will be required.\n *\n * @summary Joins host, namespace, resource path, id, and relationship field into a request URL without query params.\n * @public\n */\nexport function buildBaseURL(urlOptions: UrlOptions): string {\n  const options = Object.assign(\n    {\n      host: CONFIG.host,\n      namespace: CONFIG.namespace,\n    },\n    urlOptions\n  );\n  assert(\n    `buildBaseURL: You must pass \\`op\\` as part of options`,\n    hasResourcePath(options) || (typeof options.op === 'string' && options.op.length > 0)\n  );\n  assert(\n    `buildBaseURL: You must pass \\`identifier\\` as part of options`,\n    hasResourcePath(options) ||\n      options.op === 'findMany' ||\n      (options.identifier && typeof options.identifier === 'object')\n  );\n  assert(\n    `buildBaseURL: You must pass \\`identifiers\\` as part of options`,\n    hasResourcePath(options) ||\n      options.op !== 'findMany' ||\n      (options.identifiers &&\n        Array.isArray(options.identifiers) &&\n        options.identifiers.length > 0 &&\n        options.identifiers.every((i) => i && typeof i === 'object'))\n  );\n  assert(\n    `buildBaseURL: You must pass valid \\`identifier\\` as part of options, expected 'id'`,\n    hasResourcePath(options) ||\n      !isOperationWithPrimaryRecord(options) ||\n      (typeof options.identifier.id === 'string' && options.identifier.id.length > 0)\n  );\n  assert(\n    `buildBaseURL: You must pass \\`identifiers\\` as part of options`,\n    hasResourcePath(options) ||\n      options.op !== 'findMany' ||\n      options.identifiers.every((i) => typeof i.id === 'string' && i.id.length > 0)\n  );\n  assert(\n    `buildBaseURL: You must pass valid \\`identifier\\` as part of options, expected 'type'`,\n    hasResourcePath(options) ||\n      options.op === 'findMany' ||\n      (typeof options.identifier.type === 'string' && options.identifier.type.length > 0)\n  );\n  assert(\n    `buildBaseURL: You must pass valid \\`identifiers\\` as part of options, expected 'type'`,\n    hasResourcePath(options) ||\n      options.op !== 'findMany' ||\n      (typeof options.identifiers[0].type === 'string' && options.identifiers[0].type.length > 0)\n  );\n\n  // prettier-ignore\n  const idPath: string =\n      isOperationWithPrimaryRecord(options) ? encodeURIComponent(options.identifier.id)\n      : '';\n  const resourcePath = options.resourcePath || resourcePathForType(options);\n  const { host, namespace } = options;\n  const fieldPath = 'fieldPath' in options ? options.fieldPath : '';\n\n  assert(\n    `buildBaseURL: You tried to build a url for a ${String(\n      'op' in options ? options.op + ' ' : ''\n    )}request to ${resourcePath} but resourcePath must be set or op must be one of \"${[\n      'findRecord',\n      'findRelatedRecord',\n      'findRelatedCollection',\n      'updateRecord',\n      'deleteRecord',\n      'createRecord',\n      'query',\n      'findMany',\n    ].join('\",\"')}\".`,\n    hasResourcePath(options) ||\n      [\n        'findRecord',\n        'query',\n        'findMany',\n        'findRelatedCollection',\n        'findRelatedRecord',\n        'createRecord',\n        'updateRecord',\n        'deleteRecord',\n      ].includes(options.op)\n  );\n\n  assert(`buildBaseURL: host must NOT end with '/', received '${host}'`, host === '/' || !host.endsWith('/'));\n  assert(`buildBaseURL: namespace must NOT start with '/', received '${namespace}'`, !namespace.startsWith('/'));\n  assert(`buildBaseURL: namespace must NOT end with '/', received '${namespace}'`, !namespace.endsWith('/'));\n  assert(\n    `buildBaseURL: resourcePath must NOT start with '/', received '${resourcePath}'`,\n    !resourcePath.startsWith('/')\n  );\n  assert(`buildBaseURL: resourcePath must NOT end with '/', received '${resourcePath}'`, !resourcePath.endsWith('/'));\n  assert(`buildBaseURL: fieldPath must NOT start with '/', received '${fieldPath}'`, !fieldPath.startsWith('/'));\n  assert(`buildBaseURL: fieldPath must NOT end with '/', received '${fieldPath}'`, !fieldPath.endsWith('/'));\n  assert(`buildBaseURL: idPath must NOT start with '/', received '${idPath}'`, !idPath.startsWith('/'));\n  assert(`buildBaseURL: idPath must NOT end with '/', received '${idPath}'`, !idPath.endsWith('/'));\n\n  const hasHost = host !== '' && host !== '/';\n  const url = [hasHost ? host : '', namespace, resourcePath, idPath, fieldPath].filter(Boolean).join('/');\n  return hasHost ? url : `/${url}`;\n}\n\nconst DEFAULT_QUERY_PARAMS_SERIALIZATION_OPTIONS: QueryParamsSerializationOptions = {\n  arrayFormat: 'comma',\n};\n\nfunction handleInclude(include: string | string[]): string[] {\n  assert(\n    `Expected include to be a string or array, got ${typeof include}`,\n    typeof include === 'string' || Array.isArray(include)\n  );\n  return typeof include === 'string' ? include.split(',') : include;\n}\n\n/**\n * filter out keys of an object that have falsy values or point to empty arrays\n * returning a new object with only those keys that have truthy values / non-empty arrays\n *\n * See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for\n * why builders need stable query params.\n *\n * @summary Returns a copy of an object without keys whose values are `undefined`, `null`, empty strings, or empty\n * arrays.\n * @public\n * @param source object to filter keys with empty values from\n * @return A new object with the keys that contained empty values removed\n */\nexport function filterEmpty(source: Record<string, Serializable>): Record<string, Serializable> {\n  const result: Record<string, Serializable> = {};\n  for (const key in source) {\n    const value = source[key];\n    // Allow `0` and `false` but filter falsy values that indicate \"empty\"\n    if (value !== undefined && value !== null && value !== '') {\n      if (!Array.isArray(value) || value.length > 0) {\n        result[key] = source[key];\n      }\n    }\n  }\n  return result;\n}\n\n/**\n * Sorts query params by both key and value returning a new URLSearchParams\n * object with the keys inserted in sorted order.\n *\n * See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for\n * why builders need stable query params.\n *\n * Treats `included` specially, splicing it into an array if it is a string and sorting the array.\n *\n * The `params` given are never mutated: neither the object itself nor any array\n * value it holds is reordered or replaced, so passing state that is also\n * rendered (a tracked array of filter values, for instance) is safe.\n *\n * Options:\n * - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'\n *\n * 'bracket': appends [] to the key for every value e.g. `&ids[]=1&ids[]=2`\n * 'indices': appends [i] to the key for every value e.g. `&ids[0]=1&ids[1]=2`\n * 'repeat': appends the key for every value e.g. `&ids=1&ids=2`\n * 'comma' (default): appends the key once with a comma separated list of values e.g. `&ids=1,2`\n *\n * @summary Builds a `URLSearchParams` with keys and array values sorted, so equivalent queries produce identical\n * params.\n * @public\n * @return A {@link URLSearchParams} with keys inserted in sorted order\n */\nexport function sortQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): URLSearchParams {\n  const opts = Object.assign({}, DEFAULT_QUERY_PARAMS_SERIALIZATION_OPTIONS, options);\n  const paramsIsObject = !(params instanceof URLSearchParams);\n  const urlParams = new URLSearchParams();\n  // shallow copy so that normalizing `include` below does not write back onto\n  // the caller's object. Array values are still shared with the caller, so\n  // everything downstream must sort copies rather than sorting in place.\n  const dictionaryParams: Record<string, Serializable> = paramsIsObject ? Object.assign({}, params) : {};\n\n  if (!paramsIsObject) {\n    params.forEach((value, key) => {\n      const hasExisting = key in dictionaryParams;\n      if (!hasExisting) {\n        dictionaryParams[key] = value;\n      } else {\n        const existingValue = dictionaryParams[key];\n        if (Array.isArray(existingValue)) {\n          existingValue.push(value);\n        } else {\n          dictionaryParams[key] = [existingValue, value];\n        }\n      }\n    });\n  }\n\n  if ('include' in dictionaryParams) {\n    dictionaryParams.include = handleInclude(dictionaryParams.include as string | string[]);\n  }\n\n  const sortedKeys = Object.keys(dictionaryParams).sort();\n  sortedKeys.forEach((key) => {\n    const value = dictionaryParams[key];\n    if (Array.isArray(value)) {\n      const sortedValue = value.toSorted();\n      switch (opts.arrayFormat) {\n        case 'indices':\n          sortedValue.forEach((v, i) => {\n            urlParams.append(`${key}[${i}]`, String(v));\n          });\n          return;\n        case 'bracket':\n          sortedValue.forEach((v) => {\n            urlParams.append(`${key}[]`, String(v));\n          });\n          return;\n        case 'repeat':\n          sortedValue.forEach((v) => {\n            urlParams.append(key, String(v));\n          });\n          return;\n        case 'comma':\n        default:\n          urlParams.append(key, sortedValue.join(','));\n          return;\n      }\n    } else {\n      urlParams.append(key, String(value));\n    }\n  });\n\n  return urlParams;\n}\n\n/**\n * Sorts query params by both key and value, returning a query params string\n *\n * See [Cache Keys for Requests](/guides/the-manual/requests/builders#cache-keys-for-requests) for\n * why builders need stable query params.\n *\n * Treats `included` specially, splicing it into an array if it is a string and sorting the array.\n *\n * The `params` given are never mutated: neither the object itself nor any array\n * value it holds is reordered or replaced, so passing state that is also\n * rendered (a tracked array of filter values, for instance) is safe.\n *\n * Options:\n * - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'\n *\n * 'bracket': appends [] to the key for every value e.g. `ids[]=1&ids[]=2`\n * 'indices': appends [i] to the key for every value e.g. `ids[0]=1&ids[1]=2`\n * 'repeat': appends the key for every value e.g. `ids=1&ids=2`\n * 'comma' (default): appends the key once with a comma separated list of values e.g. `ids=1,2`\n *\n * @summary Serializes query params into a string with keys and array values sorted, so equivalent queries share one\n * URL.\n * @public\n * @return A sorted query params string without the leading `?`\n */\nexport function buildQueryParams(params: QueryParamsSource, options?: QueryParamsSerializationOptions): string {\n  return sortQueryParams(params, options).toString();\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgCA,MAAMG,SAAyBH,eAAe,UAAU;CACtDI,MAAM;CACNC,WAAW;AACb,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CD,SAAgBC,kBAAkBC,QAA8B;CAC9DN,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,kDAAkD;CAAA,EAAA,CAAEL,MAAM;CACjEN,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,wFAAwF;CAAA,EAAA,CACxF,UAAUL,UAAU,eAAeA,MAAM;CAG3CJ,OAAOC,OAAOG,OAAOH,QAAQ;CAC7BD,OAAOE,YAAYE,OAAOF,aAAa;CAEvCJ,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,uDAAuDT,OAAOC,KAAI,EAAG;CAAA,EAAA,CACrED,OAAOC,SAAS,OAAO,CAACD,OAAOC,KAAKS,SAAS,GAAG,CAAC;CAEnDZ,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,8DAA8DT,OAAOE,UAAS,EAAG;CAAA,EAAA,CACjF,CAACF,OAAOE,UAAUS,WAAW,GAAG,CAAC;CAEnCb,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,4DAA4DT,OAAOE,UAAS,EAAG;CAAA,EAAA,CAC/E,CAACF,OAAOE,UAAUQ,SAAS,GAAG,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqWA,MAAME,kDAAkC,IAAIC,IAAI;CAC9C;CACA;CACA;CACA;CACA;AAAc,CACf;AAED,SAASC,6BACPC,SAMyB;CACzB,OAAO,QAAQA,WAAWH,gCAAgCI,IAAID,QAAQE,EAAE;AAC1E;AAEA,SAASC,gBAAgBH,SAAmD;CAC1E,OAAO,kBAAkBA,WAAW,OAAOA,QAAQI,iBAAiB,YAAYJ,QAAQI,aAAaC,SAAS;AAChH;AAEA,SAASC,oBAAoBN,SAA6B;CACxDjB,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,kEAAkE;CAAA,EAAA,CAClE,QAAQM,WAAW,OAAOA,QAAQE,OAAO,QAAQ;CAEnD,OAAOF,QAAQE,OAAO,aAAaF,QAAQO,YAAY,EAAE,CAACC,OAAOR,QAAQS,WAAWD;AACtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgBE,aAAaC,YAAgC;CAC3D,MAAMX,UAAUY,OAAOC,OACrB;EACE3B,MAAMD,OAAOC;EACbC,WAAWF,OAAOE;CACpB,GACAwB,UACF;CACA5B,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,uDAAuD;CAAA,EAAA,CACvDS,gBAAgBH,OAAO,KAAM,OAAOA,QAAQE,OAAO,YAAYF,QAAQE,GAAGG,SAAS,CAAE;CAEvFtB,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,+DAA+D;CAAA,EAAA,CAC/DS,gBAAgBH,OAAO,KACrBA,QAAQE,OAAO,cACdF,QAAQS,cAAc,OAAOT,QAAQS,eAAe,QAAS;CAElE1B,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,gEAAgE;CAAA,EAAA,CAChES,gBAAgBH,OAAO,KACrBA,QAAQE,OAAO,cACdF,QAAQO,eACPO,MAAMC,QAAQf,QAAQO,WAAW,KACjCP,QAAQO,YAAYF,SAAS,KAC7BL,QAAQO,YAAYS,OAAOC,MAAMA,KAAK,OAAOA,MAAM,QAAQ,CAAE;CAEnElC,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,oFAAoF;CAAA,EAAA,CACpFS,gBAAgBH,OAAO,KACrB,CAACD,6BAA6BC,OAAO,KACpC,OAAOA,QAAQS,WAAWS,OAAO,YAAYlB,QAAQS,WAAWS,GAAGb,SAAS,CAAE;CAEnFtB,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,gEAAgE;CAAA,EAAA,CAChES,gBAAgBH,OAAO,KACrBA,QAAQE,OAAO,cACfF,QAAQO,YAAYS,OAAOC,MAAM,OAAOA,EAAEC,OAAO,YAAYD,EAAEC,GAAGb,SAAS,CAAC,CAAC;CAEjFtB,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,sFAAsF;CAAA,EAAA,CACtFS,gBAAgBH,OAAO,KACrBA,QAAQE,OAAO,cACd,OAAOF,QAAQS,WAAWD,SAAS,YAAYR,QAAQS,WAAWD,KAAKH,SAAS,CAAE;CAEvFtB,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,uFAAuF;CAAA,EAAA,CACvFS,gBAAgBH,OAAO,KACrBA,QAAQE,OAAO,cACd,OAAOF,QAAQO,YAAY,EAAE,CAACC,SAAS,YAAYR,QAAQO,YAAY,EAAE,CAACC,KAAKH,SAAS,CAAE;CAI/F,MAAMc,SACFpB,6BAA6BC,OAAO,IAAIoB,mBAAmBpB,QAAQS,WAAWS,EAAE,IAC9E;CACN,MAAMd,eAAeJ,QAAQI,gBAAgBE,oBAAoBN,OAAO;CACxE,MAAM,EAAEd,MAAMC,cAAca;CAC5B,MAAMqB,YAAY,eAAerB,UAAUA,QAAQqB,YAAY;CAE/DtC,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,gDAAgD4B,OAC9C,QAAQtB,UAAUA,QAAQE,KAAK,MAAM,EACvC,EAAC,aAAcE,aAAY,sDAAuD;GAChF;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EAAU,CACX,CAACmB,KAAK,OAAK,EAAC,GAAI;CAAA,EAAA,CACjBpB,gBAAgBH,OAAO,KACrB;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CAAc,CACf,CAACwB,SAASxB,QAAQE,EAAE,CAAC;CAG1BnB,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,uDAAuDR,KAAI,EAAG;CAAA,EAAA,CAAEA,SAAS,OAAO,CAACA,KAAKS,SAAS,GAAG,CAAC;CAC1GZ,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,8DAA8DP,UAAS,EAAG;CAAA,EAAA,CAAE,CAACA,UAAUS,WAAW,GAAG,CAAC;CAC7Gb,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,4DAA4DP,UAAS,EAAG;CAAA,EAAA,CAAE,CAACA,UAAUQ,SAAS,GAAG,CAAC;CACzGZ,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,iEAAiEU,aAAY,EAAG;CAAA,EAAA,CAChF,CAACA,aAAaR,WAAW,GAAG,CAAC;CAE/Bb,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,+DAA+DU,aAAY,EAAG;CAAA,EAAA,CAAE,CAACA,aAAaT,SAAS,GAAG,CAAC;CAClHZ,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,8DAA8D2B,UAAS,EAAG;CAAA,EAAA,CAAE,CAACA,UAAUzB,WAAW,GAAG,CAAC;CAC7Gb,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,4DAA4D2B,UAAS,EAAG;CAAA,EAAA,CAAE,CAACA,UAAU1B,SAAS,GAAG,CAAC;CACzGZ,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,2DAA2DyB,OAAM,EAAG;CAAA,EAAA,CAAE,CAACA,OAAOvB,WAAW,GAAG,CAAC;CACpGb,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MAAO,yDAAyDyB,OAAM,EAAG;CAAA,EAAA,CAAE,CAACA,OAAOxB,SAAS,GAAG,CAAC;CAEhG,MAAM8B,UAAUvC,SAAS,MAAMA,SAAS;CACxC,MAAMwC,MAAM;EAACD,UAAUvC,OAAO;EAAIC;EAAWiB;EAAce;EAAQE;CAAS,CAAC,CAACM,OAAOC,OAAO,CAAC,CAACL,KAAK,GAAG;CACtG,OAAOE,UAAUC,MAAM,IAAIA;AAC7B;AAEA,MAAMG,6CAA8E,EAClFC,aAAa,QACf;AAEA,SAASC,cAAcC,SAAsC;CAC3DjD,eAAAC,gBAAA,CAAA,CAAAM,UAAAC,IAAAC,KAAA,OAAAC,SAAA;EAAA,IAAA,CAAAA,MAAA,MAAA,IAAAC,MACE,iDAAiD,OAAOsC,SAAS;CAAA,EAAA,CACjE,OAAOA,YAAY,YAAYlB,MAAMC,QAAQiB,OAAO,CAAC;CAEvD,OAAO,OAAOA,YAAY,WAAWA,QAAQC,MAAM,GAAG,IAAID;AAC5D;;;;;;;;;;;;;;AAeA,SAAgBE,YAAYC,QAAoE;CAC9F,MAAMC,SAAuC,CAAC;CAC9C,KAAK,MAAMC,OAAOF,QAAQ;EACxB,MAAMG,QAAQH,OAAOE;EAErB,IAAIC,UAAUC,UAAaD,UAAU,QAAQA,UAAU,IACrD;OAAI,CAACxB,MAAMC,QAAQuB,KAAK,KAAKA,MAAMjC,SAAS,GAC1C+B,OAAOC,OAAOF,OAAOE;EACvB;CAEJ;CACA,OAAOD;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgBI,gBAAgBC,QAA2BzC,SAA4D;CACrH,MAAM0C,OAAO9B,OAAOC,OAAO,CAAC,GAAGgB,4CAA4C7B,OAAO;CAClF,MAAM2C,iBAAiB,EAAEF,kBAAkBG;CAC3C,MAAMC,YAAY,IAAID,gBAAgB;CAItC,MAAME,mBAAiDH,iBAAiB/B,OAAOC,OAAO,CAAC,GAAG4B,MAAM,IAAI,CAAC;CAErG,IAAI,CAACE,gBACHF,OAAOM,SAAST,OAAOD,QAAQ;EAE7B,IAAI,EADgBA,OAAOS,mBAEzBA,iBAAiBT,OAAOC;OACnB;GACL,MAAMW,gBAAgBH,iBAAiBT;GACvC,IAAIvB,MAAMC,QAAQkC,aAAa,GAC7BA,cAAcC,KAAKZ,KAAK;QAExBQ,iBAAiBT,OAAO,CAACY,eAAeX,KAAK;EAEjD;CACF,CAAC;CAGH,IAAI,aAAaQ,kBACfA,iBAAiBd,UAAUD,cAAce,iBAAiBd,OAA4B;CAIxFmB,AADmBvC,OAAOwC,KAAKN,gBAAgB,CAAC,CAACO,KACjDF,CAAU,CAACJ,SAASV,QAAQ;EAC1B,MAAMC,QAAQQ,iBAAiBT;EAC/B,IAAIvB,MAAMC,QAAQuB,KAAK,GAAG;GACxB,MAAMgB,cAAchB,MAAMiB,SAAS;GACnC,QAAQb,KAAKZ,aAAb;IACE,KAAK;KACHwB,YAAYP,SAASS,GAAGvC,MAAM;MAC5B4B,UAAUY,OAAO,GAAGpB,IAAG,GAAIpB,EAAC,IAAKK,OAAOkC,CAAC,CAAC;KAC5C,CAAC;KACD;IACF,KAAK;KACHF,YAAYP,SAASS,MAAM;MACzBX,UAAUY,OAAO,GAAGpB,IAAG,KAAMf,OAAOkC,CAAC,CAAC;KACxC,CAAC;KACD;IACF,KAAK;KACHF,YAAYP,SAASS,MAAM;MACzBX,UAAUY,OAAOpB,KAAKf,OAAOkC,CAAC,CAAC;KACjC,CAAC;KACD;IAEF;KACEX,UAAUY,OAAOpB,KAAKiB,YAAY/B,KAAK,GAAG,CAAC;KAC3C;GACJ;EACF,OACEsB,UAAUY,OAAOpB,KAAKf,OAAOgB,KAAK,CAAC;CAEvC,CAAC;CAED,OAAOO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgBa,iBAAiBjB,QAA2BzC,SAAmD;CAC7G,OAAOwC,gBAAgBC,QAAQzC,OAAO,CAAC,CAAC2D,SAAS;AACnD"}

package/dist/json-api.d.ts

@@ -1,4 +1,4 @@
-import { t as BuildURLConfig } from "./index-D6QIwzqm.js";
+import { t as BuildURLConfig } from "./index-Ds06tKwC.js";
 import { ReactiveDataDocument } from "@warp-drive/core/reactive";
 import { TypeFromInstance, TypedRecordInstance } from "@warp-drive/core/types/record";
 import { ConstrainedRequestOptions, CreateRequestOptions, DeleteRequestOptions, FindRecordOptions, FindRecordRequestOptions, PostQueryRequestOptions, QueryRequestOptions, RemotelyAccessibleIdentifier, UpdateRequestOptions } from "@warp-drive/core/types/request";
@@ -13,6 +13,9 @@ import { Value } from "@warp-drive/core/types/json/raw";
  * Builds request options to fetch a single resource by a known id or identifier
  * configured for the url and header expectations of most JSON:API APIs.
  *
+ * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+ * when to use one.
+ *
  * :::tabs
  *
  * == Basic Usage
@@ -82,6 +85,7 @@ import { Value } from "@warp-drive/core/types/json/raw";
  * );
  * ```
  *
+ * @summary Builds a JSON:API `GET` request for one resource by type and id, with optional `include`.
  * @public
  */
 export declare function findRecord<T, M extends Meta | undefined = Meta | undefined, E extends object = ApiError>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T, M, E>, T>;
@@ -94,6 +98,9 @@ export declare function findRecord(type: string, id: string, options?: FindRecor
  * Builds request options to query for resources, usually by a primary
  * type, configured for the url and header expectations of most JSON:API APIs.
  *
+ * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+ * when to use one.
+ *
  * The key difference between this and `postQuery` is that this method will send the query
  * as query params in the url of a "GET" request instead of as the JSON body of a "POST"
  * request.
@@ -136,6 +143,7 @@ export declare function findRecord(type: string, id: string, options?: FindRecor
  * const data = await store.request(options);
  * ```
  *
+ * @summary Builds a JSON:API `GET` request that queries a resource type, sending the query as URL query params.
  * @public
  * @badge Builder
  */
@@ -145,6 +153,9 @@ export declare function query(type: string, query?: QueryParamsSource, options?:
  * Builds request options to query for resources, usually by a primary
  * type, configured for the url and header expectations of most JSON:API APIs.
  *
+ * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+ * when to use one.
+ *
  * The key difference between this and `query` is that this method will send the query
  * as the JSON body of a "POST" request instead of as query params in the url of a "GET"
  * request.
@@ -180,6 +191,8 @@ export declare function query(type: string, query?: QueryParamsSource, options?:
  * const data = await store.request(options);
  * ```
  *
+ * @summary Builds a JSON:API `POST` request that sends a query as the JSON body, cached under a key built from the
+ * query params.
  * @public
  * @param type - the name of the resource type to query
  * @param query - the query params to send with the request
@@ -198,6 +211,9 @@ export declare function postQuery(type: string, query?: QueryParamsSource, optio
  * Builds request options to delete record for resources,
  * configured for the url, method and header expectations of most JSON:API APIs.
  *
+ * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+ * when to use one.
+ *
  * **Basic Usage**
  *
  * ```ts
@@ -239,6 +255,7 @@ export declare function postQuery(type: string, query?: QueryParamsSource, optio
  * const data = await store.request(options);
  * ```
  *
+ * @summary Builds a JSON:API `DELETE` request that persists deletion of an existing record.
  * @public
  * @param record
  * @param options
@@ -254,6 +271,9 @@ export declare function deleteRecord(record: unknown, options?: ConstrainedReque
  * Builds request options to create new record for resources,
  * configured for the url, method and header expectations of most JSON:API APIs.
  *
+ * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+ * when to use one.
+ *
  * **Basic Usage**
  *
  * ```ts
@@ -295,6 +315,7 @@ export declare function deleteRecord(record: unknown, options?: ConstrainedReque
  * const data = await store.request(options);
  * ```
  *
+ * @summary Builds a JSON:API `POST` request for saving a new record; the app must set the request body itself.
  * @public
  * @param record
  * @param options
@@ -310,6 +331,9 @@ export declare function createRecord(record: unknown, options?: ConstrainedReque
  * Builds request options to update existing record for resources,
  * configured for the url, method and header expectations of most JSON:API APIs.
  *
+ * See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+ * when to use one.
+ *
  * **Example Usage**
  *
  * ```ts
@@ -354,6 +378,8 @@ export declare function createRecord(record: unknown, options?: ConstrainedReque
  * const data = await store.request(options);
  * ```
  *
+ * @summary Builds a JSON:API `PUT` (or `PATCH`) request for saving an existing record; the app must set the request
+ * body itself.
  * @public
  * @param record
  * @param options
@@ -389,6 +415,8 @@ type JsonApiResourcePatch = {
  *
  * Serializes the current state of a resource or array of resources for use with POST or PUT requests.
  *
+ * @summary Copies the cached state of one or more resources into a JSON:API-style `{ data }` object, a starting point
+ * for request bodies.
  * @public
  * @param cache - the cache to serialize the resource(s) from
  * @param identifiers - the resource(s) to serialize
@@ -429,6 +457,8 @@ export declare function serializeResources(cache: Cache, identifiers: ResourceKe
  * const relationshipDiffMap = cache.changedRelationships(identifier);
  * ```
  *
+ * @summary Serializes only a resource's changed attributes and relationships from the cache into a JSON:API-style
+ * `{ data }` patch.
  * @public
  * @param cache - the cache to serialize the resource's changes from
  * @param identifier - the resource whose changes should be serialized
@@ -458,6 +488,9 @@ interface JSONAPIConfig extends BuildURLConfig {
  * Extensions and profiles are keyed by their namespace with the value being
  * their URI.
  *
+ * The [Basic Usage](/guides/the-manual/cookbook/basic-usage#step-2-configure-some-request-defaults)
+ * guide uses it to configure a host, a namespace and a pagination profile.
+ *
  * Example:
  *
  * ```ts
@@ -487,6 +520,8 @@ interface JSONAPIConfig extends BuildURLConfig {
  * }
  * ```
  *
+ * @summary Sets the JSON:API extensions and profiles sent in the `Accept` header, plus the global URL host and
+ * namespace.
  * @public
  * @param {BuildURLConfig} config
  * @return {void}

package/dist/json-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-api.d.ts","names":[],"sources":["../src/-private/json-api/find-record.ts","../src/-private/json-api/query.ts","../src/-private/json-api/save-record.ts","../src/-private/json-api/serialize.ts","../src/-private/json-api/-utils.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA0FgB,WAAW,GAAG,UAAU,mBAAmB,kBAAkB,mBAAmB,UAC9F,YAAY,6BAA6B,iBAAiB,KAC1D,UAAU,oBACT,yBAAyB,qBAAqB,GAAG,GAAG,IAAI;wBAC3C,WACd,YAAY,8BACZ,UAAU,oBACT;wBACa,WAAW,GAAG,UAAU,mBAAmB,kBAAkB,mBAAmB,UAC9F,MAAM,iBAAiB,IACvB,YACA,UAAU,oBACT,yBAAyB,qBAAqB,GAAG,GAAG,IAAI;wBAC3C,WAAW,cAAc,YAAY,UAAU,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBCtCnE,MACd,UAAU,qBACV,UAAU,mBAAmB,kBAC7B,mBAAmB,UAEnB,MAAM,iBAAiB,IACvB,QAAQ,mBACR,UAAU,4BACT,oBAAoB,qBAAqB,KAAK,GAAG;wBACpC,MACd,cACA,QAAQ,mBACR,UAAU,4BACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA0Ea,UAAU,GAAG,UAAU,mBAAmB,kBAAkB,mBAAmB,UAC7F,MAAM,iBAAiB,IACvB,QAAQ,mBACR,UAAU,4BACT,wBAAwB,qBAAqB,KAAK,GAAG;wBACxC,UACd,cACA,QAAQ,mBACR,UAAU,4BACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBC/Ea,aAAa,GAAG,QAAQ,GAAG,UAAU,4BAA4B,qBAAqB;wBACtF,aAAa,iBAAiB,UAAU,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoFpE,aAAa,GAAG,QAAQ,GAAG,UAAU,4BAA4B,qBAAqB;wBACtF,aAAa,iBAAiB,UAAU,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAsFpE,aACd,UAAU,qBACV,WAAW,sBAAsB,GACjC,UAAU,mBAAmB,kBAC7B,mBAAmB,UAEnB,QAAQ,GACR,UAAU;EAA8B;IACvC,qBAAqB,qBAAqB,IAAI,GAAG,IAAI;wBACxC,aACd,iBACA,UAAU;EAA8B;IACvC;;;KCnQE,0BAA0B;KAEnB;EAEN;EACA;EACA,aAAa,eAAe;EAC5B,gBAAgB,eAAe;;EAG/B;EACA;EACA;EACA,aAAa,eAAe;EAC5B,gBAAgB,eAAe;;;;;;;;;;;;;;;;;wBAkBrB,mBACd,OAAO,OACP,aAAa;;;;EAKb,MAAM;;wBAEQ,mBACd,OAAO,OACP,aAAa;;;;EAKb,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAqGQ,eACd,OAAO,OACP,YAAY;;;;EAMZ,MAAM;;;;UC/JS,sBAAsB;EACrC;IACE;;;EAGF;IACE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAiDY,kBAAkB,QAAQ"}
+{"version":3,"file":"json-api.d.ts","names":[],"sources":["../src/-private/json-api/find-record.ts","../src/-private/json-api/query.ts","../src/-private/json-api/save-record.ts","../src/-private/json-api/serialize.ts","../src/-private/json-api/-utils.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA8FgB,WAAW,GAAG,UAAU,mBAAmB,kBAAkB,mBAAmB,UAC9F,YAAY,6BAA6B,iBAAiB,KAC1D,UAAU,oBACT,yBAAyB,qBAAqB,GAAG,GAAG,IAAI;wBAC3C,WACd,YAAY,8BACZ,UAAU,oBACT;wBACa,WAAW,GAAG,UAAU,mBAAmB,kBAAkB,mBAAmB,UAC9F,MAAM,iBAAiB,IACvB,YACA,UAAU,oBACT,yBAAyB,qBAAqB,GAAG,GAAG,IAAI;wBAC3C,WAAW,cAAc,YAAY,UAAU,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBCtCnE,MACd,UAAU,qBACV,UAAU,mBAAmB,kBAC7B,mBAAmB,UAEnB,MAAM,iBAAiB,IACvB,QAAQ,mBACR,UAAU,4BACT,oBAAoB,qBAAqB,KAAK,GAAG;wBACpC,MACd,cACA,QAAQ,mBACR,UAAU,4BACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA+Ea,UAAU,GAAG,UAAU,mBAAmB,kBAAkB,mBAAmB,UAC7F,MAAM,iBAAiB,IACvB,QAAQ,mBACR,UAAU,4BACT,wBAAwB,qBAAqB,KAAK,GAAG;wBACxC,UACd,cACA,QAAQ,mBACR,UAAU,4BACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBCpFa,aAAa,GAAG,QAAQ,GAAG,UAAU,4BAA4B,qBAAqB;wBACtF,aAAa,iBAAiB,UAAU,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwFpE,aAAa,GAAG,QAAQ,GAAG,UAAU,4BAA4B,qBAAqB;wBACtF,aAAa,iBAAiB,UAAU,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2FpE,aACd,UAAU,qBACV,WAAW,sBAAsB,GACjC,UAAU,mBAAmB,kBAC7B,mBAAmB,UAEnB,QAAQ,GACR,UAAU;EAA8B;IACvC,qBAAqB,qBAAqB,IAAI,GAAG,IAAI;wBACxC,aACd,iBACA,UAAU;EAA8B;IACvC;;;KChRE,0BAA0B;KAEnB;EAEN;EACA;EACA,aAAa,eAAe;EAC5B,gBAAgB,eAAe;;EAG/B;EACA;EACA;EACA,aAAa,eAAe;EAC5B,gBAAgB,eAAe;;;;;;;;;;;;;;;;;;;wBAoBrB,mBACd,OAAO,OACP,aAAa;;;;EAKb,MAAM;;wBAEQ,mBACd,OAAO,OACP,aAAa;;;;EAKb,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAuGQ,eACd,OAAO,OACP,YAAY;;;;EAMZ,MAAM;;;;UCnKS,sBAAsB;EACrC;IACE;;;EAGF;IACE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAsDY,kBAAkB,QAAQ"}

package/dist/json-api.js

@@ -1,5 +1,5 @@
 import { buildBaseURL, buildQueryParams, setBuildURLConfig as setBuildURLConfig$1 } from "./index.js";
-import { s as pluralize } from "./string-CWmAluxh.js";
+import { s as pluralize } from "./string-BZACNuLp.js";
 import { n as extractCacheOptions, t as copyForwardUrlOptions } from "./builder-utils-BkXwUT0x.js";
 import { getGlobalConfig, macroCondition } from "@embroider/macros";
 import { recordIdentifierFor } from "@warp-drive/core";
@@ -18,6 +18,9 @@ let ACCEPT_HEADER_VALUE = "application/vnd.api+json";
 * Extensions and profiles are keyed by their namespace with the value being
 * their URI.
 *
+* The [Basic Usage](/guides/the-manual/cookbook/basic-usage#step-2-configure-some-request-defaults)
+* guide uses it to configure a host, a namespace and a pagination profile.
+*
 * Example:
 *
 * ```ts
@@ -47,6 +50,8 @@ let ACCEPT_HEADER_VALUE = "application/vnd.api+json";
 * }
 * ```
 *
+* @summary Sets the JSON:API extensions and profiles sent in the `Accept` header, plus the global URL host and
+* namespace.
 * @public
 * @param {BuildURLConfig} config
 * @return {void}
@@ -155,6 +160,9 @@ function isExisting(identifier) {
 * Builds request options to delete record for resources,
 * configured for the url, method and header expectations of most JSON:API APIs.
 *
+* See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+* when to use one.
+*
 * **Basic Usage**
 *
 * ```ts
@@ -196,6 +204,7 @@ function isExisting(identifier) {
 * const data = await store.request(options);
 * ```
 *
+* @summary Builds a JSON:API `DELETE` request that persists deletion of an existing record.
 * @public
 * @param record
 * @param options
@@ -235,6 +244,9 @@ function deleteRecord(record, options = {}) {
 * Builds request options to create new record for resources,
 * configured for the url, method and header expectations of most JSON:API APIs.
 *
+* See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+* when to use one.
+*
 * **Basic Usage**
 *
 * ```ts
@@ -276,6 +288,7 @@ function deleteRecord(record, options = {}) {
 * const data = await store.request(options);
 * ```
 *
+* @summary Builds a JSON:API `POST` request for saving a new record; the app must set the request body itself.
 * @public
 * @param record
 * @param options
@@ -312,6 +325,9 @@ function createRecord(record, options = {}) {
 * Builds request options to update existing record for resources,
 * configured for the url, method and header expectations of most JSON:API APIs.
 *
+* See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+* when to use one.
+*
 * **Example Usage**
 *
 * ```ts
@@ -356,6 +372,8 @@ function createRecord(record, options = {}) {
 * const data = await store.request(options);
 * ```
 *
+* @summary Builds a JSON:API `PUT` (or `PATCH`) request for saving an existing record; the app must set the request
+* body itself.
 * @public
 * @param record
 * @param options
@@ -399,6 +417,8 @@ function updateRecord(record, options = {}) {
 *
 * Serializes the current state of a resource or array of resources for use with POST or PUT requests.
 *
+* @summary Copies the cached state of one or more resources into a JSON:API-style `{ data }` object, a starting point
+* for request bodies.
 * @public
 * @param cache - the cache to serialize the resource(s) from
 * @param identifiers - the resource(s) to serialize
@@ -461,6 +481,8 @@ function _serializeResource(cache, identifier) {
 * const relationshipDiffMap = cache.changedRelationships(identifier);
 * ```
 *
+* @summary Serializes only a resource's changed attributes and relationships from the cache into a JSON:API-style
+* `{ data }` patch.
 * @public
 * @param cache - the cache to serialize the resource's changes from
 * @param identifier - the resource whose changes should be serialized