@fgv/ts-utils 5.1.0-2 → 5.1.0-20

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

@@ -0,0 +1 @@
+{"version":3,"file":"aggregatedResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/aggregatedResultMap.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 {\n  captureResult,\n  DetailedResult,\n  Result,\n  fail,\n  failWithDetail,\n  succeed,\n  succeedWithDetail,\n  Success\n} from '../base';\nimport { Converter, Converters } from '../conversion';\nimport { Validator, Validators } from '../validation';\nimport { KeyValueEntry } from './common';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { IReadOnlyResultMapValidator } from './resultMapValidator';\nimport { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';\nimport { IResultMap, ResultMapValueFactory } from './resultMap';\nimport { IReadOnlyValidatingResultMap, ValidatingResultMap } from './validatingResultMap';\n\n/**\n * A read-only collection entry in an {@link AggregatedResultMap | aggregated result map}.\n * @public\n */\nexport interface IReadonlyAggregatedResultMapEntry<\n  TCOLLECTIONID extends string = string,\n  TITEMID extends string = string,\n  TITEM = unknown,\n  TMETADATA = unknown\n> {\n  readonly isMutable: false;\n  readonly id: TCOLLECTIONID;\n  readonly items: IReadOnlyValidatingResultMap<TITEMID, TITEM>;\n  readonly metadata?: TMETADATA;\n}\n\n/**\n * A mutable collection entry in an {@link AggregatedResultMap | aggregated result map}.\n * @public\n */\nexport interface IMutableAggregatedResultMapEntry<\n  TCOLLECTIONID extends string = string,\n  TITEMID extends string = string,\n  TITEM = unknown,\n  TMETADATA = unknown\n> {\n  readonly isMutable: true;\n  readonly id: TCOLLECTIONID;\n  readonly items: ValidatingResultMap<TITEMID, TITEM>;\n  metadata?: TMETADATA;\n}\n\n/**\n * A collection entry in an {@link AggregatedResultMap | aggregated result map}, either mutable or read-only.\n * @public\n */\nexport type AggregatedResultMapEntry<\n  TCOLLECTIONID extends string,\n  TITEMID extends string,\n  TITEM,\n  TMETADATA = unknown\n> =\n  | IReadonlyAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  | IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>;\n\n/**\n * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry using an entries array.\n * @public\n */\nexport interface IAggregatedResultMapJsonEntryWithEntries<TCOLLECTIONID extends string = string> {\n  readonly isMutable: boolean;\n  readonly id: TCOLLECTIONID;\n  readonly entries: ReadonlyArray<KeyValueEntry<string, unknown>>;\n  readonly metadata?: unknown;\n}\n\n/**\n * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry using a string-keyed items object.\n * @public\n */\nexport interface IAggregatedResultMapJsonEntryWithItems<TCOLLECTIONID extends string = string> {\n  readonly isMutable: boolean;\n  readonly id: TCOLLECTIONID;\n  readonly items: Record<string, unknown>;\n  readonly metadata?: unknown;\n}\n\n/**\n * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry - supports both entries array and items object.\n * @public\n */\nexport type AggregatedResultMapJsonEntry<TCOLLECTIONID extends string = string> =\n  | IAggregatedResultMapJsonEntryWithEntries<TCOLLECTIONID>\n  | IAggregatedResultMapJsonEntryWithItems<TCOLLECTIONID>;\n\n/**\n * Any valid input format for an {@link AggregatedResultMap | aggregated result map} collection entry.\n * @public\n */\nexport type AggregatedResultMapEntryInit<\n  TCOLLECTIONID extends string,\n  TITEMID extends string,\n  TITEM,\n  TMETADATA = unknown\n> =\n  | AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  | AggregatedResultMapJsonEntry<TCOLLECTIONID>;\n\n/**\n * Options for {@link Collections.AggregatedResultMapBase.addCollectionWithItems | addCollectionWithItems}.\n * @public\n */\nexport interface IAddCollectionWithItemsOptions<TMETADATA = unknown> {\n  /**\n   * If true, the collection will be immutable (read-only).\n   * Defaults to false (mutable).\n   */\n  readonly isImmutable?: boolean;\n\n  /**\n   * Optional metadata to attach to the collection.\n   */\n  readonly metadata?: TMETADATA;\n}\n\n/**\n * Parameters for constructing an {@link AggregatedResultMap | aggregated result map}.\n * @public\n */\nexport interface IAggregatedResultMapConstructorParams<\n  TCOMPOSITEID extends string,\n  TCOLLECTIONID extends string,\n  TITEMID extends string,\n  TITEM,\n  TMETADATA = unknown\n> {\n  /**\n   * Validator for composite IDs.\n   */\n  readonly compositeIdValidator?: Validator<TCOMPOSITEID, unknown>;\n  /**\n   * Converter or validator for collection IDs.\n   */\n  readonly collectionIdConverter: Converter<TCOLLECTIONID, unknown> | Validator<TCOLLECTIONID, unknown>;\n  /**\n   * Converter or validator for item IDs.\n   */\n  readonly itemIdConverter: Converter<TITEMID, unknown> | Validator<TITEMID, unknown>;\n  /**\n   * Converter or validator for individual items in each collection.\n   */\n  readonly itemConverter: Converter<TITEM, unknown> | Validator<TITEM, unknown>;\n  /**\n   * Optional converter or validator for collection metadata.  If not provided, a metadata field\n   * in the input will cause a validation failure.\n   */\n  readonly metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>;\n\n  /**\n   * Optional separator string for composite IDs.  Defaults to `.`.\n   */\n  readonly separator?: string;\n\n  /**\n   * Initial collections to populate the map.\n   * @remarks Each entry may be mutable or read-only.\n   */\n  readonly collections?: ReadonlyArray<\n    AggregatedResultMapEntryInit<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  >;\n}\n\n/**\n * A validator for weakly-typed access to an {@link AggregatedResultMap | aggregated result map}.\n * @public\n */\nexport class AggregatedResultMapValidator<\n  TCOMPOSITEID extends string,\n  TCOLLECTIONID extends string,\n  TITEMID extends string,\n  TITEM,\n  TMETADATA = unknown\n> implements IReadOnlyResultMapValidator<TCOMPOSITEID, TITEM>\n{\n  private readonly _map: AggregatedResultMap<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>;\n\n  /**\n   * The key-value converters used for validating weakly-typed access.\n   */\n  public readonly converters: KeyValueConverters<TCOMPOSITEID, TITEM>;\n\n  /**\n   * Constructs a new {@link AggregatedResultMapValidator | aggregated result map validator}.\n   * @param map - The {@link AggregatedResultMap | aggregated result map} being validated.\n   * @param converters - The key-value converters for weakly-typed access.\n   */\n  public constructor(\n    map: AggregatedResultMap<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>,\n    converters: KeyValueConverters<TCOMPOSITEID, TITEM>\n  ) {\n    this._map = map;\n    this.converters = converters;\n  }\n\n  /** {@inheritDoc Collections.ResultMapValidator.map} */\n  public get map(): IReadOnlyValidatingResultMap<TCOMPOSITEID, TITEM> {\n    return this._map;\n  }\n\n  /** {@inheritDoc Collections.ResultMapValidator.get} */\n  public get(key: string): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((k) => {\n      return this._map.get(k);\n    });\n  }\n\n  /** {@inheritDoc Collections.ResultMapValidator.has} */\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  /** {@inheritDoc Collections.ResultMapValidator.add} */\n  public add(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.add(vk, vv);\n    });\n  }\n\n  /** {@inheritDoc Collections.ResultMapValidator.set} */\n  public set(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.set(vk, vv);\n    });\n  }\n\n  /** {@inheritDoc Collections.ResultMapValidator.update} */\n  public update(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.update(vk, vv);\n    });\n  }\n\n  /** {@inheritDoc Collections.ResultMapValidator.delete} */\n  public delete(key: string): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((k) => {\n      return this._map.delete(k);\n    });\n  }\n}\n\n/**\n * Type guard to check if an {@link AggregatedResultMapEntry | aggregated result map entry} is mutable.\n */\nfunction isMutableEntry<TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA>(\n  entry: AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n): entry is IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA> {\n  return entry.isMutable === true;\n}\n\n/**\n * Base class for an aggregated result map that wraps a collection of {@link ValidatingResultMap} instances,\n * keyed by collection ID. Items are accessed via composite IDs that combine the collection ID\n * and item ID with a delimiter.\n * @remarks Consumers should inherit from this class or use {@link AggregatedResultMap | AggregatedResultMap}\n * for fully generic.\n * @public\n */\nexport class AggregatedResultMapBase<\n  TCOMPOSITEID extends string,\n  TCOLLECTIONID extends string,\n  TITEMID extends string,\n  TITEM,\n  TMETADATA = unknown\n> implements IResultMap<TCOMPOSITEID, TITEM>, IReadOnlyValidatingResultMap<TCOMPOSITEID, TITEM>\n{\n  private readonly _childKvConverters: KeyValueConverters<TITEMID, TITEM>;\n  private readonly _collections: ValidatingResultMap<\n    TCOLLECTIONID,\n    AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  >;\n  private readonly _collectionKvConverters: KeyValueConverters<\n    TCOLLECTIONID,\n    AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  >;\n  private readonly _compositeIdValidator: Validator<TCOMPOSITEID, unknown>;\n  private readonly _collectionIdConverter:\n    | Converter<TCOLLECTIONID, unknown>\n    | Validator<TCOLLECTIONID, unknown>;\n  private readonly _itemIdConverter: Converter<TITEMID, unknown> | Validator<TITEMID, unknown>;\n  private readonly _itemConverter: Converter<TITEM, unknown> | Validator<TITEM, unknown>;\n  private readonly _metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>;\n  private readonly _delimiter: string;\n  private readonly _compositeIdConverter: Converter<Converters.ICompositeId<TCOLLECTIONID, TITEMID>, unknown>;\n  private readonly _kvConverters: KeyValueConverters<TCOMPOSITEID, TITEM>;\n  private readonly _validating: AggregatedResultMapValidator<\n    TCOMPOSITEID,\n    TCOLLECTIONID,\n    TITEMID,\n    TITEM,\n    TMETADATA\n  >;\n\n  /**\n   * Protected constructor for derived classes.\n   * Use the {@link AggregatedResultMap.create | create static method} for safe construction with error handling.\n   * @param params - {@link IAggregatedResultMapConstructorParams | Parameters} for constructing the map.\n   * @throws If initialization fails (e.g., invalid collections).\n   * @public\n   */\n  protected constructor(\n    params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  ) {\n    this._compositeIdValidator =\n      params.compositeIdValidator ?? AggregatedResultMapBase._compositeIdValidator(params);\n    this._collectionIdConverter = params.collectionIdConverter;\n    this._itemIdConverter = params.itemIdConverter;\n    this._itemConverter = params.itemConverter;\n    this._metadataConverter = params.metadataConverter;\n    this._delimiter = params.separator ?? '.';\n\n    // Build child key-value converters for item ID/value pairs\n    this._childKvConverters = new KeyValueConverters<TITEMID, TITEM>({\n      key: params.itemIdConverter,\n      value: params.itemConverter\n    });\n\n    // Build composite ID converter for parsing composite IDs\n    this._compositeIdConverter = Converters.compositeId(\n      params.collectionIdConverter,\n      this._delimiter,\n      params.itemIdConverter\n    );\n\n    // Build key-value converters for composite ID/item pairs\n    this._kvConverters = new KeyValueConverters<TCOMPOSITEID, TITEM>({\n      key: this._compositeIdValidator,\n      value: params.itemConverter\n    });\n\n    // Build entry converter for collection entries\n    const entryConverter = AggregatedResultMapBase._entryConverter<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>(\n      params.collectionIdConverter,\n      this._childKvConverters,\n      params.metadataConverter\n    );\n\n    // Build key-value converters for the collections map\n    this._collectionKvConverters = new KeyValueConverters<\n      TCOLLECTIONID,\n      AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n    >({\n      key: params.collectionIdConverter,\n      value: entryConverter\n    });\n\n    // Convert all input collections to [id, entry] pairs for ValidatingResultMap\n    const initCollections = params.collections ?? [];\n    const initEntries: KeyValueEntry<string, unknown>[] = initCollections.map((entry) => {\n      return [entry.id, entry];\n    });\n\n    // Build the inner ValidatingResultMap - throws on error\n    this._collections = new ValidatingResultMap<\n      TCOLLECTIONID,\n      AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n    >({\n      converters: this._collectionKvConverters,\n      entries: initEntries\n    });\n\n    // Build the validator\n    this._validating = new AggregatedResultMapValidator<\n      TCOMPOSITEID,\n      TCOLLECTIONID,\n      TITEMID,\n      TITEM,\n      TMETADATA\n    >(this, this._kvConverters);\n  }\n\n  // ==================== IReadOnlyValidatingResultMap implementation ====================\n\n  /**\n   * A validator for weakly-typed access to the map.\n   */\n  public get validating(): IReadOnlyResultMapValidator<TCOMPOSITEID, TITEM> {\n    return this._validating;\n  }\n\n  /**\n   * The total number of items across all collections.\n   */\n  public get size(): number {\n    let total = 0;\n    for (const entry of Array.from(this._collections.values())) {\n      total += entry.items.size;\n    }\n    return total;\n  }\n\n  /**\n   * Gets an item by its composite ID.\n   * @param key - The composite ID of the item.\n   * @returns `Success` with the item if found, `Failure` otherwise.\n   */\n  public get(key: TCOMPOSITEID): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this._splitAndLookup(key).onSuccess(({ entry, itemId }) => {\n      return entry.items.get(itemId);\n    });\n  }\n\n  /**\n   * Checks if an item exists by its composite ID.\n   * @param key - The composite ID of the item.\n   * @returns `true` if the item exists, `false` otherwise.\n   */\n  public has(key: TCOMPOSITEID): boolean {\n    const result = this._splitAndLookup(key);\n    if (result.isFailure()) {\n      return false;\n    }\n    return result.value.entry.items.has(result.value.itemId);\n  }\n\n  /**\n   * Iterates over all entries in all collections.\n   */\n  public *entries(): IterableIterator<KeyValueEntry<TCOMPOSITEID, TITEM>> {\n    for (const collectionEntry of Array.from(this._collections.values())) {\n      for (const [itemId, item] of Array.from(collectionEntry.items.entries())) {\n        // Validate the composite ID through the converter\n        const compositeId = this._compositeIdValidator\n          .convert(`${collectionEntry.id}${this._delimiter}${itemId}`)\n          .orThrow();\n        yield [compositeId, item];\n      }\n    }\n  }\n\n  /**\n   * Iterates over all composite keys.\n   */\n  public *keys(): IterableIterator<TCOMPOSITEID> {\n    for (const [key] of Array.from(this.entries())) {\n      yield key;\n    }\n  }\n\n  /**\n   * Iterates over all values.\n   */\n  public *values(): IterableIterator<TITEM> {\n    for (const collectionEntry of Array.from(this._collections.values())) {\n      for (const value of Array.from(collectionEntry.items.values())) {\n        yield value;\n      }\n    }\n  }\n\n  /**\n   * Calls a callback for each entry.\n   * @param cb - The callback to call.\n   * @param thisArg - Optional `this` argument for the callback.\n   */\n  public forEach(cb: ResultMapForEachCb<TCOMPOSITEID, TITEM>, thisArg?: unknown): void {\n    for (const [key, value] of Array.from(this.entries())) {\n      cb.call(thisArg, value, key, this);\n    }\n  }\n\n  /**\n   * Gets an iterator over the map entries.\n   */\n  public [Symbol.iterator](): IterableIterator<KeyValueEntry<TCOMPOSITEID, TITEM>> {\n    return this.entries();\n  }\n\n  // ==================== Mutating methods ====================\n\n  /**\n   * Sets an item by its composite ID. Creates the collection if it doesn't exist and is mutable.\n   * @param key - The composite ID of the item.\n   * @param value - The value to set.\n   * @returns `Success` with the value if set, `Failure` otherwise.\n   */\n  public set(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this._splitCompositeId(key).onSuccess(({ collectionId, itemId }) => {\n      return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {\n        return collection.set(itemId, value);\n      });\n    });\n  }\n\n  /**\n   * Adds an item by its composite ID. Fails if the item already exists.\n   * @param key - The composite ID of the item.\n   * @param value - The value to add.\n   * @returns `Success` with the value if added, `Failure` otherwise.\n   */\n  public add(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this._splitCompositeId(key).onSuccess(({ collectionId, itemId }) => {\n      return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {\n        return collection.add(itemId, value);\n      });\n    });\n  }\n\n  /**\n   * Updates an existing item by its composite ID. Fails if the item doesn't exist.\n   * @param key - The composite ID of the item.\n   * @param value - The new value.\n   * @returns `Success` with the value if updated, `Failure` otherwise.\n   */\n  public update(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this._splitAndLookupMutable(key).onSuccess(({ entry, itemId }) => {\n      return entry.items.update(itemId, value);\n    });\n  }\n\n  /**\n   * Deletes an item by its composite ID.\n   * @param key - The composite ID of the item.\n   * @returns `Success` with the deleted value, `Failure` otherwise.\n   */\n  public delete(key: TCOMPOSITEID): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this._splitAndLookupMutable(key).onSuccess(({ entry, itemId }) => {\n      return entry.items.delete(itemId);\n    });\n  }\n\n  /**\n   * Gets an existing item or adds a new one.\n   * @param key - The composite ID of the item.\n   * @param value - The value to add if not found.\n   * @returns `Success` with the existing or new value.\n   */\n  public getOrAdd(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;\n\n  /**\n   * Gets an existing item or adds a new one using a factory.\n   * @param key - The composite ID of the item.\n   * @param factory - A factory function to create the value if not found. Receives the composite ID.\n   * @returns `Success` with the existing or new value.\n   */\n  public getOrAdd(\n    key: TCOMPOSITEID,\n    factory: ResultMapValueFactory<TCOMPOSITEID, TITEM>\n  ): DetailedResult<TITEM, ResultMapResultDetail>;\n\n  public getOrAdd(\n    key: TCOMPOSITEID,\n    valueOrFactory: TITEM | ResultMapValueFactory<TCOMPOSITEID, TITEM>\n  ): DetailedResult<TITEM, ResultMapResultDetail> {\n    return this._splitCompositeId(key).onSuccess(({ collectionId, itemId }) => {\n      return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {\n        // Use type guard to check if valueOrFactory is a factory function\n        if (this._isFactory(valueOrFactory)) {\n          return collection.getOrAdd(itemId, () => valueOrFactory(key));\n        }\n        return collection.getOrAdd(itemId, valueOrFactory);\n      });\n    });\n  }\n\n  /**\n   * Clears all items from all mutable collections.\n   * Immutable collections are not affected.\n   */\n  public clear(): void {\n    for (const entry of Array.from(this._collections.values())) {\n      if (isMutableEntry(entry)) {\n        entry.items.clear();\n      }\n    }\n  }\n\n  /**\n   * Returns a read-only view of this map.\n   */\n  public toReadOnly(): IReadOnlyResultMap<TCOMPOSITEID, TITEM> {\n    return this;\n  }\n\n  // ==================== Convenience methods for split IDs ====================\n\n  /**\n   * Composes a collection ID and item ID into a composite ID.\n   * @param collectionId - The collection ID.\n   * @param itemId - The item ID.\n   * @returns `Success` with the composite ID if valid, `Failure` otherwise.\n   */\n  public composeId(collectionId: TCOLLECTIONID, itemId: TITEMID): Result<TCOMPOSITEID> {\n    const rawId = `${collectionId}${this._delimiter}${itemId}`;\n    return this._compositeIdValidator.convert(rawId);\n  }\n\n  /**\n   * Adds an item using separate collection and item IDs.\n   * @param collectionId - The collection ID.\n   * @param itemId - The item ID.\n   * @param value - The value to add.\n   * @returns `Success` with the composite ID if added, `Failure` otherwise.\n   */\n  public addToCollection(\n    collectionId: TCOLLECTIONID,\n    itemId: TITEMID,\n    value: TITEM\n  ): DetailedResult<TCOMPOSITEID, ResultMapResultDetail> {\n    return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {\n      return collection.add(itemId, value).onSuccess(() => {\n        return this.composeId(collectionId, itemId).withDetail('invalid-key', 'added');\n      });\n    });\n  }\n\n  /**\n   * Sets an item using separate collection and item IDs.\n   * @param collectionId - The collection ID.\n   * @param itemId - The item ID.\n   * @param value - The value to set.\n   * @returns `Success` with the composite ID if set, `Failure` otherwise.\n   */\n  public setInCollection(\n    collectionId: TCOLLECTIONID,\n    itemId: TITEMID,\n    value: TITEM\n  ): DetailedResult<TCOMPOSITEID, ResultMapResultDetail> {\n    return this._getOrCreateMutableCollection(collectionId).onSuccess((collection) => {\n      return collection.set(itemId, value).onSuccess((_, detail) => {\n        return this.composeId(collectionId, itemId).withDetail('invalid-key', detail);\n      });\n    });\n  }\n\n  /**\n   * Updates an item using separate collection and item IDs.\n   * @param collectionId - The collection ID.\n   * @param itemId - The item ID.\n   * @param value - The new value.\n   * @returns `Success` with the composite ID if updated, `Failure` otherwise.\n   */\n  public updateInCollection(\n    collectionId: TCOLLECTIONID,\n    itemId: TITEMID,\n    value: TITEM\n  ): DetailedResult<TCOMPOSITEID, ResultMapResultDetail> {\n    return this._getMutableCollection(collectionId).onSuccess((collection) => {\n      return collection.update(itemId, value).onSuccess(() => {\n        return this.composeId(collectionId, itemId).withDetail('invalid-key', 'updated');\n      });\n    });\n  }\n\n  /**\n   * Deletes an item using separate collection and item IDs.\n   * @param collectionId - The collection ID.\n   * @param itemId - The item ID.\n   * @returns `Success` with the composite ID if deleted, `Failure` otherwise.\n   */\n  public deleteFromCollection(\n    collectionId: TCOLLECTIONID,\n    itemId: TITEMID\n  ): DetailedResult<TCOMPOSITEID, ResultMapResultDetail> {\n    return this._getMutableCollection(collectionId).onSuccess((collection) => {\n      return collection.delete(itemId).onSuccess(() => {\n        return this.composeId(collectionId, itemId).withDetail('invalid-key', 'deleted');\n      });\n    });\n  }\n\n  // ==================== Collection-level methods ====================\n\n  /**\n   * Provides read-only access to the underlying collections map.\n   * Use `collections.has(id)` and `collections.get(id)` to check existence and retrieve collections.\n   */\n  public get collections(): IReadOnlyValidatingResultMap<\n    TCOLLECTIONID,\n    AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  > {\n    return this._collections;\n  }\n\n  /**\n   * The number of collections.\n   */\n  public get collectionCount(): number {\n    return this._collections.size;\n  }\n\n  /**\n   * Gets the metadata for a specific collection.\n   * @param collectionId - The collection ID.\n   * @returns `Success` with the metadata if found, `Failure` otherwise.\n   */\n  public getCollectionMetadata(collectionId: TCOLLECTIONID): Result<TMETADATA | undefined> {\n    return this._collections.get(collectionId).asResult.onSuccess((entry) => {\n      return succeed(entry.metadata);\n    });\n  }\n\n  /**\n   * Sets the metadata for a mutable collection.\n   * @param collectionId - The collection ID.\n   * @param metadata - The metadata to set.\n   * @returns `Success` if set, `Failure` otherwise.\n   */\n  public setCollectionMetadata(collectionId: TCOLLECTIONID, metadata: TMETADATA): Result<TMETADATA> {\n    return this._collections.get(collectionId).asResult.onSuccess((entry) => {\n      if (!isMutableEntry(entry)) {\n        return fail(`Cannot modify metadata of immutable collection '${collectionId}'`);\n      }\n      entry.metadata = metadata;\n      return succeed(metadata);\n    });\n  }\n\n  /**\n   * Adds a new collection from a pre-built entry object.\n   * @param entry - The collection entry to add (JSON with items/entries, or pre-instantiated).\n   * @returns `Success` with the entry if added, `Failure` otherwise.\n   */\n  public addCollectionEntry(\n    entry: AggregatedResultMapEntryInit<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  ): DetailedResult<\n    AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>,\n    ResultMapResultDetail\n  > {\n    return AggregatedResultMapBase._entryConverter<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>(\n      this._collectionIdConverter,\n      this._childKvConverters,\n      this._metadataConverter\n    )\n      .convert(entry)\n      .withFailureDetail<ResultMapResultDetail>('invalid-value')\n      .onSuccess((c) => this._collections.add(c.id, c));\n  }\n\n  /**\n   * Adds a new collection with the specified ID and optional initial entries.\n   * @param collectionId - The collection ID as a string (will be validated).\n   * @param items - Optional initial entries for the collection.\n   * @param options - Optional settings (isImmutable defaults to false).\n   * @returns `Success` with the validated collection ID if added, `Failure` otherwise.\n   */\n  public addCollectionWithItems(\n    collectionId: string,\n    items?: Iterable<KeyValueEntry<string, unknown>>,\n    options?: IAddCollectionWithItemsOptions<TMETADATA>\n  ): Result<TCOLLECTIONID> {\n    const isMutable = options?.isImmutable !== true;\n    const entries = items ? Array.from(items) : [];\n    return this._collectionIdConverter\n      .convert(collectionId)\n      .onSuccess((id) =>\n        this.addCollectionEntry({ isMutable, id, entries, metadata: options?.metadata }).asResult.onSuccess(\n          () => Success.with(id)\n        )\n      );\n  }\n\n  // ==================== Protected helpers ====================\n\n  /**\n   * Deletes a collection from the internal collections map.\n   * This is a protected method for use by derived classes that need to implement\n   * collection deletion functionality.\n   *\n   * @param collectionId - The collection ID to delete.\n   * @returns `Success` with the deleted entry if found, `Failure` otherwise.\n   * @remarks\n   * - Does NOT check if the collection is mutable - callers should validate this first.\n   * - Use `collections.get(id)` to check if a collection exists and its mutability before calling.\n   */\n  protected _deleteCollection(\n    collectionId: TCOLLECTIONID\n  ): DetailedResult<\n    AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>,\n    ResultMapResultDetail\n  > {\n    // ValidatingResultMap extends ResultMap which has delete method\n    return this._collections.delete(collectionId);\n  }\n\n  // ==================== Private helpers ====================\n\n  /**\n   * Type guard to check if a value is a factory function.\n   */\n  private _isFactory(\n    valueOrFactory: TITEM | ResultMapValueFactory<TCOMPOSITEID, TITEM>\n  ): valueOrFactory is ResultMapValueFactory<TCOMPOSITEID, TITEM> {\n    return typeof valueOrFactory === 'function';\n  }\n\n  private _splitCompositeId(\n    key: TCOMPOSITEID\n  ): DetailedResult<Converters.ICompositeId<TCOLLECTIONID, TITEMID>, ResultMapResultDetail> {\n    return this._compositeIdConverter.convert(key).withDetail('invalid-key', 'success');\n  }\n\n  private _splitAndLookup(\n    key: TCOMPOSITEID\n  ): DetailedResult<\n    { entry: AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>; itemId: TITEMID },\n    ResultMapResultDetail\n  > {\n    return this._splitCompositeId(key).onSuccess(({ collectionId, itemId }) => {\n      return this._collections.get(collectionId).onSuccess((entry) => {\n        return succeedWithDetail({ entry, itemId }, 'success');\n      });\n    });\n  }\n\n  private _splitAndLookupMutable(\n    key: TCOMPOSITEID\n  ): DetailedResult<\n    { entry: IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>; itemId: TITEMID },\n    ResultMapResultDetail\n  > {\n    return this._splitAndLookup(key).onSuccess(({ entry, itemId }) => {\n      if (!isMutableEntry(entry)) {\n        return failWithDetail(`Cannot modify immutable collection '${entry.id}'`, 'failure');\n      }\n      return succeedWithDetail({ entry, itemId }, 'success');\n    });\n  }\n\n  /**\n   * Gets an existing mutable collection by ID.\n   * Returns failure if the collection doesn't exist or is immutable.\n   */\n  private _getMutableCollection(\n    collectionId: TCOLLECTIONID\n  ): DetailedResult<ValidatingResultMap<TITEMID, TITEM>, ResultMapResultDetail> {\n    return this._collections.get(collectionId).onSuccess((entry) => {\n      if (!isMutableEntry(entry)) {\n        return failWithDetail(`Cannot modify immutable collection '${collectionId}'`, 'failure');\n      }\n      return succeedWithDetail(entry.items, 'exists');\n    });\n  }\n\n  /**\n   * Gets an existing mutable collection or creates a new one.\n   */\n  private _getOrCreateMutableCollection(\n    collectionId: TCOLLECTIONID\n  ): DetailedResult<ValidatingResultMap<TITEMID, TITEM>, ResultMapResultDetail> {\n    const existing = this._collections.get(collectionId);\n    if (existing.isSuccess()) {\n      if (!isMutableEntry(existing.value)) {\n        return failWithDetail(`Cannot modify immutable collection '${collectionId}'`, 'failure');\n      }\n      return succeedWithDetail(existing.value.items, 'exists');\n    }\n\n    // Create a new mutable collection\n    const newItems = new ValidatingResultMap<TITEMID, TITEM>({\n      converters: this._childKvConverters\n    });\n    const newEntry: IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA> = {\n      isMutable: true,\n      id: collectionId,\n      items: newItems\n    };\n    return this._collections.add(collectionId, newEntry).onSuccess(() => {\n      return succeedWithDetail(newItems, 'added');\n    });\n  }\n\n  // ==================== Static converter factories ====================\n\n  /**\n   * Constructs a composite id validator using other converters/validators and separator supplied in params.\n   * @param params - Constructor params.\n   * @returns The composite ID validator.\n   */\n  private static _compositeIdValidator<\n    TCOMPOSITEID extends string,\n    TCOLLECTIONID extends string,\n    TITEMID extends string,\n    TITEM,\n    TMETADATA = unknown\n  >(\n    params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  ): Validator<TCOMPOSITEID, unknown> {\n    return Validators.compositeId<TCOMPOSITEID, TCOLLECTIONID, TITEMID>({\n      collectionId: Converters.asValidator(params.collectionIdConverter),\n      separator: params.separator ?? '.',\n      itemId: Converters.asValidator(params.itemIdConverter)\n    });\n  }\n\n  /**\n   * Converts metadata from source, failing fast if metadata is present but no converter is configured.\n   * @param sourceMetadata - The metadata from the source (may be undefined).\n   * @param metadataConverter - Optional converter for metadata.\n   * @returns Success with converted metadata (or undefined), or Failure if metadata is present but disallowed.\n   */\n  private static _convertMetadata<TMETADATA>(\n    sourceMetadata: unknown,\n    metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>\n  ): Result<TMETADATA | undefined> {\n    if (sourceMetadata === undefined) {\n      return succeed(undefined);\n    }\n    if (!metadataConverter) {\n      return fail('metadata is not allowed when no metadataConverter is configured');\n    }\n    return metadataConverter.convert(sourceMetadata);\n  }\n\n  /**\n   * Extracts metadata from a source object if present.\n   */\n  private static _extractSourceMetadata(from: unknown): unknown {\n    return typeof from === 'object' && from !== null && 'metadata' in from ? from.metadata : undefined;\n  }\n\n  /**\n   * Creates a converter for pre-instantiated mutable entries.\n   * These are entries that already have a ValidatingResultMap as their items property.\n   */\n  private static _instantiatedMutableConverter<\n    TCOLLECTIONID extends string,\n    TITEMID extends string,\n    TITEM,\n    TMETADATA = unknown\n  >(\n    collectionIdConverter: Converter<TCOLLECTIONID, unknown> | Validator<TCOLLECTIONID, unknown>,\n    metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>\n  ): Converter<IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, unknown> {\n    const baseConverter = Converters.strictObject<{\n      isMutable: true;\n      id: TCOLLECTIONID;\n      items: ValidatingResultMap<TITEMID, TITEM>;\n    }>({\n      isMutable: Converters.literal(true),\n      id: collectionIdConverter,\n      items: Converters.isA<ValidatingResultMap<TITEMID, TITEM>>(\n        'ValidatingResultMap',\n        (t) => t instanceof ValidatingResultMap\n      )\n    });\n\n    return Converters.generic<\n      IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>,\n      unknown\n    >((from) => {\n      return baseConverter.convert(from).onSuccess((base) => {\n        const sourceMetadata = AggregatedResultMapBase._extractSourceMetadata(from);\n        return AggregatedResultMapBase._convertMetadata(sourceMetadata, metadataConverter).onSuccess(\n          (metadata) => {\n            const entry: IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA> = {\n              isMutable: true,\n              id: base.id,\n              items: base.items,\n              metadata\n            };\n            return succeed(entry);\n          }\n        );\n      });\n    });\n  }\n\n  /**\n   * Creates a converter for pre-instantiated read-only entries.\n   * These are entries that already have an IReadOnlyValidatingResultMap as their items property.\n   */\n  private static _instantiatedReadonlyConverter<\n    TCOLLECTIONID extends string,\n    TITEMID extends string,\n    TITEM,\n    TMETADATA = unknown\n  >(\n    collectionIdConverter: Converter<TCOLLECTIONID, unknown> | Validator<TCOLLECTIONID, unknown>,\n    metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>\n  ): Converter<IReadonlyAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, unknown> {\n    const baseConverter = Converters.strictObject<{\n      isMutable: false;\n      id: TCOLLECTIONID;\n      items: IReadOnlyValidatingResultMap<TITEMID, TITEM>;\n    }>({\n      isMutable: Converters.literal(false),\n      id: collectionIdConverter,\n      items: Converters.isA<IReadOnlyValidatingResultMap<TITEMID, TITEM>>(\n        'IReadOnlyValidatingResultMap',\n        (t) => t instanceof ValidatingResultMap\n      )\n    });\n\n    return Converters.generic<\n      IReadonlyAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>,\n      unknown\n    >((from) => {\n      return baseConverter.convert(from).onSuccess((base) => {\n        const sourceMetadata = AggregatedResultMapBase._extractSourceMetadata(from);\n        return AggregatedResultMapBase._convertMetadata(sourceMetadata, metadataConverter).onSuccess(\n          (metadata) => {\n            const entry: IReadonlyAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA> = {\n              isMutable: false,\n              id: base.id,\n              items: base.items,\n              metadata\n            };\n            return succeed(entry);\n          }\n        );\n      });\n    });\n  }\n\n  /**\n   * Creates a converter for JSON entries with an entries array.\n   * Converts the entries array to a ValidatingResultMap.\n   */\n  private static _jsonWithEntriesConverter<\n    TCOLLECTIONID extends string,\n    TITEMID extends string,\n    TITEM,\n    TMETADATA = unknown\n  >(\n    collectionIdConverter: Converter<TCOLLECTIONID, unknown> | Validator<TCOLLECTIONID, unknown>,\n    childKvConverters: KeyValueConverters<TITEMID, TITEM>,\n    metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>\n  ): Converter<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, unknown> {\n    const entriesArrayConverter = Converters.isA<KeyValueEntry<string, unknown>[]>(\n      'entries array',\n      (t): t is KeyValueEntry<string, unknown>[] =>\n        Array.isArray(t) && t.every((item) => Array.isArray(item) && item.length === 2)\n    );\n\n    const baseConverter = Converters.object<{\n      isMutable: boolean;\n      id: TCOLLECTIONID;\n      entries: KeyValueEntry<string, unknown>[];\n    }>({\n      isMutable: Converters.boolean,\n      id: collectionIdConverter,\n      entries: entriesArrayConverter\n    });\n\n    return Converters.generic<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>((from) => {\n      return baseConverter.convert(from).onSuccess((json) => {\n        const sourceMetadata = AggregatedResultMapBase._extractSourceMetadata(from);\n\n        return childKvConverters.convertEntries(json.entries).onSuccess((convertedEntries) => {\n          const items = new ValidatingResultMap<TITEMID, TITEM>({\n            converters: childKvConverters,\n            entries: convertedEntries\n          });\n          return AggregatedResultMapBase._convertMetadata(sourceMetadata, metadataConverter).onSuccess(\n            (metadata) => {\n              if (json.isMutable) {\n                return succeed<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>({\n                  isMutable: true,\n                  id: json.id,\n                  items,\n                  metadata\n                });\n              }\n              return succeed<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>({\n                isMutable: false,\n                id: json.id,\n                items: items.toReadOnly(),\n                metadata\n              });\n            }\n          );\n        });\n      });\n    });\n  }\n\n  /**\n   * Creates a converter for JSON entries with an items object.\n   * Converts the items object to a ValidatingResultMap.\n   */\n  private static _jsonWithItemsConverter<\n    TCOLLECTIONID extends string,\n    TITEMID extends string,\n    TITEM,\n    TMETADATA = unknown\n  >(\n    collectionIdConverter: Converter<TCOLLECTIONID, unknown> | Validator<TCOLLECTIONID, unknown>,\n    childKvConverters: KeyValueConverters<TITEMID, TITEM>,\n    metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>\n  ): Converter<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, unknown> {\n    const baseConverter = Converters.object<{\n      isMutable: boolean;\n      id: TCOLLECTIONID;\n      items: Record<string, unknown>;\n    }>({\n      isMutable: Converters.boolean,\n      id: collectionIdConverter,\n      items: Converters.generic<Record<string, unknown>>((from) => {\n        if (typeof from === 'object' && from !== null && !Array.isArray(from)) {\n          return succeed(from as Record<string, unknown>);\n        }\n        return fail('expected an object');\n      })\n    });\n\n    return Converters.generic<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>((from) => {\n      return baseConverter.convert(from).onSuccess((json) => {\n        const sourceMetadata = AggregatedResultMapBase._extractSourceMetadata(from);\n        const entries = Object.entries(json.items) as KeyValueEntry<string, unknown>[];\n\n        return childKvConverters.convertEntries(entries).onSuccess((convertedEntries) => {\n          const items = new ValidatingResultMap<TITEMID, TITEM>({\n            converters: childKvConverters,\n            entries: convertedEntries\n          });\n          return AggregatedResultMapBase._convertMetadata(sourceMetadata, metadataConverter).onSuccess(\n            (metadata) => {\n              if (json.isMutable) {\n                return succeed<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>({\n                  isMutable: true,\n                  id: json.id,\n                  items,\n                  metadata\n                });\n              }\n              return succeed<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>({\n                isMutable: false,\n                id: json.id,\n                items: items.toReadOnly(),\n                metadata\n              });\n            }\n          );\n        });\n      });\n    });\n  }\n\n  /**\n   * Creates a unified entry converter that handles all entry formats.\n   * Tries each format in order: instantiated mutable, instantiated readonly,\n   * JSON with entries array, JSON with items object.\n   */\n  private static _entryConverter<\n    TCOLLECTIONID extends string,\n    TITEMID extends string,\n    TITEM,\n    TMETADATA = unknown\n  >(\n    collectionIdConverter: Converter<TCOLLECTIONID, unknown> | Validator<TCOLLECTIONID, unknown>,\n    childKvConverters: KeyValueConverters<TITEMID, TITEM>,\n    metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>\n  ): Converter<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, unknown> {\n    return Converters.oneOf<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, unknown>([\n      AggregatedResultMapBase._instantiatedMutableConverter<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>(\n        collectionIdConverter,\n        metadataConverter\n      ),\n      AggregatedResultMapBase._instantiatedReadonlyConverter<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>(\n        collectionIdConverter,\n        metadataConverter\n      ),\n      AggregatedResultMapBase._jsonWithEntriesConverter<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>(\n        collectionIdConverter,\n        childKvConverters,\n        metadataConverter\n      ),\n      AggregatedResultMapBase._jsonWithItemsConverter<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>(\n        collectionIdConverter,\n        childKvConverters,\n        metadataConverter\n      )\n    ]);\n  }\n}\n\n/**\n * An aggregated result map that wraps a collection of {@link ValidatingResultMap | ValidatingResultMap} instances,\n * keyed by collection ID. Items are accessed via composite IDs that combine the collection ID\n * and item ID with a delimiter.\n * @public\n */\nexport class AggregatedResultMap<\n  TCOMPOSITEID extends string,\n  TCOLLECTIONID extends string,\n  TITEMID extends string,\n  TITEM,\n  TMETADATA = unknown\n> extends AggregatedResultMapBase<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA> {\n  /**\n   * Constructs a new {@link AggregatedResultMap | AggregatedResultMap}.\n   * @param params -\n   */\n  public constructor(\n    params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  ) {\n    super(params);\n  }\n\n  /**\n   * Creates a new {@link AggregatedResultMap | AggregatedResultMap}.\n   * @param params - Parameters for constructing the map.\n   * @returns `Success` with the new map if successful, `Failure` otherwise.\n   */\n  public static create<\n    TCOMPOSITEID extends string,\n    TCOLLECTIONID extends string,\n    TITEMID extends string,\n    TITEM,\n    TMETADATA = unknown\n  >(\n    params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>\n  ): Result<AggregatedResultMap<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>> {\n    return captureResult(() => new AggregatedResultMap(params));\n  }\n}\n"]}

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.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,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 './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.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 { ILogger } from '../logging';\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/**\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"]}