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

package/dist/{string-CWmAluxh.js → string-BZACNuLp.js}

@@ -24,6 +24,7 @@ const CAPITALIZE_CACHE = new LRUCache((str) => str.replace(STRING_CAPITALIZE_REG
 * dasherize('privateDocs/ownerInvoice';  // 'private-docs/owner-invoice'
 * ```
 *
+* @summary Converts camelCase, underscored, or spaced strings to dasherized form, such as `innerHTML` to `inner-html`.
 * @public
 * @since 4.13.0
 */
@@ -42,6 +43,8 @@ const dasherize$1 = dasherize;
 * camelize('private-docs/owner-invoice');  // 'privateDocs/ownerInvoice'
 * ```
 *
+* @summary Converts dashed, underscored, dotted, or spaced strings to lowerCamelCase, such as `action_name` to
+* `actionName`.
 * @public
 * @since 4.13.0
 */
@@ -61,6 +64,7 @@ function camelize(str) {
 * underscore('privateDocs/ownerInvoice');  // 'private_docs/owner_invoice'
 * ```
 *
+* @summary Converts camelCase, dashed, or spaced strings to lowercase snake_case, such as `innerHTML` to `inner_html`.
 * @public
 * @since 4.13.0
 */
@@ -80,6 +84,7 @@ function underscore(str) {
 * capitalize('privateDocs/ownerInvoice'); // 'PrivateDocs/ownerInvoice'
 * ```
 *
+* @summary Uppercases the first letter of a string, and of each `/`-separated path segment, leaving the rest unchanged.
 * @public
 * @since 4.13.0
 */
@@ -90,6 +95,8 @@ function capitalize(str) {
 * Sets the maximum size of the LRUCache for all string transformation functions.
 * The default size is 10,000.
 *
+* @summary Sets how many results the `camelize`, `underscore`, `capitalize`, and `dasherize` caches each keep (default
+* 10,000).
 * @public
 * @since 4.13.0
 */
@@ -121,6 +128,7 @@ const PLURAL_RULES = new Map(defaultRules.plurals.reverse());
 * Marks a word as uncountable. Uncountable words are not pluralized
 * or singularized.
 *
+* @summary Registers a word that `pluralize` and `singularize` should always return unchanged.
 * @public
 * @since 4.13.0
 */
@@ -131,6 +139,7 @@ function uncountable(word) {
 * Marks a list of words as uncountable. Uncountable words are not pluralized
 * or singularized.
 *
+* @summary Registers a list of words that `pluralize` and `singularize` should always return unchanged.
 * @public
 * @since 4.13.0
 */
@@ -143,6 +152,8 @@ function loadUncountable(uncountables) {
 * Marks a word as irregular. Irregular words have unique
 * pluralization and singularization rules.
 *
+* @summary Registers a singular and plural word pair that `pluralize` and `singularize` map directly instead of
+* applying rules.
 * @public
 * @since 4.13.0
 */
@@ -156,6 +167,7 @@ function irregular(single, plur) {
 * Marks a list of word pairs as irregular. Irregular words have unique
 * pluralization and singularization rules.
 *
+* @summary Registers a list of singular and plural word pairs that `pluralize` and `singularize` map directly.
 * @public
 * @since 4.13.0
 */
@@ -171,6 +183,7 @@ loadIrregular(defaultRules.irregularPairs);
 /**
 * Clears the caches for singularize and pluralize.
 *
+* @summary Empties the cached results of `singularize` and `pluralize` while keeping all inflection rules.
 * @public
 * @since 4.13.0
 */
@@ -181,6 +194,7 @@ function clear() {
 /**
 * Resets the inflection rules to the defaults.
 *
+* @summary Discards all custom inflection rules and caches, then restores the built-in default rules.
 * @public
 * @since 4.13.0
 */
@@ -195,6 +209,7 @@ function resetToDefaults() {
 * Clears all inflection rules
 * and resets the caches for singularize and pluralize.
 *
+* @summary Removes every inflection rule, including the defaults, and empties the `singularize` and `pluralize` caches.
 * @public
 * @since 4.13.0
 */
@@ -210,6 +225,7 @@ function clearRules() {
 /**
 * Singularizes a word.
 *
+* @summary Returns the singular form of an English word using the registered inflection rules, with cached results.
 * @public
 * @since 4.13.0
 */
@@ -223,6 +239,7 @@ function singularize(word) {
 /**
 * Pluralizes a word.
 *
+* @summary Returns the plural form of an English word using the registered inflection rules, with cached results.
 * @public
 * @since 4.13.0
 */
@@ -243,6 +260,7 @@ function unshiftMap(v, map) {
 /**
 * Adds a pluralization rule.
 *
+* @summary Adds a regex and replacement rule that `pluralize` checks before all existing plural rules.
 * @public
 * @since 4.13.0
 */
@@ -253,6 +271,7 @@ function plural(regex, string) {
 /**
 * Adds a singularization rule.
 *
+* @summary Adds a regex and replacement rule that `singularize` checks before all existing singular rules.
 * @public
 * @since 4.13.0
 */
@@ -287,4 +306,4 @@ function inflect(word, typeRules, irregulars) {
 
 //#endregion
 export { loadUncountable as a, resetToDefaults as c, uncountable as d, camelize as f, underscore as g, setMaxLRUCacheSize as h, loadIrregular as i, singular as l, dasherize$1 as m, clearRules as n, plural as o, capitalize as p, irregular as r, pluralize as s, clear as t, singularize as u };
-//# sourceMappingURL=string-CWmAluxh.js.map
+//# sourceMappingURL=string-BZACNuLp.js.map

package/dist/string-BZACNuLp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-BZACNuLp.js","names":["dasherize","internalDasherize","LRUCache","defaultRules","capitalize","macroCondition","getGlobalConfig","BLANK_REGEX","LAST_WORD_DASHED_REGEX","LAST_WORD_CAMELIZED_REGEX","CAMELIZED_REGEX","SINGULARS","word","_singularize","PLURALS","_pluralize","UNCOUNTABLE","Set","uncountable","IRREGULAR","Map","INVERSE_IRREGULAR","SINGULAR_RULES","singular","reverse","PLURAL_RULES","plurals","add","toLowerCase","loadUncountable","uncountables","forEach","irregular","single","plur","set","loadIrregular","irregularPairs","pair","clear","resetToDefaults","clearRules","v","singularize","WarpDrive","env","DEBUG","test","Error","length","get","pluralize","unshiftMap","map","rules","entries","rule","plural","regex","string","has","delete","inflect","typeRules","irregulars","isBlank","lowercase","wordSplit","exec","lastWord","isCamelized","substitution","match","replace","RegExp"],"sources":["../src/-private/string/transform.ts","../src/-private/string/inflect.ts"],"sourcesContent":["import { dasherize as internalDasherize, LRUCache, STRING_DASHERIZE_CACHE } from '@warp-drive/core/utils/string';\n\n// oxlint-disable-next-line no-useless-escape\nconst STRING_CAMELIZE_REGEXP_1 = /(\\-|\\_|\\.|\\s)+(.)?/g;\nconst STRING_CAMELIZE_REGEXP_2 = /(^|\\/)([A-Z])/g;\nconst CAMELIZE_CACHE = new LRUCache<string, string>((key: string) =>\n  key\n    .replace(STRING_CAMELIZE_REGEXP_1, (_match, _separator, chr: string | null) => (chr ? chr.toUpperCase() : ''))\n    .replace(STRING_CAMELIZE_REGEXP_2, (match /*, separator, chr */) => match.toLowerCase())\n);\n\nconst STRING_UNDERSCORE_REGEXP_1 = /([a-z\\d])([A-Z]+)/g;\n// oxlint-disable-next-line no-useless-escape\nconst STRING_UNDERSCORE_REGEXP_2 = /\\-|\\s+/g;\nconst UNDERSCORE_CACHE = new LRUCache<string, string>((str: string) =>\n  str.replace(STRING_UNDERSCORE_REGEXP_1, '$1_$2').replace(STRING_UNDERSCORE_REGEXP_2, '_').toLowerCase()\n);\n\nconst STRING_CAPITALIZE_REGEXP = /(^|\\/)([a-z\\u00C0-\\u024F])/g;\nconst CAPITALIZE_CACHE = new LRUCache<string, string>((str: string) =>\n  str.replace(STRING_CAPITALIZE_REGEXP, (match /*, separator, chr */) => match.toUpperCase())\n);\n\n/**\n * Replaces underscores, spaces, or camelCase with dashes.\n *\n * ```js\n * import { dasherize } from '@warp-drive/utilities/string';\n *\n * dasherize('innerHTML');                // 'inner-html'\n * dasherize('action_name');              // 'action-name'\n * dasherize('css-class-name');           // 'css-class-name'\n * dasherize('my favorite items');        // 'my-favorite-items'\n * dasherize('privateDocs/ownerInvoice';  // 'private-docs/owner-invoice'\n * ```\n *\n * @summary Converts camelCase, underscored, or spaced strings to dasherized form, such as `innerHTML` to `inner-html`.\n * @public\n * @since 4.13.0\n */\nexport const dasherize: (str: string) => string = internalDasherize;\n\n/**\n * Returns the lowerCamelCase form of a string.\n *\n * ```js\n * import { camelize } from '@warp-drive/utilities/string';\n *\n * camelize('innerHTML');                   // 'innerHTML'\n * camelize('action_name');                 // 'actionName'\n * camelize('css-class-name');              // 'cssClassName'\n * camelize('my favorite items');           // 'myFavoriteItems'\n * camelize('My Favorite Items');           // 'myFavoriteItems'\n * camelize('private-docs/owner-invoice');  // 'privateDocs/ownerInvoice'\n * ```\n *\n * @summary Converts dashed, underscored, dotted, or spaced strings to lowerCamelCase, such as `action_name` to\n * `actionName`.\n * @public\n * @since 4.13.0\n */\nexport function camelize(str: string): string {\n  return CAMELIZE_CACHE.get(str);\n}\n\n/**\n * Returns the lower\\_case\\_and\\_underscored form of a string.\n *\n * ```js\n * import { underscore } from '@warp-drive/utilities/string';\n *\n * underscore('innerHTML');                 // 'inner_html'\n * underscore('action_name');               // 'action_name'\n * underscore('css-class-name');            // 'css_class_name'\n * underscore('my favorite items');         // 'my_favorite_items'\n * underscore('privateDocs/ownerInvoice');  // 'private_docs/owner_invoice'\n * ```\n *\n * @summary Converts camelCase, dashed, or spaced strings to lowercase snake_case, such as `innerHTML` to `inner_html`.\n * @public\n * @since 4.13.0\n */\nexport function underscore(str: string): string {\n  return UNDERSCORE_CACHE.get(str);\n}\n\n/**\n * Returns the Capitalized form of a string\n *\n * ```js\n * import { capitalize } from '@warp-drive/utilities/string';\n *\n * capitalize('innerHTML')                 // 'InnerHTML'\n * capitalize('action_name')               // 'Action_name'\n * capitalize('css-class-name')            // 'Css-class-name'\n * capitalize('my favorite items')         // 'My favorite items'\n * capitalize('privateDocs/ownerInvoice'); // 'PrivateDocs/ownerInvoice'\n * ```\n *\n * @summary Uppercases the first letter of a string, and of each `/`-separated path segment, leaving the rest unchanged.\n * @public\n * @since 4.13.0\n */\nexport function capitalize(str: string): string {\n  return CAPITALIZE_CACHE.get(str);\n}\n\n/**\n * Sets the maximum size of the LRUCache for all string transformation functions.\n * The default size is 10,000.\n *\n * @summary Sets how many results the `camelize`, `underscore`, `capitalize`, and `dasherize` caches each keep (default\n * 10,000).\n * @public\n * @since 4.13.0\n */\nexport function setMaxLRUCacheSize(size: number): void {\n  CAMELIZE_CACHE.size = size;\n  UNDERSCORE_CACHE.size = size;\n  CAPITALIZE_CACHE.size = size;\n  STRING_DASHERIZE_CACHE.size = size;\n}\n","import { assert } from '@warp-drive/core/build-config/macros';\nimport { LRUCache } from '@warp-drive/core/utils/string';\n\nimport { defaultRules } from './inflections.ts';\nimport { capitalize } from './transform.ts';\n\nconst BLANK_REGEX = /^\\s*$/;\nconst LAST_WORD_DASHED_REGEX = /([\\w/-]+[_/\\s-])([a-z\\d]+$)/;\nconst LAST_WORD_CAMELIZED_REGEX = /([\\w/\\s-]+)([A-Z][a-z\\d]*$)/;\nconst CAMELIZED_REGEX = /[A-Z][a-z\\d]*$/;\n\nconst SINGULARS = new LRUCache<string, string>((word: string) => {\n  return _singularize(word);\n});\nconst PLURALS = new LRUCache<string, string>((word: string) => {\n  return _pluralize(word);\n});\nconst UNCOUNTABLE = new Set(defaultRules.uncountable);\nconst IRREGULAR: Map<string, string> = new Map();\nconst INVERSE_IRREGULAR: Map<string, string> = new Map();\nconst SINGULAR_RULES = new Map(defaultRules.singular.reverse());\nconst PLURAL_RULES = new Map(defaultRules.plurals.reverse());\n\n/**\n * Marks a word as uncountable. Uncountable words are not pluralized\n * or singularized.\n *\n * @summary Registers a word that `pluralize` and `singularize` should always return unchanged.\n * @public\n * @since 4.13.0\n */\nexport function uncountable(word: string): void {\n  UNCOUNTABLE.add(word.toLowerCase());\n}\n\n/**\n * Marks a list of words as uncountable. Uncountable words are not pluralized\n * or singularized.\n *\n * @summary Registers a list of words that `pluralize` and `singularize` should always return unchanged.\n * @public\n * @since 4.13.0\n */\nexport function loadUncountable(uncountables: string[]): void {\n  uncountables.forEach((word) => {\n    uncountable(word);\n  });\n}\n\n/**\n * Marks a word as irregular. Irregular words have unique\n * pluralization and singularization rules.\n *\n * @summary Registers a singular and plural word pair that `pluralize` and `singularize` map directly instead of\n * applying rules.\n * @public\n * @since 4.13.0\n */\nexport function irregular(single: string, plur: string): void {\n  //pluralizing\n  IRREGULAR.set(single.toLowerCase(), plur);\n  IRREGULAR.set(plur.toLowerCase(), plur);\n\n  //singularizing\n  INVERSE_IRREGULAR.set(plur.toLowerCase(), single);\n  INVERSE_IRREGULAR.set(single.toLowerCase(), single);\n}\n\n/**\n * Marks a list of word pairs as irregular. Irregular words have unique\n * pluralization and singularization rules.\n *\n * @summary Registers a list of singular and plural word pairs that `pluralize` and `singularize` map directly.\n * @public\n * @since 4.13.0\n */\nexport function loadIrregular(irregularPairs: Array<[string, string]>): void {\n  irregularPairs.forEach((pair) => {\n    //pluralizing\n    IRREGULAR.set(pair[0].toLowerCase(), pair[1]);\n    IRREGULAR.set(pair[1].toLowerCase(), pair[1]);\n\n    //singularizing\n    INVERSE_IRREGULAR.set(pair[1].toLowerCase(), pair[0]);\n    INVERSE_IRREGULAR.set(pair[0].toLowerCase(), pair[0]);\n  });\n}\nloadIrregular(defaultRules.irregularPairs);\n\n/**\n * Clears the caches for singularize and pluralize.\n *\n * @summary Empties the cached results of `singularize` and `pluralize` while keeping all inflection rules.\n * @public\n * @since 4.13.0\n */\nexport function clear(): void {\n  SINGULARS.clear();\n  PLURALS.clear();\n}\n\n/**\n * Resets the inflection rules to the defaults.\n *\n * @summary Discards all custom inflection rules and caches, then restores the built-in default rules.\n * @public\n * @since 4.13.0\n */\nexport function resetToDefaults(): void {\n  clearRules();\n  defaultRules.uncountable.forEach((v) => UNCOUNTABLE.add(v));\n  defaultRules.singular.forEach((v) => SINGULAR_RULES.set(v[0], v[1]));\n  defaultRules.plurals.forEach((v) => PLURAL_RULES.set(v[0], v[1]));\n  loadIrregular(defaultRules.irregularPairs);\n}\n\n/**\n * Clears all inflection rules\n * and resets the caches for singularize and pluralize.\n *\n * @summary Removes every inflection rule, including the defaults, and empties the `singularize` and `pluralize` caches.\n * @public\n * @since 4.13.0\n */\nexport function clearRules(): void {\n  SINGULARS.clear();\n  PLURALS.clear();\n  UNCOUNTABLE.clear();\n  IRREGULAR.clear();\n  INVERSE_IRREGULAR.clear();\n  SINGULAR_RULES.clear();\n  PLURAL_RULES.clear();\n}\n\n/**\n * Singularizes a word.\n *\n * @summary Returns the singular form of an English word using the registered inflection rules, with cached results.\n * @public\n * @since 4.13.0\n */\nexport function singularize(word: string): string {\n  assert(`singularize expects to receive a non-empty string`, typeof word === 'string' && word.length > 0);\n  if (!word) return '';\n  return SINGULARS.get(word);\n}\n\n/**\n * Pluralizes a word.\n *\n * @summary Returns the plural form of an English word using the registered inflection rules, with cached results.\n * @public\n * @since 4.13.0\n */\nexport function pluralize(word: string): string {\n  assert(`pluralize expects to receive a non-empty string`, typeof word === 'string' && word.length > 0);\n  if (!word) return '';\n  return PLURALS.get(word);\n}\n\nfunction unshiftMap<K, V>(v: [K, V], map: Map<K, V>) {\n  // reorder\n  const rules = [v, ...map.entries()];\n  map.clear();\n  rules.forEach((rule) => {\n    map.set(rule[0], rule[1]);\n  });\n}\n\n/**\n * Adds a pluralization rule.\n *\n * @summary Adds a regex and replacement rule that `pluralize` checks before all existing plural rules.\n * @public\n * @since 4.13.0\n */\nexport function plural(regex: RegExp, string: string): void {\n  // rule requires reordering if exists, so remove it first\n  if (PLURAL_RULES.has(regex)) {\n    PLURAL_RULES.delete(regex);\n  }\n\n  // reorder\n  unshiftMap([regex, string], PLURAL_RULES);\n}\n\n/**\n * Adds a singularization rule.\n *\n * @summary Adds a regex and replacement rule that `singularize` checks before all existing singular rules.\n * @public\n * @since 4.13.0\n */\nexport function singular(regex: RegExp, string: string): void {\n  // rule requires reordering if exists, so remove it first\n  if (SINGULAR_RULES.has(regex)) {\n    SINGULAR_RULES.delete(regex);\n  }\n\n  // reorder\n  unshiftMap([regex, string], SINGULAR_RULES);\n}\n\nfunction _pluralize(word: string) {\n  return inflect(word, PLURAL_RULES, IRREGULAR);\n}\n\nfunction _singularize(word: string) {\n  return inflect(word, SINGULAR_RULES, INVERSE_IRREGULAR);\n}\n\nfunction inflect(word: string, typeRules: Map<RegExp, string>, irregulars: Map<string, string>) {\n  // empty strings\n  const isBlank = !word || BLANK_REGEX.test(word);\n  if (isBlank) {\n    return word;\n  }\n\n  // basic uncountables\n  const lowercase = word.toLowerCase();\n  if (UNCOUNTABLE.has(lowercase)) {\n    return word;\n  }\n\n  // adv uncountables\n  const wordSplit = LAST_WORD_DASHED_REGEX.exec(word) || LAST_WORD_CAMELIZED_REGEX.exec(word);\n  const lastWord = wordSplit ? wordSplit[2].toLowerCase() : null;\n  if (lastWord && UNCOUNTABLE.has(lastWord)) {\n    return word;\n  }\n\n  // handle irregulars\n  const isCamelized = CAMELIZED_REGEX.test(word);\n  for (let [rule, substitution] of irregulars) {\n    if (lowercase.match(rule + '$')) {\n      if (isCamelized && lastWord && irregulars.has(lastWord)) {\n        substitution = capitalize(substitution);\n        rule = capitalize(rule);\n      }\n\n      return word.replace(new RegExp(rule, 'i'), substitution);\n    }\n  }\n\n  // do the actual inflection\n  for (const [rule, substitution] of typeRules) {\n    if (rule.test(word)) {\n      return word.replace(rule, substitution);\n    }\n  }\n\n  return word;\n}\n"],"mappings":"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"}

package/dist/string.d.ts

@@ -3,6 +3,7 @@
  * Marks a word as uncountable. Uncountable words are not pluralized
  * or singularized.
  *
+ * @summary Registers a word that `pluralize` and `singularize` should always return unchanged.
  * @public
  * @since 4.13.0
  */
@@ -11,6 +12,7 @@ export declare function uncountable(word: string): void;
  * Marks a list of words as uncountable. Uncountable words are not pluralized
  * or singularized.
  *
+ * @summary Registers a list of words that `pluralize` and `singularize` should always return unchanged.
  * @public
  * @since 4.13.0
  */
@@ -19,6 +21,8 @@ export declare function loadUncountable(uncountables: string[]): void;
  * Marks a word as irregular. Irregular words have unique
  * pluralization and singularization rules.
  *
+ * @summary Registers a singular and plural word pair that `pluralize` and `singularize` map directly instead of
+ * applying rules.
  * @public
  * @since 4.13.0
  */
@@ -27,6 +31,7 @@ export declare function irregular(single: string, plur: string): void;
  * Marks a list of word pairs as irregular. Irregular words have unique
  * pluralization and singularization rules.
  *
+ * @summary Registers a list of singular and plural word pairs that `pluralize` and `singularize` map directly.
  * @public
  * @since 4.13.0
  */
@@ -34,6 +39,7 @@ export declare function loadIrregular(irregularPairs: Array<[string, string]>):
 /**
  * Clears the caches for singularize and pluralize.
  *
+ * @summary Empties the cached results of `singularize` and `pluralize` while keeping all inflection rules.
  * @public
  * @since 4.13.0
  */
@@ -41,6 +47,7 @@ export declare function clear(): void;
 /**
  * Resets the inflection rules to the defaults.
  *
+ * @summary Discards all custom inflection rules and caches, then restores the built-in default rules.
  * @public
  * @since 4.13.0
  */
@@ -49,6 +56,7 @@ export declare function resetToDefaults(): void;
  * Clears all inflection rules
  * and resets the caches for singularize and pluralize.
  *
+ * @summary Removes every inflection rule, including the defaults, and empties the `singularize` and `pluralize` caches.
  * @public
  * @since 4.13.0
  */
@@ -56,6 +64,7 @@ export declare function clearRules(): void;
 /**
  * Singularizes a word.
  *
+ * @summary Returns the singular form of an English word using the registered inflection rules, with cached results.
  * @public
  * @since 4.13.0
  */
@@ -63,6 +72,7 @@ export declare function singularize(word: string): string;
 /**
  * Pluralizes a word.
  *
+ * @summary Returns the plural form of an English word using the registered inflection rules, with cached results.
  * @public
  * @since 4.13.0
  */
@@ -70,6 +80,7 @@ export declare function pluralize(word: string): string;
 /**
  * Adds a pluralization rule.
  *
+ * @summary Adds a regex and replacement rule that `pluralize` checks before all existing plural rules.
  * @public
  * @since 4.13.0
  */
@@ -77,6 +88,7 @@ export declare function plural(regex: RegExp, string: string): void;
 /**
  * Adds a singularization rule.
  *
+ * @summary Adds a regex and replacement rule that `singularize` checks before all existing singular rules.
  * @public
  * @since 4.13.0
  */
@@ -96,6 +108,7 @@ export declare function singular(regex: RegExp, string: string): void;
  * dasherize('privateDocs/ownerInvoice';  // 'private-docs/owner-invoice'
  * ```
  *
+ * @summary Converts camelCase, underscored, or spaced strings to dasherized form, such as `innerHTML` to `inner-html`.
  * @public
  * @since 4.13.0
  */
@@ -114,6 +127,8 @@ export declare const dasherize: (str: string) => string;
  * camelize('private-docs/owner-invoice');  // 'privateDocs/ownerInvoice'
  * ```
  *
+ * @summary Converts dashed, underscored, dotted, or spaced strings to lowerCamelCase, such as `action_name` to
+ * `actionName`.
  * @public
  * @since 4.13.0
  */
@@ -131,6 +146,7 @@ export declare function camelize(str: string): string;
  * underscore('privateDocs/ownerInvoice');  // 'private_docs/owner_invoice'
  * ```
  *
+ * @summary Converts camelCase, dashed, or spaced strings to lowercase snake_case, such as `innerHTML` to `inner_html`.
  * @public
  * @since 4.13.0
  */
@@ -148,6 +164,7 @@ export declare function underscore(str: string): string;
  * capitalize('privateDocs/ownerInvoice'); // 'PrivateDocs/ownerInvoice'
  * ```
  *
+ * @summary Uppercases the first letter of a string, and of each `/`-separated path segment, leaving the rest unchanged.
  * @public
  * @since 4.13.0
  */
@@ -156,6 +173,8 @@ export declare function capitalize(str: string): string;
  * Sets the maximum size of the LRUCache for all string transformation functions.
  * The default size is 10,000.
  *
+ * @summary Sets how many results the `camelize`, `underscore`, `capitalize`, and `dasherize` caches each keep (default
+ * 10,000).
  * @public
  * @since 4.13.0
  */

package/dist/string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","names":[],"sources":["../src/-private/string/inflect.ts","../src/-private/string/transform.ts"],"mappings":";;;;;;;;wBA8BgB,YAAY;;;;;;;;wBAWZ,gBAAgB;;;;;;;;wBAahB,UAAU,gBAAgB;;;;;;;;wBAiB1B,cAAc,gBAAgB;;;;;;;wBAmB9B;;;;;;;wBAWA;;;;;;;;wBAeA;;;;;;;wBAgBA,YAAY;;;;;;;wBAYZ,UAAU;;;;;;;wBAqBV,OAAO,OAAO,QAAQ;;;;;;;wBAgBtB,SAAS,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;qBC9I3B,YAAY;;;;;;;;;;;;;;;;;;wBAmBT,SAAS;;;;;;;;;;;;;;;;;wBAoBT,WAAW;;;;;;;;;;;;;;;;;wBAoBX,WAAW;;;;;;;;wBAWX,mBAAmB"}
+{"version":3,"file":"string.d.ts","names":[],"sources":["../src/-private/string/inflect.ts","../src/-private/string/transform.ts"],"mappings":";;;;;;;;;wBA+BgB,YAAY;;;;;;;;;wBAYZ,gBAAgB;;;;;;;;;;wBAehB,UAAU,gBAAgB;;;;;;;;;wBAkB1B,cAAc,gBAAgB;;;;;;;;wBAoB9B;;;;;;;;wBAYA;;;;;;;;;wBAgBA;;;;;;;;wBAiBA,YAAY;;;;;;;;wBAaZ,UAAU;;;;;;;;wBAsBV,OAAO,OAAO,QAAQ;;;;;;;;wBAiBtB,SAAS,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;qBCzJ3B,YAAY;;;;;;;;;;;;;;;;;;;;wBAqBT,SAAS;;;;;;;;;;;;;;;;;;wBAqBT,WAAW;;;;;;;;;;;;;;;;;;wBAqBX,WAAW;;;;;;;;;;wBAaX,mBAAmB"}

package/dist/string.js

@@ -1,3 +1,3 @@
-import { a as loadUncountable, c as resetToDefaults, d as uncountable, f as camelize, g as underscore, h as setMaxLRUCacheSize, i as loadIrregular, l as singular, m as dasherize, n as clearRules, o as plural, p as capitalize, r as irregular, s as pluralize, t as clear, u as singularize } from "./string-CWmAluxh.js";
+import { a as loadUncountable, c as resetToDefaults, d as uncountable, f as camelize, g as underscore, h as setMaxLRUCacheSize, i as loadIrregular, l as singular, m as dasherize, n as clearRules, o as plural, p as capitalize, r as irregular, s as pluralize, t as clear, u as singularize } from "./string-BZACNuLp.js";
 
 export { camelize, capitalize, clear, clearRules, dasherize, irregular, loadIrregular, loadUncountable, plural, pluralize, resetToDefaults, setMaxLRUCacheSize, singular, singularize, uncountable, underscore };

package/dist/unpkg/dev/active-record.js

@@ -1,5 +1,5 @@
 import { buildBaseURL, buildQueryParams } from "./index.js";
-import { g as underscore, s as pluralize } from "./string-j4ur-TDs.js";
+import { g as underscore, s as pluralize } from "./string-I8KHJXV7.js";
 import { n as extractCacheOptions, t as copyForwardUrlOptions } from "./builder-utils-BkXwUT0x.js";
 import { recordIdentifierFor } from "@warp-drive/core";
 
@@ -62,6 +62,9 @@ function isExisting(identifier) {
 * Builds request options to delete record for resources,
 * configured for the url, method and header expectations of ActiveRecord APIs.
 *
+* See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+* when to use one.
+*
 * **Basic Usage**
 *
 * ```ts
@@ -103,6 +106,7 @@ function isExisting(identifier) {
 * const data = await store.request(options);
 * ```
 *
+* @summary Builds a `DELETE` request that persists deletion of an existing record, using ActiveRecord-style URLs.
 * @public
 * @param record
 * @param options
@@ -137,6 +141,9 @@ function deleteRecord(record, options = {}) {
 * Builds request options to create new record for resources,
 * configured for the url, method and header expectations of most ActiveRecord APIs.
 *
+* See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+* when to use one.
+*
 * **Basic Usage**
 *
 * ```ts
@@ -168,6 +175,7 @@ function deleteRecord(record, options = {}) {
 * const data = await store.request(options);
 * ```
 *
+* @summary Builds a `POST` request that saves a newly created record, using ActiveRecord-style URLs.
 * @public
 * @param record
 * @param options
@@ -199,6 +207,9 @@ function createRecord(record, options = {}) {
 * Builds request options to update existing record for resources,
 * configured for the url, method and header expectations of most ActiveRecord APIs.
 *
+* See the [Builders](/guides/the-manual/requests/builders) guide for what request builders do and
+* when to use one.
+*
 * **Basic Usage**
 *
 * ```ts
@@ -233,6 +244,7 @@ function createRecord(record, options = {}) {
 * const data = await store.request(options);
 * ```
 *
+* @summary Builds a `PUT` (or `PATCH`) request that saves changes to an existing record, using ActiveRecord-style URLs.
 * @public
 * @param record
 * @param options

package/dist/unpkg/dev/active-record.js.map

@@ -1 +1 @@
-{"version":3,"file":"active-record.js","names":["recordIdentifierFor","buildBaseURL","pluralize","underscore","copyForwardUrlOptions","isExisting","identifier","id","type","deleteRecord","record","options","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/core/reactive';\nimport type { TypeFromInstance } from '@warp-drive/core/types/record';\nimport type {\n  FindRecordOptions,\n  FindRecordRequestOptions,\n  RemotelyAccessibleIdentifier,\n} from '@warp-drive/core/types/request';\nimport type { Meta } from '@warp-drive/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/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/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/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/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/core/reactive';\nimport type { QueryParamsSource } from '@warp-drive/core/types/params';\nimport type { TypeFromInstance } from '@warp-drive/core/types/record';\nimport type { ConstrainedRequestOptions, QueryRequestOptions } from '@warp-drive/core/types/request';\nimport type { Meta } from '@warp-drive/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/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/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/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/core';\nimport { assert } from '@warp-drive/core/build-config/macros';\nimport type { ReactiveDataDocument } from '@warp-drive/core/reactive';\nimport type { PersistedResourceKey, ResourceKey } from '@warp-drive/core/types/identifier';\nimport type { TypedRecordInstance } from '@warp-drive/core/types/record';\nimport type {\n  ConstrainedRequestOptions,\n  CreateRequestOptions,\n  DeleteRequestOptions,\n  UpdateRequestOptions,\n} from '@warp-drive/core/types/request';\nimport type { Meta } from '@warp-drive/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/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/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/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/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/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/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","isExisting","identifier","id","type","deleteRecord","record","options","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/core/reactive';\nimport type { TypeFromInstance } from '@warp-drive/core/types/record';\nimport type {\n  FindRecordOptions,\n  FindRecordRequestOptions,\n  RemotelyAccessibleIdentifier,\n} from '@warp-drive/core/types/request';\nimport type { Meta } from '@warp-drive/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/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/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/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/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/core/reactive';\nimport type { QueryParamsSource } from '@warp-drive/core/types/params';\nimport type { TypeFromInstance } from '@warp-drive/core/types/record';\nimport type { ConstrainedRequestOptions, QueryRequestOptions } from '@warp-drive/core/types/request';\nimport type { Meta } from '@warp-drive/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/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/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/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/core';\nimport { assert } from '@warp-drive/core/build-config/macros';\nimport type { ReactiveDataDocument } from '@warp-drive/core/reactive';\nimport type { PersistedResourceKey, ResourceKey } from '@warp-drive/core/types/identifier';\nimport type { TypedRecordInstance } from '@warp-drive/core/types/record';\nimport type {\n  ConstrainedRequestOptions,\n  CreateRequestOptions,\n  DeleteRequestOptions,\n  UpdateRequestOptions,\n} from '@warp-drive/core/types/request';\nimport type { Meta } from '@warp-drive/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/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/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/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/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/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/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":"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"}

package/dist/unpkg/dev/derivations.js

@@ -2,11 +2,17 @@ import { Type } from "@warp-drive/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/unpkg/dev/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/core/reactive';\nimport { Type } from '@warp-drive/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/core/reactive';\nimport { Type } from '@warp-drive/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/unpkg/dev/handlers.js

@@ -6,6 +6,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 = (() => {
@@ -56,6 +58,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
@@ -125,6 +129,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
 */
@@ -190,6 +196,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) {
@@ -222,12 +229,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);
@@ -240,6 +250,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) {
@@ -251,6 +263,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;
@@ -259,6 +272,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) {