@fgv/ts-utils 5.0.1-9 → 5.0.1

package/dist/packlets/base/utils.js

@@ -0,0 +1,185 @@
+/*
+ * Copyright (c) 2020 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.
+ */
+import { fail, succeed } from './result';
+/**
+ * Helper type-guard function to report whether a specified key is present in
+ * a supplied object.
+ * @param key - The key to be tested.
+ * @param item - The object to be tested.
+ * @returns Returns `true` if the key is present, `false` otherwise.
+ * @public
+ */
+export function isKeyOf(key, item) {
+    return item.hasOwnProperty(key);
+}
+/**
+ * Simple implicit pick function, which picks a set of properties from a supplied
+ * object.  Ignores picked properties that do not exist regardless of type signature.
+ * @param from - The object from which keys are to be picked.
+ * @param include - The keys of the properties to be picked from `from`.
+ * @returns A new object containing the requested properties from `from`, where present.
+ * @public
+ */
+export function pick(from, include) {
+    const rtrn = {};
+    for (const key of include) {
+        if (key in from) {
+            rtrn[key] = from[key];
+        }
+    }
+    return rtrn;
+}
+/**
+ * Simple implicit omit function, which picks all of the properties from a supplied
+ * object except those specified for exclusion.
+ * @param from - The object from which keys are to be picked.
+ * @param exclude - The keys of the properties to be excluded from the returned object.
+ * @returns A new object containing all of the properties from `from` that were not
+ * explicitly excluded.
+ * @public
+ */
+export function omit(from, exclude) {
+    const rtrn = {};
+    for (const entry of Object.entries(from).filter((e) => !exclude.includes(e[0]))) {
+        rtrn[entry[0]] = entry[1];
+    }
+    return rtrn;
+}
+/**
+ * Gets the value of a property specified by key from an arbitrary object,
+ * or a default value if the property does not exist.
+ * @param key - The key specifying the property to be retrieved.
+ * @param item - The object from which the property is to be retrieved.
+ * @param defaultValue - An optional default value to be returned if the property
+ * is not present (default `undefined`).
+ * @returns The value of the requested property, or the default value if the
+ * requested property does not exist.
+ * @public
+ */
+export function getValueOfPropertyOrDefault(key, item, defaultValue) {
+    return isKeyOf(key, item) ? item[key] : defaultValue;
+}
+/**
+ * Gets the type of a property specified by key from an arbitrary object.
+ * @param key - The key specifying the property to be tested.
+ * @param item - The object from which the property is to be tested.
+ * @returns The type of the requested property, or `undefined` if the
+ * property does not exist.
+ * @example
+ * Returns `'undefined'` (a string) if the property exists but has the value
+ * undefined but `undefined` (the literal) if the property does not exist.
+ * @public
+ */
+export function getTypeOfProperty(key, item) {
+    return isKeyOf(key, item) ? typeof item[key] : undefined;
+}
+/**
+ * Applies a factory method to convert a `Record<TK, TS>` into a `Map<TK, TD>`.
+ * @param src - The `Record` to be converted.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting map on success, or {@link Failure} with a
+ * message if an error occurs.
+ * @public
+ */
+export function recordToMap(src, factory) {
+    const map = new Map();
+    for (const key in src) {
+        if (src[key] !== undefined) {
+            const itemResult = factory(key, src[key]);
+            if (itemResult.isSuccess()) {
+                map.set(key, itemResult.value);
+            }
+            else {
+                return fail(`${key}: ${itemResult.message}`);
+            }
+        }
+    }
+    return succeed(map);
+}
+/**
+ * Applies a factory method to convert an optional `Record<TK, TS>` into a `Map<TK, TD>`, or `undefined`.
+ * @param src - The `Record` to be converted, or undefined.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting map if conversion succeeds, or {@link Success} with `undefined`
+ * if `src` is `undefined`. Returns {@link Failure} with a message if an error occurs.
+ * @public
+ */
+export function optionalRecordToMap(src, factory) {
+    return src === undefined ? succeed(undefined) : recordToMap(src, factory);
+}
+/**
+ * Applies a factory method to convert an optional `Record<TK, TS>` into a `Map<TK, TD>`
+ * @param src - The `Record` to be converted, or `undefined`.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting map (empty if `src` is `undefined`) if conversion succeeds.
+ * Returns {@link Failure} with a message if an error occurs.
+ * @public
+ */
+export function optionalRecordToPossiblyEmptyMap(src, factory) {
+    return src === undefined ? succeed(new Map()) : recordToMap(src, factory);
+}
+/**
+ * Applies a factory method to convert a `ReadonlyMap<TK, TS>` into a `Record<TK, TD>`.
+ * @param src - The `Map` object to be converted.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting `Record<TK, TD>` if conversion succeeds, or
+ * {@link Failure} with an error message if an error occurs.
+ * @public
+ */
+export function mapToRecord(src, factory) {
+    const record = {};
+    for (const kvp of src) {
+        if (kvp[1] !== undefined) {
+            const itemResult = factory(kvp[0], kvp[1]);
+            if (itemResult.isSuccess()) {
+                record[kvp[0]] = itemResult.value;
+            }
+            else {
+                return fail(`${kvp[0]}: ${itemResult.message}`);
+            }
+        }
+    }
+    return succeed(record);
+}
+/**
+ * Applies a factory method to convert an optional `ReadonlyMap<string, TS>` into a `Record<string, TD>` or `undefined`.
+ * @param src - The `Map` object to be converted, or `undefined`.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting record if conversion succeeds, or {@link Success} with `undefined` if
+ * `src` is `undefined`. Returns {@link Failure} with a message if an error occurs.
+ * @public
+ */
+export function optionalMapToRecord(src, factory) {
+    return src === undefined ? succeed(undefined) : mapToRecord(src, factory);
+}
+/**
+ * Applies a factory method to convert an optional `ReadonlyMap<string, TS>` into a `Record<string, TD>`
+ * @param src - The `ReadonlyMap` object to be converted, or `undefined`.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting record (empty if `src` is `undefined`) if conversion succeeds.
+ * Returns {@link Failure} with a message if an error occurs.
+ * @public
+ */
+export function optionalMapToPossiblyEmptyRecord(src, factory) {
+    return src === undefined ? succeed({}) : mapToRecord(src, factory);
+}
+//# sourceMappingURL=utils.js.map

package/dist/packlets/collections/collectible.js

@@ -0,0 +1,82 @@
+/*
+ * 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.
+ */
+import { captureResult, fail, succeed } from '../base';
+import { Converters } from '../conversion';
+/**
+ * Simple implementation of {@link Collections.ICollectible | ICollectible} which does not allow the index to be
+ * changed once set.
+ * @public
+ */
+export class Collectible {
+    /**
+     * {@link Collections.ICollectible.index}
+     */
+    get index() {
+        return this._index;
+    }
+    constructor(params) {
+        this.key = params.key;
+        if ('indexConverter' in params) {
+            this._indexConverter =
+                typeof params.indexConverter === 'function'
+                    ? Converters.generic(params.indexConverter)
+                    : params.indexConverter;
+            if (params.index !== undefined) {
+                this._index = this._indexConverter.convert(params.index).orThrow();
+            }
+        }
+        else {
+            /* c8 ignore next 3 - coverage is having a bad day */
+            this._index = params.index;
+        }
+    }
+    static createCollectible(params) {
+        return captureResult(() => new Collectible(params));
+    }
+    /**
+     * {@link Collections.ICollectible.setIndex}
+     */
+    setIndex(index) {
+        let converted;
+        if (this._indexConverter) {
+            const { value, message } = this._indexConverter.convert(index);
+            /* c8 ignore next 3 - there's a test for this but coverage is having a bad day */
+            if (message) {
+                return fail(message);
+            }
+            converted = value;
+        }
+        if (index === this.index) {
+            return succeed(this.index);
+        }
+        else if (this._index !== undefined) {
+            return fail(`index ${this.index} is immutable and cannot be changed to ${index}`);
+        }
+        /* c8 ignore next 3 - should be impossible */
+        if (converted === undefined) {
+            return fail(`index ${index} cannot be set on a Collectible without an index converter`);
+        }
+        this._index = converted;
+        return succeed(converted);
+    }
+}
+//# sourceMappingURL=collectible.js.map

package/dist/packlets/collections/collector.js

@@ -0,0 +1,189 @@
+/*
+ * 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.
+ */
+import { captureResult, failWithDetail, fail, succeed, succeedWithDetail } from '../base';
+/**
+ * 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 class Collector {
+    /**
+     * {@inheritdoc Collections.ResultMap.size}
+     */
+    get size() {
+        return this._byIndex.length;
+    }
+    /**
+     * 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 = [];
+        for (const item of (_a = params === null || params === void 0 ? void 0 : params.items) !== null && _a !== void 0 ? _a : []) {
+            this.add(item).orThrow();
+        }
+    }
+    /**
+     * 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.
+     */
+    static createCollector(params) {
+        return captureResult(() => new Collector(params));
+    }
+    /**
+     * Adds an item to the collection, failing if a different item with the same key already exists. Note
+     * that adding an object that is already in the collection again will succeed without updating the collection.
+     * @param item - The item to add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+     * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+     * an error message and appropriate detail if the item could not be added.
+     */
+    add(item) {
+        const existing = this._byKey.get(item.key);
+        if (existing === item) {
+            return succeedWithDetail(item, 'exists');
+        }
+        else if (existing) {
+            return failWithDetail(`${item.key}: already exists`, 'exists');
+        }
+        const indexResult = item.setIndex(this._byIndex.length);
+        if (indexResult.isFailure()) {
+            return failWithDetail(`${item.key}: ${indexResult.message}`, 'invalid-index');
+        }
+        else if (item.index !== this._byIndex.length) {
+            return failWithDetail(`${item.key}: index mismatch - built item has ${item.index}`, 'invalid-index');
+        }
+        this._byKey.set(item.key, item);
+        this._byIndex.push(item);
+        return succeedWithDetail(item, 'added');
+    }
+    /**
+     * {@inheritdoc Collections.ResultMap.entries}
+     */
+    entries() {
+        return this._byKey.entries();
+    }
+    /**
+     * {@inheritdoc Collections.ResultMap.forEach}
+     */
+    forEach(callback, arg) {
+        for (const [key, value] of this._byKey.entries()) {
+            callback(value, key, this, arg);
+        }
+    }
+    /**
+     * {@inheritdoc Collections.ResultMap.get}
+     */
+    get(key) {
+        const item = this._byKey.get(key);
+        return item ? succeedWithDetail(item, 'exists') : failWithDetail(`${key}: not found`, 'not-found');
+    }
+    /**
+     * {@inheritdoc Collections.IReadOnlyCollector.getAt}
+     */
+    getAt(index) {
+        if (typeof index !== 'number') {
+            // Handle Symbol conversion safely
+            const indexStr = typeof index === 'symbol' ? index.toString() : String(index);
+            return fail(`${indexStr}: collector index must be a number.`);
+        }
+        // Check that the number is a finite integer (handles NaN, Infinity, and non-integers)
+        if (!Number.isFinite(index) || !Number.isInteger(index)) {
+            return fail(`${index}: collector index must be a finite integer.`);
+        }
+        if (index < 0 || index >= this._byIndex.length) {
+            return fail(`${index}: collector index out of range.`);
+        }
+        return succeed(this._byIndex[index]);
+    }
+    getOrAdd(keyOrItem, factory) {
+        const key = !this._isItem(keyOrItem) ? keyOrItem : keyOrItem.key;
+        const existing = this._byKey.get(key);
+        if (existing) {
+            return succeedWithDetail(existing, 'exists');
+        }
+        const itemResult = !this._isItem(keyOrItem)
+            ? factory(keyOrItem, this._byIndex.length)
+            : succeed(keyOrItem);
+        if (itemResult.isFailure()) {
+            return failWithDetail(`${key}: ${itemResult.message}`, 'invalid-value');
+        }
+        const item = itemResult.value;
+        if (item.key !== key) {
+            return failWithDetail(`${key}: key mismatch - built item has ${key}`, 'invalid-key');
+        }
+        return itemResult.withFailureDetail('invalid-index').onSuccess((item) => {
+            return this.add(item);
+        });
+    }
+    /**
+     * {@inheritdoc Collections.ResultMap.has}
+     */
+    has(key) {
+        return this._byKey.has(key);
+    }
+    /**
+     * {@inheritdoc Collections.ResultMap.keys}
+     */
+    keys() {
+        return this._byKey.keys();
+    }
+    /**
+     * {@inheritdoc Collections.ResultMap.values}
+     */
+    values() {
+        return this._byKey.values();
+    }
+    /**
+     * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+     */
+    valuesByIndex() {
+        return this._byIndex;
+    }
+    /**
+     * Gets a read-only version of this collector.
+     */
+    toReadOnly() {
+        return this;
+    }
+    /**
+     * Gets an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    [Symbol.iterator]() {
+        return this._byKey[Symbol.iterator]();
+    }
+    _isItem(keyOrItem) {
+        return typeof keyOrItem !== 'string';
+    }
+}
+//# sourceMappingURL=collector.js.map

package/dist/packlets/collections/collectorValidator.js

@@ -0,0 +1,94 @@
+/*
+ * 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.
+ */
+/**
+ * A {@link Collections.Collector | Collector} wrapper which validates weakly-typed keys
+ * and values before calling the wrapped collector.
+ * @public
+ */
+export 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');
+    }
+}
+//# sourceMappingURL=collectorValidator.js.map

package/dist/packlets/collections/common.js

@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=common.js.map

package/dist/packlets/collections/convertingCollector.js

@@ -0,0 +1,118 @@
+/*
+ * 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.
+ */
+import { captureResult, failWithDetail, succeedWithDetail } from '../base';
+import { Collector } from './collector';
+/**
+ * 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 class ConvertingCollector extends Collector {
+    /**
+     * Constructs a new {@link Collections.ConvertingCollector | ConvertingCollector}.
+     * @param params - Parameters for constructing the collector.
+     */
+    constructor(params) {
+        var _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}.
+     * @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.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static createConvertingCollector(params) {
+        return captureResult(() => new ConvertingCollector(params));
+    }
+    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._buildItem(keyOrItem, itemOrCb)
+            .withFailureDetail('invalid-value')
+            .onSuccess((item) => {
+            if (item.key !== keyOrItem) {
+                return failWithDetail(`${keyOrItem}: key mismatch - item has unexpected key ${item.key}`, 'invalid-key');
+            }
+            return succeedWithDetail(item, 'success');
+        })
+            .onSuccess((item) => {
+            return super.add(item);
+        });
+    }
+    /**
+     * 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
+     */
+    _buildItem(key, itemOrCb) {
+        return this._isFactoryCB(itemOrCb) ? itemOrCb(key, this.size) : this._factory(key, this.size, itemOrCb);
+    }
+}
+//# sourceMappingURL=convertingCollector.js.map