@fgv/ts-utils 4.3.0 → 4.5.0-0

package/lib/packlets/collections/collectorValidator.js

@@ -0,0 +1,98 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollectorValidator = void 0;
+/**
+ * A {@link Collections.Collector | Collector} wrapper which validates weakly-typed keys
+ * and values before calling the wrapped collector.
+ * @public
+ */
+class CollectorValidator {
+    get map() {
+        return this._collector.toReadOnly();
+    }
+    /**
+     * Constructs a new {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.
+     * @param params - Required parameters for constructing the collector validator.
+     */
+    constructor(params) {
+        this._collector = params.collector;
+        this.converters = params.converters;
+    }
+    /**
+     * {@inheritdoc Collections.Collector.add}
+     */
+    add(item) {
+        return this._convertValue(item).onSuccess((i) => {
+            return this._collector.add(i);
+        });
+    }
+    /**
+     * {@inheritdoc Collections.Collector.get}
+     */
+    get(key) {
+        return this.converters.convertKey(key).onSuccess((k) => {
+            return this._collector.get(k);
+        });
+    }
+    getOrAdd(keyOrItem, factoryCb) {
+        if (factoryCb === undefined) {
+            return this._convertValue(keyOrItem).onSuccess((item) => this._collector.getOrAdd(item));
+        }
+        else {
+            return this.converters
+                .convertKey(keyOrItem)
+                .withDetail('invalid-key', 'success')
+                .onSuccess((key) => this._collector.getOrAdd(key, factoryCb));
+        }
+    }
+    /**
+     * {@inheritdoc Collections.ResultMap.has}
+     */
+    has(key) {
+        return this._collector.has(key);
+    }
+    /**
+     * {@inheritdoc Collections.Collector.toReadOnly}
+     */
+    toReadOnly() {
+        return this;
+    }
+    /**
+     * Helper to convert a value, returning a {@link DetailedResult | DetailedResult}
+     * and formatting the error message.
+     * @param value - The value to convert.
+     * @returns {@link DetailedSuccess | DetailedSuccess} with the converted value
+     * and detail `success` if conversion is successful, or
+     * {@link DetailedFailure | DetailedFailure} with the error message and detail `invalid-value`
+     * if conversion fails.
+     */
+    _convertValue(value) {
+        return this.converters
+            .convertValue(value)
+            .withErrorFormat((message) => `invalid item: ${message}`)
+            .withDetail('invalid-value', 'success');
+    }
+}
+exports.CollectorValidator = CollectorValidator;
+//# sourceMappingURL=collectorValidator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collectorValidator.js","sourceRoot":"","sources":["../../../src/packlets/collections/collectorValidator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAuDH;;;;GAIG;AACH,MAAa,kBAAkB;IAO7B,IAAW,GAAG;QACZ,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAID;;;OAGG;IACH,YAAmB,MAA8C;QAC/D,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACtC,CAAC;IAED;;OAEG;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;IAgBM,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;AAjGD,gDAiGC","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.ConvertingCollectorValidator.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   * {@inheritdoc Collections.Collector.(getOrAdd:2)}\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  readonly collector: Collector<TITEM>;\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   * {@inheritdoc Collections.Collector.add}\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   * {@inheritdoc Collections.Collector.(getOrAdd:2)}\n   */\n  public getOrAdd(\n    key: string,\n    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * {@inheritdoc Collections.Collector.(getOrAdd:1)}\n   * @param item - The item to add to the collector.\n   */\n  public getOrAdd(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;\n\n  public getOrAdd(\n    keyOrItem: string | unknown,\n    factoryCb?: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (factoryCb === undefined) {\n      return this._convertValue(keyOrItem).onSuccess((item) => this._collector.getOrAdd(item));\n    } else {\n      return this.converters\n        .convertKey(keyOrItem)\n        .withDetail<CollectorResultDetail>('invalid-key', 'success')\n        .onSuccess((key) => this._collector.getOrAdd(key, factoryCb));\n    }\n  }\n\n  /**\n   * {@inheritdoc Collections.ResultMap.has}\n   */\n  public has(key: string): boolean {\n    return this._collector.has(key as CollectibleKey<TITEM>);\n  }\n\n  /**\n   * {@inheritdoc Collections.Collector.toReadOnly}\n   */\n  public toReadOnly(): IReadOnlyCollectorValidator<TITEM> {\n    return this;\n  }\n\n  /**\n   * Helper to convert a value, returning a {@link DetailedResult | DetailedResult}\n   * and formatting the error message.\n   * @param value - The value to convert.\n   * @returns {@link DetailedSuccess | DetailedSuccess} with the converted value\n   * and detail `success` if conversion is successful, or\n   * {@link DetailedFailure | DetailedFailure} with the error message and detail `invalid-value`\n   * if conversion fails.\n   */\n  protected _convertValue(value: unknown): DetailedResult<TITEM, CollectorResultDetail> {\n    return this.converters\n      .convertValue(value)\n      .withErrorFormat((message) => `invalid item: ${message}`)\n      .withDetail<CollectorResultDetail>('invalid-value', 'success');\n  }\n}\n"]}

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

@@ -1,67 +1,108 @@
 import { DetailedResult, Result } from '../base';
-import { CollectibleFactory, CollectibleFactoryCallback, ICollectible } from './collectible';
-import { Collector } from './collector';
-import { CollectorConverter } from './collectorConverter';
+import { ICollectible, CollectibleFactoryCallback, CollectibleFactory, CollectibleKey } from './collectible';
+import { Collector, CollectorResultDetail } from './collector';
 import { KeyValueEntry } from './common';
-import { IReadOnlyConvertingResultMap } from './convertingResultMap';
-import { KeyValueConverters } from './keyValueConverters';
-import { ResultMapResultDetail } from './readonlyResultMap';
 /**
  * Parameters for constructing a {@link Collections.ConvertingCollector | ConvertingCollector}.
  * @public
  */
-export interface IConvertingCollectorConstructorParams<TKEY extends string = string, TINDEX extends number = number, TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>, TSRC = TITEM> {
+export interface IConvertingCollectorConstructorParams<TITEM extends ICollectible<any, any>, TSRC = TITEM> {
     /**
-     * {@inheritdoc Collections.ICollectorConstructorParams.factory}
+     * The default {@link Collections.CollectibleFactory | factory} to create items.
      */
-    factory: CollectibleFactory<TKEY, TINDEX, TITEM, TSRC>;
+    factory: CollectibleFactory<TITEM, TSRC>;
     /**
-     * {@inheritdoc Collections.ICollectorConverterCreateParams.converters}
+     * An optional array of entries to add to the collector.
      */
-    converters: KeyValueConverters<TKEY, TSRC>;
-    /**
-     * {@inheritdoc Collections.ICollectorConstructorParams.entries}
-     */
-    entries?: KeyValueEntry<TKEY, TSRC>[];
+    entries?: KeyValueEntry<CollectibleKey<TITEM>, TSRC>[];
 }
 /**
- * A {@link Collections.Collector | Collector} with a {@link Collections.CollectorConverter | CollectorConverter}
- * property that enables validated use of the underlying map with weakly-typed keys and values.
+ * A {@link Collector | collector} that collects {@link Collections.ICollectible | ICollectible} items,
+ * optionally converting them from a source representation to the target representation using a factory
+ * supplied at default or at the time of collection.
  * @public
  */
-export declare class ConvertingCollector<TKEY extends string = string, TINDEX extends number = number, TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>, TSRC = TITEM> extends Collector<TKEY, TINDEX, TITEM, TSRC> {
+export declare class ConvertingCollector<TITEM extends ICollectible<any, any>, TSRC = TITEM> extends Collector<TITEM> {
+    private _factory;
     /**
-     * A {@link Collections.CollectorConverter | CollectorConverter} which validates keys and values
-     * before inserting them into this collector.
+     * Constructs a new {@link Collections.ConvertingCollector | ConvertingCollector}.
+     * @param params - Parameters for constructing the collector.
      */
-    readonly converting: CollectorConverter<TKEY, TINDEX, TITEM, TSRC>;
-    protected readonly _converters: KeyValueConverters<TKEY, TSRC>;
+    constructor(params: IConvertingCollectorConstructorParams<TITEM, TSRC>);
     /**
-     * Constructs a new {@link Collections.ConvertingCollector | ConvertingCollector}
-     * from the supplied {@link Collections.IConvertingCollectorConstructorParams | parameters}.
+     * Creates a new {@link Collections.ConvertingCollector | ConvertingCollector}.
      * @param params - Required parameters for constructing the collector.
+     * @returns Returns {@link Success | Success} with the new collector if it is created, or {@link Failure | Failure}
+     * with an error if the collector cannot be created.
      */
-    constructor(params: IConvertingCollectorConstructorParams<TKEY, TINDEX, TITEM, TSRC>);
+    static createConvertingCollector<TITEM extends ICollectible<any, any>, TSRC = TITEM>(params: IConvertingCollectorConstructorParams<TITEM, TSRC>): Result<ConvertingCollector<TITEM, TSRC>>;
     /**
-     * Creates a new {@link Collections.ConvertingCollector | ConvertingCollector} instance from
-     * the supplied {@link Collections.IConvertingCollectorConstructorParams | parameters}.
-     * @param params - Required parameters for constructing the collector.
-     * @returns {@link Success} with the new collector if successful, {@link Failure} otherwise.
+     * {@inheritdoc Collections.Collector.add}
+     */
+    add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
+    /**
+     * Adds an item to the collector using the default {@link Collections.CollectibleFactory | factory}
+     * at a specified key, failing if an item with that key already exists.
+     * @param key - The key of the item to add.
+     * @param item - The source representation of the item to be added.
+     * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with
+     * an error if the item cannot be created and indexed.
+     * @public
+     */
+    add(key: CollectibleKey<TITEM>, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;
+    /**
+     * Adds an item to the collector using a supplied {@link Collections.CollectibleFactoryCallback | factory callback}
+     * at a specified key, failing if an item with that key already exists or if the created item is invalid.
+     * @param key - The key of the item to add.
+     * @param callback - The factory callback to create the item.
+     * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with
+     * an error if the item cannot be created and indexed.
      */
-    static createConvertingCollector<TKEY extends string = string, TINDEX extends number = number, TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>, TSRC = TITEM>(params: IConvertingCollectorConstructorParams<TKEY, TINDEX, TITEM, TSRC>): Result<ConvertingCollector<TKEY, TINDEX, TITEM, TSRC>>;
+    add(key: CollectibleKey<TITEM>, cb: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**
      * {@inheritdoc Collections.Collector.(getOrAdd:1)}
      */
-    getOrAdd(key: TKEY, item: TSRC): DetailedResult<TITEM, ResultMapResultDetail>;
+    getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
     /**
      * {@inheritdoc Collections.Collector.(getOrAdd:2)}
      */
-    getOrAdd(key: TKEY, cb: CollectibleFactoryCallback<TKEY, TINDEX, TITEM>): DetailedResult<TITEM, ResultMapResultDetail>;
+    getOrAdd(key: CollectibleKey<TITEM>, callback: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
+    /**
+     * 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.
+     * @param key - The key of the item to retrieve.
+     * @param item - The source representation of the item to be added if it does not exist.
+     * @returns Returns {@link Success | Success} with the item if it exists or could be created, or {@link Failure | Failure} with an error if the
+     * item cannot be created and indexed.
+     */
+    getOrAdd(key: CollectibleKey<TITEM>, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;
+    /**
+     * Helper method for derived classes to determine if a supplied
+     * itemOrCb parameter is a factory callback.
+     * @param itemOrCb - Overloaded parameter is either `CollectibleKey<TITEM>` or
+     * a {@link Collections.CollectibleFactoryCallback | factory callback}.
+     * @returns Returns `true` if the parameter is a factory callback, `false` otherwise.
+     * @public
+     */
+    protected _isFactoryCB(itemOrCb: TSRC | CollectibleFactoryCallback<TITEM>): itemOrCb is CollectibleFactoryCallback<TITEM>;
+    /**
+     * Helper method for derived classes to determine if a supplied
+     * keyOrItem parameter is an item.
+     * @param keyOrItem - Overloaded parameter is either `CollectibleKey<TITEM>` or `TITEM`.
+     * @param itemOrCb - Overloaded parameter is either `TSRC`, a {@link Collections.CollectibleFactoryCallback | factory callback}
+     * or `undefined`.
+     * @returns Returns `true` if the parameter is an item, `false` otherwise.
+     * @public
+     */
+    protected _overloadIsItem(keyOrItem: CollectibleKey<TITEM> | TITEM, itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>): keyOrItem is TITEM;
     /**
-     * Gets a read-only version of this collector as a
-     * {@link Collections.IReadOnlyConvertingResultMap | read-only map}.
-     * @returns
+     * Helper method for derived classes to build an item from a key and a source representation using
+     * a default or supplied factory.
+     * @param key - The key of the item to build.
+     * @param itemOrCb - The source representation of the item to build, or a factory callback to create it.
+     * @returns Returns {@link Success | Success} with the item if it is built, or {@link Failure | Failure}
+     * with an error if the item cannot be built.
+     * @public
      */
-    toReadOnly(): IReadOnlyConvertingResultMap<TKEY, TITEM>;
+    protected _buildItem(key: CollectibleKey<TITEM>, itemOrCb: TSRC | CollectibleFactoryCallback<TITEM>): Result<TITEM>;
 }
 //# sourceMappingURL=convertingCollector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"convertingCollector.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/convertingCollector.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAiB,cAAc,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,qCAAqC,CACpD,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,KAAK,SAAS,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EACrE,IAAI,GAAG,KAAK;IAEZ;;OAEG;IACH,OAAO,EAAE,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAEvD;;OAEG;IACH,UAAU,EAAE,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAE3C;;OAEG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;CACvC;AAED;;;;GAIG;AACH,qBAAa,mBAAmB,CAC9B,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,KAAK,SAAS,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EACrE,IAAI,GAAG,KAAK,CACZ,SAAQ,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC;IAC5C;;;OAGG;IACH,SAAgB,UAAU,EAAE,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAE1E,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAE/D;;;;OAIG;gBACgB,MAAM,EAAE,qCAAqC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC;IAS3F;;;;;OAKG;WACW,yBAAyB,CACrC,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,KAAK,SAAS,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EACrE,IAAI,GAAG,KAAK,EAEZ,MAAM,EAAE,qCAAqC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,GACvE,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAIzD;;OAEG;IACI,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAEpF;;OAEG;IACI,QAAQ,CACb,GAAG,EAAE,IAAI,EACT,EAAE,EAAE,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,GAClD,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAe/C;;;;OAIG;IACI,UAAU,IAAI,4BAA4B,CAAC,IAAI,EAAE,KAAK,CAAC;CAG/D"}
+{"version":3,"file":"convertingCollector.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/convertingCollector.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAiB,cAAc,EAAkB,MAAM,EAAqB,MAAM,SAAS,CAAC;AACnG,OAAO,EAAE,YAAY,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC7G,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,qCAAqC,CAEpD,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,IAAI,GAAG,KAAK;IAEZ;;OAEG;IACH,OAAO,EAAE,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACzC;;OAEG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;CACxD;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB,CAE9B,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,IAAI,GAAG,KAAK,CACZ,SAAQ,SAAS,CAAC,KAAK,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAkC;IAElD;;;OAGG;gBACgB,MAAM,EAAE,qCAAqC,CAAC,KAAK,EAAE,IAAI,CAAC;IAQ7E;;;;;OAKG;WAEW,yBAAyB,CAAC,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,KAAK,EACxF,MAAM,EAAE,qCAAqC,CAAC,KAAK,EAAE,IAAI,CAAC,GACzD,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAI3C;;OAEG;IACI,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAErE;;;;;;;;OAQG;IACI,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAEhG;;;;;;;OAOG;IACI,GAAG,CACR,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,EAC1B,EAAE,EAAE,0BAA0B,CAAC,KAAK,CAAC,GACpC,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAgB/C;;OAEG;IACI,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAE1E;;OAEG;IACI,QAAQ,CACb,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,EAC1B,QAAQ,EAAE,0BAA0B,CAAC,KAAK,CAAC,GAC1C,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IAE/C;;;;;;OAMG;IACI,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,cAAc,CAAC,KAAK,EAAE,qBAAqB,CAAC;IA8BrG;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,CACpB,QAAQ,EAAE,IAAI,GAAG,0BAA0B,CAAC,KAAK,CAAC,GACjD,QAAQ,IAAI,0BAA0B,CAAC,KAAK,CAAC;IAIhD;;;;;;;;OAQG;IACH,SAAS,CAAC,eAAe,CACvB,SAAS,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,KAAK,EACxC,QAAQ,CAAC,EAAE,IAAI,GAAG,0BAA0B,CAAC,KAAK,CAAC,GAClD,SAAS,IAAI,KAAK;IAIrB;;;;;;;;OAQG;IACH,SAAS,CAAC,UAAU,CAClB,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,EAC1B,QAAQ,EAAE,IAAI,GAAG,0BAA0B,CAAC,KAAK,CAAC,GACjD,MAAM,CAAC,KAAK,CAAC;CAGjB"}

package/lib/packlets/collections/convertingCollector.js

@@ -24,53 +24,98 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConvertingCollector = void 0;
 const base_1 = require("../base");
 const collector_1 = require("./collector");
-const collectorConverter_1 = require("./collectorConverter");
 /**
- * A {@link Collections.Collector | Collector} with a {@link Collections.CollectorConverter | CollectorConverter}
- * property that enables validated use of the underlying map with weakly-typed keys and values.
+ * A {@link Collector | collector} that collects {@link Collections.ICollectible | ICollectible} items,
+ * optionally converting them from a source representation to the target representation using a factory
+ * supplied at default or at the time of collection.
  * @public
  */
 class ConvertingCollector extends collector_1.Collector {
     /**
-     * Constructs a new {@link Collections.ConvertingCollector | ConvertingCollector}
-     * from the supplied {@link Collections.IConvertingCollectorConstructorParams | parameters}.
-     * @param params - Required parameters for constructing the collector.
+     * Constructs a new {@link Collections.ConvertingCollector | ConvertingCollector}.
+     * @param params - Parameters for constructing the collector.
      */
     constructor(params) {
         var _a;
-        super({ factory: params.factory });
-        this._converters = params.converters;
-        this.converting = new collectorConverter_1.CollectorConverter({ collector: this, converters: params.converters });
-        for (const entry of (_a = params.entries) !== null && _a !== void 0 ? _a : []) {
+        super();
+        this._factory = params.factory;
+        (_a = params.entries) === null || _a === void 0 ? void 0 : _a.forEach((entry) => {
             this.getOrAdd(entry[0], entry[1]).orThrow();
-        }
+        });
     }
     /**
-     * Creates a new {@link Collections.ConvertingCollector | ConvertingCollector} instance from
-     * the supplied {@link Collections.IConvertingCollectorConstructorParams | parameters}.
+     * Creates a new {@link Collections.ConvertingCollector | ConvertingCollector}.
      * @param params - Required parameters for constructing the collector.
-     * @returns {@link Success} with the new collector if successful, {@link Failure} otherwise.
+     * @returns Returns {@link Success | Success} with the new collector if it is created, or {@link Failure | Failure}
+     * with an error if the collector cannot be created.
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static createConvertingCollector(params) {
         return (0, base_1.captureResult)(() => new ConvertingCollector(params));
     }
-    getOrAdd(key, itemOrCb) {
-        if (this._isFactoryCB(itemOrCb)) {
-            return this.converting.converters.convertKey(key).onSuccess((k) => {
-                return super.getOrAdd(k, itemOrCb);
-            });
+    add(keyOrItem, itemOrCb) {
+        if (this._overloadIsItem(keyOrItem, itemOrCb)) {
+            return super.add(keyOrItem);
+        }
+        return this._buildItem(keyOrItem, itemOrCb)
+            .withFailureDetail('invalid-value')
+            .onSuccess((item) => {
+            return super.add(item);
+        });
+    }
+    getOrAdd(keyOrItem, itemOrCb) {
+        if (this._overloadIsItem(keyOrItem, itemOrCb)) {
+            return super.getOrAdd(keyOrItem);
+        }
+        if (this.has(keyOrItem)) {
+            return this.get(keyOrItem);
         }
-        return this.converting.converters.convertEntry([key, itemOrCb]).onSuccess(([k, v]) => {
-            return super.getOrAdd(k, v);
+        return this._buildItem(keyOrItem, itemOrCb)
+            .withFailureDetail('invalid-value')
+            .onSuccess((item) => {
+            if (item.key !== keyOrItem) {
+                return (0, base_1.failWithDetail)(`${keyOrItem}: key mismatch - item has unexpected key ${item.key}`, 'invalid-key');
+            }
+            return (0, base_1.succeedWithDetail)(item, 'success');
+        })
+            .onSuccess((item) => {
+            return super.add(item);
         });
     }
     /**
-     * Gets a read-only version of this collector as a
-     * {@link Collections.IReadOnlyConvertingResultMap | read-only map}.
-     * @returns
+     * Helper method for derived classes to determine if a supplied
+     * itemOrCb parameter is a factory callback.
+     * @param itemOrCb - Overloaded parameter is either `CollectibleKey<TITEM>` or
+     * a {@link Collections.CollectibleFactoryCallback | factory callback}.
+     * @returns Returns `true` if the parameter is a factory callback, `false` otherwise.
+     * @public
+     */
+    _isFactoryCB(itemOrCb) {
+        return typeof itemOrCb === 'function';
+    }
+    /**
+     * Helper method for derived classes to determine if a supplied
+     * keyOrItem parameter is an item.
+     * @param keyOrItem - Overloaded parameter is either `CollectibleKey<TITEM>` or `TITEM`.
+     * @param itemOrCb - Overloaded parameter is either `TSRC`, a {@link Collections.CollectibleFactoryCallback | factory callback}
+     * or `undefined`.
+     * @returns Returns `true` if the parameter is an item, `false` otherwise.
+     * @public
+     */
+    _overloadIsItem(keyOrItem, itemOrCb) {
+        return itemOrCb === undefined;
+    }
+    /**
+     * Helper method for derived classes to build an item from a key and a source representation using
+     * a default or supplied factory.
+     * @param key - The key of the item to build.
+     * @param itemOrCb - The source representation of the item to build, or a factory callback to create it.
+     * @returns Returns {@link Success | Success} with the item if it is built, or {@link Failure | Failure}
+     * with an error if the item cannot be built.
+     * @public
      */
-    toReadOnly() {
-        return this;
+    _buildItem(key, itemOrCb) {
+        return this._isFactoryCB(itemOrCb) ? itemOrCb(key, this.size) : this._factory(key, this.size, itemOrCb);
     }
 }
 exports.ConvertingCollector = ConvertingCollector;

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

@@ -1 +1 @@
-{"version":3,"file":"convertingCollector.js","sourceRoot":"","sources":["../../../src/packlets/collections/convertingCollector.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,kCAAgE;AAEhE,2CAAwC;AACxC,6DAA0D;AAgC1D;;;;GAIG;AACH,MAAa,mBAKX,SAAQ,qBAAoC;IAS5C;;;;OAIG;IACH,YAAmB,MAAwE;;QACzF,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,uCAAkB,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QAC7F,KAAK,MAAM,KAAK,IAAI,MAAA,MAAM,CAAC,OAAO,mCAAI,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,yBAAyB,CAMrC,MAAwE;QAExE,OAAO,IAAA,oBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IAcM,QAAQ,CACb,GAAS,EACT,QAAgE;QAEhE,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;gBAChE,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YACrC,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE;YACnF,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AA/ED,kDA+EC","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 { CollectibleFactory, CollectibleFactoryCallback, ICollectible } from './collectible';\nimport { Collector } from './collector';\nimport { CollectorConverter } from './collectorConverter';\nimport { KeyValueEntry } from './common';\nimport { IReadOnlyConvertingResultMap } from './convertingResultMap';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { ResultMapResultDetail } from './readonlyResultMap';\n\n/**\n * Parameters for constructing a {@link Collections.ConvertingCollector | ConvertingCollector}.\n * @public\n */\nexport interface IConvertingCollectorConstructorParams<\n  TKEY extends string = string,\n  TINDEX extends number = number,\n  TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>,\n  TSRC = TITEM\n> {\n  /**\n   * {@inheritdoc Collections.ICollectorConstructorParams.factory}\n   */\n  factory: CollectibleFactory<TKEY, TINDEX, TITEM, TSRC>;\n\n  /**\n   * {@inheritdoc Collections.ICollectorConverterCreateParams.converters}\n   */\n  converters: KeyValueConverters<TKEY, TSRC>;\n\n  /**\n   * {@inheritdoc Collections.ICollectorConstructorParams.entries}\n   */\n  entries?: KeyValueEntry<TKEY, TSRC>[];\n}\n\n/**\n * A {@link Collections.Collector | Collector} with a {@link Collections.CollectorConverter | CollectorConverter}\n * property that enables validated use of the underlying map with weakly-typed keys and values.\n * @public\n */\nexport class ConvertingCollector<\n  TKEY extends string = string,\n  TINDEX extends number = number,\n  TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>,\n  TSRC = TITEM\n> extends Collector<TKEY, TINDEX, TITEM, TSRC> {\n  /**\n   * A {@link Collections.CollectorConverter | CollectorConverter} which validates keys and values\n   * before inserting them into this collector.\n   */\n  public readonly converting: CollectorConverter<TKEY, TINDEX, TITEM, TSRC>;\n\n  protected readonly _converters: KeyValueConverters<TKEY, TSRC>;\n\n  /**\n   * Constructs a new {@link Collections.ConvertingCollector | ConvertingCollector}\n   * from the supplied {@link Collections.IConvertingCollectorConstructorParams | parameters}.\n   * @param params - Required parameters for constructing the collector.\n   */\n  public constructor(params: IConvertingCollectorConstructorParams<TKEY, TINDEX, TITEM, TSRC>) {\n    super({ factory: params.factory });\n    this._converters = params.converters;\n    this.converting = new CollectorConverter({ collector: this, converters: params.converters });\n    for (const entry of params.entries ?? []) {\n      this.getOrAdd(entry[0], entry[1]).orThrow();\n    }\n  }\n\n  /**\n   * Creates a new {@link Collections.ConvertingCollector | ConvertingCollector} instance from\n   * the supplied {@link Collections.IConvertingCollectorConstructorParams | parameters}.\n   * @param params - Required parameters for constructing the collector.\n   * @returns {@link Success} with the new collector if successful, {@link Failure} otherwise.\n   */\n  public static createConvertingCollector<\n    TKEY extends string = string,\n    TINDEX extends number = number,\n    TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>,\n    TSRC = TITEM\n  >(\n    params: IConvertingCollectorConstructorParams<TKEY, TINDEX, TITEM, TSRC>\n  ): Result<ConvertingCollector<TKEY, TINDEX, TITEM, TSRC>> {\n    return captureResult(() => new ConvertingCollector(params));\n  }\n\n  /**\n   * {@inheritdoc Collections.Collector.(getOrAdd:1)}\n   */\n  public getOrAdd(key: TKEY, item: TSRC): DetailedResult<TITEM, ResultMapResultDetail>;\n\n  /**\n   * {@inheritdoc Collections.Collector.(getOrAdd:2)}\n   */\n  public getOrAdd(\n    key: TKEY,\n    cb: CollectibleFactoryCallback<TKEY, TINDEX, TITEM>\n  ): DetailedResult<TITEM, ResultMapResultDetail>;\n  public getOrAdd(\n    key: TKEY,\n    itemOrCb: TSRC | CollectibleFactoryCallback<TKEY, TINDEX, TITEM>\n  ): DetailedResult<TITEM, ResultMapResultDetail> {\n    if (this._isFactoryCB(itemOrCb)) {\n      return this.converting.converters.convertKey(key).onSuccess((k) => {\n        return super.getOrAdd(k, itemOrCb);\n      });\n    }\n    return this.converting.converters.convertEntry([key, itemOrCb]).onSuccess(([k, v]) => {\n      return super.getOrAdd(k, v);\n    });\n  }\n\n  /**\n   * Gets a read-only version of this collector as a\n   * {@link Collections.IReadOnlyConvertingResultMap | read-only map}.\n   * @returns\n   */\n  public toReadOnly(): IReadOnlyConvertingResultMap<TKEY, TITEM> {\n    return this;\n  }\n}\n"]}
+{"version":3,"file":"convertingCollector.js","sourceRoot":"","sources":["../../../src/packlets/collections/convertingCollector.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,kCAAmG;AAEnG,2CAA+D;AAsB/D;;;;;GAKG;AACH,MAAa,mBAIX,SAAQ,qBAAgB;IAGxB;;;OAGG;IACH,YAAmB,MAA0D;;QAC3E,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC;QAC/B,MAAA,MAAM,CAAC,OAAO,0CAAE,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YAChC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC9C,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,8DAA8D;IACvD,MAAM,CAAC,yBAAyB,CACrC,MAA0D;QAE1D,OAAO,IAAA,oBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IA+BM,GAAG,CACR,SAAwC,EACxC,QAAmD;QAEnD,IAAI,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC9C,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,QAAS,CAAC;aACzC,iBAAiB,CAAwB,eAAe,CAAC;aACzD,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YAClB,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;IACP,CAAC;IAwBM,QAAQ,CACb,SAAwC,EACxC,QAAmD;QAEnD,IAAI,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC9C,OAAO,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;QAED,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,QAAS,CAAC;aACzC,iBAAiB,CAAwB,eAAe,CAAC;aACzD,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YAClB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBAC3B,OAAO,IAAA,qBAAc,EACnB,GAAG,SAAS,4CAA4C,IAAI,CAAC,GAAG,EAAE,EAClE,aAAa,CACd,CAAC;YACJ,CAAC;YACD,OAAO,IAAA,wBAAiB,EAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC5C,CAAC,CAAC;aACD,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YAClB,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;OAOG;IACO,YAAY,CACpB,QAAkD;QAElD,OAAO,OAAO,QAAQ,KAAK,UAAU,CAAC;IACxC,CAAC;IAED;;;;;;;;OAQG;IACO,eAAe,CACvB,SAAwC,EACxC,QAAmD;QAEnD,OAAO,QAAQ,KAAK,SAAS,CAAC;IAChC,CAAC;IAED;;;;;;;;OAQG;IACO,UAAU,CAClB,GAA0B,EAC1B,QAAkD;QAElD,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC1G,CAAC;CACF;AA1KD,kDA0KC","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   * {@inheritdoc Collections.Collector.add}\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 callback - 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   * {@inheritdoc Collections.Collector.(getOrAdd:1)}\n   */\n  public getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * {@inheritdoc Collections.Collector.(getOrAdd:2)}\n   */\n  public getOrAdd(\n    key: CollectibleKey<TITEM>,\n    callback: CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Gets an item by key if it exists, or creates a new item and adds it using the default {@link Collections.CollectibleFactory | factory} if not.\n   * @param key - The key of the item to retrieve.\n   * @param item - The source representation of the item to be added if it does not exist.\n   * @returns Returns {@link Success | Success} with the item if it exists or could be created, or {@link Failure | Failure} with an error if the\n   * item cannot be created and indexed.\n   */\n  public getOrAdd(key: CollectibleKey<TITEM>, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;\n\n  public getOrAdd(\n    keyOrItem: CollectibleKey<TITEM> | TITEM,\n    itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (this._overloadIsItem(keyOrItem, itemOrCb)) {\n      return super.getOrAdd(keyOrItem);\n    }\n\n    if (this.has(keyOrItem)) {\n      return this.get(keyOrItem);\n    }\n\n    return this._buildItem(keyOrItem, itemOrCb!)\n      .withFailureDetail<CollectorResultDetail>('invalid-value')\n      .onSuccess((item) => {\n        if (item.key !== keyOrItem) {\n          return failWithDetail<TITEM, CollectorResultDetail>(\n            `${keyOrItem}: key mismatch - item has unexpected key ${item.key}`,\n            'invalid-key'\n          );\n        }\n        return succeedWithDetail(item, 'success');\n      })\n      .onSuccess((item) => {\n        return super.add(item);\n      });\n  }\n\n  /**\n   * Helper method for derived classes to determine if a supplied\n   * itemOrCb parameter is a factory callback.\n   * @param itemOrCb - Overloaded parameter is either `CollectibleKey<TITEM>` or\n   * a {@link Collections.CollectibleFactoryCallback | factory callback}.\n   * @returns Returns `true` if the parameter is a factory callback, `false` otherwise.\n   * @public\n   */\n  protected _isFactoryCB(\n    itemOrCb: TSRC | CollectibleFactoryCallback<TITEM>\n  ): itemOrCb is CollectibleFactoryCallback<TITEM> {\n    return typeof itemOrCb === 'function';\n  }\n\n  /**\n   * Helper method for derived classes to determine if a supplied\n   * keyOrItem parameter is an item.\n   * @param keyOrItem - Overloaded parameter is either `CollectibleKey<TITEM>` or `TITEM`.\n   * @param itemOrCb - Overloaded parameter is either `TSRC`, a {@link Collections.CollectibleFactoryCallback | factory callback}\n   * or `undefined`.\n   * @returns Returns `true` if the parameter is an item, `false` otherwise.\n   * @public\n   */\n  protected _overloadIsItem(\n    keyOrItem: CollectibleKey<TITEM> | TITEM,\n    itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>\n  ): keyOrItem is TITEM {\n    return itemOrCb === undefined;\n  }\n\n  /**\n   * Helper method for derived classes to build an item from a key and a source representation using\n   * a default or supplied factory.\n   * @param key - The key of the item to build.\n   * @param itemOrCb - The source representation of the item to build, or a factory callback to create it.\n   * @returns Returns {@link Success | Success} with the item if it is built, or {@link Failure | Failure}\n   * with an error if the item cannot be built.\n   * @public\n   */\n  protected _buildItem(\n    key: CollectibleKey<TITEM>,\n    itemOrCb: TSRC | CollectibleFactoryCallback<TITEM>\n  ): Result<TITEM> {\n    return this._isFactoryCB(itemOrCb) ? itemOrCb(key, this.size) : this._factory(key, this.size, itemOrCb);\n  }\n}\n"]}

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

@@ -0,0 +1,69 @@
+import { DetailedResult } from '../base';
+import { IReadOnlyResultMap, ResultMapResultDetail } from './readonlyResultMap';
+import { ResultMapValueFactory } from './resultMap';
+import { KeyValueConverters } from './keyValueConverters';
+import { CollectibleFactoryCallback, CollectibleKey, ICollectible } from './collectible';
+import { CollectorResultDetail } from './collector';
+import { ConvertingCollector } from './convertingCollector';
+import { IReadOnlyCollectorValidator } from './collectorValidator';
+/**
+ * Parameters for constructing a {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.
+ * @public
+ */
+export interface IConvertingCollectorValidatorCreateParams<TITEM extends ICollectible<any, any>, TSRC = TITEM> {
+    collector: ConvertingCollector<TITEM, TSRC>;
+    converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;
+}
+/**
+ * A {@link Collections.ConvertingCollector | ConvertingCollector} wrapper which validates weakly-typed keys
+ * and values before calling the wrapped collector.  Unlike the basic {@link Collections.CollectorValidator | CollectorValidator},
+ * the converting collector expects the items to be in the source type of the converting collector, not the target type.
+ * @public
+ */
+export declare class ConvertingCollectorValidator<TITEM extends ICollectible<any, any>, TSRC = TITEM> implements IReadOnlyCollectorValidator<TITEM> {
+    readonly converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;
+    get map(): IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM>;
+    protected _collector: ConvertingCollector<TITEM, TSRC>;
+    /**
+     * Constructs a new {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.
+     * @param params - Required parameters for constructing the collector validator.
+     */
+    constructor(params: IConvertingCollectorValidatorCreateParams<TITEM, TSRC>);
+    /**
+     * {@inheritdoc Collections.ConvertingCollector.(add:1)}
+     */
+    add(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
+    /**
+     * {@inheritdoc Collections.ConvertingCollector.(add:2)}
+     */
+    add(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
+    /**
+     * {@inheritdoc Collections.Collector.get}
+     */
+    get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * {@inheritdoc Collections.ConvertingCollector.(getOrAdd:3)}
+     */
+    getOrAdd(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
+    /**
+     * {@inheritdoc Collections.Collector.(getOrAdd:2)}
+     */
+    getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
+    /**
+     * {@inheritdoc Collections.ResultMap.has}
+     */
+    has(key: string): boolean;
+    /**
+     * {@inheritdoc Collections.Collector.toReadOnly}
+     */
+    toReadOnly(): IReadOnlyCollectorValidator<TITEM>;
+    /**
+     * Determines if a value is a {@link Collections.CollectibleFactoryCallback | CollectibleFactoryCallback}.
+     * @param value - The value to check.
+     * @returns `true` if the value is a {@link Collections.CollectibleFactoryCallback | CollectibleFactoryCallback},
+     * `false` otherwise.
+     * @public
+     */
+    protected _isCollectibleFactoryCallback(value: unknown | CollectibleFactoryCallback<TITEM>): value is CollectibleFactoryCallback<TITEM>;
+}
+//# sourceMappingURL=convertingCollectorValidator.d.ts.map

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

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

package/lib/packlets/collections/{collectorConverter.js → convertingCollectorValidator.js}

@@ -21,24 +21,32 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CollectorConverter = void 0;
+exports.ConvertingCollectorValidator = void 0;
+const base_1 = require("../base");
 /**
- * A {@link Collections.Collector | Collector} wrapper which validates weakly-typed keys
- * and values before calling the wrapped collector.
+ * A {@link Collections.ConvertingCollector | ConvertingCollector} wrapper which validates weakly-typed keys
+ * and values before calling the wrapped collector.  Unlike the basic {@link Collections.CollectorValidator | CollectorValidator},
+ * the converting collector expects the items to be in the source type of the converting collector, not the target type.
  * @public
  */
-class CollectorConverter {
+class ConvertingCollectorValidator {
     get map() {
         return this._collector.toReadOnly();
     }
     /**
-     * Constructs a new {@link Collections.CollectorConverter | CollectorConverter}.
-     * @param params - Required parameters for constructing the collector converter.
+     * Constructs a new {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.
+     * @param params - Required parameters for constructing the collector validator.
      */
     constructor(params) {
         this._collector = params.collector;
         this.converters = params.converters;
     }
+    add(key, valueOrFactory) {
+        if (this.has(key)) {
+            return (0, base_1.failWithDetail)(`${key}: already exists`, 'exists');
+        }
+        return this.getOrAdd(key, valueOrFactory);
+    }
     /**
      * {@inheritdoc Collections.Collector.get}
      */
@@ -49,18 +57,23 @@ class CollectorConverter {
     }
     getOrAdd(key, valueOrFactory) {
         if (!this._isCollectibleFactoryCallback(valueOrFactory)) {
-            return this.converters.convertEntry([key, valueOrFactory]).onSuccess(([vk, vs]) => {
-                return this._collector.getOrAdd(vk, vs);
-            });
+            const converted = this.converters.convertEntry([key, valueOrFactory]);
+            if (converted.isFailure()) {
+                return (0, base_1.failWithDetail)(converted.message, converted.detail);
+            }
+            const [vk, vs] = converted.value;
+            return this._collector.getOrAdd(vk, vs);
         }
         else {
-            return this.converters.convertKey(key).onSuccess((k) => {
-                return this._collector.getOrAdd(k, valueOrFactory);
-            });
+            const converted = this.converters.convertKey(key);
+            if (converted.isFailure()) {
+                return (0, base_1.failWithDetail)(converted.message, converted.detail);
+            }
+            return this._collector.getOrAdd(converted.value, valueOrFactory);
         }
     }
     /**
-     * {@inheritdoc Collections.Collector.has}
+     * {@inheritdoc Collections.ResultMap.has}
      */
     has(key) {
         return this._collector.has(key);
@@ -82,5 +95,5 @@ class CollectorConverter {
         return typeof value === 'function';
     }
 }
-exports.CollectorConverter = CollectorConverter;
-//# sourceMappingURL=collectorConverter.js.map
+exports.ConvertingCollectorValidator = ConvertingCollectorValidator;
+//# sourceMappingURL=convertingCollectorValidator.js.map