@fgv/ts-utils 4.4.0 → 4.5.0-0

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

@@ -1,194 +1,129 @@
 import { DetailedResult, Result } from '../base';
-import { ICollectible, CollectibleFactoryCallback, CollectibleFactory } from './collectible';
+import { CollectibleFactoryCallback, CollectibleKey, ICollectible } from './collectible';
 import { KeyValueEntry } from './common';
 import { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';
 /**
- * Additional success or failure details for mutating {@link ICollector | Collector} calls.
+ * Additional success or failure details for mutating collector calls.
  * @public
  */
 export type CollectorResultDetail = ResultMapResultDetail | 'invalid-index';
 /**
- * A read-only interface exposing non-mutating methods of a {@link Collections.ICollector | Collector}.
+ * A read-only interface exposing only the non-mutating methods of a {@link Collections.Collector | ICollector}.
  * @public
  */
-export interface IReadOnlyCollector<TKEY extends string = string, TINDEX extends number = number, TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>> extends IReadOnlyResultMap<TKEY, TITEM> {
+export interface IReadOnlyCollector<TITEM extends ICollectible<any, any>> extends IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM> {
     /**
      * 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.
+     * @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: number): Result<TITEM>;
 }
 /**
- * Collects {@link Collections.ICollectible | ICollectible} items. Items in a collector are created by key and are assigned an index at the
- * time of addition.  Items are immutable once added.
+ * Parameters for constructing a {@link Collections.Collector | ICollector}.
  * @public
  */
-export interface ICollector<TKEY extends string = string, TINDEX extends number = number, TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>, TSRC = TITEM> extends IReadOnlyCollector<TKEY, TINDEX, TITEM> {
-    /**
-     * 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: TKEY, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;
-    add(key: TKEY, callback: CollectibleFactoryCallback<TKEY, TINDEX>): 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 item - The item to add.
-     * @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.
-     */
-    addItem(item: 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: TKEY, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;
-    /**
-     * Gets an item by key if it exists, or creates a new item and adds it using the specified {@link Collections.CollectibleFactoryCallback | factory callback} if not.
-     * @param key - The key of the item to retrieve.
-     * @param callback - The factory callback to create the item if it does not exist.
-     * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure} with an error if the item is not found.
-     */
-    getOrAdd(key: TKEY, callback: CollectibleFactoryCallback<TKEY, TINDEX>): DetailedResult<TITEM, CollectorResultDetail>;
-    /**
-     * Gets an existing item with a key matching that of a supplied item, or adds the supplied
-     * item to the collector if no item with that key exists.
-     * @param item - The item to retrieve or add.
-     * @returns Returns {@link Success | Success} with the item stored in the collector
-     * or {@link Failure | Failure} with an error if the item cannot be created and indexed.
-     */
-    getOrAddItem(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
-    /**
-     * Gets a {@link IReadOnlyResultMap | read-only map} which can access the items in the collector.
-     */
-    toReadOnly(): IReadOnlyCollector<TKEY, TINDEX, TITEM>;
-}
-/**
- * A simple {@link ICollector | ICollector} with non-branded `string` key and `number` index, and no transformation of source items.
- * @public
- */
-export type ISimpleCollector<TITEM extends ICollectible<string, number>> = ICollector<string, number, TITEM, TITEM>;
-/**
- * A {@link ICollector | Collector} with non-branded `string` key and `number` index, and transformation of source items.
- * @public
- */
-export type IConvertingCollector<TITEM extends ICollectible<string, number>, TSRC> = ICollector<string, number, TITEM, TSRC>;
-/**
- * Parameters for constructing a {@link ICollector | Collector}.
- * @public
- */
-export interface ICollectorConstructorParams<TKEY extends string = string, TINDEX extends number = number, TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>, TSRC = TITEM> {
-    /**
-     * The default {@link Collections.CollectibleFactory | factory} to create items.
-     */
-    factory: CollectibleFactory<TKEY, TINDEX, TITEM, TSRC>;
-    /**
-     * An optional array of entries to add to the collector.
-     */
-    entries?: KeyValueEntry<TKEY, TSRC>[];
+export interface ICollectorConstructorParams<TITEM extends ICollectible<any, any>> {
+    items?: TITEM[];
 }
 /**
- * A {@link ICollector | Collector} that collects {@link Collections.ICollectible | ICollectible} items. Items in a collector are created by key and are assigned an index at the
- * time of addition.  Items are immutable once added.  Keys and indexes might be branded types, and source items might be transformed on addition.
+ * A {@link Collections.Collector | Collector} that is a specialized collection
+ * which contains items of type {@link Collections.ICollectible | ICollectible},
+ * which have a unique key and a write-once index.
+ *
+ * Items are assigned an index sequentially as they are added to the collection.
+ * Once added, items are immutable - they cannot be removed or replaced.
  * @public
  */
-export declare class Collector<TKEY extends string = string, TINDEX extends number = number, TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>, TSRC = TITEM> implements ICollector<TKEY, TINDEX, TITEM, TSRC> {
-    private _byKey;
-    private _byIndex;
-    private _factory;
+export declare class Collector<TITEM extends ICollectible<any, any>> implements IReadOnlyCollector<TITEM> {
+    private readonly _byKey;
+    private readonly _byIndex;
     /**
-     * {@inheritdoc IReadOnlyResultMap.inner}
+     * {@inheritdoc Collections.ResultMap.size}
      */
-    get inner(): ReadonlyMap<TKEY, TITEM>;
+    get size(): number;
     /**
-     * Constructor for derived classes.
-     * @param params - Parameters for constructing the collector.
+     * Constructs a new {@link Collections.Collector | Collector}.
+     * @param params - Optional {@link Collections.ICollectorConstructorParams | initialization parameters} used
+     * to construct the collector.
      */
-    protected constructor(params: ICollectorConstructorParams<TKEY, TINDEX, TITEM, TSRC>);
+    constructor(params?: ICollectorConstructorParams<TITEM>);
     /**
-     * {@inheritdoc IReadOnlyResultMap.size}
+     * Creates a new {@link Collections.Collector | Collector} instance.
+     * @param params - Optional {@link Collections.ICollectorConstructorParams | initialization parameters} used
+     * to create the collector.
+     * @returns Returns {@link Success | Success} with the new collector if it was created successfully,
+     * or {@link Failure | Failure} with an error if the collector could not be created.
      */
-    get size(): number;
+    static createCollector<TITEM extends ICollectible<any, any>>(params?: ICollectorConstructorParams<TITEM>): Result<Collector<TITEM>>;
     /**
-     * {@inheritdoc IReadOnlyResultMap.keys}
+     * 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.
      */
-    keys(): IterableIterator<TKEY>;
+    add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritdoc IReadOnlyResultMap.values}
+     * {@inheritdoc Collections.ResultMap.entries}
      */
-    values(): IterableIterator<TITEM>;
+    entries(): MapIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>>;
     /**
-     * {@inheritdoc IReadOnlyResultMap.entries}
+     * {@inheritdoc Collections.ResultMap.forEach}
      */
-    entries(): IterableIterator<[TKEY, TITEM]>;
+    forEach(callback: ResultMapForEachCb<CollectibleKey<TITEM>, TITEM>, arg?: unknown): void;
     /**
-     * {@inheritdoc IReadOnlyResultMap.forEach}
+     * {@inheritdoc Collections.ResultMap.get}
      */
-    forEach(callback: ResultMapForEachCb<TKEY, TITEM>, arg?: unknown): void;
-    /**
-     * {@inheritdoc IReadOnlyResultMap.get}
-     */
-    get(key: TKEY): DetailedResult<TITEM, ResultMapResultDetail>;
+    get(key: CollectibleKey<TITEM>): DetailedResult<TITEM, ResultMapResultDetail>;
     /**
      * {@inheritdoc Collections.IReadOnlyCollector.getAt}
      */
     getAt(index: number): Result<TITEM>;
     /**
-     * {@inheritdoc ICollector.(add:1)}
-     */
-    add(key: TKEY, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;
-    /**
-     * {@inheritdoc ICollector.(add:2)}
-     */
-    add(key: TKEY, cb: CollectibleFactoryCallback<TKEY, TINDEX, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
-    /**
-     * {@inheritdoc ICollector.addItem}
+     * Gets an existing item with a key matching that of a supplied item, or adds the supplied
+     * item to the collector if no item with that key exists.
+     * @param item - The item to get or add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item return and detail `added` indicates that the
+     * item was added. Returns {@link DetailedFailure | Failure} with an error and appropriate
+     * detail if the item could not be added.
      */
-    addItem(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
+    getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritdoc ICollector.(getOrAdd:1)}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The key of the item to add.
+     * @param callback - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item return and detail `added` indicates that the
+     * item was added. Returns {@link DetailedFailure | Failure} with an error and appropriate
+     * detail if the item could not be added.
      */
-    getOrAdd(key: TKEY, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;
+    getOrAdd(key: CollectibleKey<TITEM>, factory: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritdoc ICollector.(getOrAdd:2)}
+     * {@inheritdoc Collections.ResultMap.has}
      */
-    getOrAdd(key: TKEY, cb: CollectibleFactoryCallback<TKEY, TINDEX, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
+    has(key: CollectibleKey<TITEM>): boolean;
     /**
-     * {@inheritdoc ICollector.getOrAddItem}
+     * {@inheritdoc Collections.ResultMap.keys}
      */
-    getOrAddItem(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
+    keys(): IterableIterator<CollectibleKey<TITEM>>;
     /**
-     * {@inheritdoc IReadOnlyResultMap.has}
+     * {@inheritdoc Collections.ResultMap.values}
      */
-    has(key: TKEY): boolean;
+    values(): IterableIterator<TITEM>;
     /**
-     * {@inheritdoc ICollector.toReadOnly}
+     * Gets a read-only version of this collector.
      */
-    toReadOnly(): IReadOnlyCollector<TKEY, TINDEX, TITEM>;
+    toReadOnly(): IReadOnlyCollector<TITEM>;
     /**
      * Gets an iterator over the map entries.
      * @returns An iterator over the map entries.
      */
-    [Symbol.iterator](): IterableIterator<KeyValueEntry<TKEY, TITEM>>;
-    /**
-     * A simple factory method for derived classes which directly store the supplied
-     * object.
-     * @param key - The key of the item to create.
-     * @param index - The index of the item to create.
-     * @param item - The source item to create.
-     * @returns `Success` with the created item and a detail of 'success', or
-     * `Failure` with an error message and appropriate detail.
-     */
-    protected static _simpleFactory<TKEY extends string = string, TINDEX extends number = number, TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>>(key: TKEY, index: number, item: TITEM): Result<TITEM>;
-    protected _isFactoryCB(item: TSRC | CollectibleFactoryCallback<TKEY, TINDEX, TITEM>): item is CollectibleFactoryCallback<TKEY, TINDEX, TITEM>;
+    [Symbol.iterator](): IterableIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>>;
+    protected _isItem(keyOrItem: CollectibleKey<TITEM> | TITEM): keyOrItem is TITEM;
 }
 //# sourceMappingURL=collector.d.ts.map

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

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

package/lib/packlets/collections/collector.js

@@ -24,56 +24,79 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Collector = void 0;
 const base_1 = require("../base");
 /**
- * A {@link ICollector | Collector} that collects {@link Collections.ICollectible | ICollectible} items. Items in a collector are created by key and are assigned an index at the
- * time of addition.  Items are immutable once added.  Keys and indexes might be branded types, and source items might be transformed on addition.
+ * A {@link Collections.Collector | Collector} that is a specialized collection
+ * which contains items of type {@link Collections.ICollectible | ICollectible},
+ * which have a unique key and a write-once index.
+ *
+ * Items are assigned an index sequentially as they are added to the collection.
+ * Once added, items are immutable - they cannot be removed or replaced.
  * @public
  */
 class Collector {
     /**
-     * {@inheritdoc IReadOnlyResultMap.inner}
+     * {@inheritdoc Collections.ResultMap.size}
      */
-    get inner() {
-        return this._byKey;
+    get size() {
+        return this._byIndex.length;
     }
     /**
-     * Constructor for derived classes.
-     * @param params - Parameters for constructing the collector.
+     * Constructs a new {@link Collections.Collector | Collector}.
+     * @param params - Optional {@link Collections.ICollectorConstructorParams | initialization parameters} used
+     * to construct the collector.
      */
     constructor(params) {
         var _a;
         this._byKey = new Map();
         this._byIndex = [];
-        this._factory = params.factory;
-        (_a = params.entries) === null || _a === void 0 ? void 0 : _a.forEach((entry) => {
-            this.getOrAdd(entry[0], entry[1]);
-        });
-    }
-    /**
-     * {@inheritdoc IReadOnlyResultMap.size}
-     */
-    get size() {
-        return this._byKey.size;
+        for (const item of (_a = params === null || params === void 0 ? void 0 : params.items) !== null && _a !== void 0 ? _a : []) {
+            this.add(item).orThrow();
+        }
     }
     /**
-     * {@inheritdoc IReadOnlyResultMap.keys}
+     * Creates a new {@link Collections.Collector | Collector} instance.
+     * @param params - Optional {@link Collections.ICollectorConstructorParams | initialization parameters} used
+     * to create the collector.
+     * @returns Returns {@link Success | Success} with the new collector if it was created successfully,
+     * or {@link Failure | Failure} with an error if the collector could not be created.
      */
-    keys() {
-        return this._byKey.keys();
+    static createCollector(params) {
+        return (0, base_1.captureResult)(() => new Collector(params));
     }
     /**
-     * {@inheritdoc IReadOnlyResultMap.values}
+     * 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.
      */
-    values() {
-        return this._byKey.values();
+    add(item) {
+        const existing = this._byKey.get(item.key);
+        if (existing === item) {
+            return (0, base_1.succeedWithDetail)(item, 'exists');
+        }
+        else if (existing) {
+            return (0, base_1.failWithDetail)(`${item.key}: already exists`, 'exists');
+        }
+        const indexResult = item.setIndex(this._byIndex.length);
+        if (indexResult.isFailure()) {
+            return (0, base_1.failWithDetail)(`${item.key}: ${indexResult.message}`, 'invalid-index');
+        }
+        else if (item.index !== this._byIndex.length) {
+            return (0, base_1.failWithDetail)(`${item.key}: index mismatch - built item has ${item.index}`, 'invalid-index');
+        }
+        this._byKey.set(item.key, item);
+        this._byIndex.push(item);
+        return (0, base_1.succeedWithDetail)(item, 'added');
     }
     /**
-     * {@inheritdoc IReadOnlyResultMap.entries}
+     * {@inheritdoc Collections.ResultMap.entries}
      */
     entries() {
         return this._byKey.entries();
     }
     /**
-     * {@inheritdoc IReadOnlyResultMap.forEach}
+     * {@inheritdoc Collections.ResultMap.forEach}
      */
     forEach(callback, arg) {
         for (const [key, value] of this._byKey.entries()) {
@@ -81,14 +104,11 @@ class Collector {
         }
     }
     /**
-     * {@inheritdoc IReadOnlyResultMap.get}
+     * {@inheritdoc Collections.ResultMap.get}
      */
     get(key) {
         const item = this._byKey.get(key);
-        if (item === undefined) {
-            return (0, base_1.failWithDetail)(`${key}: not found.`, 'not-found');
-        }
-        return (0, base_1.succeedWithDetail)(item, 'success');
+        return item ? (0, base_1.succeedWithDetail)(item, 'exists') : (0, base_1.failWithDetail)(`${key}: not found`, 'not-found');
     }
     /**
      * {@inheritdoc Collections.IReadOnlyCollector.getAt}
@@ -99,65 +119,46 @@ class Collector {
         }
         return (0, base_1.succeed)(this._byIndex[index]);
     }
-    add(key, itemOrCb) {
-        if (this._byKey.has(key)) {
-            return (0, base_1.failWithDetail)(`${key}: already exists.`, 'exists');
+    getOrAdd(keyOrItem, factory) {
+        const key = !this._isItem(keyOrItem) ? keyOrItem : keyOrItem.key;
+        const existing = this._byKey.get(key);
+        if (existing) {
+            return (0, base_1.succeedWithDetail)(existing, 'exists');
+        }
+        const itemResult = !this._isItem(keyOrItem)
+            ? factory(keyOrItem, this._byIndex.length)
+            : (0, base_1.succeed)(keyOrItem);
+        if (itemResult.isFailure()) {
+            return (0, base_1.failWithDetail)(`${key}: ${itemResult.message}`, 'invalid-value');
         }
-        return this.getOrAdd(key, itemOrCb);
+        const item = itemResult.value;
+        if (item.key !== key) {
+            return (0, base_1.failWithDetail)(`${key}: key mismatch - built item has ${key}`, 'invalid-key');
+        }
+        return itemResult.withFailureDetail('invalid-index').onSuccess((item) => {
+            return this.add(item);
+        });
     }
     /**
-     * {@inheritdoc ICollector.addItem}
+     * {@inheritdoc Collections.ResultMap.has}
      */
-    addItem(item) {
-        if (this._byKey.has(item.key)) {
-            return (0, base_1.failWithDetail)(`${item.key}: already exists.`, 'exists');
-        }
-        return this.getOrAddItem(item);
-    }
-    getOrAdd(key, itemOrCb) {
-        if (this._byKey.has(key)) {
-            return (0, base_1.succeedWithDetail)(this._byKey.get(key), 'exists');
-        }
-        const build = this._isFactoryCB(itemOrCb)
-            ? itemOrCb(key, this._byIndex.length)
-            : this._factory(key, this._byIndex.length, itemOrCb);
-        if (build.isFailure()) {
-            return (0, base_1.failWithDetail)(build.message, 'invalid-value');
-        }
-        const newItem = build.value;
-        if (newItem.key !== key) {
-            return (0, base_1.failWithDetail)(`$[key}: key mismatch in created item - ${newItem.key} !== ${key}`, 'invalid-key');
-        }
-        if (newItem.index !== this._byIndex.length) {
-            return (0, base_1.failWithDetail)(`$[key}: index mismatch in created item - ${newItem.index} !== ${this._byIndex.length}`, 'invalid-index');
-        }
-        this._byKey.set(key, newItem);
-        this._byIndex.push(newItem);
-        return (0, base_1.succeedWithDetail)(newItem, 'added');
+    has(key) {
+        return this._byKey.has(key);
     }
     /**
-     * {@inheritdoc ICollector.getOrAddItem}
+     * {@inheritdoc Collections.ResultMap.keys}
      */
-    getOrAddItem(item) {
-        if (this._byKey.has(item.key)) {
-            return (0, base_1.succeedWithDetail)(this._byKey.get(item.key), 'exists');
-        }
-        const { message } = item.setIndex(this._byIndex.length);
-        if (message !== undefined) {
-            return (0, base_1.failWithDetail)(message, 'invalid-index');
-        }
-        this._byKey.set(item.key, item);
-        this._byIndex.push(item);
-        return (0, base_1.succeedWithDetail)(item, 'added');
+    keys() {
+        return this._byKey.keys();
     }
     /**
-     * {@inheritdoc IReadOnlyResultMap.has}
+     * {@inheritdoc Collections.ResultMap.values}
      */
-    has(key) {
-        return this._byKey.has(key);
+    values() {
+        return this._byKey.values();
     }
     /**
-     * {@inheritdoc ICollector.toReadOnly}
+     * Gets a read-only version of this collector.
      */
     toReadOnly() {
         return this;
@@ -169,20 +170,8 @@ class Collector {
     [Symbol.iterator]() {
         return this._byKey[Symbol.iterator]();
     }
-    /**
-     * A simple factory method for derived classes which directly store the supplied
-     * object.
-     * @param key - The key of the item to create.
-     * @param index - The index of the item to create.
-     * @param item - The source item to create.
-     * @returns `Success` with the created item and a detail of 'success', or
-     * `Failure` with an error message and appropriate detail.
-     */
-    static _simpleFactory(key, index, item) {
-        return item.setIndex(index).onSuccess(() => (0, base_1.succeed)(item));
-    }
-    _isFactoryCB(item) {
-        return typeof item === 'function';
+    _isItem(keyOrItem) {
+        return typeof keyOrItem !== 'string';
     }
 }
 exports.Collector = Collector;

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

@@ -1 +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 { DetailedResult, Result, fail, failWithDetail, succeed, succeedWithDetail } from '../base';\nimport { ICollectible, CollectibleFactoryCallback, CollectibleFactory } from './collectible';\nimport { KeyValueEntry } from './common';\nimport { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';\n\n/**\n * Additional success or failure details for mutating {@link ICollector | Collector} calls.\n * @public\n */\nexport type CollectorResultDetail = ResultMapResultDetail | 'invalid-index';\n\n/**\n * A read-only interface exposing non-mutating methods of a {@link Collections.ICollector | Collector}.\n * @public\n */\nexport interface IReadOnlyCollector<\n  TKEY extends string = string,\n  TINDEX extends number = number,\n  TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>\n> extends IReadOnlyResultMap<TKEY, 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} with an error if the index is out of range.\n   */\n  getAt(index: number): Result<TITEM>;\n}\n\n/**\n * Collects {@link Collections.ICollectible | ICollectible} items. Items in a collector are created by key and are assigned an index at the\n * time of addition.  Items are immutable once added.\n * @public\n */\nexport interface ICollector<\n  TKEY extends string = string,\n  TINDEX extends number = number,\n  TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>,\n  TSRC = TITEM\n> extends IReadOnlyCollector<TKEY, TINDEX, TITEM> {\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  add(key: TKEY, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;\n  add(\n    key: TKEY,\n    callback: CollectibleFactoryCallback<TKEY, TINDEX>\n  ): 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 item - The item to add.\n   * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with an\n   * error if the item cannot be created and indexed.\n   */\n  addItem(item: TITEM): 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  getOrAdd(key: TKEY, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Gets an item by key if it exists, or creates a new item and adds it using the specified {@link Collections.CollectibleFactoryCallback | factory callback} if not.\n   * @param key - The key of the item to retrieve.\n   * @param callback - The factory callback to create the item if it does not exist.\n   * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure} with an error if the item is not found.\n   */\n  getOrAdd(\n    key: TKEY,\n    callback: CollectibleFactoryCallback<TKEY, TINDEX>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\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 retrieve or add.\n   * @returns Returns {@link Success | Success} with the item stored in the collector\n   * or {@link Failure | Failure} with an error if the item cannot be created and indexed.\n   */\n  getOrAddItem(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;\n\n  /**\n   * Gets a {@link IReadOnlyResultMap | read-only map} which can access the items in the collector.\n   */\n  toReadOnly(): IReadOnlyCollector<TKEY, TINDEX, TITEM>;\n}\n\n/**\n * A simple {@link ICollector | ICollector} with non-branded `string` key and `number` index, and no transformation of source items.\n * @public\n */\nexport type ISimpleCollector<TITEM extends ICollectible<string, number>> = ICollector<\n  string,\n  number,\n  TITEM,\n  TITEM\n>;\n\n/**\n * A {@link ICollector | Collector} with non-branded `string` key and `number` index, and transformation of source items.\n * @public\n */\nexport type IConvertingCollector<TITEM extends ICollectible<string, number>, TSRC> = ICollector<\n  string,\n  number,\n  TITEM,\n  TSRC\n>;\n\n/**\n * Parameters for constructing a {@link ICollector | Collector}.\n * @public\n */\nexport interface ICollectorConstructorParams<\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   * The default {@link Collections.CollectibleFactory | factory} to create items.\n   */\n  factory: CollectibleFactory<TKEY, TINDEX, TITEM, TSRC>;\n  /**\n   * An optional array of entries to add to the collector.\n   */\n  entries?: KeyValueEntry<TKEY, TSRC>[];\n}\n\n/**\n * A {@link ICollector | Collector} that collects {@link Collections.ICollectible | ICollectible} items. Items in a collector are created by key and are assigned an index at the\n * time of addition.  Items are immutable once added.  Keys and indexes might be branded types, and source items might be transformed on addition.\n * @public\n */\nexport class Collector<\n  TKEY extends string = string,\n  TINDEX extends number = number,\n  TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>,\n  TSRC = TITEM\n> implements ICollector<TKEY, TINDEX, TITEM, TSRC>\n{\n  private _byKey: Map<TKEY, TITEM>;\n  private _byIndex: TITEM[];\n  private _factory: CollectibleFactory<TKEY, TINDEX, TITEM, TSRC>;\n\n  /**\n   * {@inheritdoc IReadOnlyResultMap.inner}\n   */\n  public get inner(): ReadonlyMap<TKEY, TITEM> {\n    return this._byKey;\n  }\n\n  /**\n   * Constructor for derived classes.\n   * @param params - Parameters for constructing the collector.\n   */\n  protected constructor(params: ICollectorConstructorParams<TKEY, TINDEX, TITEM, TSRC>) {\n    this._byKey = new Map<TKEY, TITEM>();\n    this._byIndex = [];\n    this._factory = params.factory;\n    params.entries?.forEach((entry) => {\n      this.getOrAdd(entry[0], entry[1]);\n    });\n  }\n\n  /**\n   * {@inheritdoc IReadOnlyResultMap.size}\n   */\n  public get size(): number {\n    return this._byKey.size;\n  }\n\n  /**\n   * {@inheritdoc IReadOnlyResultMap.keys}\n   */\n  public keys(): IterableIterator<TKEY> {\n    return this._byKey.keys();\n  }\n\n  /**\n   * {@inheritdoc IReadOnlyResultMap.values}\n   */\n  public values(): IterableIterator<TITEM> {\n    return this._byKey.values();\n  }\n\n  /**\n   * {@inheritdoc IReadOnlyResultMap.entries}\n   */\n  public entries(): IterableIterator<[TKEY, TITEM]> {\n    return this._byKey.entries();\n  }\n\n  /**\n   * {@inheritdoc IReadOnlyResultMap.forEach}\n   */\n  public forEach(callback: ResultMapForEachCb<TKEY, TITEM>, arg?: unknown): void {\n    for (const [key, value] of this._byKey.entries()) {\n      callback(value, key, this, arg);\n    }\n  }\n\n  /**\n   * {@inheritdoc IReadOnlyResultMap.get}\n   */\n  public get(key: TKEY): DetailedResult<TITEM, ResultMapResultDetail> {\n    const item = this._byKey.get(key);\n    if (item === undefined) {\n      return failWithDetail<TITEM, ResultMapResultDetail>(`${key}: not found.`, 'not-found');\n    }\n    return succeedWithDetail(item, 'success');\n  }\n\n  /**\n   * {@inheritdoc Collections.IReadOnlyCollector.getAt}\n   */\n  public getAt(index: number): Result<TITEM> {\n    if (index < 0 || index >= this._byIndex.length) {\n      return fail(`${index}: out of range.`);\n    }\n    return succeed(this._byIndex[index]);\n  }\n\n  /**\n   * {@inheritdoc ICollector.(add:1)}\n   */\n  public add(key: TKEY, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;\n  /**\n   * {@inheritdoc ICollector.(add:2)}\n   */\n  public add(\n    key: TKEY,\n    cb: CollectibleFactoryCallback<TKEY, TINDEX, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n  public add(\n    key: TKEY,\n    itemOrCb: TSRC | CollectibleFactoryCallback<TKEY, TINDEX, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (this._byKey.has(key)) {\n      return failWithDetail(`${key}: already exists.`, 'exists');\n    }\n    return this.getOrAdd(key, itemOrCb as TSRC);\n  }\n\n  /**\n   * {@inheritdoc ICollector.addItem}\n   */\n  public addItem(item: TITEM): DetailedResult<TITEM, CollectorResultDetail> {\n    if (this._byKey.has(item.key)) {\n      return failWithDetail(`${item.key}: already exists.`, 'exists');\n    }\n    return this.getOrAddItem(item);\n  }\n\n  /**\n   * {@inheritdoc ICollector.(getOrAdd:1)}\n   */\n  public getOrAdd(key: TKEY, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;\n  /**\n   * {@inheritdoc ICollector.(getOrAdd:2)}\n   */\n  public getOrAdd(\n    key: TKEY,\n    cb: CollectibleFactoryCallback<TKEY, TINDEX, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail>;\n\n  public getOrAdd(\n    key: TKEY,\n    itemOrCb: TSRC | CollectibleFactoryCallback<TKEY, TINDEX, TITEM>\n  ): DetailedResult<TITEM, CollectorResultDetail> {\n    if (this._byKey.has(key)) {\n      return succeedWithDetail(this._byKey.get(key)!, 'exists');\n    }\n    const build = this._isFactoryCB(itemOrCb)\n      ? itemOrCb(key, this._byIndex.length)\n      : this._factory(key, this._byIndex.length, itemOrCb);\n    if (build.isFailure()) {\n      return failWithDetail<TITEM, CollectorResultDetail>(build.message, 'invalid-value');\n    }\n    const newItem = build.value;\n\n    if (newItem.key !== key) {\n      return failWithDetail(\n        `$[key}: key mismatch in created item - ${newItem.key} !== ${key}`,\n        'invalid-key'\n      );\n    }\n    if (newItem.index !== this._byIndex.length) {\n      return failWithDetail(\n        `$[key}: index mismatch in created item - ${newItem.index} !== ${this._byIndex.length}`,\n        'invalid-index'\n      );\n    }\n    this._byKey.set(key, newItem);\n    this._byIndex.push(newItem);\n    return succeedWithDetail(newItem, 'added');\n  }\n\n  /**\n   * {@inheritdoc ICollector.getOrAddItem}\n   */\n  public getOrAddItem(item: TITEM): DetailedResult<TITEM, CollectorResultDetail> {\n    if (this._byKey.has(item.key)) {\n      return succeedWithDetail(this._byKey.get(item.key)!, 'exists');\n    }\n    const { message } = item.setIndex(this._byIndex.length);\n    if (message !== undefined) {\n      return failWithDetail(message, 'invalid-index');\n    }\n    this._byKey.set(item.key, item);\n    this._byIndex.push(item);\n    return succeedWithDetail(item, 'added');\n  }\n\n  /**\n   * {@inheritdoc IReadOnlyResultMap.has}\n   */\n  public has(key: TKEY): boolean {\n    return this._byKey.has(key);\n  }\n\n  /**\n   * {@inheritdoc ICollector.toReadOnly}\n   */\n  public toReadOnly(): IReadOnlyCollector<TKEY, TINDEX, 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<TKEY, TITEM>> {\n    return this._byKey[Symbol.iterator]();\n  }\n\n  /**\n   * A simple factory method for derived classes which directly store the supplied\n   * object.\n   * @param key - The key of the item to create.\n   * @param index - The index of the item to create.\n   * @param item - The source item to create.\n   * @returns `Success` with the created item and a detail of 'success', or\n   * `Failure` with an error message and appropriate detail.\n   */\n  protected static _simpleFactory<\n    TKEY extends string = string,\n    TINDEX extends number = number,\n    TITEM extends ICollectible<TKEY, TINDEX> = ICollectible<TKEY, TINDEX>\n  >(key: TKEY, index: number, item: TITEM): Result<TITEM> {\n    return item.setIndex(index).onSuccess(() => succeed(item));\n  }\n\n  protected _isFactoryCB(\n    item: TSRC | CollectibleFactoryCallback<TKEY, TINDEX, TITEM>\n  ): item is CollectibleFactoryCallback<TKEY, TINDEX, TITEM> {\n    return typeof item === 'function';\n  }\n}\n"]}
+{"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/**\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  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   * {@inheritdoc Collections.ResultMap.size}\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   * {@inheritdoc Collections.ResultMap.entries}\n   */\n  public entries(): MapIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>> {\n    return this._byKey.entries();\n  }\n\n  /**\n   * {@inheritdoc Collections.ResultMap.forEach}\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   * {@inheritdoc Collections.ResultMap.get}\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   * {@inheritdoc Collections.IReadOnlyCollector.getAt}\n   */\n  public getAt(index: number): Result<TITEM> {\n    if (index < 0 || index >= this._byIndex.length) {\n      return fail(`${index}: out of range.`);\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 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 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   * {@inheritdoc Collections.ResultMap.has}\n   */\n  public has(key: CollectibleKey<TITEM>): boolean {\n    return this._byKey.has(key);\n  }\n\n  /**\n   * {@inheritdoc Collections.ResultMap.keys}\n   */\n  public keys(): IterableIterator<CollectibleKey<TITEM>> {\n    return this._byKey.keys();\n  }\n\n  /**\n   * {@inheritdoc Collections.ResultMap.values}\n   */\n  public values(): IterableIterator<TITEM> {\n    return this._byKey.values();\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"]}