@fgv/ts-utils 5.0.0-12 → 5.0.0-14

package/src/packlets/collections/convertingCollector.ts

@@ -0,0 +1,223 @@
+/*
+ * 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, DetailedResult, failWithDetail, Result, succeedWithDetail } from '../base';
+import { ICollectible, CollectibleFactoryCallback, CollectibleFactory, CollectibleKey } from './collectible';
+import { Collector, CollectorResultDetail } from './collector';
+import { KeyValueEntry } from './common';
+
+/**
+ * Parameters for constructing a {@link Collections.ConvertingCollector | ConvertingCollector}.
+ * @public
+ */
+export interface IConvertingCollectorConstructorParams<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TITEM extends ICollectible<any, any>,
+  TSRC = TITEM
+> {
+  /**
+   * The default {@link Collections.CollectibleFactory | factory} to create items.
+   */
+  factory: CollectibleFactory<TITEM, TSRC>;
+  /**
+   * An optional array of entries to add to the collector.
+   */
+  entries?: KeyValueEntry<CollectibleKey<TITEM>, TSRC>[];
+}
+
+/**
+ * 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<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TITEM extends ICollectible<any, any>,
+  TSRC = TITEM
+> extends Collector<TITEM> {
+  private _factory: CollectibleFactory<TITEM, TSRC>;
+
+  /**
+   * Constructs a new {@link Collections.ConvertingCollector | ConvertingCollector}.
+   * @param params - Parameters for constructing the collector.
+   */
+  public constructor(params: IConvertingCollectorConstructorParams<TITEM, TSRC>) {
+    super();
+    this._factory = params.factory;
+    params.entries?.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
+  public static createConvertingCollector<TITEM extends ICollectible<any, any>, TSRC = TITEM>(
+    params: IConvertingCollectorConstructorParams<TITEM, TSRC>
+  ): Result<ConvertingCollector<TITEM, TSRC>> {
+    return captureResult(() => new ConvertingCollector(params));
+  }
+
+  /**
+   * {@inheritdoc Collections.Collector.add}
+   */
+  public add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
+
+  /**
+   * Adds an item to the collector using the default {@link Collections.CollectibleFactory | factory}
+   * at a specified key, failing if an item with that key already exists.
+   * @param key - The key of the item to add.
+   * @param item - The source representation of the item to be added.
+   * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with
+   * an error if the item cannot be created and indexed.
+   * @public
+   */
+  public add(key: CollectibleKey<TITEM>, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;
+
+  /**
+   * Adds an item to the collector using a supplied {@link Collections.CollectibleFactoryCallback | factory callback}
+   * at a specified key, failing if an item with that key already exists or if the created item is invalid.
+   * @param key - The key of the item to add.
+   * @param callback - The factory callback to create the item.
+   * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with
+   * an error if the item cannot be created and indexed.
+   */
+  public add(
+    key: CollectibleKey<TITEM>,
+    cb: CollectibleFactoryCallback<TITEM>
+  ): DetailedResult<TITEM, CollectorResultDetail>;
+
+  public add(
+    keyOrItem: CollectibleKey<TITEM> | TITEM,
+    itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>
+  ): DetailedResult<TITEM, CollectorResultDetail> {
+    if (this._overloadIsItem(keyOrItem, itemOrCb)) {
+      return super.add(keyOrItem);
+    }
+    return this._buildItem(keyOrItem, itemOrCb!)
+      .withFailureDetail<CollectorResultDetail>('invalid-value')
+      .onSuccess((item) => {
+        return super.add(item);
+      });
+  }
+
+  /**
+   * {@inheritdoc Collections.Collector.(getOrAdd:1)}
+   */
+  public getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
+
+  /**
+   * {@inheritdoc Collections.Collector.(getOrAdd:2)}
+   */
+  public getOrAdd(
+    key: CollectibleKey<TITEM>,
+    callback: CollectibleFactoryCallback<TITEM>
+  ): DetailedResult<TITEM, CollectorResultDetail>;
+
+  /**
+   * Gets an item by key if it exists, or creates a new item and adds it using the default {@link Collections.CollectibleFactory | factory} if not.
+   * @param key - The key of the item to retrieve.
+   * @param item - The source representation of the item to be added if it does not exist.
+   * @returns Returns {@link Success | Success} with the item if it exists or could be created, or {@link Failure | Failure} with an error if the
+   * item cannot be created and indexed.
+   */
+  public getOrAdd(key: CollectibleKey<TITEM>, item: TSRC): DetailedResult<TITEM, CollectorResultDetail>;
+
+  public getOrAdd(
+    keyOrItem: CollectibleKey<TITEM> | TITEM,
+    itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>
+  ): DetailedResult<TITEM, CollectorResultDetail> {
+    if (this._overloadIsItem(keyOrItem, itemOrCb)) {
+      return super.getOrAdd(keyOrItem);
+    }
+
+    if (this.has(keyOrItem)) {
+      return this.get(keyOrItem);
+    }
+
+    return this._buildItem(keyOrItem, itemOrCb!)
+      .withFailureDetail<CollectorResultDetail>('invalid-value')
+      .onSuccess((item) => {
+        if (item.key !== keyOrItem) {
+          return failWithDetail<TITEM, CollectorResultDetail>(
+            `${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
+   */
+  protected _isFactoryCB(
+    itemOrCb: TSRC | CollectibleFactoryCallback<TITEM>
+  ): itemOrCb is CollectibleFactoryCallback<TITEM> {
+    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
+   */
+  protected _overloadIsItem(
+    keyOrItem: CollectibleKey<TITEM> | TITEM,
+    itemOrCb?: TSRC | CollectibleFactoryCallback<TITEM>
+  ): keyOrItem is TITEM {
+    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
+   */
+  protected _buildItem(
+    key: CollectibleKey<TITEM>,
+    itemOrCb: TSRC | CollectibleFactoryCallback<TITEM>
+  ): Result<TITEM> {
+    return this._isFactoryCB(itemOrCb) ? itemOrCb(key, this.size) : this._factory(key, this.size, itemOrCb);
+  }
+}

package/src/packlets/collections/convertingCollectorValidator.ts

@@ -0,0 +1,164 @@
+/*
+ * 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 { DetailedResult, failWithDetail } from '../base';
+import { IReadOnlyResultMap, ResultMapResultDetail } from './readonlyResultMap';
+import { ResultMapValueFactory } from './resultMap';
+import { KeyValueConverters } from './keyValueConverters';
+import { CollectibleFactoryCallback, CollectibleKey, ICollectible } from './collectible';
+import { CollectorResultDetail } from './collector';
+import { ConvertingCollector } from './convertingCollector';
+import { IReadOnlyCollectorValidator } from './collectorValidator';
+
+/**
+ * Parameters for constructing a {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.
+ * @public
+ */
+export interface IConvertingCollectorValidatorCreateParams<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TITEM extends ICollectible<any, any>,
+  TSRC = TITEM
+> {
+  collector: ConvertingCollector<TITEM, TSRC>;
+  converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;
+}
+
+/**
+ * A {@link Collections.ConvertingCollector | ConvertingCollector} wrapper which validates weakly-typed keys
+ * and values before calling the wrapped collector.  Unlike the basic {@link Collections.CollectorValidator | CollectorValidator},
+ * the converting collector expects the items to be in the source type of the converting collector, not the target type.
+ * @public
+ */
+export class ConvertingCollectorValidator<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TITEM extends ICollectible<any, any>,
+  TSRC = TITEM
+> implements IReadOnlyCollectorValidator<TITEM>
+{
+  public readonly converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;
+
+  public get map(): IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM> {
+    return this._collector.toReadOnly();
+  }
+
+  protected _collector: ConvertingCollector<TITEM, TSRC>;
+
+  /**
+   * Constructs a new {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}.
+   * @param params - Required parameters for constructing the collector validator.
+   */
+  public constructor(params: IConvertingCollectorValidatorCreateParams<TITEM, TSRC>) {
+    this._collector = params.collector;
+    this.converters = params.converters;
+  }
+
+  /**
+   * {@inheritdoc Collections.ConvertingCollector.(add:1)}
+   */
+  public add(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
+
+  /**
+   * {@inheritdoc Collections.ConvertingCollector.(add:2)}
+   */
+  public add(
+    key: string,
+    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>
+  ): DetailedResult<TITEM, CollectorResultDetail>;
+  public add(
+    key: string,
+    valueOrFactory: unknown | ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>
+  ): DetailedResult<TITEM, CollectorResultDetail> {
+    if (this.has(key)) {
+      return failWithDetail(`${key}: already exists`, 'exists');
+    }
+    return this.getOrAdd(key, valueOrFactory);
+  }
+
+  /**
+   * {@inheritdoc Collections.Collector.get}
+   */
+  public get(key: string): DetailedResult<TITEM, ResultMapResultDetail> {
+    return this.converters.convertKey(key).onSuccess((k) => {
+      return this._collector.get(k);
+    });
+  }
+
+  /**
+   * {@inheritdoc Collections.ConvertingCollector.(getOrAdd:3)}
+   */
+  public getOrAdd(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
+
+  /**
+   * {@inheritdoc Collections.Collector.(getOrAdd:2)}
+   */
+  public getOrAdd(
+    key: string,
+    factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>
+  ): DetailedResult<TITEM, CollectorResultDetail>;
+
+  public getOrAdd(
+    key: string,
+    valueOrFactory: unknown | CollectibleFactoryCallback<TITEM>
+  ): DetailedResult<TITEM, CollectorResultDetail> {
+    if (!this._isCollectibleFactoryCallback(valueOrFactory)) {
+      const converted = this.converters.convertEntry([key, valueOrFactory]);
+      if (converted.isFailure()) {
+        return failWithDetail(converted.message, converted.detail);
+      }
+      const [vk, vs] = converted.value;
+      return this._collector.getOrAdd(vk, vs);
+    } else {
+      const converted = this.converters.convertKey(key);
+      if (converted.isFailure()) {
+        return failWithDetail(converted.message, converted.detail);
+      }
+      return this._collector.getOrAdd(converted.value, valueOrFactory);
+    }
+  }
+
+  /**
+   * {@inheritdoc Collections.ResultMap.has}
+   */
+  public has(key: string): boolean {
+    return this._collector.has(key as CollectibleKey<TITEM>);
+  }
+
+  /**
+   * {@inheritdoc Collections.Collector.toReadOnly}
+   */
+  public toReadOnly(): IReadOnlyCollectorValidator<TITEM> {
+    return this;
+  }
+
+  /**
+   * Determines if a value is a {@link Collections.CollectibleFactoryCallback | CollectibleFactoryCallback}.
+   * @param value - The value to check.
+   * @returns `true` if the value is a {@link Collections.CollectibleFactoryCallback | CollectibleFactoryCallback},
+   * `false` otherwise.
+   * @public
+   */
+  protected _isCollectibleFactoryCallback(
+    value: unknown | CollectibleFactoryCallback<TITEM>
+  ): value is CollectibleFactoryCallback<TITEM> {
+    return typeof value === 'function';
+  }
+}

package/src/packlets/collections/index.ts

@@ -0,0 +1,39 @@
+/*
+ * 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 * as Utils from './utils';
+
+export * from './collectible';
+export * from './convertingCollector';
+export * from './collector';
+export * from './collectorValidator';
+export * from './convertingCollectorValidator';
+export * from './validatingConvertingCollector';
+export * from './common';
+export * from './keyValueConverters';
+export * from './readonlyResultMap';
+export * from './resultMap';
+export * from './resultMapValidator';
+export * from './validatingCollector';
+export * from './validatingResultMap';
+
+export { Utils };

package/src/packlets/collections/keyValueConverters.ts

@@ -0,0 +1,142 @@
+/*
+ * 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 {
+  DetailedResult,
+  failWithDetail,
+  MessageAggregator,
+  Result,
+  succeed,
+  succeedWithDetail
+} from '../base';
+import { Converter, ConverterFunc, Converters } from '../conversion';
+import { Validator } from '../validation';
+import { KeyValueEntry } from './common';
+import { ResultMapResultDetail } from './readonlyResultMap';
+
+/**
+ * Parameters for constructing a {@link Collections.KeyValueConverters | KeyValueConverters} instance.
+ * @public
+ */
+export interface IKeyValueConverterConstructorParams<TK extends string = string, TV = unknown> {
+  /**
+   * Required key {@link Validator | validator}, {@link Converter | converter},
+   * or {@link Conversion.ConverterFunc | converter function}.
+   */
+  key: Validator<TK, unknown> | Converter<TK, unknown> | ConverterFunc<TK, unknown>;
+
+  /**
+   * Required value {@link Validator | validator}, {@link Converter | converter},
+   * or {@link Conversion.ConverterFunc | converter function}.
+   */
+  value: Validator<TV, unknown> | Converter<TV, unknown> | ConverterFunc<TV, unknown>;
+}
+
+/**
+ * Helper class for converting strongly-typed keys, values, or entries
+ * from unknown values.
+ * @public
+ */
+export class KeyValueConverters<TK extends string = string, TV = unknown> {
+  /**
+   * Required key {@link Validator | validator} or {@link Converter | converter}.
+   */
+  public readonly key: Validator<TK, unknown> | Converter<TK, unknown>;
+  /**
+   * Required value {@link Validator | validator} or {@link Converter | converter}.
+   */
+  public readonly value: Validator<TV, unknown> | Converter<TV, unknown>;
+
+  /**
+   * 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}.
+   */
+  public constructor({ key, value }: IKeyValueConverterConstructorParams<TK, TV>) {
+    this.key = typeof key === 'function' ? Converters.generic(key) : key;
+    this.value = typeof value === 'function' ? Converters.generic(value) : value;
+  }
+
+  /**
+   * Converts a supplied unknown to a valid key value of type `<TK>`.
+   * @param key - The unknown to be converted.
+   * @returns `Success` with the converted key value and 'success' detail if the key is valid,
+   * or `Failure` with an error message and 'invalid-key' detail if the key is invalid.
+   */
+  public convertKey(key: unknown): DetailedResult<TK, ResultMapResultDetail> {
+    return this.key.convert(key).withFailureDetail('invalid-key');
+  }
+
+  /**
+   * Converts a supplied unknown to a valid value of type `<TV>`.
+   * @param key - The unknown to be converted.
+   * @returns `Success` with the converted value and 'success' detail if the value is valid,
+   * or `Failure` with an error message and 'invalid-value' detail if the value is invalid.
+   */
+  public convertValue(key: unknown): DetailedResult<TV, ResultMapResultDetail> {
+    return this.value.convert(key).withFailureDetail('invalid-value');
+  }
+
+  /**
+   * Converts a supplied unknown to a valid entry of type `[<TK>, <TV>]`.
+   * @param entry - The unknown to be converted.
+   * @returns `Success` with the converted entry and 'success' detail if the entry
+   * is valid, or `Failure` with an error message and 'invalid-key' or 'invalid-value' detail if
+   * the entry is invalid
+   */
+  public convertEntry(entry: unknown): DetailedResult<KeyValueEntry<TK, TV>, ResultMapResultDetail> {
+    if (Array.isArray(entry) && entry.length === 2) {
+      const errors = new MessageAggregator();
+      const key = this.convertKey(entry[0]).aggregateError(errors).orDefault();
+      const value = this.convertValue(entry[1]).aggregateError(errors).orDefault();
+      if (key && value) {
+        return succeedWithDetail([key, value], 'success');
+      }
+      const detail = key ? 'invalid-value' : 'invalid-key';
+      return failWithDetail(`invalid entry: ${errors.toString()}`, detail);
+    }
+    /* c8 ignore next 2 */
+    return failWithDetail(`malformed entry: "${JSON.stringify(entry)}"`, 'invalid-value');
+  }
+
+  /**
+   * Converts a supplied iterable of unknowns to valid key-value pairs.
+   * @param entries - The iterable of unknowns to be converted.
+   * @returns `Success` with an array of converted key-value pairs if all entries are valid,
+   * or `Failure` with an error message if any entry is invalid.
+   */
+  public convertEntries(entries: Iterable<unknown>): Result<KeyValueEntry<TK, TV>[]> {
+    const errors = new MessageAggregator();
+    const converted: KeyValueEntry<TK, TV>[] = [];
+    for (const element of entries) {
+      this.convertEntry(element)
+        .onSuccess((e) => {
+          converted.push(e);
+          return succeedWithDetail(e, 'success');
+        })
+        .aggregateError(errors);
+    }
+    return errors.returnOrReport(succeed(converted));
+  }
+}

package/src/packlets/collections/readonlyResultMap.ts

@@ -0,0 +1,99 @@
+/*
+ * 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 { DetailedResult } from '../base';
+import { KeyValueEntry } from './common';
+
+/**
+ * Additional success or failure details for {@link Collections.ResultMap | ResultMap} calls.
+ * @public
+ */
+export type ResultMapResultDetail =
+  | 'added'
+  | 'deleted'
+  | 'exists'
+  | 'failure'
+  | 'invalid-key'
+  | 'invalid-value'
+  | 'not-found'
+  | 'success'
+  | 'updated';
+
+/**
+ * Callback for {@link Collections.ResultMap | ResultMap} `forEach` method.
+ * @public
+ */
+export type ResultMapForEachCb<TK extends string = string, TE = unknown> = (
+  value: TE,
+  key: TK,
+  map: IReadOnlyResultMap<TK, TE>,
+  thisArg?: unknown
+) => void;
+
+/**
+ * A readonly `ReadonlyMap<TK, TV>`-like object which reports success or failure
+ * with additional details using the
+ * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#the-result-pattern | result pattern}.
+ * @public
+ */
+export interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {
+  /**
+   * {@inheritdoc Collections.ResultMap.size}
+   */
+  readonly size: number;
+
+  /**
+   * {@inheritdoc Collections.ResultMap.entries}
+   */
+  entries(): IterableIterator<KeyValueEntry<TK, TV>>;
+
+  /**
+   * {@inheritdoc Collections.ResultMap.forEach}
+   */
+  forEach(cb: ResultMapForEachCb, arg?: unknown): void;
+
+  /**
+   * {@inheritdoc Collections.ResultMap.get}
+   */
+  get(key: TK): DetailedResult<TV, ResultMapResultDetail>;
+
+  /**
+   * {@inheritdoc Collections.ResultMap.has}
+   */
+  has(key: TK): boolean;
+
+  /**
+   * {@inheritdoc Collections.ResultMap.keys}
+   */
+  keys(): IterableIterator<TK>;
+
+  /**
+   * {@inheritdoc Collections.ResultMap.values}
+   */
+  values(): IterableIterator<TV>;
+
+  /**
+   * Gets an iterator over the map entries.
+   * @returns An iterator over the map entries.
+   */
+  [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TV>>;
+}