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

package/dist/packlets/collections/collectible.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectible.js","sourceRoot":"","sources":["../../../src/packlets/collections/collectible.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAU,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAA4B,UAAU,EAAE,MAAM,eAAe,CAAC;AAuFrE;;;;GAIG;AACH,MAAM,OAAO,WAAW;IAQtB;;OAEG;IACH,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IA2BD,YAAmB,MAAmD;QACpE,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,gBAAgB,IAAI,MAAM,EAAE,CAAC;YAC/B,IAAI,CAAC,eAAe;gBAClB,OAAO,MAAM,CAAC,cAAc,KAAK,UAAU;oBACzC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC;oBAC3C,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC;YAC5B,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC/B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YACrE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,qDAAqD;YACrD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;QAC7B,CAAC;IACH,CAAC;IAkCM,MAAM,CAAC,iBAAiB,CAC7B,MAAmD;QAEnD,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACI,QAAQ,CAAC,KAAa;QAC3B,IAAI,SAA6B,CAAC;QAClC,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC/D,iFAAiF;YACjF,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;YACvB,CAAC;YACD,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;QAED,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACzB,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,0CAA0C,KAAK,EAAE,CAAC,CAAC;QACpF,CAAC;QAED,6CAA6C;QAC7C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,SAAS,KAAK,4DAA4D,CAAC,CAAC;QAC1F,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;CACF","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 { Result, captureResult, fail, succeed } from '../base';\nimport { Converter, ConverterFunc, Converters } from '../conversion';\nimport { Validator } from '../validation';\n\n/**\n * An item that can be collected by some {@link ConvertingCollector | Collector}.\n * @public\n */\nexport interface ICollectible<TKEY extends string = string, TINDEX extends number = number> {\n  readonly key: TKEY;\n  readonly index: TINDEX | undefined;\n  setIndex(index: number): Result<TINDEX>;\n}\n\n/**\n * Infer the key type from an {@link Collections.ICollectible | ICollectible} type.\n * @public\n */\nexport type CollectibleKey<TITEM extends ICollectible> = TITEM extends ICollectible<infer TKEY>\n  ? TKEY\n  : never;\n\n/**\n * Infer the index type from an {@link Collections.ICollectible | ICollectible} type.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type CollectibleIndex<TITEM extends ICollectible> = TITEM extends ICollectible<any, infer TINDEX>\n  ? TINDEX\n  : never;\n\n/**\n * Factory function for creating a new {@link Collections.ICollectible | ICollectible} instance given a key, an index and a source representation\n * of the item to be added.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type CollectibleFactory<TITEM extends ICollectible<any, any>, TSRC> = (\n  key: CollectibleKey<TITEM>,\n  index: number,\n  item: TSRC\n) => Result<TITEM>;\n\n/**\n * Factory function for creating a new {@link Collections.ICollectible | ICollectible} instance given a key and an index.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type CollectibleFactoryCallback<TITEM extends ICollectible<any, any>> = (\n  key: CollectibleKey<TITEM>,\n  index: number\n) => Result<TITEM>;\n\n/**\n * Parameters for constructing a new {@link Collections.ICollectible | ICollectible} instance with\n * a defined, strongly-typed index.\n * @public\n */\nexport interface ICollectibleConstructorParamsWithIndex<\n  TKEY extends string = string,\n  TINDEX extends number = number\n> {\n  key: TKEY;\n  index: TINDEX;\n}\n\n/**\n * Parameters for constructing a new {@link Collections.ICollectible | ICollectible} instance with an\n * index converter.\n * @public\n */\nexport interface ICollectibleConstructorParamsWithConverter<\n  TKEY extends string = string,\n  TINDEX extends number = number\n> {\n  key: TKEY;\n  index?: number;\n  indexConverter: Validator<TINDEX, unknown> | Converter<TINDEX, unknown> | ConverterFunc<TINDEX, undefined>;\n}\n\n/**\n * Parameters for constructing a new {@link Collections.ICollectible | ICollectible} instance.\n * @public\n */\nexport type ICollectibleConstructorParams<TKEY extends string = string, TINDEX extends number = number> =\n  | ICollectibleConstructorParamsWithIndex<TKEY, TINDEX>\n  | ICollectibleConstructorParamsWithConverter<TKEY, TINDEX>;\n\n/**\n * Simple implementation of {@link Collections.ICollectible | ICollectible} which does not allow the index to be\n * changed once set.\n * @public\n */\nexport class Collectible<TKEY extends string = string, TINDEX extends number = number>\n  implements ICollectible<TKEY, TINDEX>\n{\n  /**\n   * {@link Collections.ICollectible.key}\n   */\n  public readonly key: TKEY;\n\n  /**\n   * {@link Collections.ICollectible.index}\n   */\n  public get index(): TINDEX | undefined {\n    return this._index;\n  }\n\n  protected _index: TINDEX | undefined;\n  protected readonly _indexConverter?: Validator<TINDEX, unknown> | Converter<TINDEX, unknown>;\n\n  /**\n   * Constructs a new {@link Collections.Collectible | Collectible} instance\n   * with a defined, strongly-typed index.\n   * @param params - {@link Collections.ICollectibleConstructorParamsWithIndex | Parameters} for constructing\n   * the collectible.\n   */\n  public constructor(params: ICollectibleConstructorParamsWithIndex<TKEY, TINDEX>);\n\n  /**\n   * Constructs a new {@link Collections.Collectible | Collectible} instance with\n   * an undefined index and an index converter to validate te index when it is set.\n   * @param params - {@link Collections.ICollectibleConstructorParamsWithConverter | Parameters} for constructing\n   * the collectible.\n   */\n  public constructor(params: ICollectibleConstructorParamsWithConverter<TKEY, TINDEX>);\n\n  /**\n   * Constructs a new {@link Collections.Collectible | Collectible} instance.\n   * @param params - {@link Collections.ICollectibleConstructorParams | Parameters} for constructing\n   * the collectible.\n   */\n  public constructor(params: ICollectibleConstructorParams<TKEY, TINDEX>);\n  public constructor(params: ICollectibleConstructorParams<TKEY, TINDEX>) {\n    this.key = params.key;\n    if ('indexConverter' in params) {\n      this._indexConverter =\n        typeof params.indexConverter === 'function'\n          ? Converters.generic(params.indexConverter)\n          : params.indexConverter;\n      if (params.index !== undefined) {\n        this._index = this._indexConverter.convert(params.index).orThrow();\n      }\n    } else {\n      /* c8 ignore next 3 - coverage is having a bad day */\n      this._index = params.index;\n    }\n  }\n\n  /**\n   * Creates a new {@link Collections.Collectible | Collectible} instance with a defined, strongly-typed index.\n   * @param params - {@link Collections.ICollectibleConstructorParamsWithIndex | Parameters} for constructing\n   * the collectible.\n   * @returns {@link Success} with the new collectible if successful, {@link Failure} otherwise.\n   */\n  public static createCollectible<TKEY extends string = string, TINDEX extends number = number>(\n    params: ICollectibleConstructorParamsWithIndex<TKEY, TINDEX>\n  ): Result<Collectible<TKEY, TINDEX>>;\n\n  /**\n   * Creates a new {@link Collections.Collectible | Collectible} instance with an undefined index and an index\n   * converter to validate the index when it is set.\n   * @param params - {@link Collections.ICollectibleConstructorParamsWithConverter | Parameters} for constructing\n   * the collectible.\n   * @returns {@link Success} with the new collectible if successful, {@link Failure} otherwise.\n   */\n  public static createCollectible<TKEY extends string = string, TINDEX extends number = number>(\n    params: ICollectibleConstructorParamsWithConverter<TKEY, TINDEX>\n  ): Result<Collectible<TKEY, TINDEX>>;\n\n  /**\n   * Creates a new {@link Collections.Collectible | Collectible} instance.\n   * @param params - {@link Collections.ICollectibleConstructorParams | Parameters} for constructing\n   * the collectible.\n   * @returns {@link Success} with the new collectible if successful, {@link Failure} otherwise\n   * @public\n   */\n  public static createCollectible<TKEY extends string = string, TINDEX extends number = number>(\n    params: ICollectibleConstructorParams<TKEY, TINDEX>\n  ): Result<Collectible<TKEY, TINDEX>>;\n\n  public static createCollectible<TKEY extends string = string, TINDEX extends number = number>(\n    params: ICollectibleConstructorParams<TKEY, TINDEX>\n  ): Result<Collectible<TKEY, TINDEX>> {\n    return captureResult(() => new Collectible(params));\n  }\n\n  /**\n   * {@link Collections.ICollectible.setIndex}\n   */\n  public setIndex(index: number): Result<TINDEX> {\n    let converted: TINDEX | undefined;\n    if (this._indexConverter) {\n      const { value, message } = this._indexConverter.convert(index);\n      /* c8 ignore next 3 - there's a test for this but coverage is having a bad day */\n      if (message) {\n        return fail(message);\n      }\n      converted = value;\n    }\n\n    if (index === this.index) {\n      return succeed(this.index);\n    } else if (this._index !== undefined) {\n      return fail(`index ${this.index} is immutable and cannot be changed to ${index}`);\n    }\n\n    /* c8 ignore next 3 - should be impossible */\n    if (converted === undefined) {\n      return fail(`index ${index} cannot be set on a Collectible without an index converter`);\n    }\n\n    this._index = converted;\n    return succeed(converted);\n  }\n}\n"]}

package/dist/packlets/collections/collector.js

@@ -31,7 +31,7 @@ import { captureResult, failWithDetail, fail, succeed, succeedWithDetail } from
  */
 export class Collector {
     /**
-     * {@inheritDoc Collections.ResultMap.size}
+     * Returns the number of entries in the map.
      */
     get size() {
         return this._byIndex.length;
@@ -87,13 +87,16 @@ export class Collector {
         return 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()) {
@@ -101,14 +104,20 @@ export 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 ? succeedWithDetail(item, 'exists') : 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') {
@@ -146,25 +155,30 @@ export 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/dist/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/dist/packlets/collections/collectorValidator.js

@@ -37,7 +37,12 @@ export 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/dist/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,MAAM,OAAO,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","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/dist/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/dist/packlets/collections/converters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../src/packlets/collections/converters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAa,UAAU,EAAE,MAAM,eAAe,CAAC;AAYtD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA6C;IAE7C,OAAO,UAAU,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,OAAO,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/dist/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/dist/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,OAAO,EAAkB,cAAc,EAAE,MAAM,SAAS,CAAC;AAwBzD;;;;;GAKG;AACH,MAAM,OAAO,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,cAAc,CAAC,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,cAAc,CAAC,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,cAAc,CAAC,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","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/dist/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/dist/packlets/collections/index.js

@@ -31,6 +31,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/dist/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,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","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/dist/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,OAAO,EAEL,cAAc,EACd,iBAAiB,EAEjB,OAAO,EACP,iBAAiB,EAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAA4B,UAAU,EAAE,MAAM,eAAe,CAAC;AAuBrE;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IAU7B;;;OAGG;IACH,YAAmB,EAAE,GAAG,EAAE,KAAK,EAA+C;QAC5E,IAAI,CAAC,GAAG,GAAG,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACrE,IAAI,CAAC,KAAK,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,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,iBAAiB,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,iBAAiB,CAAC,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,cAAc,CAAC,kBAAkB,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QACvE,CAAC;QACD,sBAAsB;QACtB,OAAO,cAAc,CAAC,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,iBAAiB,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,iBAAiB,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;YACzC,CAAC,CAAC;iBACD,cAAc,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IACnD,CAAC;CACF","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/dist/packlets/collections/readOnlyConvertingResultMap.js

@@ -20,6 +20,24 @@
  * SOFTWARE.
  */
 import { captureResult, failWithDetail, succeedWithDetail } from '../base';
+import { Converters } from '../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
+ */
+export const allConversionErrorHandling = conversionErrorHandlingValues;
+/**
+ * A ready-made {@link Converter | Converter} for
+ * {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.
+ * @public
+ */
+export const conversionErrorHandling = Converters.enumeratedValue(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.

package/dist/packlets/collections/readOnlyConvertingResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readOnlyConvertingResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/readOnlyConvertingResultMap.ts"],"names":[],"mappings":"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","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 { captureResult, DetailedResult, failWithDetail, Result, succeedWithDetail } from '../base';\nimport { Converter, Converters } from '../conversion';\nimport { ILogger } from '../logging-interface';\nimport { KeyValueEntry } from './common';\nimport { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';\n\n/**\n * A function that converts a source value to a target value.\n * @public\n */\nexport type ConvertingResultMapValueConverter<TK extends string, TSRC, TTARGET> = (\n  src: TSRC,\n  key: TK\n) => Result<TTARGET>;\n\n/**\n * Error handling behavior for conversion failures during iteration.\n * - `'ignore'`: Silently skip failed conversions (default behavior)\n * - `'warn'`: Log warning and skip failed conversions\n * - `'fail'`: Throw error on first conversion failure\n * @public\n */\nexport type ConversionErrorHandling = 'ignore' | 'warn' | 'fail';\n\n// Untyped (literal-tuple-inferred) source of truth for allConversionErrorHandling, kept separate from\n// the widened public export below so the exhaustiveness check actually inspects the literal values\n// instead of being widened away to {@link Collections.ConversionErrorHandling | ConversionErrorHandling} before the check runs.\nconst conversionErrorHandlingValues = ['ignore', 'warn', 'fail'] as const;\n\n/**\n * Compile-time exhaustiveness guard ensuring {@link conversionErrorHandlingValues} exactly matches every\n * member of {@link Collections.ConversionErrorHandling | ConversionErrorHandling}. Adding or removing a\n * union member without updating the array fails the build.\n * Deliberately not exported - this exists only to force the compiler to evaluate the check below.\n */\ntype _ConversionErrorHandlingExhaustivenessCheck = [\n  Exclude<ConversionErrorHandling, (typeof conversionErrorHandlingValues)[number]>,\n  Exclude<(typeof conversionErrorHandlingValues)[number], ConversionErrorHandling>\n] extends [never, never]\n  ? true\n  : never;\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nconst _conversionErrorHandlingExhaustivenessCheck: _ConversionErrorHandlingExhaustivenessCheck = true;\n\n/**\n * Exhaustive list of all {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.\n * @public\n */\nexport const allConversionErrorHandling: readonly ConversionErrorHandling[] = conversionErrorHandlingValues;\n\n/**\n * A ready-made {@link Converter | Converter} for\n * {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.\n * @public\n */\nexport const conversionErrorHandling: Converter<\n  ConversionErrorHandling,\n  ReadonlyArray<ConversionErrorHandling>\n> = Converters.enumeratedValue<ConversionErrorHandling>(allConversionErrorHandling);\n\n/**\n * Parameters for constructing a {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.\n * @public\n */\nexport interface IReadOnlyConvertingResultMapConstructorParams<TK extends string, TSRC, TTARGET> {\n  /**\n   * The inner map containing source values.\n   */\n  inner: IReadOnlyResultMap<TK, TSRC>;\n\n  /**\n   * The converter function to transform source values to target values.\n   */\n  converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;\n\n  /**\n   * Error handling behavior for conversion failures during iteration.\n   * Defaults to `'ignore'` (silently skip failed conversions).\n   */\n  onConversionError?: ConversionErrorHandling;\n\n  /**\n   * Optional logger for warnings when `onConversionError` is `'warn'`.\n   */\n  logger?: ILogger;\n}\n\n/**\n * A read-only result map that wraps an inner {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}\n * of source type and returns lazily-converted, cached values of a target type.\n * @public\n */\nexport class ReadOnlyConvertingResultMap<TK extends string, TSRC, TTARGET>\n  implements IReadOnlyResultMap<TK, TTARGET>\n{\n  /**\n   * The inner map containing source values.\n   */\n  protected readonly _inner: IReadOnlyResultMap<TK, TSRC>;\n\n  /**\n   * The converter function to transform source values to target values.\n   */\n  protected readonly _converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;\n\n  /**\n   * Cache of converted target values.\n   */\n  protected readonly _cache: Map<TK, TTARGET>;\n\n  /**\n   * Error handling behavior for conversion failures during iteration.\n   */\n  protected readonly _onConversionError: ConversionErrorHandling;\n\n  /**\n   * Optional logger for warnings.\n   */\n  protected readonly _logger?: ILogger;\n\n  /**\n   * Constructs a new {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   */\n  public constructor(params: IReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>) {\n    this._inner = params.inner;\n    this._converter = params.converter;\n    this._cache = new Map<TK, TTARGET>();\n    this._onConversionError = params.onConversionError ?? 'ignore';\n    this._logger = params.logger;\n  }\n\n  /**\n   * Creates a new {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.\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 create<TK extends string, TSRC, TTARGET>(\n    params: IReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>\n  ): Result<ReadOnlyConvertingResultMap<TK, TSRC, TTARGET>> {\n    return captureResult(() => new ReadOnlyConvertingResultMap(params));\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   * Gets a converted value from the map by key.\n   * @param key - The key to retrieve.\n   * @returns `Success` with the converted value and detail `exists` if the key was found,\n   * `Failure` with detail `not-found` if the key was not found, or `Failure` with\n   * detail `invalid-value` if conversion failed.\n   */\n  public get(key: TK): DetailedResult<TTARGET, ResultMapResultDetail> {\n    const cached = this._cache.get(key);\n    if (cached !== undefined) {\n      return succeedWithDetail(cached, 'exists');\n    }\n\n    return this._inner.get(key).onSuccess((src) => {\n      return this._convertAndCache(key, src);\n    });\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   * Returns an iterator over the map entries with converted values.\n   * @returns An iterator over the map entries.\n   */\n  public *entries(): IterableIterator<KeyValueEntry<TK, TTARGET>> {\n    for (const [key, src] of this._inner.entries()) {\n      const target = this._getOrConvert(key, src);\n      if (target !== undefined) {\n        yield [key, target];\n      }\n    }\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 converted map values.\n   * @returns An iterator over the map values.\n   */\n  public *values(): IterableIterator<TTARGET> {\n    for (const [key, src] of this._inner.entries()) {\n      const target = this._getOrConvert(key, src);\n      if (target !== undefined) {\n        yield target;\n      }\n    }\n  }\n\n  /**\n   * Calls a callback for each entry in the map with converted values.\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, TTARGET>, thisArg?: unknown): void {\n    for (const [key, src] of this._inner.entries()) {\n      const target = this._getOrConvert(key, src);\n      if (target !== undefined) {\n        cb.call(thisArg, target, key, this);\n      }\n    }\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, TTARGET>> {\n    return this.entries();\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, TTARGET> {\n    return this;\n  }\n\n  /**\n   * Converts a source value to a target value and caches the result.\n   * @param key - The key of the value.\n   * @param src - The source value to convert.\n   * @returns `Success` with the converted value if successful, `Failure` otherwise.\n   */\n  protected _convertAndCache(key: TK, src: TSRC): DetailedResult<TTARGET, ResultMapResultDetail> {\n    const result = this._converter(src, key);\n    if (result.isFailure()) {\n      return failWithDetail(result.message, 'invalid-value');\n    }\n    this._cache.set(key, result.value);\n    return succeedWithDetail(result.value, 'exists');\n  }\n\n  /**\n   * Gets a cached value or converts and caches a source value.\n   * Used by iterators. Handles conversion failures according to `_onConversionError`.\n   * @param key - The key of the value.\n   * @param src - The source value to convert if not cached.\n   * @returns The converted value, or `undefined` if conversion failed.\n   * @throws Error if `_onConversionError` is `'fail'` and conversion fails.\n   */\n  protected _getOrConvert(key: TK, src: TSRC): TTARGET | undefined {\n    const cached = this._cache.get(key);\n    if (cached !== undefined) {\n      return cached;\n    }\n\n    const result = this._converter(src, key);\n    if (result.isSuccess()) {\n      this._cache.set(key, result.value);\n      return result.value;\n    }\n\n    switch (this._onConversionError) {\n      case 'fail':\n        throw new Error(`Conversion failed for key '${key}': ${result.message}`);\n      case 'warn':\n        this._logger?.log('warning', `Conversion failed for key '${key}': ${result.message}`);\n        break;\n    }\n    return undefined;\n  }\n\n  /**\n   * Clears a single entry from the cache.\n   * @param key - The key to clear from the cache.\n   */\n  protected _clearCacheEntry(key: TK): void {\n    this._cache.delete(key);\n  }\n\n  /**\n   * Clears all entries from the cache.\n   */\n  protected _clearCache(): void {\n    this._cache.clear();\n  }\n}\n"]}

package/dist/packlets/collections/readonlyResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readonlyResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/readonlyResultMap.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\nimport { DetailedResult } from '../base';\nimport { KeyValueEntry } from './common';\n\n/**\n * Additional success or failure details for {@link Collections.ResultMap | ResultMap} calls.\n * @public\n */\nexport type ResultMapResultDetail =\n  | 'added'\n  | 'deleted'\n  | 'exists'\n  | 'failure'\n  | 'invalid-key'\n  | 'invalid-value'\n  | 'not-found'\n  | 'success'\n  | 'updated';\n\n/**\n * Callback for {@link Collections.ResultMap | ResultMap} `forEach` method.\n * @public\n */\nexport type ResultMapForEachCb<TK extends string = string, TE = unknown> = (\n  value: TE,\n  key: TK,\n  map: IReadOnlyResultMap<TK, TE>,\n  thisArg?: unknown\n) => void;\n\n/**\n * A readonly `ReadonlyMap<TK, TV>`-like object which reports success or failure\n * with additional details using the\n * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#the-result-pattern | result pattern}.\n * @public\n */\nexport interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {\n  /**\n   * Returns the number of entries in the map.\n   */\n  readonly size: number;\n\n  /**\n   * Returns an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  entries(): IterableIterator<KeyValueEntry<TK, TV>>;\n\n  /**\n   * Calls a function for each entry in the map.\n   * @param cb - The function to call for each entry.\n   * @param arg - An optional argument to pass to the callback.\n   */\n  forEach(cb: ResultMapForEachCb, arg?: unknown): void;\n\n  /**\n   * Gets a value from the map.\n   * @param key - The key to retrieve.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Failure` with detail `not-found` if the key was not found or with detail\n   * `invalid-key` if the key is invalid.\n   */\n  get(key: TK): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Returns `true` if the map contains a key.\n   * @param key - The key to check.\n   * @returns `true` if the key exists, `false` otherwise.\n   */\n  has(key: TK): boolean;\n\n  /**\n   * Returns an iterator over the map keys.\n   * @returns An iterator over the map keys.\n   */\n  keys(): IterableIterator<TK>;\n\n  /**\n   * Returns an iterator over the map values.\n   * @returns An iterator over the map values.\n   */\n  values(): IterableIterator<TV>;\n\n  /**\n   * Gets an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TV>>;\n}\n"]}

package/dist/packlets/collections/resultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/resultMap.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, succeed, succeedWithDetail } from '../base';\nimport { KeyValueEntry } from './common';\nimport { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';\nimport { isIterable } from './utils';\n\n/**\n * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.\n * @public\n */\nexport interface IResultMapConstructorParams<TK extends string = string, TV = unknown> {\n  entries?: Iterable<KeyValueEntry<TK, TV>>;\n}\n\n/**\n * Deferred constructor for the {@link Collections.ResultMap.getOrAdd | getOrAdd} method.\n * @public\n */\nexport type ResultMapValueFactory<TK extends string = string, TV = unknown> = (key: TK) => Result<TV>;\n\n/**\n * Interface for a mutable {@link Collections.ResultMap | ResultMap}.\n * @public\n */\nexport interface IResultMap<TK extends string = string, TV = unknown> extends IReadOnlyResultMap<TK, TV> {\n  /**\n   * Sets a key/value pair in the map if the key does not already exist.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns `Success` with the value and detail `added` if the key was added,\n   * `Failure` with detail `exists` if the key already exists. Fails with detail\n   * 'invalid-key' or 'invalid-value' and an error message if either is invalid.\n   */\n  add(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Sets a key/value pair in the map regardless of whether the key already exists.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns `Success` with the new value and the detail `updated` if the\n   * key was found and updated, `Success` with the new value and detail\n   * `added` if the key was not found and added.  Fails with detail\n   * 'invalid-key' or 'invalid-value' and an error message if either is invalid.\n   */\n  set(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Updates the value associated with a key in the map.\n   * @param key - The key to update.\n   * @param value - The value to set.\n   * @returns `Success` with the value and detail 'updated' if the key was found\n   * and the value updated, `Failure` an error message and with detail `not-found`\n   * if the key was not found, or with detail 'invalid-key' or 'invalid-value'\n   * if either is invalid.\n   */\n  update(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Deletes a key from the map.\n   * @param key - The key to delete.\n   * @returns `Success` with the previous value and the detail 'deleted'\n   * if the key was found and deleted, `Failure` with detail 'not-found'\n   * if the key was not found, or with detail 'invalid-key' if the key is invalid.\n   */\n  delete(key: TK): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map.\n   * @param key - The key to retrieve.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Failure` with detail `not-found` if the key was not found or with detail\n   * `invalid-key` if the key is invalid.\n   */\n  get(key: TK): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map, or adds a supplied value if it does not exist.\n   * @param key - The key to be retrieved or created.\n   * @param value - The value to add if the key does not exist.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Success` with the value and detail `added` if the key was not found and added.\n   * Fails with detail 'invalid-key' or 'invalid-value' and an error message if either\n   * is invalid.\n   * {@label WITH_VALUE}\n   */\n  getOrAdd(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map, or adds a value created by a factory function if it does not exist.\n   * @param key - The key of the element to be retrieved or created.\n   * @param factory - A {@link Collections.ResultMapValueFactory | factory function} to create the value if\n   * the key does not exist.\n   * @returns `Success` with the value and detail `exists` if the key was found, `Success` with\n   * the value and detail `added` if the key was not found and added. Fails with detail 'invalid-key'\n   * or 'invalid-value' and an error message if either is invalid.\n   * {@label WITH_FACTORY}\n   */\n  getOrAdd(key: TK, factory: ResultMapValueFactory<TK, TV>): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Returns an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  entries(): IterableIterator<KeyValueEntry<TK, TV>>;\n\n  /**\n   * Returns the number of entries in the map.\n   */\n  readonly size: number;\n\n  /**\n   * Returns an iterator over the map keys.\n   * @returns An iterator over the map keys.\n   */\n  keys(): IterableIterator<TK>;\n\n  /**\n   * Returns an iterator over the map values.\n   * @returns An iterator over the map values.\n   */\n  values(): IterableIterator<TV>;\n\n  /**\n   * Calls a function for each entry in the map.\n   * @param cb - The function to call for each entry.\n   * @param arg - An optional argument to pass to the callback.\n   */\n  forEach(cb: ResultMapForEachCb<TK, TV>, arg?: unknown): void;\n\n  /**\n   * Clears all entries from the map.\n   */\n  clear(): void;\n\n  /**\n   * Gets a readonly version of this map.\n   */\n  toReadOnly(): IReadOnlyResultMap<TK, TV>;\n}\n\n/**\n * A {@link Collections.ResultMap | ResultMap} class as a `Map<TK, TV>`-like object which\n * reports success or failure with additional details using the\n * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#the-result-pattern | result pattern}.\n * @public\n */\nexport class ResultMap<TK extends string = string, TV = unknown> implements IResultMap<TK, TV> {\n  /**\n   * Protected raw access to the inner `Map<TK, TV>` object.\n   * @public\n   */\n  protected readonly _inner: Map<TK, TV>;\n\n  /**\n   * Constructs a new {@link Collections.ResultMap | ResultMap}.\n   * @param iterable - An iterable to initialize the map.\n   */\n  public constructor(iterable?: Iterable<KeyValueEntry<TK, TV>>);\n\n  /**\n   * Constructs a new {@link Collections.ResultMap | ResultMap}.\n   * @param params - An optional set of parameters to configure the map.\n   */\n  public constructor(params: IResultMapConstructorParams);\n\n  /**\n   * Constructs a new {@link Collections.ResultMap | ResultMap}.\n   * @param iterableOrParams - An iterable to initialize the map, or a set of parameters\n   * to configure the map.\n   */\n  public constructor(\n    iterableOrParams?: Iterable<KeyValueEntry<TK, TV>> | IResultMapConstructorParams<TK, TV>\n  ) {\n    const params = isIterable(iterableOrParams) ? { entries: iterableOrParams } : iterableOrParams ?? {};\n    this._inner = new Map(params.entries);\n  }\n\n  /**\n   * Creates a new {@link Collections.ResultMap | ResultMap}.\n   * @param elements - An optional iterable to initialize the map.\n   * @returns `Success` with the new map, or `Failure` with error details\n   * if an error occurred.\n   * @public\n   */\n  public static create<TK extends string = string, TV = unknown>(\n    elements: Iterable<KeyValueEntry<TK, TV>>\n  ): Result<ResultMap<TK, TV>>;\n\n  /**\n   * Creates a new {@link Collections.ResultMap | ResultMap}.\n   * @param params - An optional set of parameters to configure the map.\n   * @returns `Success` with the new map, or `Failure` with error details\n   * if an error occurred.\n   * @public\n   */\n  public static create<TK extends string = string, TV = unknown>(\n    params?: IResultMapConstructorParams<TK, TV>\n  ): Result<ResultMap<TK, TV>>;\n\n  /**\n   * Creates a new {@link Collections.ResultMap | ResultMap}.\n   * @param elementsOrParams - An optional iterable to initialize the map, or a set of parameters\n   * to configure the map.\n   * @returns `Success` with the new map, or `Failure` with error details\n   * if an error occurred.\n   * @public\n   */\n  public static create<TK extends string = string, TV = unknown>(\n    elementsOrParams?: Iterable<KeyValueEntry<TK, TV>> | IResultMapConstructorParams<TK, TV>\n  ): Result<ResultMap<TK, TV>> {\n    return captureResult(() => new ResultMap(elementsOrParams as IResultMapConstructorParams<TK, TV>));\n  }\n\n  /**\n   * Sets a key/value pair in the map if the key does not already exist.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns `Success` with the value and detail `added` if the key was added,\n   * `Failure` with detail `exists` if the key already exists. Fails with detail\n   * 'invalid-key' or 'invalid-value' and an error message if either is invalid.\n   */\n  public add(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail> {\n    if (this._inner.has(key)) {\n      return failWithDetail(`${key}: already exists.`, 'exists');\n    }\n    this._inner.set(key, value);\n    return succeedWithDetail(value, 'added');\n  }\n\n  /**\n   * Clears the map.\n   */\n  public clear(): void {\n    this._inner.clear();\n  }\n\n  /**\n   * Deletes a key from the map.\n   * @param key - The key to delete.\n   * @returns `Success` with the previous value and the detail 'deleted'\n   * if the key was found and deleted, `Failure` with detail 'not-found'\n   * if the key was not found, or with detail 'invalid-key' if the key is invalid.\n   */\n  public delete(key: TK): DetailedResult<TV, ResultMapResultDetail> {\n    const was = this._inner.get(key);\n    if (this._inner.delete(key)) {\n      return succeedWithDetail(was!, 'deleted');\n    }\n    return failWithDetail(`${key}: not found.`, 'not-found');\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, TV>> {\n    return this._inner.entries();\n  }\n\n  /**\n   * Calls a function for each entry in the map.\n   * @param cb - The function to call for each entry.\n   * @param arg - An optional argument to pass to the callback.\n   */\n  public forEach(cb: ResultMapForEachCb<TK, TV>, arg?: unknown): void {\n    for (const [key, value] of this._inner.entries()) {\n      cb(value, key as TK, this, arg);\n    }\n  }\n\n  /**\n   * Gets a value from the map.\n   * @param key - The key to retrieve.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Failure` with detail `not-found` if the key was not found or with detail\n   * `invalid-key` if the key is invalid.\n   */\n  public get(key: TK): DetailedResult<TV, ResultMapResultDetail> {\n    if (this._inner.has(key)) {\n      return succeedWithDetail(this._inner.get(key)!, 'exists');\n    }\n    return failWithDetail(`${key}: not found.`, 'not-found');\n  }\n\n  /**\n   * Gets a value from the map, or adds a supplied value it if it does not exist.\n   * @param key - The key to be retrieved or created.\n   * @param value - The value to add if the key does not exist.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Success` with the value and detail `added` if the key was not found and added.\n   * Fails with detail 'invalid-key' or 'invalid-value' and an error message if either\n   * is invalid.\n   * {@label WITH_VALUE}\n   */\n  public getOrAdd(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map, or adds a value created by a factory function if it does not exist.\n   * @param key - The key of the element to be retrieved or created.\n   * @param factory - A {@link Collections.ResultMapValueFactory | factory function} to create the value if\n   * the key does not exist.\n   * @returns `Success` with the value and detail `exists` if the key was found, `Success` with\n   * the value and detail `added` if the key was not found and added. Fails with detail 'invalid-key'\n   * or 'invalid-value' and an error message if either is invalid.\n   * {@label WITH_FACTORY}\n   */\n  public getOrAdd(key: TK, factory: ResultMapValueFactory<TK, TV>): DetailedResult<TV, ResultMapResultDetail>;\n  public getOrAdd(\n    key: TK,\n    valueOrFactory: TV | ResultMapValueFactory<TK, TV>\n  ): DetailedResult<TV, ResultMapResultDetail> {\n    if (this._inner.has(key)) {\n      return succeedWithDetail(this._inner.get(key)!, 'exists');\n    }\n\n    const factory: ResultMapValueFactory<TK, TV> = this._isResultMapValueFactory(valueOrFactory)\n      ? valueOrFactory\n      : () => succeed(valueOrFactory);\n\n    return factory(key)\n      .onSuccess((val) => {\n        this._inner.set(key, val);\n        return succeedWithDetail(val, 'added');\n      })\n      .withDetail('invalid-value', 'added');\n  }\n\n  /**\n   * Returns `true` 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   * 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   * Sets a key/value pair in the map.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns `Success` with the new value and the detail `updated` if the\n   * key was found and updated, `Success` with the new value and detail\n   * `added` if the key was not found and added.  Fails with detail\n   * 'invalid-key' or 'invalid-value' and an error message if either is invalid.\n   */\n  public set(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail> {\n    const detail: ResultMapResultDetail = this._inner.has(key) ? 'updated' : 'added';\n    this._inner.set(key, value);\n    return succeedWithDetail(value, detail);\n  }\n\n  /**\n   * Returns the number of entries in the map.\n   */\n  public get size(): number {\n    return this._inner.size;\n  }\n\n  /**\n   * Updates an existing key in the map - the map is not updated if the key does\n   * not exist.\n   * @param key - The key to update.\n   * @param value - The value to set.\n   * @returns `Success` with the value and detail 'exists' if the key was found\n   * and the value updated, `Failure` an error message and with detail `not-found`\n   * if the key was not found, or with detail 'invalid-key' or 'invalid-value'\n   * if either is invalid.\n   */\n  public update(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail> {\n    if (this._inner.has(key)) {\n      this._inner.set(key, value);\n      return succeedWithDetail(value, 'updated');\n    }\n    return failWithDetail(`${key}: not found.`, 'not-found');\n  }\n\n  /**\n   * Returns an iterator over the map values.\n   * @returns An iterator over the map values.\n   */\n  public values(): IterableIterator<TV> {\n    return this._inner.values();\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, TV>> {\n    return this._inner[Symbol.iterator]();\n  }\n\n  /**\n   * Gets a readonly version of this map.\n   * @returns A readonly version of this map.\n   */\n  public toReadOnly(): IReadOnlyResultMap<TK, TV> {\n    return this;\n  }\n\n  /**\n   * Determines if a value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory}.\n   * @param value - The value to check.\n   * @returns `true` if the value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory},\n   * `false` otherwise.\n   * @public\n   */\n  protected _isResultMapValueFactory<TK extends string, TV>(\n    value: TV | ResultMapValueFactory<TK, TV>\n  ): value is ResultMapValueFactory<TK, TV> {\n    return typeof value === 'function';\n  }\n}\n"]}

package/dist/packlets/collections/resultMapValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultMapValidator.js","sourceRoot":"","sources":["../../../src/packlets/collections/resultMapValidator.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 { DetailedResult, failWithDetail, succeedWithDetail } from '../base';\nimport { IReadOnlyResultMap, ResultMapResultDetail } from './readonlyResultMap';\nimport { ResultMap, ResultMapValueFactory } from './resultMap';\nimport { KeyValueConverters } from './keyValueConverters';\n\n/**\n * A read-only interface exposing non-mutating methods of a {@link Collections.ResultMapValidator | ResultMapValidator}.\n * @public\n */\nexport interface IReadOnlyResultMapValidator<TK extends string = string, TV = unknown> {\n  /**\n   * {@inheritDoc Collections.ReadOnlyResultMapValidator.map}\n   */\n  readonly map: IReadOnlyResultMap<TK, TV>;\n\n  /**\n   * {@inheritDoc Collections.ResultMap.get}\n   */\n  get(key: string): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * {@inheritDoc Collections.ResultMap.has}\n   */\n  has(key: string): boolean;\n}\n\n/**\n * Parameters for constructing a {@link Collections.ResultMapValidator | ResultMapValidator}.\n * @public\n */\nexport interface IResultMapValidatorCreateParams<TK extends string = string, TV = unknown> {\n  map: ResultMap<TK, TV>;\n  converters: KeyValueConverters<TK, TV>;\n}\n\n/**\n * A read-only validator for any {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}\n * that validates weakly-typed keys before accessing values.\n * @public\n */\nexport class ReadOnlyResultMapValidator<TK extends string = string, TV = unknown>\n  implements IReadOnlyResultMapValidator<TK, TV>\n{\n  /**\n   * The key-value converters used for validation.\n   */\n  public readonly converters: KeyValueConverters<TK, TV>;\n\n  /**\n   * The underlying map.\n   */\n  public get map(): IReadOnlyResultMap<TK, TV> {\n    return this._map;\n  }\n\n  private readonly _map: IReadOnlyResultMap<TK, TV>;\n\n  /**\n   * Constructs a new {@link Collections.ReadOnlyResultMapValidator | ReadOnlyResultMapValidator}.\n   * @param map - The map to validate access to.\n   * @param converters - The key-value converters for validation.\n   */\n  public constructor(map: IReadOnlyResultMap<TK, TV>, converters: KeyValueConverters<TK, TV>) {\n    this._map = map;\n    this.converters = converters;\n  }\n\n  /**\n   * Gets a value from the map by key, validating the key first.\n   * @param key - The key to retrieve (will be validated).\n   * @returns `Success` with the value if found, `Failure` otherwise.\n   */\n  public get(key: string): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((validKey) => {\n      return this._map.get(validKey);\n    });\n  }\n\n  /**\n   * Checks if the map contains a key, validating the key first.\n   * @param key - The key to check (will be validated).\n   * @returns `true` if the key exists and is valid, `false` otherwise.\n   */\n  public has(key: string): boolean {\n    const result = this.converters.convertKey(key);\n    if (result.isFailure()) {\n      return false;\n    }\n    return this._map.has(result.value);\n  }\n}\n\n/**\n * A {@link Collections.ResultMap | ResultMap} wrapper which validates weakly-typed keys\n * before calling the wrapped result map.\n * @public\n */\nexport class ResultMapValidator<TK extends string = string, TV = unknown>\n  implements IReadOnlyResultMapValidator<TK, TV>\n{\n  public readonly converters: KeyValueConverters<TK, TV>;\n  public get map(): IReadOnlyResultMap<TK, TV> {\n    return this._map;\n  }\n\n  protected _map: ResultMap<TK, TV>;\n\n  /**\n   * Constructs a new {@link Collections.ResultMapValidator | ResultMapValidator}.\n   * @param params - Required parameters for constructing the result map validator.\n   */\n  public constructor(params: IResultMapValidatorCreateParams<TK, TV>) {\n    this._map = params.map;\n    this.converters = params.converters;\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.add}\n   */\n  public add(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.add(vk, vv);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.delete}\n   */\n  public delete(key: string): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((k) => {\n      return this._map.delete(k);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.get}\n   */\n  public get(key: string): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((k) => {\n      return this._map.get(k);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.getOrAdd}\n   */\n  public getOrAdd(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * {@inheritDoc Collections.ResultMap.getOrAdd}\n   */\n  public getOrAdd(\n    key: string,\n    factory: ResultMapValueFactory<TK, TV>\n  ): DetailedResult<TV, ResultMapResultDetail>;\n  public getOrAdd(\n    key: string,\n    valueOrFactory: unknown | ResultMapValueFactory<TK, TV>\n  ): DetailedResult<TV, ResultMapResultDetail> {\n    if (!this._isResultMapValueFactory(valueOrFactory)) {\n      return this.converters.convertEntry([key, valueOrFactory]).onSuccess(([vk, vv]) => {\n        return this._map.getOrAdd(vk, vv);\n      });\n    } else {\n      return this.converters.convertKey(key).onSuccess((k) => {\n        return this._map.get(k).onFailure(() => {\n          const value = valueOrFactory(k)\n            .onSuccess((value) => this.converters.convertEntry([k, value]))\n            .onSuccess(([__key, value]) => succeedWithDetail(value, 'added'));\n\n          return value.success\n            ? this._map.add(k, value.value)\n            : failWithDetail<TV, ResultMapResultDetail>(value.message, 'invalid-value');\n        });\n      });\n    }\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.has}\n   */\n  public has(key: string): boolean {\n    return this._map.has(key as TK);\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.set}\n   */\n  public set(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.set(vk, vv);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.update}\n   */\n  public update(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.update(vk, vv);\n    });\n  }\n\n  /**\n   * Gets a read-only version of this validator.\n   */\n  public toReadOnly(): IReadOnlyResultMapValidator<TK, TV> {\n    return this;\n  }\n\n  /**\n   * Determines if a value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory}.\n   * @param value - The value to check.\n   * @returns `true` if the value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory},\n   * `false` otherwise.\n   * @public\n   */\n  protected _isResultMapValueFactory<TK extends string, TV>(\n    value: TV | ResultMapValueFactory<TK, TV>\n  ): value is ResultMapValueFactory<TK, TV> {\n    return typeof value === 'function';\n  }\n}\n"]}