@fgv/ts-utils 5.1.0-4 → 5.1.0-40

package/lib/packlets/collections/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/collector.ts"],"names":[],"mappings":"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"}

package/lib/packlets/collections/collector.js

@@ -34,7 +34,7 @@ const base_1 = require("../base");
  */
 class Collector {
     /**
-     * {@inheritDoc Collections.ResultMap.size}
+     * Returns the number of entries in the map.
      */
     get size() {
         return this._byIndex.length;
@@ -90,13 +90,16 @@ class Collector {
         return (0, base_1.succeedWithDetail)(item, 'added');
     }
     /**
-     * {@inheritDoc Collections.ResultMap.entries}
+     * Returns an iterator over the map entries.
+     * @returns An iterator over the map entries.
      */
     entries() {
         return this._byKey.entries();
     }
     /**
-     * {@inheritDoc Collections.ResultMap.forEach}
+     * Calls a function for each entry in the map.
+     * @param callback - The function to call for each entry.
+     * @param arg - An optional argument to pass to the callback.
      */
     forEach(callback, arg) {
         for (const [key, value] of this._byKey.entries()) {
@@ -104,14 +107,20 @@ class Collector {
         }
     }
     /**
-     * {@inheritDoc Collections.ResultMap.get}
+     * Gets a value by key.
+     * @param key - The key to look up.
+     * @returns Returns {@link DetailedSuccess | Success} with the value and detail `exists` if found,
+     * or {@link DetailedFailure | Failure} with detail `not-found` if the key does not exist.
      */
     get(key) {
         const item = this._byKey.get(key);
         return item ? (0, base_1.succeedWithDetail)(item, 'exists') : (0, base_1.failWithDetail)(`${key}: not found`, 'not-found');
     }
     /**
-     * {@inheritDoc Collections.IReadOnlyCollector.getAt}
+     * Gets the item at a specified index.
+     * @param index - The index of the item to retrieve.
+     * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure}
+     * with an error if the index is out of range.
      */
     getAt(index) {
         if (typeof index !== 'number') {
@@ -149,25 +158,30 @@ class Collector {
         });
     }
     /**
-     * {@inheritDoc Collections.ResultMap.has}
+     * Returns true if the map contains an entry with the given key.
+     * @param key - The key to check for.
+     * @returns `true` if the key exists, `false` otherwise.
      */
     has(key) {
         return this._byKey.has(key);
     }
     /**
-     * {@inheritDoc Collections.ResultMap.keys}
+     * Returns an iterator over the map keys.
+     * @returns An iterator over the map keys.
      */
     keys() {
         return this._byKey.keys();
     }
     /**
-     * {@inheritDoc Collections.ResultMap.values}
+     * Returns an iterator over the map values.
+     * @returns An iterator over the map values.
      */
     values() {
         return this._byKey.values();
     }
     /**
-     * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
+     * Gets all items in the collection, ordered by index.
+     * @returns An array of items in the collection, ordered by index.
      */
     valuesByIndex() {
         return this._byIndex;

package/lib/packlets/collections/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../../../src/packlets/collections/collector.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport {\n  captureResult,\n  DetailedResult,\n  failWithDetail,\n  Result,\n  fail,\n  succeed,\n  succeedWithDetail\n} from '../base';\nimport { CollectibleFactoryCallback, CollectibleKey, ICollectible } from './collectible';\nimport { KeyValueEntry } from './common';\nimport { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';\n\n/**\n * Additional success or failure details for mutating collector calls.\n * @public\n */\nexport type CollectorResultDetail = ResultMapResultDetail | 'invalid-index';\n\n/**\n * A read-only interface exposing only the non-mutating methods of a {@link Collections.Collector | ICollector}.\n * @public\n */\nexport interface IReadOnlyCollector<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> extends IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM> {\n  /**\n   * Gets the item at a specified index.\n   * @param index - The index of the item to retrieve.\n   * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure}\n   * with an error if the index is out of range.\n   */\n  getAt(index: number): Result<TITEM>;\n\n  /**\n   * Gets all items in the collection, ordered by index.\n   * @returns An array of items in the collection, ordered by index.\n   */\n  valuesByIndex(): ReadonlyArray<TITEM>;\n}\n\n/**\n * Parameters for constructing a {@link Collections.Collector | ICollector}.\n * @public\n */\nexport interface ICollectorConstructorParams<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> {\n  /** Optional initial items to populate the collector. */\n  items?: TITEM[];\n}\n\n/**\n * A {@link Collections.Collector | Collector} that is a specialized collection\n * which contains items of type {@link Collections.ICollectible | ICollectible},\n * which have a unique key and a write-once index.\n *\n * Items are assigned an index sequentially as they are added to the collection.\n * Once added, items are immutable - they cannot be removed or replaced.\n * @public\n */\nexport class Collector<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> implements IReadOnlyCollector<TITEM>\n{\n  private readonly _byKey: Map<CollectibleKey<TITEM>, TITEM>;\n  private readonly _byIndex: TITEM[];\n\n  /**\n   * Returns the number of entries in the map.\n   */\n  public get size(): number {\n    return this._byIndex.length;\n  }\n\n  /**\n   * Constructs a new {@link Collections.Collector | Collector}.\n   * @param params - Optional {@link Collections.ICollectorConstructorParams | initialization parameters} used\n   * to construct the collector.\n   */\n  public constructor(params?: ICollectorConstructorParams<TITEM>) {\n    this._byKey = new Map<CollectibleKey<TITEM>, TITEM>();\n    this._byIndex = [];\n    for (const item of params?.items ?? []) {\n      this.add(item).orThrow();\n    }\n  }\n\n  /**\n   * Creates a new {@link Collections.Collector | Collector} instance.\n   * @param params - Optional {@link Collections.ICollectorConstructorParams | initialization parameters} used\n   * to create the collector.\n   * @returns Returns {@link Success | Success} with the new collector if it was created successfully,\n   * or {@link Failure | Failure} with an error if the collector could not be created.\n   */\n  public static createCollector<\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    TITEM extends ICollectible<any, any>\n  >(params?: ICollectorConstructorParams<TITEM>): Result<Collector<TITEM>> {\n    return captureResult(() => new Collector(params));\n  }\n\n  /**\n   * Adds an item to the collection, failing if a different item with the same key already exists. Note\n   * that adding an object that is already in the collection again will succeed without updating the collection.\n   * @param item - The item to add.\n   * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added\n   * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with\n   * an error message and appropriate detail if the item could not be added.\n   */\n  public add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail> {\n    const existing = this._byKey.get(item.key);\n    if (existing === item) {\n      return succeedWithDetail(item, 'exists');\n    } else if (existing) {\n      return failWithDetail(`${item.key}: already exists`, 'exists');\n    }\n    const indexResult = item.setIndex(this._byIndex.length);\n    if (indexResult.isFailure()) {\n      return failWithDetail(`${item.key}: ${indexResult.message}`, 'invalid-index');\n    } else if (item.index !== this._byIndex.length) {\n      return failWithDetail(`${item.key}: index mismatch - built item has ${item.index}`, 'invalid-index');\n    }\n    this._byKey.set(item.key, item);\n    this._byIndex.push(item);\n    return succeedWithDetail(item, 'added');\n  }\n\n  /**\n   * Returns an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  public entries(): IterableIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>> {\n    return this._byKey.entries();\n  }\n\n  /**\n   * Calls a function for each entry in the map.\n   * @param callback - The function to call for each entry.\n   * @param arg - An optional argument to pass to the callback.\n   */\n  public forEach(callback: ResultMapForEachCb<CollectibleKey<TITEM>, TITEM>, arg?: unknown): void {\n    for (const [key, value] of this._byKey.entries()) {\n      callback(value, key, this, arg);\n    }\n  }\n\n  /**\n   * Gets a value by key.\n   * @param key - The key to look up.\n   * @returns Returns {@link DetailedSuccess | Success} with the value and detail `exists` if found,\n   * or {@link DetailedFailure | Failure} with detail `not-found` if the key does not exist.\n   */\n  public get(key: CollectibleKey<TITEM>): DetailedResult<TITEM, ResultMapResultDetail> {\n    const item = this._byKey.get(key);\n    return item ? succeedWithDetail(item, 'exists') : failWithDetail(`${key}: not found`, 'not-found');\n  }\n\n  /**\n   * Gets the item at a specified index.\n   * @param index - The index of the item to retrieve.\n   * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure}\n   * with an error if the index is out of range.\n   */\n  public getAt(index: number): Result<TITEM> {\n    if (typeof index !== 'number') {\n      // Handle Symbol conversion safely\n      const indexStr = typeof index === 'symbol' ? (index as symbol).toString() : String(index);\n      return fail(`${indexStr}: collector index must be a number.`);\n    }\n\n    // Check that the number is a finite integer (handles NaN, Infinity, and non-integers)\n    if (!Number.isFinite(index) || !Number.isInteger(index)) {\n      return fail(`${index}: collector index must be a finite integer.`);\n    }\n\n    if (index < 0 || index >= this._byIndex.length) {\n      return fail(`${index}: collector index out of range.`);\n    }\n\n    return succeed(this._byIndex[index]);\n  }\n\n  /**\n   * Gets an existing item with a key matching that of a supplied item, or adds the supplied\n   * item to the collector if no item with that key exists.\n   * @param item - The item to get or add.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item return and detail `added` indicates that the\n   * item was added. Returns {@link DetailedFailure | Failure} with an error and appropriate\n   * detail if the item could not be added.\n   */\n  public getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Gets an existing item with a key matching the supplied key, or adds a new item to the collector\n   * using a factory callback if no item with that key exists.\n   * @param key - The key of the item to add.\n   * @param factory - The factory callback to create the item.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item return and detail `added` indicates that the\n   * item was added. Returns {@link DetailedFailure | Failure} with an error and appropriate\n   * detail if the item could not be added.\n   */\n  public getOrAdd(\n    key: CollectibleKey<TITEM>,\n    factory: CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n\n  public getOrAdd(\n    keyOrItem: CollectibleKey<TITEM> | TITEM,\n    factory?: CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    const key = !this._isItem(keyOrItem) ? keyOrItem : keyOrItem.key;\n    const existing = this._byKey.get(key);\n    if (existing) {\n      return succeedWithDetail(existing, 'exists');\n    }\n\n    const itemResult = !this._isItem(keyOrItem)\n      ? factory!(keyOrItem, this._byIndex.length)\n      : succeed(keyOrItem);\n    if (itemResult.isFailure()) {\n      return failWithDetail(`${key}: ${itemResult.message}`, 'invalid-value');\n    }\n    const item = itemResult.value;\n\n    if (item.key !== key) {\n      return failWithDetail(`${key}: key mismatch - built item has ${key}`, 'invalid-key');\n    }\n\n    return itemResult.withFailureDetail<CollectorResultDetail>('invalid-index').onSuccess((item) => {\n      return this.add(item);\n    });\n  }\n\n  /**\n   * Returns true if the map contains an entry with the given key.\n   * @param key - The key to check for.\n   * @returns `true` if the key exists, `false` otherwise.\n   */\n  public has(key: CollectibleKey<TITEM>): boolean {\n    return this._byKey.has(key);\n  }\n\n  /**\n   * Returns an iterator over the map keys.\n   * @returns An iterator over the map keys.\n   */\n  public keys(): IterableIterator<CollectibleKey<TITEM>> {\n    return this._byKey.keys();\n  }\n\n  /**\n   * Returns an iterator over the map values.\n   * @returns An iterator over the map values.\n   */\n  public values(): IterableIterator<TITEM> {\n    return this._byKey.values();\n  }\n\n  /**\n   * Gets all items in the collection, ordered by index.\n   * @returns An array of items in the collection, ordered by index.\n   */\n  public valuesByIndex(): ReadonlyArray<TITEM> {\n    return this._byIndex;\n  }\n\n  /**\n   * Gets a read-only version of this collector.\n   */\n  public toReadOnly(): IReadOnlyCollector<TITEM> {\n    return this;\n  }\n\n  /**\n   * Gets an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  public [Symbol.iterator](): IterableIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>> {\n    return this._byKey[Symbol.iterator]();\n  }\n\n  protected _isItem(keyOrItem: CollectibleKey<TITEM> | TITEM): keyOrItem is TITEM {\n    return typeof keyOrItem !== 'string';\n  }\n}\n"]}

package/lib/packlets/collections/collectorValidator.d.ts

@@ -24,7 +24,14 @@ export interface IReadOnlyCollectorValidator<TITEM extends ICollectible<any, any
      */
     has(key: string): boolean;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The weakly-typed key of the item to get or add.
+     * @param factory - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
 }
@@ -53,7 +60,12 @@ export declare class CollectorValidator<TITEM extends ICollectible<any, any>> im
      */
     constructor(params: ICollectorValidatorCreateParams<TITEM>);
     /**
-     * {@inheritDoc Collections.Collector.add}
+     * Adds an item to the collection, failing if a different item with the same key already exists. Note
+     * that adding an object that is already in the collection again will succeed without updating the collection.
+     * @param item - The item to add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+     * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+     * an error message and appropriate detail if the item could not be added.
      */
     add(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
     /**
@@ -61,12 +73,24 @@ export declare class CollectorValidator<TITEM extends ICollectible<any, any>> im
      */
     get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The weakly-typed key of the item to get or add.
+     * @param factory - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
-     * @param item - The item to add to the collector.
+     * Gets an existing item with a key matching that of the supplied item, or adds the supplied
+     * item to the collector if no item with that key exists.
+     * @param item - The weakly-typed item to get or add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
     /**

package/lib/packlets/collections/collectorValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectorValidator.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/collectorValidator.ts"],"names":[],"mappings":"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"}

package/lib/packlets/collections/collectorValidator.js

@@ -40,7 +40,12 @@ class CollectorValidator {
         this.converters = params.converters;
     }
     /**
-     * {@inheritDoc Collections.Collector.add}
+     * Adds an item to the collection, failing if a different item with the same key already exists. Note
+     * that adding an object that is already in the collection again will succeed without updating the collection.
+     * @param item - The item to add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+     * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+     * an error message and appropriate detail if the item could not be added.
      */
     add(item) {
         return this._convertValue(item).onSuccess((i) => {

package/lib/packlets/collections/collectorValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectorValidator.js","sourceRoot":"","sources":["../../../src/packlets/collections/collectorValidator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAgEH;;;;GAIG;AACH,MAAa,kBAAkB;IAO7B,IAAW,GAAG;QACZ,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAID;;;OAGG;IACH,YAAmB,MAA8C;QAC/D,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACtC,CAAC;IAED;;;;;;;OAOG;IACI,GAAG,CAAC,IAAa;QACtB,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;YAC9C,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;YACrD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC;IA4BM,QAAQ,CACb,SAA2B,EAC3B,SAA+D;QAE/D,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3F,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,CAAC,UAAU;iBACnB,UAAU,CAAC,SAAS,CAAC;iBACrB,UAAU,CAAwB,aAAa,EAAE,SAAS,CAAC;iBAC3D,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAA4B,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACO,aAAa,CAAC,KAAc;QACpC,OAAO,IAAI,CAAC,UAAU;aACnB,YAAY,CAAC,KAAK,CAAC;aACnB,eAAe,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,iBAAiB,OAAO,EAAE,CAAC;aACxD,UAAU,CAAwB,eAAe,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;CACF;AAlHD,gDAkHC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { DetailedResult } from '../base';\nimport { IReadOnlyResultMap, ResultMapResultDetail } from './readonlyResultMap';\nimport { ResultMapValueFactory } from './resultMap';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { Collector, CollectorResultDetail } from './collector';\nimport { IReadOnlyResultMapValidator } from './resultMapValidator';\nimport { CollectibleKey, ICollectible } from './collectible';\n\n/**\n * A read-only interface exposing non-mutating methods of a\n * {@link Collections.CollectorValidator | CollectorValidator}.\n * @public\n */\nexport interface IReadOnlyCollectorValidator<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> extends IReadOnlyResultMapValidator<CollectibleKey<TITEM>, TITEM> {\n  /**\n   * {@inheritDoc Collections.ReadOnlyResultMapValidator.map}\n   */\n  readonly map: IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM>;\n\n  /**\n   * {@inheritDoc Collections.Collector.get}\n   */\n  get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;\n\n  /**\n   * {@inheritDoc Collections.ResultMap.has}\n   */\n  has(key: string): boolean;\n\n  /**\n   * Gets an existing item with a key matching the supplied key, or adds a new item to the collector\n   * using a factory callback if no item with that key exists.\n   * @param key - The weakly-typed key of the item to get or add.\n   * @param factory - The factory callback to create the item.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item was returned and detail `added` indicates\n   * that the item was added. Returns {@link DetailedFailure | Failure} with an error and\n   * appropriate detail if the item could not be added.\n   */\n  getOrAdd(\n    key: string,\n    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n}\n\n/**\n * Parameters for constructing a {@link Collections.CollectorValidator | CollectorValidator}.\n * @public\n */\nexport interface ICollectorValidatorCreateParams<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> {\n  /** The collector to validate access to. */\n  readonly collector: Collector<TITEM>;\n  /** The key-value converters for validation. */\n  readonly converters: KeyValueConverters<CollectibleKey<TITEM>, TITEM>;\n}\n\n/**\n * A {@link Collections.Collector | Collector} wrapper which validates weakly-typed keys\n * and values before calling the wrapped collector.\n * @public\n */\nexport class CollectorValidator<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> implements IReadOnlyCollectorValidator<TITEM>\n{\n  public readonly converters: KeyValueConverters<CollectibleKey<TITEM>, TITEM>;\n\n  public get map(): IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM> {\n    return this._collector.toReadOnly();\n  }\n\n  protected _collector: Collector<TITEM>;\n\n  /**\n   * Constructs a new {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.\n   * @param params - Required parameters for constructing the collector validator.\n   */\n  public constructor(params: ICollectorValidatorCreateParams<TITEM>) {\n    this._collector = params.collector;\n    this.converters = params.converters;\n  }\n\n  /**\n   * Adds an item to the collection, failing if a different item with the same key already exists. Note\n   * that adding an object that is already in the collection again will succeed without updating the collection.\n   * @param item - The item to add.\n   * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added\n   * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with\n   * an error message and appropriate detail if the item could not be added.\n   */\n  public add(item: unknown): DetailedResult<TITEM, CollectorResultDetail> {\n    return this._convertValue(item).onSuccess((i) => {\n      return this._collector.add(i);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.Collector.get}\n   */\n  public get(key: string): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((k) => {\n      return this._collector.get(k);\n    });\n  }\n\n  /**\n   * Gets an existing item with a key matching the supplied key, or adds a new item to the collector\n   * using a factory callback if no item with that key exists.\n   * @param key - The weakly-typed key of the item to get or add.\n   * @param factory - The factory callback to create the item.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item was returned and detail `added` indicates\n   * that the item was added. Returns {@link DetailedFailure | Failure} with an error and\n   * appropriate detail if the item could not be added.\n   */\n  public getOrAdd(\n    key: string,\n    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Gets an existing item with a key matching that of the supplied item, or adds the supplied\n   * item to the collector if no item with that key exists.\n   * @param item - The weakly-typed item to get or add.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item was returned and detail `added` indicates\n   * that the item was added. Returns {@link DetailedFailure | Failure} with an error and\n   * appropriate detail if the item could not be added.\n   */\n  public getOrAdd(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;\n\n  public getOrAdd(\n    keyOrItem: string | unknown,\n    factoryCb?: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (factoryCb === undefined) {\n      return this._convertValue(keyOrItem).onSuccess((item) => this._collector.getOrAdd(item));\n    } else {\n      return this.converters\n        .convertKey(keyOrItem)\n        .withDetail<CollectorResultDetail>('invalid-key', 'success')\n        .onSuccess((key) => this._collector.getOrAdd(key, factoryCb));\n    }\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.has}\n   */\n  public has(key: string): boolean {\n    return this._collector.has(key as CollectibleKey<TITEM>);\n  }\n\n  /**\n   * {@inheritDoc Collections.Collector.toReadOnly}\n   */\n  public toReadOnly(): IReadOnlyCollectorValidator<TITEM> {\n    return this;\n  }\n\n  /**\n   * Helper to convert a value, returning a {@link DetailedResult | DetailedResult}\n   * and formatting the error message.\n   * @param value - The value to convert.\n   * @returns {@link DetailedSuccess | DetailedSuccess} with the converted value\n   * and detail `success` if conversion is successful, or\n   * {@link DetailedFailure | DetailedFailure} with the error message and detail `invalid-value`\n   * if conversion fails.\n   */\n  protected _convertValue(value: unknown): DetailedResult<TITEM, CollectorResultDetail> {\n    return this.converters\n      .convertValue(value)\n      .withErrorFormat((message) => `invalid item: ${message}`)\n      .withDetail<CollectorResultDetail>('invalid-value', 'success');\n  }\n}\n"]}

package/lib/packlets/collections/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/common.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC"}

package/lib/packlets/collections/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../src/packlets/collections/common.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Generic key-value entry.\n * @public\n */\nexport type KeyValueEntry<TK extends string = string, TV = unknown> = [TK, TV];\n"]}

package/lib/packlets/collections/converters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/converters.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,SAAS,EAAc,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,6BAA6B,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE;IAClE,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAC5B,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,EACjD,MAAM,EAAE,6BAA6B,CAAC,EAAE,EAAE,EAAE,CAAC,GAC5C,SAAS,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAQ3C"}

package/lib/packlets/collections/converters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../src/packlets/collections/converters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAqBH,sCAUC;AA7BD,kCAA0C;AAC1C,8CAAsD;AAYtD;;;;;GAKG;AACH,SAAgB,aAAa,CAC3B,MAA6C;IAE7C,OAAO,uBAAU,CAAC,OAAO,CAAC,CAAC,IAAa,EAAiC,EAAE;QACzE,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,GAAO,EAAE,EAAE;YACpD,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,KAAS,EAAE,EAAE;gBACxD,OAAO,cAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;YACpC,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, Success } from '../base';\nimport { Converter, Converters } from '../conversion';\nimport { KeyValueEntry } from './common';\n\n/**\n * Initialization parameters for the {@link Collections.Converters.keyValueEntry | keyValueEntry} converter.\n * @public\n */\nexport interface IKeyValueEntryConverterParams<TK extends string, TV> {\n  key: Converter<TK, unknown>;\n  value: Converter<TV, unknown>;\n}\n\n/**\n * A {@link Converter | Converter} for {@link Collections.KeyValueEntry | KeyValueEntry} instances.\n * @param params - Conversion parameters.\n * @returns A converter for which validates key value entries using the supplied validators.\n * @public\n */\nexport function keyValueEntry<TK extends string, TV>(\n  params: IKeyValueEntryConverterParams<TK, TV>\n): Converter<KeyValueEntry<TK, TV>, unknown> {\n  return Converters.generic((from: unknown): Result<KeyValueEntry<TK, TV>> => {\n    return params.key.convert(from).onSuccess((key: TK) => {\n      return params.value.convert(from).onSuccess((value: TV) => {\n        return Success.with([key, value]);\n      });\n    });\n  });\n}\n"]}

package/lib/packlets/collections/convertingCollector.d.ts

@@ -37,7 +37,12 @@ export declare class ConvertingCollector<TITEM extends ICollectible<any, any>, T
      */
     static createConvertingCollector<TITEM extends ICollectible<any, any>, TSRC = TITEM>(params: IConvertingCollectorConstructorParams<TITEM, TSRC>): Result<ConvertingCollector<TITEM, TSRC>>;
     /**
-     * {@inheritDoc Collections.Collector.add}
+     * Adds an item to the collection, failing if a different item with the same key already exists. Note
+     * that adding an object that is already in the collection again will succeed without updating the collection.
+     * @param item - The item to add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+     * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+     * an error message and appropriate detail if the item could not be added.
      */
     add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
     /**
@@ -60,11 +65,24 @@ export declare class ConvertingCollector<TITEM extends ICollectible<any, any>, T
      */
     add(key: CollectibleKey<TITEM>, cb: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching that of the supplied item, or adds the supplied
+     * item to the collector if no item with that key exists.
+     * @param item - The item to get or add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The key of the item to get or add.
+     * @param callback - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: CollectibleKey<TITEM>, callback: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**

package/lib/packlets/collections/convertingCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertingCollector.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/convertingCollector.ts"],"names":[],"mappings":"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"}

package/lib/packlets/collections/convertingCollector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertingCollector.js","sourceRoot":"","sources":["../../../src/packlets/collections/convertingCollector.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { captureResult, DetailedResult, failWithDetail, Result, succeedWithDetail } from '../base';\nimport { ICollectible, CollectibleFactoryCallback, CollectibleFactory, CollectibleKey } from './collectible';\nimport { Collector, CollectorResultDetail } from './collector';\nimport { KeyValueEntry } from './common';\n\n/**\n * Parameters for constructing a {@link Collections.ConvertingCollector | ConvertingCollector}.\n * @public\n */\nexport interface IConvertingCollectorConstructorParams<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>,\n  TSRC = TITEM\n> {\n  /**\n   * The default {@link Collections.CollectibleFactory | factory} to create items.\n   */\n  factory: CollectibleFactory<TITEM, TSRC>;\n  /**\n   * An optional array of entries to add to the collector.\n   */\n  entries?: KeyValueEntry<CollectibleKey<TITEM>, TSRC>[];\n}\n\n/**\n * A {@link Collector | collector} that collects {@link Collections.ICollectible | ICollectible} items,\n * optionally converting them from a source representation to the target representation using a factory\n * supplied at default or at the time of collection.\n * @public\n */\nexport class ConvertingCollector<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>,\n  TSRC = TITEM\n> extends Collector<TITEM> {\n  private _factory: CollectibleFactory<TITEM, TSRC>;\n\n  /**\n   * Constructs a new {@link Collections.ConvertingCollector | ConvertingCollector}.\n   * @param params - Parameters for constructing the collector.\n   */\n  public constructor(params: IConvertingCollectorConstructorParams<TITEM, TSRC>) {\n    super();\n    this._factory = params.factory;\n    params.entries?.forEach((entry) => {\n      this.getOrAdd(entry[0], entry[1]).orThrow();\n    });\n  }\n\n  /**\n   * Creates a new {@link Collections.ConvertingCollector | ConvertingCollector}.\n   * @param params - Required parameters for constructing the collector.\n   * @returns Returns {@link Success | Success} with the new collector if it is created, or {@link Failure | Failure}\n   * with an error if the collector cannot be created.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  public static createConvertingCollector<TITEM extends ICollectible<any, any>, TSRC = TITEM>(\n    params: IConvertingCollectorConstructorParams<TITEM, TSRC>\n  ): Result<ConvertingCollector<TITEM, TSRC>> {\n    return captureResult(() => new ConvertingCollector(params));\n  }\n\n  /**\n   * Adds an item to the collection, failing if a different item with the same key already exists. Note\n   * that adding an object that is already in the collection again will succeed without updating the collection.\n   * @param item - The item to add.\n   * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added\n   * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with\n   * an error message and appropriate detail if the item could not be added.\n   */\n  public add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Adds an item to the collector using the default {@link Collections.CollectibleFactory | factory}\n   * at a specified key, failing if an item with that key already exists.\n   * @param key - The key of the item to add.\n   * @param item - The source representation of the item to be added.\n   * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with\n   * an error if the item cannot be created and indexed.\n   * @public\n   */\n  public add(key: CollectibleKey<TITEM>, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Adds an item to the collector using a supplied {@link Collections.CollectibleFactoryCallback | factory callback}\n   * at a specified key, failing if an item with that key already exists or if the created item is invalid.\n   * @param key - The key of the item to add.\n   * @param cb - The factory callback to create the item.\n   * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with\n   * an error if the item cannot be created and indexed.\n   */\n  public add(\n    key: CollectibleKey<TITEM>,\n    cb: CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n\n  public add(\n    keyOrItem: CollectibleKey<TITEM> | TITEM,\n    itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (this._overloadIsItem(keyOrItem, itemOrCb)) {\n      return super.add(keyOrItem);\n    }\n    return this._buildItem(keyOrItem, itemOrCb!)\n      .withFailureDetail<CollectorResultDetail>('invalid-value')\n      .onSuccess((item) => {\n        return super.add(item);\n      });\n  }\n\n  /**\n   * Gets an existing item with a key matching that of the supplied item, or adds the supplied\n   * item to the collector if no item with that key exists.\n   * @param item - The item to get or add.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item was returned and detail `added` indicates\n   * that the item was added. Returns {@link DetailedFailure | Failure} with an error and\n   * appropriate detail if the item could not be added.\n   */\n  public getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Gets an existing item with a key matching the supplied key, or adds a new item to the collector\n   * using a factory callback if no item with that key exists.\n   * @param key - The key of the item to get or add.\n   * @param callback - The factory callback to create the item.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item was returned and detail `added` indicates\n   * that the item was added. Returns {@link DetailedFailure | Failure} with an error and\n   * appropriate detail if the item could not be added.\n   */\n  public getOrAdd(\n    key: CollectibleKey<TITEM>,\n    callback: CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Gets an item by key if it exists, or creates a new item and adds it using the default {@link Collections.CollectibleFactory | factory} if not.\n   * @param key - The key of the item to retrieve.\n   * @param item - The source representation of the item to be added if it does not exist.\n   * @returns Returns {@link Success | Success} with the item if it exists or could be created, or {@link Failure | Failure} with an error if the\n   * item cannot be created and indexed.\n   */\n  public getOrAdd(key: CollectibleKey<TITEM>, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;\n\n  public getOrAdd(\n    keyOrItem: CollectibleKey<TITEM> | TITEM,\n    itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (this._overloadIsItem(keyOrItem, itemOrCb)) {\n      return super.getOrAdd(keyOrItem);\n    }\n\n    if (this.has(keyOrItem)) {\n      return this.get(keyOrItem);\n    }\n\n    return this._buildItem(keyOrItem, itemOrCb!)\n      .withFailureDetail<CollectorResultDetail>('invalid-value')\n      .onSuccess((item) => {\n        if (item.key !== keyOrItem) {\n          return failWithDetail<TITEM, CollectorResultDetail>(\n            `${keyOrItem}: key mismatch - item has unexpected key ${item.key}`,\n            'invalid-key'\n          );\n        }\n        return succeedWithDetail(item, 'success');\n      })\n      .onSuccess((item) => {\n        return super.add(item);\n      });\n  }\n\n  /**\n   * Helper method for derived classes to determine if a supplied\n   * itemOrCb parameter is a factory callback.\n   * @param itemOrCb - Overloaded parameter is either `CollectibleKey<TITEM>` or\n   * a {@link Collections.CollectibleFactoryCallback | factory callback}.\n   * @returns Returns `true` if the parameter is a factory callback, `false` otherwise.\n   * @public\n   */\n  protected _isFactoryCB(\n    itemOrCb: TSRC | CollectibleFactoryCallback<TITEM>\n  ): itemOrCb is CollectibleFactoryCallback<TITEM> {\n    return typeof itemOrCb === 'function';\n  }\n\n  /**\n   * Helper method for derived classes to determine if a supplied\n   * keyOrItem parameter is an item.\n   * @param keyOrItem - Overloaded parameter is either `CollectibleKey<TITEM>` or `TITEM`.\n   * @param itemOrCb - Overloaded parameter is either `TSRC`, a {@link Collections.CollectibleFactoryCallback | factory callback}\n   * or `undefined`.\n   * @returns Returns `true` if the parameter is an item, `false` otherwise.\n   * @public\n   */\n  protected _overloadIsItem(\n    keyOrItem: CollectibleKey<TITEM> | TITEM,\n    itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>\n  ): keyOrItem is TITEM {\n    return itemOrCb === undefined;\n  }\n\n  /**\n   * Helper method for derived classes to build an item from a key and a source representation using\n   * a default or supplied factory.\n   * @param key - The key of the item to build.\n   * @param itemOrCb - The source representation of the item to build, or a factory callback to create it.\n   * @returns Returns {@link Success | Success} with the item if it is built, or {@link Failure | Failure}\n   * with an error if the item cannot be built.\n   * @public\n   */\n  protected _buildItem(\n    key: CollectibleKey<TITEM>,\n    itemOrCb: TSRC | CollectibleFactoryCallback<TITEM>\n  ): Result<TITEM> {\n    return this._isFactoryCB(itemOrCb) ? itemOrCb(key, this.size) : this._factory(key, this.size, itemOrCb);\n  }\n}\n"]}

package/lib/packlets/collections/convertingCollectorValidator.d.ts

@@ -32,7 +32,12 @@ export declare class ConvertingCollectorValidator<TITEM extends ICollectible<any
      */
     constructor(params: IConvertingCollectorValidatorCreateParams<TITEM, TSRC>);
     /**
-     * {@inheritDoc Collections.ConvertingCollector.add}
+     * Adds an item to the collector using the default factory at a specified key,
+     * failing if an item with that key already exists.
+     * @param key - The weakly-typed key of the item to add.
+     * @param value - The source representation of the item to be added.
+     * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with
+     * an error if the item cannot be created and indexed.
      */
     add(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
     /**
@@ -45,11 +50,25 @@ export declare class ConvertingCollectorValidator<TITEM extends ICollectible<any
      */
     get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
     /**
-     * {@inheritDoc Collections.ConvertingCollector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * by converting the supplied weakly-typed value if no item with that key exists.
+     * @param key - The weakly-typed key of the item to get or add.
+     * @param value - The weakly-typed source value to convert and add if the key does not exist.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The weakly-typed key of the item to get or add.
+     * @param factory - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**

package/lib/packlets/collections/convertingCollectorValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertingCollectorValidator.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/convertingCollectorValidator.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,cAAc,EAAkB,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,yCAAyC,CAExD,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,IAAI,GAAG,KAAK;IAEZ,sDAAsD;IACtD,SAAS,EAAE,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC5C,+CAA+C;IAC/C,UAAU,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;CAC7D;AAED;;;;;GAKG;AACH,qBAAa,4BAA4B,CAEvC,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,IAAI,GAAG,KAAK,CACZ,YAAW,2BAA2B,CAAC,KAAK,CAAC;IAE7C,SAAgB,UAAU,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IAE5E,IAAW,GAAG,IAAI,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAEjE;IAED,SAAS,CAAC,UAAU,EAAE,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAEvD;;;OAGG;gBACgB,MAAM,EAAE,yCAAyC,CAAC,KAAK,EAAE,IAAI,CAAC;IAKjF;;;;;;;OAOG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAErF;;;OAGG;IACI,GAAG,CACR,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,qBAAqB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,GAC3D,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAW/C;;OAEG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAMrE;;;;;;;;;OASG;IACI,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAE1F;;;;;;;;;OASG;IACI,QAAQ,CACb,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,qBAAqB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,GAC3D,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAsB/C;;OAEG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACI,UAAU,IAAI,2BAA2B,CAAC,KAAK,CAAC;IAIvD;;;;;;OAMG;IACH,SAAS,CAAC,6BAA6B,CACrC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAAC,KAAK,CAAC,GACjD,KAAK,IAAI,0BAA0B,CAAC,KAAK,CAAC;CAG9C"}

package/lib/packlets/collections/convertingCollectorValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertingCollectorValidator.js","sourceRoot":"","sources":["../../../src/packlets/collections/convertingCollectorValidator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,kCAAyD;AAwBzD;;;;;GAKG;AACH,MAAa,4BAA4B;IAQvC,IAAW,GAAG;QACZ,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAID;;;OAGG;IACH,YAAmB,MAA8D;QAC/E,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACtC,CAAC;IAoBM,GAAG,CACR,GAAW,EACX,cAA6E;QAE7E,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,OAAO,IAAA,qBAAc,EAAC,GAAG,GAAG,kBAAkB,EAAE,QAAQ,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;YACrD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC;IA6BM,QAAQ,CACb,GAAW,EACX,cAA2D;QAE3D,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,cAAc,CAAC,EAAE,CAAC;YACxD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;YACtE,IAAI,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;gBAC1B,OAAO,IAAA,qBAAc,EAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;YAC7D,CAAC;YACD,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC;YACjC,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YAClD,IAAI,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;gBAC1B,OAAO,IAAA,qBAAc,EAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;YAC7D,CAAC;YACD,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAA4B,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACO,6BAA6B,CACrC,KAAkD;QAElD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;IACrC,CAAC;CACF;AArID,oEAqIC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { DetailedResult, failWithDetail } from '../base';\nimport { IReadOnlyResultMap, ResultMapResultDetail } from './readonlyResultMap';\nimport { ResultMapValueFactory } from './resultMap';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { CollectibleFactoryCallback, CollectibleKey, ICollectible } from './collectible';\nimport { CollectorResultDetail } from './collector';\nimport { ConvertingCollector } from './convertingCollector';\nimport { IReadOnlyCollectorValidator } from './collectorValidator';\n\n/**\n * Parameters for constructing a {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.\n * @public\n */\nexport interface IConvertingCollectorValidatorCreateParams<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>,\n  TSRC = TITEM\n> {\n  /** The converting collector to validate access to. */\n  collector: ConvertingCollector<TITEM, TSRC>;\n  /** The key-value converters for validation. */\n  converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;\n}\n\n/**\n * A {@link Collections.ConvertingCollector | ConvertingCollector} wrapper which validates weakly-typed keys\n * and values before calling the wrapped collector.  Unlike the basic {@link Collections.CollectorValidator | CollectorValidator},\n * the converting collector expects the items to be in the source type of the converting collector, not the target type.\n * @public\n */\nexport class ConvertingCollectorValidator<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>,\n  TSRC = TITEM\n> implements IReadOnlyCollectorValidator<TITEM>\n{\n  public readonly converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;\n\n  public get map(): IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM> {\n    return this._collector.toReadOnly();\n  }\n\n  protected _collector: ConvertingCollector<TITEM, TSRC>;\n\n  /**\n   * Constructs a new {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.\n   * @param params - Required parameters for constructing the collector validator.\n   */\n  public constructor(params: IConvertingCollectorValidatorCreateParams<TITEM, TSRC>) {\n    this._collector = params.collector;\n    this.converters = params.converters;\n  }\n\n  /**\n   * Adds an item to the collector using the default factory at a specified key,\n   * failing if an item with that key already exists.\n   * @param key - The weakly-typed key of the item to add.\n   * @param value - The source representation of the item to be added.\n   * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with\n   * an error if the item cannot be created and indexed.\n   */\n  public add(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Adds an item to the collector using a supplied factory callback\n   * at a specified key, validating the key first.\n   */\n  public add(\n    key: string,\n    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n  public add(\n    key: string,\n    valueOrFactory: unknown | ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (this.has(key)) {\n      return failWithDetail(`${key}: already exists`, 'exists');\n    }\n    return this.getOrAdd(key, valueOrFactory);\n  }\n\n  /**\n   * {@inheritDoc Collections.Collector.get}\n   */\n  public get(key: string): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((k) => {\n      return this._collector.get(k);\n    });\n  }\n\n  /**\n   * Gets an existing item with a key matching the supplied key, or adds a new item to the collector\n   * by converting the supplied weakly-typed value if no item with that key exists.\n   * @param key - The weakly-typed key of the item to get or add.\n   * @param value - The weakly-typed source value to convert and add if the key does not exist.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item was returned and detail `added` indicates\n   * that the item was added. Returns {@link DetailedFailure | Failure} with an error and\n   * appropriate detail if the item could not be added.\n   */\n  public getOrAdd(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Gets an existing item with a key matching the supplied key, or adds a new item to the collector\n   * using a factory callback if no item with that key exists.\n   * @param key - The weakly-typed key of the item to get or add.\n   * @param factory - The factory callback to create the item.\n   * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -\n   * detail `exists` indicates that an existing item was returned and detail `added` indicates\n   * that the item was added. Returns {@link DetailedFailure | Failure} with an error and\n   * appropriate detail if the item could not be added.\n   */\n  public getOrAdd(\n    key: string,\n    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n\n  public getOrAdd(\n    key: string,\n    valueOrFactory: unknown | CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (!this._isCollectibleFactoryCallback(valueOrFactory)) {\n      const converted = this.converters.convertEntry([key, valueOrFactory]);\n      if (converted.isFailure()) {\n        return failWithDetail(converted.message, converted.detail);\n      }\n      const [vk, vs] = converted.value;\n      return this._collector.getOrAdd(vk, vs);\n    } else {\n      const converted = this.converters.convertKey(key);\n      if (converted.isFailure()) {\n        return failWithDetail(converted.message, converted.detail);\n      }\n      return this._collector.getOrAdd(converted.value, valueOrFactory);\n    }\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.has}\n   */\n  public has(key: string): boolean {\n    return this._collector.has(key as CollectibleKey<TITEM>);\n  }\n\n  /**\n   * {@inheritDoc Collections.Collector.toReadOnly}\n   */\n  public toReadOnly(): IReadOnlyCollectorValidator<TITEM> {\n    return this;\n  }\n\n  /**\n   * Determines if a value is a {@link Collections.CollectibleFactoryCallback | CollectibleFactoryCallback}.\n   * @param value - The value to check.\n   * @returns `true` if the value is a {@link Collections.CollectibleFactoryCallback | CollectibleFactoryCallback},\n   * `false` otherwise.\n   * @public\n   */\n  protected _isCollectibleFactoryCallback(\n    value: unknown | CollectibleFactoryCallback<TITEM>\n  ): value is CollectibleFactoryCallback<TITEM> {\n    return typeof value === 'function';\n  }\n}\n"]}

package/lib/packlets/collections/convertingResultMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertingResultMap.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/convertingResultMap.ts"],"names":[],"mappings":"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"}

package/lib/packlets/collections/convertingResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertingResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/convertingResultMap.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { captureResult, DetailedResult, Result } from '../base';\nimport { KeyValueEntry } from './common';\nimport { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';\nimport {\n  ReadOnlyConvertingResultMap,\n  ConvertingResultMapValueConverter,\n  IReadOnlyConvertingResultMapConstructorParams\n} from './readOnlyConvertingResultMap';\nimport { IResultMap, ResultMapValueFactory } from './resultMap';\n\n/**\n * Parameters for constructing a {@link Collections.ConvertingResultMap | ConvertingResultMap}.\n * @public\n */\nexport interface IConvertingResultMapConstructorParams<\n  TK extends string,\n  TSRC,\n  TTARGET,\n  TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n> {\n  /**\n   * The inner map containing source values.\n   */\n  inner: TSRCMAP;\n\n  /**\n   * The converter function to transform source values to target values.\n   */\n  converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;\n}\n\n/**\n * A wrapper around a mutable result map that invalidates cache entries\n * in the parent {@link Collections.ConvertingResultMap | ConvertingResultMap} when mutations occur.\n * @public\n */\nexport class CacheInvalidatingResultMapWrapper<\n  TK extends string,\n  TSRC,\n  TTARGET,\n  TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n> implements IResultMap<TK, TSRC>\n{\n  private readonly _inner: TSRCMAP;\n  private readonly _parent: ConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP>;\n\n  /**\n   * Constructs a new cache-invalidating wrapper.\n   * @param inner - The inner map to wrap.\n   * @param parent - The parent converting map whose cache should be invalidated.\n   */\n  public constructor(inner: TSRCMAP, parent: ConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP>) {\n    this._inner = inner;\n    this._parent = parent;\n  }\n\n  /**\n   * The number of entries in the map.\n   */\n  public get size(): number {\n    return this._inner.size;\n  }\n\n  /**\n   * Adds a key/value pair to the map if the key does not already exist.\n   * Invalidates the cache entry for the key.\n   * @param key - The key to add.\n   * @param value - The value to add.\n   * @returns The result of the add operation.\n   */\n  public add(key: TK, value: TSRC): DetailedResult<TSRC, ResultMapResultDetail> {\n    this._parent._clearCacheEntry(key);\n    return this._inner.add(key, value);\n  }\n\n  /**\n   * Sets a key/value pair in the map.\n   * Invalidates the cache entry for the key.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns The result of the set operation.\n   */\n  public set(key: TK, value: TSRC): DetailedResult<TSRC, ResultMapResultDetail> {\n    this._parent._clearCacheEntry(key);\n    return this._inner.set(key, value);\n  }\n\n  /**\n   * Updates an existing key in the map.\n   * Invalidates the cache entry for the key.\n   * @param key - The key to update.\n   * @param value - The new value.\n   * @returns The result of the update operation.\n   */\n  public update(key: TK, value: TSRC): DetailedResult<TSRC, ResultMapResultDetail> {\n    this._parent._clearCacheEntry(key);\n    return this._inner.update(key, value);\n  }\n\n  /**\n   * Deletes a key from the map.\n   * Invalidates the cache entry for the key.\n   * @param key - The key to delete.\n   * @returns The result of the delete operation.\n   */\n  public delete(key: TK): DetailedResult<TSRC, ResultMapResultDetail> {\n    this._parent._clearCacheEntry(key);\n    return this._inner.delete(key);\n  }\n\n  /**\n   * Gets a value from the map.\n   * @param key - The key to retrieve.\n   * @returns The result of the get operation.\n   */\n  public get(key: TK): DetailedResult<TSRC, ResultMapResultDetail> {\n    return this._inner.get(key);\n  }\n\n  /**\n   * Gets a value from the map, or adds a supplied value if it does not exist.\n   * Invalidates the cache entry for the key if a new value is added.\n   * @param key - The key to retrieve or add.\n   * @param value - The value to add if the key does not exist.\n   * @returns The result of the operation.\n   */\n  public getOrAdd(key: TK, value: TSRC): DetailedResult<TSRC, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map, or adds a value created by a factory if it does not exist.\n   * Invalidates the cache entry for the key if a new value is added.\n   * @param key - The key to retrieve or add.\n   * @param factory - A factory function to create the value if the key does not exist.\n   * @returns The result of the operation.\n   */\n  public getOrAdd(\n    key: TK,\n    factory: ResultMapValueFactory<TK, TSRC>\n  ): DetailedResult<TSRC, ResultMapResultDetail>;\n\n  public getOrAdd(\n    key: TK,\n    valueOrFactory: TSRC | ResultMapValueFactory<TK, TSRC>\n  ): DetailedResult<TSRC, ResultMapResultDetail> {\n    const result =\n      typeof valueOrFactory === 'function'\n        ? this._inner.getOrAdd(key, valueOrFactory as ResultMapValueFactory<TK, TSRC>)\n        : this._inner.getOrAdd(key, valueOrFactory);\n\n    if (result.isSuccess() && result.detail === 'added') {\n      this._parent._clearCacheEntry(key);\n    }\n    return result;\n  }\n\n  /**\n   * Checks if the map contains a key.\n   * @param key - The key to check.\n   * @returns `true` if the key exists, `false` otherwise.\n   */\n  public has(key: TK): boolean {\n    return this._inner.has(key);\n  }\n\n  /**\n   * Clears all entries from the map.\n   * Clears the entire cache.\n   */\n  public clear(): void {\n    this._parent._clearCache();\n    this._inner.clear();\n  }\n\n  /**\n   * Returns an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  public entries(): IterableIterator<KeyValueEntry<TK, TSRC>> {\n    return this._inner.entries();\n  }\n\n  /**\n   * Returns an iterator over the map keys.\n   * @returns An iterator over the map keys.\n   */\n  public keys(): IterableIterator<TK> {\n    return this._inner.keys();\n  }\n\n  /**\n   * Returns an iterator over the map values.\n   * @returns An iterator over the map values.\n   */\n  public values(): IterableIterator<TSRC> {\n    return this._inner.values();\n  }\n\n  /**\n   * Calls a callback for each entry in the map.\n   * @param cb - The callback to call for each entry.\n   * @param thisArg - Optional `this` argument for the callback.\n   */\n  public forEach(cb: ResultMapForEachCb<TK, TSRC>, thisArg?: unknown): void {\n    this._inner.forEach(cb, thisArg);\n  }\n\n  /**\n   * Gets an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  public [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TSRC>> {\n    return this._inner[Symbol.iterator]();\n  }\n\n  /**\n   * Gets a read-only version of this map.\n   * @returns A read-only version of this map.\n   */\n  public toReadOnly(): IReadOnlyResultMap<TK, TSRC> {\n    return this._inner.toReadOnly();\n  }\n}\n\n/**\n * A result map that wraps an inner {@link Collections.IResultMap | IResultMap} of source type\n * and returns lazily-converted, cached values of a target type. Exposes the inner map\n * via a {@link Collections.CacheInvalidatingResultMapWrapper | source} property that\n * invalidates cache entries when mutations occur.\n * @public\n */\nexport class ConvertingResultMap<\n  TK extends string,\n  TSRC,\n  TTARGET,\n  TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n> extends ReadOnlyConvertingResultMap<TK, TSRC, TTARGET> {\n  /**\n   * A wrapper around the inner map that invalidates cache entries when mutations occur.\n   * Use this property to add, update, or delete source values.\n   */\n  public readonly source: CacheInvalidatingResultMapWrapper<TK, TSRC, TTARGET, TSRCMAP>;\n\n  /**\n   * The inner map, typed as the specific source map type.\n   */\n  protected readonly _typedInner: TSRCMAP;\n\n  /**\n   * Constructs a new {@link Collections.ConvertingResultMap | ConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   */\n  public constructor(params: IConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>) {\n    super(params as IReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>);\n    this._typedInner = params.inner;\n    this.source = new CacheInvalidatingResultMapWrapper<TK, TSRC, TTARGET, TSRCMAP>(params.inner, this);\n  }\n\n  /**\n   * Creates a new {@link Collections.ConvertingResultMap | ConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   * @returns `Success` with the new map, or `Failure` with error details if an error occurred.\n   */\n  public static override create<\n    TK extends string,\n    TSRC,\n    TTARGET,\n    TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n  >(\n    params: IConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>\n  ): Result<ConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP>> {\n    return captureResult(() => new ConvertingResultMap(params));\n  }\n\n  /**\n   * Clears a single entry from the cache.\n   * This method is public to allow the cache-invalidating wrapper to call it.\n   * @param key - The key to clear from the cache.\n   * @internal\n   */\n  public override _clearCacheEntry(key: TK): void {\n    super._clearCacheEntry(key);\n  }\n\n  /**\n   * Clears all entries from the cache.\n   * This method is public to allow the cache-invalidating wrapper to call it.\n   * @internal\n   */\n  public override _clearCache(): void {\n    super._clearCache();\n  }\n}\n"]}

package/lib/packlets/collections/index.d.ts

@@ -10,6 +10,7 @@ export * from './common';
 export * from './keyValueConverters';
 export * from './readonlyResultMap';
 export * from './readOnlyConvertingResultMap';
+export * from './retainingRingBuffer';
 export * from './resultMap';
 export * from './resultMapValidator';
 export * from './validatingCollector';

package/lib/packlets/collections/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AAEtC,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/lib/packlets/collections/index.js

@@ -71,6 +71,7 @@ __exportStar(require("./common"), exports);
 __exportStar(require("./keyValueConverters"), exports);
 __exportStar(require("./readonlyResultMap"), exports);
 __exportStar(require("./readOnlyConvertingResultMap"), exports);
+__exportStar(require("./retainingRingBuffer"), exports);
 __exportStar(require("./resultMap"), exports);
 __exportStar(require("./resultMapValidator"), exports);
 __exportStar(require("./validatingCollector"), exports);

package/lib/packlets/collections/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/collections/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,+CAAiC;AAqBxB,sBAAK;AAnBd,gDAA8B;AAC9B,wDAAsC;AACtC,wDAAsC;AACtC,8CAA4B;AAC5B,uDAAqC;AACrC,iEAA+C;AAC/C,kEAAgD;AAChD,2CAAyB;AACzB,uDAAqC;AACrC,sDAAoC;AACpC,gEAA8C;AAC9C,wDAAsC;AACtC,8CAA4B;AAC5B,uDAAqC;AACrC,wDAAsC;AACtC,kEAAgD;AAChD,wDAAsC;AACtC,wDAAsC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport * as Utils from './utils';\n\nexport * from './collectible';\nexport * from './convertingCollector';\nexport * from './convertingResultMap';\nexport * from './collector';\nexport * from './collectorValidator';\nexport * from './convertingCollectorValidator';\nexport * from './validatingConvertingCollector';\nexport * from './common';\nexport * from './keyValueConverters';\nexport * from './readonlyResultMap';\nexport * from './readOnlyConvertingResultMap';\nexport * from './retainingRingBuffer';\nexport * from './resultMap';\nexport * from './resultMapValidator';\nexport * from './validatingCollector';\nexport * from './validatingConvertingResultMap';\nexport * from './validatingResultMap';\nexport * from './aggregatedResultMap';\n\nexport { Utils };\n"]}

package/lib/packlets/collections/keyValueConverters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyValueConverters.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/keyValueConverters.ts"],"names":[],"mappings":"AAsBA,OAAO,EACL,cAAc,EAGd,MAAM,EAGP,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAc,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,mCAAmC,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO;IAC3F;;;OAGG;IACH,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,aAAa,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAElF;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,aAAa,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;CACrF;AAED;;;;GAIG;AACH,qBAAa,kBAAkB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO;IACtE;;OAEG;IACH,SAAgB,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACrE;;OAEG;IACH,SAAgB,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAEvE;;;OAGG;gBACgB,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,mCAAmC,CAAC,EAAE,EAAE,EAAE,CAAC;IAK9E;;;;;OAKG;IACI,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAAC,EAAE,EAAE,qBAAqB,CAAC;IAI1E;;;;;OAKG;IACI,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAAC,EAAE,EAAE,qBAAqB,CAAC;IAI5E;;;;;;OAMG;IACI,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,qBAAqB,CAAC;IAejG;;;;;OAKG;IACI,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;CAanF"}

package/lib/packlets/collections/keyValueConverters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyValueConverters.js","sourceRoot":"","sources":["../../../src/packlets/collections/keyValueConverters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,kCAOiB;AACjB,8CAAqE;AAuBrE;;;;GAIG;AACH,MAAa,kBAAkB;IAU7B;;;OAGG;IACH,YAAmB,EAAE,GAAG,EAAE,KAAK,EAA+C;QAC5E,IAAI,CAAC,GAAG,GAAG,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,uBAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACrE,IAAI,CAAC,KAAK,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,uBAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC/E,CAAC;IAED;;;;;OAKG;IACI,UAAU,CAAC,GAAY;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAChE,CAAC;IAED;;;;;OAKG;IACI,YAAY,CAAC,GAAY;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,eAAe,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;OAMG;IACI,YAAY,CAAC,KAAc;QAChC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAI,wBAAiB,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC;YACzE,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC;YAC7E,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;gBACjB,OAAO,IAAA,wBAAiB,EAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;YACpD,CAAC;YACD,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,aAAa,CAAC;YACrD,OAAO,IAAA,qBAAc,EAAC,kBAAkB,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QACvE,CAAC;QACD,sBAAsB;QACtB,OAAO,IAAA,qBAAc,EAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IACxF,CAAC;IAED;;;;;OAKG;IACI,cAAc,CAAC,OAA0B;QAC9C,MAAM,MAAM,GAAG,IAAI,wBAAiB,EAAE,CAAC;QACvC,MAAM,SAAS,GAA4B,EAAE,CAAC;QAC9C,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;iBACvB,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;gBACf,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,OAAO,IAAA,wBAAiB,EAAC,CAAC,EAAE,SAAS,CAAC,CAAC;YACzC,CAAC,CAAC;iBACD,cAAc,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,MAAM,CAAC,cAAc,CAAC,IAAA,cAAO,EAAC,SAAS,CAAC,CAAC,CAAC;IACnD,CAAC;CACF;AAhFD,gDAgFC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport {\n  DetailedResult,\n  failWithDetail,\n  MessageAggregator,\n  Result,\n  succeed,\n  succeedWithDetail\n} from '../base';\nimport { Converter, ConverterFunc, Converters } from '../conversion';\nimport { Validator } from '../validation';\nimport { KeyValueEntry } from './common';\nimport { ResultMapResultDetail } from './readonlyResultMap';\n\n/**\n * Parameters for constructing a {@link Collections.KeyValueConverters | KeyValueConverters} instance.\n * @public\n */\nexport interface IKeyValueConverterConstructorParams<TK extends string = string, TV = unknown> {\n  /**\n   * Required key {@link Validator | validator}, {@link Converter | converter},\n   * or {@link Conversion.ConverterFunc | converter function}.\n   */\n  key: Validator<TK, unknown> | Converter<TK, unknown> | ConverterFunc<TK, unknown>;\n\n  /**\n   * Required value {@link Validator | validator}, {@link Converter | converter},\n   * or {@link Conversion.ConverterFunc | converter function}.\n   */\n  value: Validator<TV, unknown> | Converter<TV, unknown> | ConverterFunc<TV, unknown>;\n}\n\n/**\n * Helper class for converting strongly-typed keys, values, or entries\n * from unknown values.\n * @public\n */\nexport class KeyValueConverters<TK extends string = string, TV = unknown> {\n  /**\n   * Required key {@link Validator | validator} or {@link Converter | converter}.\n   */\n  public readonly key: Validator<TK, unknown> | Converter<TK, unknown>;\n  /**\n   * Required value {@link Validator | validator} or {@link Converter | converter}.\n   */\n  public readonly value: Validator<TV, unknown> | Converter<TV, unknown>;\n\n  /**\n   * Constructs a new key-value validator.\n   * @param params - Key and value converters or validators.\n   */\n  public constructor({ key, value }: IKeyValueConverterConstructorParams<TK, TV>) {\n    this.key = typeof key === 'function' ? Converters.generic(key) : key;\n    this.value = typeof value === 'function' ? Converters.generic(value) : value;\n  }\n\n  /**\n   * Converts a supplied unknown to a valid key value of type `<TK>`.\n   * @param key - The unknown to be converted.\n   * @returns `Success` with the converted key value and 'success' detail if the key is valid,\n   * or `Failure` with an error message and 'invalid-key' detail if the key is invalid.\n   */\n  public convertKey(key: unknown): DetailedResult<TK, ResultMapResultDetail> {\n    return this.key.convert(key).withFailureDetail('invalid-key');\n  }\n\n  /**\n   * Converts a supplied unknown to a valid value of type `<TV>`.\n   * @param key - The unknown to be converted.\n   * @returns `Success` with the converted value and 'success' detail if the value is valid,\n   * or `Failure` with an error message and 'invalid-value' detail if the value is invalid.\n   */\n  public convertValue(key: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.value.convert(key).withFailureDetail('invalid-value');\n  }\n\n  /**\n   * Converts a supplied unknown to a valid entry of type `[<TK>, <TV>]`.\n   * @param entry - The unknown to be converted.\n   * @returns `Success` with the converted entry and 'success' detail if the entry\n   * is valid, or `Failure` with an error message and 'invalid-key' or 'invalid-value' detail if\n   * the entry is invalid\n   */\n  public convertEntry(entry: unknown): DetailedResult<KeyValueEntry<TK, TV>, ResultMapResultDetail> {\n    if (Array.isArray(entry) && entry.length === 2) {\n      const errors = new MessageAggregator();\n      const key = this.convertKey(entry[0]).aggregateError(errors).orDefault();\n      const value = this.convertValue(entry[1]).aggregateError(errors).orDefault();\n      if (key && value) {\n        return succeedWithDetail([key, value], 'success');\n      }\n      const detail = key ? 'invalid-value' : 'invalid-key';\n      return failWithDetail(`invalid entry: ${errors.toString()}`, detail);\n    }\n    /* c8 ignore next 2 */\n    return failWithDetail(`malformed entry: \"${JSON.stringify(entry)}\"`, 'invalid-value');\n  }\n\n  /**\n   * Converts a supplied iterable of unknowns to valid key-value pairs.\n   * @param entries - The iterable of unknowns to be converted.\n   * @returns `Success` with an array of converted key-value pairs if all entries are valid,\n   * or `Failure` with an error message if any entry is invalid.\n   */\n  public convertEntries(entries: Iterable<unknown>): Result<KeyValueEntry<TK, TV>[]> {\n    const errors = new MessageAggregator();\n    const converted: KeyValueEntry<TK, TV>[] = [];\n    for (const element of entries) {\n      this.convertEntry(element)\n        .onSuccess((e) => {\n          converted.push(e);\n          return succeedWithDetail(e, 'success');\n        })\n        .aggregateError(errors);\n    }\n    return errors.returnOrReport(succeed(converted));\n  }\n}\n"]}

package/lib/packlets/collections/readOnlyConvertingResultMap.d.ts

@@ -1,5 +1,6 @@
 import { DetailedResult, Result } from '../base';
-import { ILogger } from '../logging';
+import { Converter } from '../conversion';
+import { ILogger } from '../logging-interface';
 import { KeyValueEntry } from './common';
 import { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';
 /**
@@ -15,6 +16,17 @@ export type ConvertingResultMapValueConverter<TK extends string, TSRC, TTARGET>
  * @public
  */
 export type ConversionErrorHandling = 'ignore' | 'warn' | 'fail';
+/**
+ * Exhaustive list of all {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.
+ * @public
+ */
+export declare const allConversionErrorHandling: readonly ConversionErrorHandling[];
+/**
+ * A ready-made {@link Converter | Converter} for
+ * {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.
+ * @public
+ */
+export declare const conversionErrorHandling: Converter<ConversionErrorHandling, ReadonlyArray<ConversionErrorHandling>>;
 /**
  * Parameters for constructing a {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.
  * @public

package/lib/packlets/collections/readOnlyConvertingResultMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readOnlyConvertingResultMap.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/readOnlyConvertingResultMap.ts"],"names":[],"mappings":"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"}

package/lib/packlets/collections/readOnlyConvertingResultMap.js

@@ -21,8 +21,26 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReadOnlyConvertingResultMap = void 0;
+exports.ReadOnlyConvertingResultMap = exports.conversionErrorHandling = exports.allConversionErrorHandling = void 0;
 const base_1 = require("../base");
+const conversion_1 = require("../conversion");
+// Untyped (literal-tuple-inferred) source of truth for allConversionErrorHandling, kept separate from
+// the widened public export below so the exhaustiveness check actually inspects the literal values
+// instead of being widened away to {@link Collections.ConversionErrorHandling | ConversionErrorHandling} before the check runs.
+const conversionErrorHandlingValues = ['ignore', 'warn', 'fail'];
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _conversionErrorHandlingExhaustivenessCheck = true;
+/**
+ * Exhaustive list of all {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.
+ * @public
+ */
+exports.allConversionErrorHandling = conversionErrorHandlingValues;
+/**
+ * A ready-made {@link Converter | Converter} for
+ * {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.
+ * @public
+ */
+exports.conversionErrorHandling = conversion_1.Converters.enumeratedValue(exports.allConversionErrorHandling);
 /**
  * A read-only result map that wraps an inner {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}
  * of source type and returns lazily-converted, cached values of a target type.