@fgv/ts-utils 5.0.2 → 5.1.0-0

package/dist/packlets/collections/collector.js

@@ -31,7 +31,7 @@ import { captureResult, failWithDetail, fail, succeed, succeedWithDetail } from
  */
 export class Collector {
     /**
-     * {@inheritdoc Collections.ResultMap.size}
+     * {@inheritDoc Collections.ResultMap.size}
      */
     get size() {
         return this._byIndex.length;
@@ -87,13 +87,13 @@ export class Collector {
         return succeedWithDetail(item, 'added');
     }
     /**
-     * {@inheritdoc Collections.ResultMap.entries}
+     * {@inheritDoc Collections.ResultMap.entries}
      */
     entries() {
         return this._byKey.entries();
     }
     /**
-     * {@inheritdoc Collections.ResultMap.forEach}
+     * {@inheritDoc Collections.ResultMap.forEach}
      */
     forEach(callback, arg) {
         for (const [key, value] of this._byKey.entries()) {
@@ -101,14 +101,14 @@ export class Collector {
         }
     }
     /**
-     * {@inheritdoc Collections.ResultMap.get}
+     * {@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}
+     * {@inheritDoc Collections.IReadOnlyCollector.getAt}
      */
     getAt(index) {
         if (typeof index !== 'number') {
@@ -146,25 +146,25 @@ export class Collector {
         });
     }
     /**
-     * {@inheritdoc Collections.ResultMap.has}
+     * {@inheritDoc Collections.ResultMap.has}
      */
     has(key) {
         return this._byKey.has(key);
     }
     /**
-     * {@inheritdoc Collections.ResultMap.keys}
+     * {@inheritDoc Collections.ResultMap.keys}
      */
     keys() {
         return this._byKey.keys();
     }
     /**
-     * {@inheritdoc Collections.ResultMap.values}
+     * {@inheritDoc Collections.ResultMap.values}
      */
     values() {
         return this._byKey.values();
     }
     /**
-     * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+     * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
      */
     valuesByIndex() {
         return this._byIndex;

package/dist/packlets/collections/collectorValidator.js

@@ -37,7 +37,7 @@ export class CollectorValidator {
         this.converters = params.converters;
     }
     /**
-     * {@inheritdoc Collections.Collector.add}
+     * {@inheritDoc Collections.Collector.add}
      */
     add(item) {
         return this._convertValue(item).onSuccess((i) => {
@@ -45,7 +45,7 @@ export class CollectorValidator {
         });
     }
     /**
-     * {@inheritdoc Collections.Collector.get}
+     * {@inheritDoc Collections.Collector.get}
      */
     get(key) {
         return this.converters.convertKey(key).onSuccess((k) => {
@@ -64,13 +64,13 @@ export class CollectorValidator {
         }
     }
     /**
-     * {@inheritdoc Collections.ResultMap.has}
+     * {@inheritDoc Collections.ResultMap.has}
      */
     has(key) {
         return this._collector.has(key);
     }
     /**
-     * {@inheritdoc Collections.Collector.toReadOnly}
+     * {@inheritDoc Collections.Collector.toReadOnly}
      */
     toReadOnly() {
         return this;

package/dist/packlets/collections/converters.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2026 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 { Success } from '../base';
+import { Converters } from '../conversion';
+/**
+ * A {@link Converter | Converter} for {@link Collections.KeyValueEntry | KeyValueEntry} instances.
+ * @param params - Conversion parameters.
+ * @returns A converter for which validates key value entries using the supplied validators.
+ * @public
+ */
+export function keyValueEntry(params) {
+    return Converters.generic((from) => {
+        return params.key.convert(from).onSuccess((key) => {
+            return params.value.convert(from).onSuccess((value) => {
+                return Success.with([key, value]);
+            });
+        });
+    });
+}
+//# sourceMappingURL=converters.js.map

package/dist/packlets/collections/convertingCollectorValidator.js

@@ -45,7 +45,7 @@ export class ConvertingCollectorValidator {
         return this.getOrAdd(key, valueOrFactory);
     }
     /**
-     * {@inheritdoc Collections.Collector.get}
+     * {@inheritDoc Collections.Collector.get}
      */
     get(key) {
         return this.converters.convertKey(key).onSuccess((k) => {
@@ -70,13 +70,13 @@ export class ConvertingCollectorValidator {
         }
     }
     /**
-     * {@inheritdoc Collections.ResultMap.has}
+     * {@inheritDoc Collections.ResultMap.has}
      */
     has(key) {
         return this._collector.has(key);
     }
     /**
-     * {@inheritdoc Collections.Collector.toReadOnly}
+     * {@inheritDoc Collections.Collector.toReadOnly}
      */
     toReadOnly() {
         return this;

package/dist/packlets/collections/convertingResultMap.js

@@ -0,0 +1,208 @@
+/*
+ * 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 } from '../base';
+import { ReadOnlyConvertingResultMap } from './readOnlyConvertingResultMap';
+/**
+ * A wrapper around a mutable result map that invalidates cache entries
+ * in the parent {@link Collections.ConvertingResultMap | ConvertingResultMap} when mutations occur.
+ * @public
+ */
+export class CacheInvalidatingResultMapWrapper {
+    /**
+     * Constructs a new cache-invalidating wrapper.
+     * @param inner - The inner map to wrap.
+     * @param parent - The parent converting map whose cache should be invalidated.
+     */
+    constructor(inner, parent) {
+        this._inner = inner;
+        this._parent = parent;
+    }
+    /**
+     * The number of entries in the map.
+     */
+    get size() {
+        return this._inner.size;
+    }
+    /**
+     * Adds a key/value pair to the map if the key does not already exist.
+     * Invalidates the cache entry for the key.
+     * @param key - The key to add.
+     * @param value - The value to add.
+     * @returns The result of the add operation.
+     */
+    add(key, value) {
+        this._parent._clearCacheEntry(key);
+        return this._inner.add(key, value);
+    }
+    /**
+     * Sets a key/value pair in the map.
+     * Invalidates the cache entry for the key.
+     * @param key - The key to set.
+     * @param value - The value to set.
+     * @returns The result of the set operation.
+     */
+    set(key, value) {
+        this._parent._clearCacheEntry(key);
+        return this._inner.set(key, value);
+    }
+    /**
+     * Updates an existing key in the map.
+     * Invalidates the cache entry for the key.
+     * @param key - The key to update.
+     * @param value - The new value.
+     * @returns The result of the update operation.
+     */
+    update(key, value) {
+        this._parent._clearCacheEntry(key);
+        return this._inner.update(key, value);
+    }
+    /**
+     * Deletes a key from the map.
+     * Invalidates the cache entry for the key.
+     * @param key - The key to delete.
+     * @returns The result of the delete operation.
+     */
+    delete(key) {
+        this._parent._clearCacheEntry(key);
+        return this._inner.delete(key);
+    }
+    /**
+     * Gets a value from the map.
+     * @param key - The key to retrieve.
+     * @returns The result of the get operation.
+     */
+    get(key) {
+        return this._inner.get(key);
+    }
+    getOrAdd(key, valueOrFactory) {
+        const result = typeof valueOrFactory === 'function'
+            ? this._inner.getOrAdd(key, valueOrFactory)
+            : this._inner.getOrAdd(key, valueOrFactory);
+        if (result.isSuccess() && result.detail === 'added') {
+            this._parent._clearCacheEntry(key);
+        }
+        return result;
+    }
+    /**
+     * Checks if the map contains a key.
+     * @param key - The key to check.
+     * @returns `true` if the key exists, `false` otherwise.
+     */
+    has(key) {
+        return this._inner.has(key);
+    }
+    /**
+     * Clears all entries from the map.
+     * Clears the entire cache.
+     */
+    clear() {
+        this._parent._clearCache();
+        this._inner.clear();
+    }
+    /**
+     * Returns an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    entries() {
+        return this._inner.entries();
+    }
+    /**
+     * Returns an iterator over the map keys.
+     * @returns An iterator over the map keys.
+     */
+    keys() {
+        return this._inner.keys();
+    }
+    /**
+     * Returns an iterator over the map values.
+     * @returns An iterator over the map values.
+     */
+    values() {
+        return this._inner.values();
+    }
+    /**
+     * Calls a callback for each entry in the map.
+     * @param cb - The callback to call for each entry.
+     * @param thisArg - Optional `this` argument for the callback.
+     */
+    forEach(cb, thisArg) {
+        this._inner.forEach(cb, thisArg);
+    }
+    /**
+     * Gets an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    [Symbol.iterator]() {
+        return this._inner[Symbol.iterator]();
+    }
+    /**
+     * Gets a read-only version of this map.
+     * @returns A read-only version of this map.
+     */
+    toReadOnly() {
+        return this._inner.toReadOnly();
+    }
+}
+/**
+ * A result map that wraps an inner {@link Collections.IResultMap | IResultMap} of source type
+ * and returns lazily-converted, cached values of a target type. Exposes the inner map
+ * via a {@link Collections.CacheInvalidatingResultMapWrapper | source} property that
+ * invalidates cache entries when mutations occur.
+ * @public
+ */
+export class ConvertingResultMap extends ReadOnlyConvertingResultMap {
+    /**
+     * Constructs a new {@link Collections.ConvertingResultMap | ConvertingResultMap}.
+     * @param params - Parameters for constructing the map.
+     */
+    constructor(params) {
+        super(params);
+        this._typedInner = params.inner;
+        this.source = new CacheInvalidatingResultMapWrapper(params.inner, this);
+    }
+    /**
+     * Creates a new {@link Collections.ConvertingResultMap | ConvertingResultMap}.
+     * @param params - Parameters for constructing the map.
+     * @returns `Success` with the new map, or `Failure` with error details if an error occurred.
+     */
+    static create(params) {
+        return captureResult(() => new ConvertingResultMap(params));
+    }
+    /**
+     * Clears a single entry from the cache.
+     * This method is public to allow the cache-invalidating wrapper to call it.
+     * @param key - The key to clear from the cache.
+     * @internal
+     */
+    _clearCacheEntry(key) {
+        super._clearCacheEntry(key);
+    }
+    /**
+     * Clears all entries from the cache.
+     * This method is public to allow the cache-invalidating wrapper to call it.
+     * @internal
+     */
+    _clearCache() {
+        super._clearCache();
+    }
+}
+//# sourceMappingURL=convertingResultMap.js.map

package/dist/packlets/collections/index.js

@@ -22,6 +22,7 @@
 import * as Utils from './utils';
 export * from './collectible';
 export * from './convertingCollector';
+export * from './convertingResultMap';
 export * from './collector';
 export * from './collectorValidator';
 export * from './convertingCollectorValidator';
@@ -29,9 +30,12 @@ export * from './validatingConvertingCollector';
 export * from './common';
 export * from './keyValueConverters';
 export * from './readonlyResultMap';
+export * from './readOnlyConvertingResultMap';
 export * from './resultMap';
 export * from './resultMapValidator';
 export * from './validatingCollector';
+export * from './validatingConvertingResultMap';
 export * from './validatingResultMap';
+export * from './aggregatedResultMap';
 export { Utils };
 //# sourceMappingURL=index.js.map

package/dist/packlets/collections/keyValueConverters.js

@@ -29,10 +29,7 @@ import { Converters } from '../conversion';
 export class KeyValueConverters {
     /**
      * Constructs a new key-value validator.
-     * @param key - Required key {@link Validator | validator}, {@link Converter | converter},
-     * or {@link Conversion.ConverterFunc | converter function}.
-     * @param value - Required value {@link Validator | validator}, {@link Converter | converter},
-     * or {@link Conversion.ConverterFunc | converter function}.
+     * @param params - Key and value converters or validators.
      */
     constructor({ key, value }) {
         this.key = typeof key === 'function' ? Converters.generic(key) : key;

package/dist/packlets/collections/readOnlyConvertingResultMap.js

@@ -0,0 +1,193 @@
+/*
+ * Copyright (c) 2026 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';
+/**
+ * A read-only result map that wraps an inner {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}
+ * of source type and returns lazily-converted, cached values of a target type.
+ * @public
+ */
+export class ReadOnlyConvertingResultMap {
+    /**
+     * Constructs a new {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.
+     * @param params - Parameters for constructing the map.
+     */
+    constructor(params) {
+        var _a;
+        this._inner = params.inner;
+        this._converter = params.converter;
+        this._cache = new Map();
+        this._onConversionError = (_a = params.onConversionError) !== null && _a !== void 0 ? _a : 'ignore';
+        this._logger = params.logger;
+    }
+    /**
+     * Creates a new {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.
+     * @param params - Parameters for constructing the map.
+     * @returns `Success` with the new map, or `Failure` with error details if an error occurred.
+     */
+    static create(params) {
+        return captureResult(() => new ReadOnlyConvertingResultMap(params));
+    }
+    /**
+     * The number of entries in the map.
+     */
+    get size() {
+        return this._inner.size;
+    }
+    /**
+     * Gets a converted value from the map by key.
+     * @param key - The key to retrieve.
+     * @returns `Success` with the converted value and detail `exists` if the key was found,
+     * `Failure` with detail `not-found` if the key was not found, or `Failure` with
+     * detail `invalid-value` if conversion failed.
+     */
+    get(key) {
+        const cached = this._cache.get(key);
+        if (cached !== undefined) {
+            return succeedWithDetail(cached, 'exists');
+        }
+        return this._inner.get(key).onSuccess((src) => {
+            return this._convertAndCache(key, src);
+        });
+    }
+    /**
+     * Checks if the map contains a key.
+     * @param key - The key to check.
+     * @returns `true` if the key exists, `false` otherwise.
+     */
+    has(key) {
+        return this._inner.has(key);
+    }
+    /**
+     * Returns an iterator over the map entries with converted values.
+     * @returns An iterator over the map entries.
+     */
+    *entries() {
+        for (const [key, src] of this._inner.entries()) {
+            const target = this._getOrConvert(key, src);
+            if (target !== undefined) {
+                yield [key, target];
+            }
+        }
+    }
+    /**
+     * Returns an iterator over the map keys.
+     * @returns An iterator over the map keys.
+     */
+    keys() {
+        return this._inner.keys();
+    }
+    /**
+     * Returns an iterator over the converted map values.
+     * @returns An iterator over the map values.
+     */
+    *values() {
+        for (const [key, src] of this._inner.entries()) {
+            const target = this._getOrConvert(key, src);
+            if (target !== undefined) {
+                yield target;
+            }
+        }
+    }
+    /**
+     * Calls a callback for each entry in the map with converted values.
+     * @param cb - The callback to call for each entry.
+     * @param thisArg - Optional `this` argument for the callback.
+     */
+    forEach(cb, thisArg) {
+        for (const [key, src] of this._inner.entries()) {
+            const target = this._getOrConvert(key, src);
+            if (target !== undefined) {
+                cb.call(thisArg, target, key, this);
+            }
+        }
+    }
+    /**
+     * Gets an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    /**
+     * Gets a read-only version of this map.
+     * @returns A read-only version of this map.
+     */
+    toReadOnly() {
+        return this;
+    }
+    /**
+     * Converts a source value to a target value and caches the result.
+     * @param key - The key of the value.
+     * @param src - The source value to convert.
+     * @returns `Success` with the converted value if successful, `Failure` otherwise.
+     */
+    _convertAndCache(key, src) {
+        const result = this._converter(src, key);
+        if (result.isFailure()) {
+            return failWithDetail(result.message, 'invalid-value');
+        }
+        this._cache.set(key, result.value);
+        return succeedWithDetail(result.value, 'exists');
+    }
+    /**
+     * Gets a cached value or converts and caches a source value.
+     * Used by iterators. Handles conversion failures according to `_onConversionError`.
+     * @param key - The key of the value.
+     * @param src - The source value to convert if not cached.
+     * @returns The converted value, or `undefined` if conversion failed.
+     * @throws Error if `_onConversionError` is `'fail'` and conversion fails.
+     */
+    _getOrConvert(key, src) {
+        var _a;
+        const cached = this._cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = this._converter(src, key);
+        if (result.isSuccess()) {
+            this._cache.set(key, result.value);
+            return result.value;
+        }
+        switch (this._onConversionError) {
+            case 'fail':
+                throw new Error(`Conversion failed for key '${key}': ${result.message}`);
+            case 'warn':
+                (_a = this._logger) === null || _a === void 0 ? void 0 : _a.log('warning', `Conversion failed for key '${key}': ${result.message}`);
+                break;
+        }
+        return undefined;
+    }
+    /**
+     * Clears a single entry from the cache.
+     * @param key - The key to clear from the cache.
+     */
+    _clearCacheEntry(key) {
+        this._cache.delete(key);
+    }
+    /**
+     * Clears all entries from the cache.
+     */
+    _clearCache() {
+        this._cache.clear();
+    }
+}
+//# sourceMappingURL=readOnlyConvertingResultMap.js.map