@fgv/ts-utils 4.1.0 → 4.2.0

package/dist/ts-utils.d.ts

@@ -22,7 +22,7 @@ export declare function allSucceed<T>(results: Iterable<Result<unknown>>, succes
  * @returns A {@link Converter | Converter} which returns an array of `<T>`.
  * @public
  */
-declare function arrayOf<T, TC = undefined>(converter: Converter<T, TC> | Validator<T, TC>, onError?: OnError): Converter<T[], TC>;
+declare function arrayOf<T, TC = unknown>(converter: Converter<T, TC> | Validator<T, TC>, onError?: OnError): Converter<T[], TC>;
 
 /**
  * Helper function to create a {@link Validation.Classes.ArrayValidator | ArrayValidator} which
@@ -84,7 +84,7 @@ declare namespace Base {
  * Base templated wrapper to simplify creation of new {@link Converter}s.
  * @public
  */
-declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
+declare class BaseConverter<T, TC = unknown> implements Converter<T, TC> {
     /**
      * @internal
      */
@@ -170,6 +170,10 @@ declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
      * @internal
      */
     protected _context(supplied?: TC): TC | undefined;
+    /**
+     * {@inheritdoc Converter.withFormattedError}
+     */
+    withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC>;
     /**
      * @internal
      */
@@ -187,7 +191,7 @@ declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
  * Anything else fails.
  * @public
  */
-declare const boolean: Converter<boolean, undefined>;
+declare const boolean: Converter<boolean, unknown>;
 
 /**
  * A {@link Validation.Classes.BooleanValidator | BooleanValidator} which validates a boolean in place.
@@ -261,6 +265,25 @@ declare namespace Classes {
     }
 }
 
+declare namespace Collections {
+    export {
+        Utils,
+        KeyValueEntry,
+        ResultMapResultDetail,
+        ResultMapForEachCb,
+        IReadOnlyResultMap,
+        IResultMapConstructorParams,
+        ResultMap,
+        IReadOnlyResultMapValidator,
+        IResultMapValidatorCreateParams,
+        ResultMapValidator,
+        IReadOnlyValidatingResultMap,
+        IValidatingResultMapConstructorParams,
+        ValidatingResultMap
+    }
+}
+export { Collections }
+
 /**
  * A {@link Validation.Constraint | Constraint<T>} function returns
  * `true` if the supplied value meets the constraint. Can return
@@ -296,6 +319,7 @@ declare namespace Conversion {
         BaseConverter,
         OnError,
         ConverterTraits,
+        ConversionErrorFormatter,
         ConstraintOptions,
         Converter,
         DefaultingConverter,
@@ -309,6 +333,16 @@ declare namespace Conversion {
 }
 export { Conversion }
 
+/**
+ * Formats an incoming error message and value that failed validation.
+ * @param val - The value that failed validation.
+ * @param message - The default error message, if any.
+ * @param context - Optional validation context.
+ * @returns The formatted error message.
+ * @public
+ */
+declare type ConversionErrorFormatter<TC = unknown> = (val: unknown, message?: string, context?: TC) => string;
+
 /**
  * Deprecated name for Infer<T> retained for compatibility
  * @deprecated use @see Infer instead
@@ -322,7 +356,7 @@ declare type ConvertedToType<TCONV> = Infer<TCONV>;
  * of optional templated type `<TC>` (default `undefined`).
  * @public
  */
-export declare interface Converter<T, TC = undefined> extends ConverterTraits {
+export declare interface Converter<T, TC = unknown> extends ConverterTraits {
     /**
      * Indicates whether this element is explicitly optional.
      */
@@ -390,7 +424,7 @@ export declare interface Converter<T, TC = undefined> extends ConverterTraits {
      * converted result from this {@link Converter}.
      * @returns A new {@link Converter} returning `<T2>`.
      */
-    mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
+    mapConvert<T2>(mapConverter: Converter<T2, unknown>): Converter<T2, TC>;
     /**
      * Creates a {@link Converter} which maps the individual items of a collection
      * resulting from this {@link Converter} using the supplied map function.
@@ -454,6 +488,13 @@ export declare interface Converter<T, TC = undefined> extends ConverterTraits {
      * @returns A new {@link Converter} returning `<T>`.
      */
     withConstraint(constraint: (val: T) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
+    /**
+     * Creates a new {@link Converter} which is derived from this one but which returns an
+     * error message formatted by the supplied formatter if the conversion fails.
+     * @param formatter - The formatter to be applied.
+     * @returns A new {@link Converter} returning `<T>`.
+     */
+    withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC>;
     /**
      * returns a converter which adds a brand to the type to prevent mismatched usage
      * of simple types.
@@ -530,7 +571,7 @@ declare class Crc32Normalizer extends HashingNormalizer {
 /**
  * @public
  */
-declare interface DefaultingConverter<T, TD = T, TC = undefined> extends Converter<T | TD, TC> {
+declare interface DefaultingConverter<T, TD = T, TC = unknown> extends Converter<T | TD, TC> {
     /**
      * Default value to use if the conversion fails.
      */
@@ -719,10 +760,10 @@ declare type DiscriminatedObjectConverters<T, TD extends string = string, TC = u
  * in the supplied array and can be converted. Returns {@link Failure | Failure} with an error message otherwise.
  * @param index - The index of the element to be extracted.
  * @param converter - A {@link Converter | Converter} or {@link Validator | Validator} for the extracted element.
- * @returns A {@link Converter | Converter<T>} which extracts the specified element from an array.
+ * @returns A {@link Converter | Converter<T, TC>} which extracts the specified element from an array.
  * @public
  */
-declare function element<T, TC = undefined>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
+declare function element<T, TC = unknown>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
 
 /**
  * @internal
@@ -866,7 +907,7 @@ export declare function failWithDetail<T, TD>(message: string, detail: TD): Deta
  * field.
  * @public
  */
-declare function field<T, TC = undefined>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
+declare function field<T, TC = unknown>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
 
 /**
  * Per-property converters or validators for each of the properties in type T.
@@ -933,7 +974,7 @@ declare interface FunctionConstraintTrait {
  * to substitute a supplied default value for any errors returned by the inner converter.
  * @public
  */
-declare class GenericDefaultingConverter<T, TD = T, TC = undefined> implements DefaultingConverter<T, TD, TC> {
+declare class GenericDefaultingConverter<T, TD = T, TC = unknown> implements DefaultingConverter<T, TD, TC> {
     private _converter;
     /**
      * {@inheritdoc Conversion.DefaultingConverter.defaultValue}
@@ -1001,6 +1042,10 @@ declare class GenericDefaultingConverter<T, TD = T, TC = undefined> implements D
      * {@inheritdoc Converter.withBrand}
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T | TD, B>, TC>;
+    /**
+     * {@inheritdoc Converter.withFormattedError}
+     */
+    withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T | TD, TC>;
     /**
      * Returns a Converter which always succeeds with the supplied default value rather
      * than failing.
@@ -1016,7 +1061,7 @@ declare class GenericDefaultingConverter<T, TD = T, TC = undefined> implements D
  * Generic base implementation for an in-place {@link Validation.Validator | Validator}.
  * @public
  */
-declare class GenericValidator<T, TC = undefined> implements Validator<T, TC> {
+declare class GenericValidator<T, TC = unknown> implements Validator<T, TC> {
     /**
      * {@inheritdoc Validation.Validator.traits}
      */
@@ -1071,6 +1116,10 @@ declare class GenericValidator<T, TC = undefined> implements Validator<T, TC> {
      * {@inheritdoc Validation.Validator.brand}
      */
     withBrand<B extends string>(brand: B): Validator<Brand<T, B>, TC>;
+    /**
+     * {@inheritdoc Validation.Validator.withFormattedError}
+     */
+    withFormattedError(formatter: ValidationErrorFormatter<TC>): Validator<T, TC>;
     /**
      * Gets a default or explicit context.
      * @param explicitContext - Optional explicit context.
@@ -1189,7 +1238,7 @@ export declare interface IMessageAggregator {
  * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`
  * @beta
  */
-declare type Infer<TCONV> = TCONV extends Converter<infer TTO> ? InnerInferredType<TTO> : never;
+declare type Infer<TCONV> = TCONV extends Converter<infer TTO, unknown> ? InnerInferredType<TTO> : never;
 
 /**
  * @public
@@ -1210,6 +1259,86 @@ declare class InMemoryLogger extends LoggerBase {
  */
 declare type InnerInferredType<TCONV> = TCONV extends Converter<infer TTO> ? TTO extends Array<infer TTOELEM> ? InnerInferredType<TTOELEM>[] : TTO : TCONV extends Array<infer TELEM> ? InnerInferredType<TELEM>[] : TCONV;
 
+/**
+ * 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 declare interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {
+    /**
+     * {@inheritdoc Collections.ResultMap.inner}
+     */
+    readonly inner: ReadonlyMap<TK, TV>;
+    /**
+     * {@inheritdoc Collections.ResultMap.size}
+     */
+    readonly size: number;
+    /**
+     * {@inheritdoc Collections.ResultMap.entries}
+     */
+    entries(): MapIterator<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(): MapIterator<TK>;
+    /**
+     * {@inheritdoc Collections.ResultMap.values}
+     */
+    values(): MapIterator<TV>;
+    /**
+     * Gets an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TV>>;
+}
+
+/**
+ * A read-only interface exposing non-mutating methods of a {@link Collections.ResultMapValidator | ResultMapValidator}.
+ * @public
+ */
+declare interface IReadOnlyResultMapValidator<TK extends string = string, TV = unknown> {
+    /**
+     * {@inheritdoc Collections.ResultMapValidator.validators}
+     */
+    readonly validators: KeyValueValidators<TK, TV>;
+    /**
+     * {@inheritdoc Collections.ResultMapValidator.map}
+     */
+    readonly map: IReadOnlyResultMap<TK, TV>;
+    /**
+     * {@inheritdoc Collections.ResultMap.get}
+     */
+    get(key: string): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * {@inheritdoc Collections.ResultMap.has}
+     */
+    has(key: string): boolean;
+}
+
+/**
+ * A read-only interface exposing non-mutating methods of a {@link Collections.ValidatingResultMap | ValidatingResultMap}.
+ * @public
+ */
+declare interface IReadOnlyValidatingResultMap<TK extends string = string, TV = unknown> extends IReadOnlyResultMap<TK, TV> {
+    /**
+     * {@inheritdoc Collections.ValidatingResultMap.validate}
+     */
+    readonly validate: IReadOnlyResultMapValidator<TK, TV>;
+}
+
 /**
  * Represents the result of some operation of sequence of operations.
  * @remarks
@@ -1352,6 +1481,23 @@ export declare interface IResultLogger {
     error(message: string): void;
 }
 
+/**
+ * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.
+ * @public
+ */
+declare interface IResultMapConstructorParams<TK extends string = string, TV = unknown> {
+    entries?: Iterable<KeyValueEntry<TK, TV>>;
+}
+
+/**
+ * Parameters for constructing a {@link Collections.ResultMapValidator | ResultMapValidator}.
+ * @public
+ */
+declare interface IResultMapValidatorCreateParams<TK extends string = string, TV = unknown> {
+    map: ResultMap<TK, TV>;
+    validators: KeyValueValidators<TK, TV>;
+}
+
 /**
  * Helper function to create a {@link Converter | Converter} from a supplied type guard function.
  * @param description - a description of the thing to be validated for use in error messages
@@ -1373,6 +1519,14 @@ declare function isA<T, TC = unknown>(description: string, guard: TypeGuardWithC
  */
 declare function isA_2<T, TC>(description: string, guard: TypeGuardWithContext<T, TC>, params?: Omit<TypeGuardValidatorConstructorParams<T, TC>, 'description' | 'guard'>): TypeGuardValidator<T, TC>;
 
+/**
+ * Determines if a supplied value is an iterable object or some other type.
+ * @param value - The value to be tested.
+ * @returns `true` if the value is an iterable object, `false` otherwise.
+ * @public
+ */
+declare function isIterable<TE = unknown, TI extends Iterable<TE> = Iterable<TE>, TO = unknown>(value: TI | TO): value is TI;
+
 /**
  * Helper type-guard function to report whether a specified key is present in
  * a supplied object.
@@ -1383,13 +1537,22 @@ declare function isA_2<T, TC>(description: string, guard: TypeGuardWithContext<T
  */
 export declare function isKeyOf<T extends object>(key: string | number | symbol, item: T): key is keyof T;
 
+/**
+ * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.
+ * @public
+ */
+declare interface IValidatingResultMapConstructorParams<TK extends string = string, TV = unknown> {
+    entries?: Iterable<KeyValueEntry<string, unknown>>;
+    validators: KeyValueValidators<TK, TV>;
+}
+
 /**
  * Options for {@link Converters.(recordOf:3) | Converters.recordOf} and
  * {@link Converters.(mapOf:3) | Converters.mapOf}
  * helper functions.
  * @public
  */
-declare interface KeyedConverterOptions<T extends string = string, TC = undefined> {
+declare interface KeyedConverterOptions<T extends string = string, TC = unknown> {
     /**
      * if `onError` is `'fail'` (default), then the entire conversion fails if any key or element
      * cannot be converted.  If `onError` is `'ignore'`, failing elements are silently ignored.
@@ -1410,6 +1573,69 @@ declare interface KeyedConverterOptions<T extends string = string, TC = undefine
  */
 declare type KeyedThingFactory<TS, TD, TK extends string = string> = (key: TK, thing: TS) => Result<TD>;
 
+/**
+ * Generic key-value entry.
+ * @public
+ */
+declare type KeyValueEntry<TK extends string = string, TV = unknown> = [TK, TV];
+
+/**
+ * Helper class for validating key-value pairs.
+ * @public
+ */
+declare class KeyValueValidators<TK extends string = string, TV = unknown> {
+    /**
+     * Required key validator or converter.
+     */
+    readonly key: Validator<TK, unknown> | Converter<TK, unknown>;
+    /**
+     * Required value validator or converter.
+     */
+    readonly value: Validator<TV, unknown> | Converter<TV, unknown>;
+    /**
+     * Optional entry validator or converter.  If no entry validator is provided,
+     * an entry is considered valid if both key and value are valid.
+     */
+    readonly entry?: Validator<KeyValueEntry<TK, TV>, unknown> | Converter<KeyValueEntry<TK, TV>, unknown>;
+    /**
+     * Constructs a new key-value validator.
+     * @param key - Required key validator or converter.
+     * @param value - Required value validator or converter.
+     * @param entry - Optional entry validator or converter.  If no entry validator is provided,
+     * an entry is considered valid if both key and value are valid.
+     */
+    constructor(key: Validator<TK, unknown> | Converter<TK, unknown>, value: Validator<TV, unknown> | Converter<TV, unknown>, entry?: Validator<KeyValueEntry<TK, TV>, unknown> | Converter<KeyValueEntry<TK, TV>, unknown>);
+    /**
+     * Validates a supplied unknown as a valid key value.
+     * @param key - The unknown to be validated.
+     * @returns `Success` with the validated 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.
+     */
+    validateKey(key: unknown): DetailedResult<TK, ResultMapResultDetail>;
+    /**
+     * Validates a supplied unknown as a valid value.
+     * @param key - The unknown to be validated.
+     * @returns `Success` with the validated value and 'success' detail if the value is valid,
+     * or `Failure` with an error message and 'invalid-value' detail if the value is invalid.
+     */
+    validateValue(key: unknown): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * Validates a supplied unknown as a valid key-value pair.
+     * @param entry - The unknown to be validated.
+     * @returns `Success` with the validated key-value pair 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
+     */
+    validateEntry(entry: unknown): DetailedResult<KeyValueEntry<TK, TV>, ResultMapResultDetail>;
+    /**
+     * Validates a supplied iterable of unknowns as valid key-value pairs.
+     * @param entries - The iterable of unknowns to be validated.
+     * @returns `Success` with an array of validated key-value pairs if all entries are valid,
+     * or `Failure` with an error message if any entry is invalid.
+     */
+    validateEntries(entries: Iterable<unknown>): Result<KeyValueEntry<TK, TV>[]>;
+}
+
 /**
  * Helper function to create a {@link Converter | Converter} which converts `unknown` to some supplied literal value. Succeeds with
  * the supplied value if an identity comparison succeeds, fails otherwise.
@@ -1417,7 +1643,7 @@ declare type KeyedThingFactory<TS, TD, TK extends string = string> = (key: TK, t
  * @returns A {@link Converter | Converter} which returns the supplied value on success.
  * @public
  */
-declare function literal<T>(value: T): Converter<T, unknown>;
+declare function literal<T, TC = unknown>(value: T): Converter<T, TC>;
 
 /**
  * Helper function to create a {@link Validation.Validator} which validates a literal value.
@@ -1501,7 +1727,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
 
  /**
   * A helper function to create a {@link Converter | Converter} which converts the `string`-keyed properties
-  * using a supplied {@link Converter | Converter<T>} or {@link Validator | Validator<T>} to produce a
+  * using a supplied {@link Converter | Converter<T, TC>} or {@link Validator | Validator<T>} to produce a
   * `Map<string, T>`.
   * @remarks
   * The resulting converter fails conversion if any element cannot be converted.
@@ -1511,11 +1737,11 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
   * {@label WITH_DEFAULT}
   * @public
   */
- declare function mapOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>): Converter<Map<TK, T>, TC>;
+ declare function mapOf<T, TC = unknown, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>): Converter<Map<TK, T>, TC>;
 
  /**
   * A helper function to create a {@link Converter | Converter} which converts the `string`-keyed properties
-  * using a supplied {@link Converter | Converter<T>} or {@link Validator | Validator<T>} to produce a
+  * using a supplied {@link Converter | Converter<T, TC>} or {@link Validator | Validator<T>} to produce a
   * `Map<string, T>` and specified handling of elements that cannot be converted.
   * @remarks
   * if `onError` is `'fail'` (default), then the entire conversion fails if any key or element
@@ -1526,11 +1752,11 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
   * {@label WITH_ON_ERROR}
   * @public
   */
- declare function mapOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>, onError: 'fail' | 'ignore'): Converter<Map<TK, T>, TC>;
+ declare function mapOf<T, TC = unknown, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>, onError: 'fail' | 'ignore'): Converter<Map<TK, T>, TC>;
 
  /**
   * A helper function to create a {@link Converter | Converter} which converts the `string`-keyed properties
-  * using a supplied {@link Converter | Converter<T>} or {@link Validator | Validator<T>} to produce
+  * using a supplied {@link Converter | Converter<T, TC>} or {@link Validator | Validator<T>} to produce
   * a `Map<TK,T>`.
   * @remarks
   * If present, the supplied {@link Converters.KeyedConverterOptions | options} can provide a strongly-typed
@@ -1543,7 +1769,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
   * {@label WITH_OPTIONS}
   * @public
   */
- declare function mapOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>, options: KeyedConverterOptions<TK, TC>): Converter<Map<TK, T>, TC>;
+ declare function mapOf<T, TC = unknown, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>, options: KeyedConverterOptions<TK, TC>): Converter<Map<TK, T>, TC>;
 
  /**
   * Helper function to create a {@link Converter | Converter} which converts `unknown` to one of a set of supplied enumerated
@@ -1558,7 +1784,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
   * @returns A {@link Converter | Converter} which applies the mapping and yields `<T>` on success.
   * @public
   */
- declare function mappedEnumeratedValue<T>(map: [T, unknown[]][], message?: string): Converter<T, undefined>;
+ declare function mappedEnumeratedValue<T, TC = unknown>(map: [T, unknown[]][], message?: string): Converter<T, TC>;
 
  /**
   * Aggregates successful result values from a collection of {@link Result | Result<T>}.
@@ -1701,7 +1927,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         * Numbers and strings with a numeric format succeed. Anything else fails.
         * @public
         */
-       declare const number: Converter<number, undefined>;
+       declare const number: Converter<number, unknown>;
 
        /**
         * A {@link Validation.Classes.NumberValidator | NumberValidator} which validates a number in place.
@@ -1716,7 +1942,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         * of numbers, returns {@link Failure | Failure} with an error message otherwise.
         * @public
         */
-       declare const numberArray: Converter<number[]>;
+       declare const numberArray: Converter<number[], unknown>;
 
        /**
         * An in-place {@link Validation.Validator | Validator} for `number` values.
@@ -1745,8 +1971,8 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
        declare type NumberValidatorConstructorParams<T extends number = number, TC = unknown> = GenericValidatorConstructorParams<T, TC>;
 
        /**
-        * Helper function to create a {@link Conversion.ObjectConverter | ObjectConverter<T>} which converts an object
-        * without changing shape, given a {@link Conversion.FieldConverters | FieldConverters<T>} and an optional
+        * Helper function to create a {@link Conversion.ObjectConverter | ObjectConverter<T, TC>} which converts an object
+        * without changing shape, given a {@link Conversion.FieldConverters | FieldConverters<T, TC>} and an optional
         * {@link Conversion.ObjectConverterOptions | ObjectConverterOptions<T>} to further refine conversion behavior.
         * @remarks
         * By default, if all of the requested fields exist and can be converted, returns {@link Success | Success}
@@ -1756,7 +1982,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         *
         * Fields that succeed but convert to undefined are omitted from the result object but do not
         * fail the conversion.
-        * @param properties - An {@link Conversion.FieldConverters | FieldConverters<T>} defining the shape of the
+        * @param properties - An {@link Conversion.FieldConverters | FieldConverters<T, TC>} defining the shape of the
         * source object and {@link Converter | converters} to be applied to each properties.
         * @param options - An {@link Conversion.ObjectConverterOptions | ObjectConverterOptions<T>} containing options
         * for the object converter.
@@ -1764,11 +1990,11 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         * {@label WITH_OPTIONS}
         * @public
         */
-       declare function object<T>(properties: FieldConverters<T>, options?: ObjectConverterOptions<T>): ObjectConverter<T>;
+       declare function object<T, TC = unknown>(properties: FieldConverters<T, TC>, options?: ObjectConverterOptions<T>): ObjectConverter<T, TC>;
 
        /**
-        * Helper function to create a {@link Conversion.ObjectConverter | ObjectConverter<T>} which converts an object
-        * without changing shape, given a {@link Conversion.FieldConverters | FieldConverters<T>} and a set of
+        * Helper function to create a {@link Conversion.ObjectConverter | ObjectConverter<T, TC>} which converts an object
+        * without changing shape, given a {@link Conversion.FieldConverters | FieldConverters<T, TC>} and a set of
         * optional properties.
         * @remarks
         * By default, if all of the requested fields exist and can be converted, returns {@link Success | Success}
@@ -1778,7 +2004,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         *
         * Fields that succeed but convert to undefined are omitted from the result object but do not
         * fail the conversion.
-        * @param properties - An {@link Conversion.FieldConverters | FieldConverters<T>} defining the shape of the
+        * @param properties - An {@link Conversion.FieldConverters | FieldConverters<T, TC>} defining the shape of the
         * source object and {@link Converter | converters} to be applied to each properties.
         * @param optional - An array of `(keyof T)` listing the keys to be considered optional.
         * {@label WITH_KEYS}
@@ -1786,7 +2012,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         * @public
         * @deprecated Use {@link Converters.(object:1) | Converters.object(fields, options)} instead.
         */
-       declare function object<T>(properties: FieldConverters<T>, optional: (keyof T)[]): ObjectConverter<T>;
+       declare function object<T, TC = unknown>(properties: FieldConverters<T, TC>, optional: (keyof T)[]): ObjectConverter<T, TC>;
 
        /**
         * Helper function to create a {@link Validation.Classes.ObjectValidator | ObjectValidator} which validates
@@ -1815,13 +2041,13 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
            /**
             * Fields converted by this {@link Conversion.ObjectConverter | ObjectConverter}.
             */
-           readonly fields: FieldConverters<T>;
+           readonly fields: FieldConverters<T, TC>;
            /**
             * Options used to initialize this {@link Conversion.ObjectConverter | ObjectConverter}.
             */
            readonly options: ObjectConverterOptions<T>;
            /**
-            * Constructs a new {@link Conversion.ObjectConverter | ObjectConverter<T>} using options
+            * Constructs a new {@link Conversion.ObjectConverter | ObjectConverter<T, TC>} using options
             * supplied in a {@link Conversion.ObjectConverterOptions | ObjectConverterOptions<T>}.
             * @param fields - A {@link Conversion.FieldConverters | FieldConverters<T>} containing
             * a {@link Converter} for each field
@@ -1830,7 +2056,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
             */
            constructor(fields: FieldConverters<T, TC>, options?: ObjectConverterOptions<T>);
            /**
-            * Constructs a new {@link Conversion.ObjectConverter | ObjectConverter<T>} with optional
+            * Constructs a new {@link Conversion.ObjectConverter | ObjectConverter<T, TC>} with optional
             * properties specified as an array of `keyof T`.
             * @param fields - A {@link Conversion.FieldConverters | FieldConverters<T>} containing
             * a {@link Converter} for each field.
@@ -2086,7 +2312,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         * with value `undefined`.
         * @public
         */
-       declare const optionalBoolean: Converter<boolean | undefined>;
+       declare const optionalBoolean: Converter<boolean | undefined, unknown>;
 
        /**
         * A helper function to create a {@link Converter | Converter} which extracts and converts an optional element from an array.
@@ -2097,10 +2323,10 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         * is not an array, if the requested index is negative, or if the element cannot be converted.
         * @param index - The index of the element to be extracted.
         * @param converter - A {@link Converter | Converter} or {@link Validator | Validator} used for the extracted element.
-        * @returns A {@link Converter | Converter<T>} which extracts the specified element from an array.
+        * @returns A {@link Converter | Converter<T, TC>} which extracts the specified element from an array.
         * @public
         */
-       declare function optionalElement<T, TC = undefined>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, TC>;
+       declare function optionalElement<T, TC = unknown>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, TC>;
 
        /**
         * A helper function to create a {@link Converter | Converter} which extracts and convert a property specified
@@ -2114,7 +2340,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         * @param converter - {@link Converter | Converter} or {@link Validator | Validator} to use for the extracted field.
         * @public
         */
-       declare function optionalField<T, TC = undefined>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, TC>;
+       declare function optionalField<T, TC = unknown>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, TC>;
 
        /**
         * Applies a factory method to convert an optional `ReadonlyMap<string, TS>` into a `Record<string, TD>`
@@ -2143,7 +2369,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
           * Anything else returns {@link Success | Success} with value `undefined`.
           * @public
           */
-         declare const optionalNumber: Converter<number | undefined>;
+         declare const optionalNumber: Converter<number | undefined, unknown>;
 
          /**
           * Applies a factory method to convert an optional `Record<TK, TS>` into a `Map<TK, TD>`, or `undefined`.
@@ -2249,7 +2475,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
 
            /**
             * A helper function to create a {@link Converter | Converter} which converts the `string`-keyed
-            * properties using a supplied {@link Converter | Converter<T>} or {@link Validator | Validator<T>} to
+            * properties using a supplied {@link Converter | Converter<T, TC>} or {@link Validator | Validator<T>} to
             * produce a `Record<string, T>`.
             * @remarks
             * The resulting converter fails conversion if any element cannot be converted.
@@ -2259,11 +2485,11 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
             * {@label WITH_DEFAULT}
             * @public
             */
-           declare function recordOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>): Converter<Record<TK, T>, TC>;
+           declare function recordOf<T, TC = unknown, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>): Converter<Record<TK, T>, TC>;
 
            /**
             * A helper function to create a {@link Converter | Converter} which converts the `string`-keyed properties
-            * using a supplied {@link Converter | Converter<T>} or {@link Validator | Validator<T>} to produce a
+            * using a supplied {@link Converter | Converter<T, TC>} or {@link Validator | Validator<T>} to produce a
             * `Record<string, T>` and optionally specified handling of elements that cannot be converted.
             * @remarks
             * if `onError` is `'fail'` (default), then the entire conversion fails if any key or element
@@ -2274,11 +2500,11 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
             * {@label WITH_ON_ERROR}
             * @public
             */
-           declare function recordOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>, onError: 'fail' | 'ignore'): Converter<Record<TK, T>, TC>;
+           declare function recordOf<T, TC = unknown, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>, onError: 'fail' | 'ignore'): Converter<Record<TK, T>, TC>;
 
            /**
             * A helper function to create a {@link Converter | Converter} or which converts the `string`-keyed properties
-            * using a supplied {@link Converter | Converter<T>} or {@link Validator | Validator<T>} to produce a
+            * using a supplied {@link Converter | Converter<T, TC>} or {@link Validator | Validator<T>} to produce a
             * `Record<TK, T>`.
             * @remarks
             * If present, the supplied {@link Converters.KeyedConverterOptions | options} can provide a strongly-typed
@@ -2290,7 +2516,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
             * {@label WITH_OPTIONS}
             * @public
             */
-           declare function recordOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>, options: KeyedConverterOptions<TK, TC>): Converter<Record<TK, T>, TC>;
+           declare function recordOf<T, TC = unknown, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>, options: KeyedConverterOptions<TK, TC>): Converter<Record<TK, T>, TC>;
 
            /**
             * Applies a factory method to convert a `Record<TK, TS>` into a `Map<TK, TD>`.
@@ -2317,6 +2543,211 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
              */
             export declare type ResultDetailType<T> = T extends DetailedResult<unknown, infer TD> ? TD : never;
 
+            /**
+             * A {@link Collections.ResultMap | ResultMap} class as a `Map<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 declare class ResultMap<TK extends string = string, TV = unknown> implements IReadOnlyResultMap<TK, TV> {
+                /**
+                 * Readonly raw access to the inner `Map<TK, TV>` object.
+                 */
+                get inner(): ReadonlyMap<TK, TV>;
+                /**
+                 * Protected raw access to the inner `Map<TK, TV>` object.
+                 * @public
+                 */
+                protected readonly _inner: Map<TK, TV>;
+                /**
+                 * Constructs a new {@link Collections.ResultMap | ResultMap}.
+                 * @param iterable - An iterable to initialize the map.
+                 */
+                constructor(iterable?: Iterable<KeyValueEntry<TK, TV>>);
+                /**
+                 * Constructs a new {@link Collections.ResultMap | ResultMap}.
+                 * @param params - An optional set of parameters to configure the map.
+                 */
+                constructor(params: IResultMapConstructorParams);
+                /**
+                 * Creates a new {@link Collections.ResultMap | ResultMap}.
+                 * @param elements - An optional iterable to initialize the map.
+                 * @returns `Success` with the new map, or `Failure` with error details
+                 * if an error occurred.
+                 * @public
+                 */
+                static create<TK extends string = string, TV = unknown>(elements: Iterable<KeyValueEntry<TK, TV>>): Result<ResultMap<TK, TV>>;
+                /**
+                 * Creates a new {@link Collections.ResultMap | ResultMap}.
+                 * @param params - An optional set of parameters to configure the map.
+                 * @returns `Success` with the new map, or `Failure` with error details
+                 * if an error occurred.
+                 * @public
+                 */
+                static create<TK extends string = string, TV = unknown>(params?: IResultMapConstructorParams<TK, TV>): Result<ResultMap<TK, TV>>;
+                /**
+                 * Sets a key/value pair in the map if the key does not already exist.
+                 * @param key - The key to set.
+                 * @param value - The value to set.
+                 * @returns `Success` with the value and detail `added` if the key was added,
+                 * `Failure` with detail `exists` if the key already exists. Fails with detail
+                 * 'invalid-key' or 'invalid-value' and an error message if either is invalid.
+                 */
+                add(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * Clears the map.
+                 */
+                clear(): void;
+                /**
+                 * Deletes a key from the map.
+                 * @param key - The key to delete.
+                 * @returns `Success` with the previous value and the detail 'deleted'
+                 * if the key was found and deleted, `Failure` with detail 'not-found'
+                 * if the key was not found, or with detail 'invalid-key' if the key is invalid.
+                 */
+                delete(key: TK): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * Returns an iterator over the map entries.
+                 * @returns An iterator over the map entries.
+                 */
+                entries(): MapIterator<KeyValueEntry<TK, TV>>;
+                /**
+                 * Calls a function for each entry in the map.
+                 * @param cb - The function to call for each entry.
+                 * @param arg - An optional argument to pass to the callback.
+                 */
+                forEach(cb: ResultMapForEachCb<TK, TV>, arg?: unknown): void;
+                /**
+                 * Gets a value from the map.
+                 * @param key - The key to retrieve.
+                 * @returns `Success` with the value and detail `exists` if the key was found,
+                 * `Failure` with detail `not-found` if the key was not found or with detail
+                 * `invalid-key` if the key is invalid.
+                 */
+                get(key: TK): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * Gets a value from the map, or adds a supplied value it if it does not exist.
+                 * @param key - The key to retrieve.
+                 * @param value - The value to add if the key does not exist.
+                 * @returns `Success` with the value and detail `exists` if the key was found,
+                 * `Success` with the value and detail `added` if the key was not found and added.
+                 * Fails with detail 'invalid-key' or 'invalid-value' and an error message if either
+                 * is invalid.
+                 */
+                getOrAdd(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * Returns `true` if the map contains a key.
+                 * @param key - The key to check.
+                 * @returns `true` if the key exists, `false` otherwise.
+                 */
+                has(key: TK): boolean;
+                /**
+                 * Returns an iterator over the map keys.
+                 * @returns An iterator over the map keys.
+                 */
+                keys(): MapIterator<TK>;
+                /**
+                 * Sets a key/value pair in the map.
+                 * @param key - The key to set.
+                 * @param value - The value to set.
+                 * @returns `Success` with the new value and the detail `updated` if the
+                 * key was found and updated, `Success` with the new value and detail
+                 * `added` if the key was not found and added.  Fails with detail
+                 * 'invalid-key' or 'invalid-value' and an error message if either is invalid.
+                 */
+                set(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * Returns the number of entries in the map.
+                 */
+                get size(): number;
+                /**
+                 * Updates an existing key in the map - the map is not updated if the key does
+                 * not exist.
+                 * @param key - The key to update.
+                 * @param value - The value to set.
+                 * @returns `Success` with the value and detail 'exists' if the key was found
+                 * and the value updated, `Failure` an error message and with detail `not-found`
+                 * if the key was not found, or with detail 'invalid-key' or 'invalid-value'
+                 * if either is invalid.
+                 */
+                update(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * Returns an iterator over the map values.
+                 * @returns An iterator over the map values.
+                 */
+                values(): MapIterator<TV>;
+                /**
+                 * Gets an iterator over the map entries.
+                 * @returns An iterator over the map entries.
+                 */
+                [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TV>>;
+                /**
+                 * Gets a readonly version of this map.
+                 * @returns A readonly version of this map.
+                 */
+                toReadOnly(): IReadOnlyResultMap<TK, TV>;
+            }
+
+            /**
+             * Callback for {@link Collections.ResultMap | ResultMap} `forEach` method.
+             * @public
+             */
+            declare type ResultMapForEachCb<TK extends string = string, TE = unknown> = (value: TE, key: TK, map: IReadOnlyResultMap<TK, TE>, thisArg?: unknown) => void;
+
+            /**
+             * Additional success or failure details for {@link Collections.ResultMap | ResultMap} calls.
+             * @public
+             */
+            declare type ResultMapResultDetail = 'added' | 'deleted' | 'exists' | 'invalid-key' | 'invalid-value' | 'not-found' | 'success' | 'updated';
+
+            /**
+             * A {@link Collections.ResultMap | ResultMap} wrapper which validates weakly-typed keys
+             * before calling the wrapped result map.
+             * @public
+             */
+            declare class ResultMapValidator<TK extends string = string, TV = unknown> implements IReadOnlyResultMapValidator<TK, TV> {
+                readonly validators: KeyValueValidators<TK, TV>;
+                get map(): IReadOnlyResultMap<TK, TV>;
+                protected _map: ResultMap<TK, TV>;
+                /**
+                 * Constructs a new {@link Collections.ValidatingResultMap | ValidatingResultMap}.
+                 * @param params - Required parameters for constructing the map.
+                 */
+                constructor(params: IResultMapValidatorCreateParams<TK, TV>);
+                /**
+                 * {@inheritdoc Collections.ResultMap.add}
+                 */
+                add(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * {@inheritdoc Collections.ResultMap.delete}
+                 */
+                delete(key: string): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * {@inheritdoc Collections.ResultMap.get}
+                 */
+                get(key: string): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * {@inheritdoc Collections.ResultMap.getOrAdd}
+                 */
+                getOrAdd(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * {@inheritdoc Collections.ResultMap.has}
+                 */
+                has(key: string): boolean;
+                /**
+                 * {@inheritdoc Collections.ResultMap.set}
+                 */
+                set(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * {@inheritdoc Collections.ResultMap.update}
+                 */
+                update(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;
+                /**
+                 * Gets a read-only version of this validator.
+                 */
+                toReadOnly(): IReadOnlyResultMapValidator<TK, TV>;
+            }
+
             /**
              * Type inference to determine the result type of an {@link Result}.
              * @beta
@@ -2325,7 +2756,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
 
             /**
              * Helper function to create a {@link Conversion.ObjectConverter | ObjectConverter} which converts an object
-             * without changing shape, a {@link Conversion.FieldConverters | FieldConverters<T>} and an optional
+             * without changing shape, a {@link Conversion.FieldConverters | FieldConverters<T, TC>} and an optional
              * {@link Converters.StrictObjectConverterOptions | StrictObjectConverterOptions<T>} to further refine
              * conversion behavior.
              *
@@ -2341,11 +2772,11 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
              * {@label WITH_OPTIONS}
              * @public
              */
-            declare function strictObject<T>(properties: FieldConverters<T>, options?: StrictObjectConverterOptions<T>): ObjectConverter<T>;
+            declare function strictObject<T, TC = unknown>(properties: FieldConverters<T, TC>, options?: StrictObjectConverterOptions<T>): ObjectConverter<T, TC>;
 
             /**
              * Helper function to create a {@link Conversion.ObjectConverter | ObjectConverter} which converts an object
-             * without changing shape, a {@link Conversion.FieldConverters | FieldConverters<T>} and an optional
+             * without changing shape, a {@link Conversion.FieldConverters | FieldConverters<T, TC>} and an optional
              * {@link Converters.StrictObjectConverterOptions | StrictObjectConverterOptions<T>} to further refine
              * conversion behavior.
              *
@@ -2362,7 +2793,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
              * @deprecated Use {@link Converters.(strictObject:1) | Converters.strictObject(options)} instead.
              * @public
              */
-            declare function strictObject<T>(properties: FieldConverters<T>, optional: (keyof T)[]): ObjectConverter<T>;
+            declare function strictObject<T, TC = unknown>(properties: FieldConverters<T, TC>, optional: (keyof T)[]): ObjectConverter<T, TC>;
 
             /**
              * Options for the {@link Converters.(strictObject:1)} helper function.
@@ -2390,7 +2821,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
              * of strings, returns {@link Failure | Failure} with an error message otherwise.
              * @public
              */
-            declare const stringArray: Converter<string[]>;
+            declare const stringArray: Converter<string[], unknown>;
 
             /**
              * The {@link Conversion.StringConverter | StringConverter} class extends
@@ -2706,6 +3137,13 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                     */
                    declare type TypeGuardWithContext<T, TC = unknown> = (from: unknown, context?: TC) => from is T;
 
+                   declare namespace Utils {
+                       export {
+                           isIterable,
+                           KeyValueValidators
+                       }
+                   }
+
                    /**
                     * Helper function to create a {@link Converter | Converter} from any {@link Validation.Validator}
                     * @param validator - the validator to be wrapped
@@ -2723,10 +3161,52 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                     * information otherwise.
                     * @param validator - A validator function to determine if the converted value is valid.
                     * @param description - A description of the validated type for use in error messages.
-                    * @returns A new {@link Converter | Converter<T>} which applies the supplied validation.
+                    * @returns A new {@link Converter | Converter<T, TC>} which applies the supplied validation.
                     * @public
                     */
-                   declare function validateWith<T, TC = undefined>(validator: (from: unknown) => from is T, description?: string): Converter<T, TC>;
+                   declare function validateWith<T, TC = unknown>(validator: (from: unknown) => from is T, description?: string): Converter<T, TC>;
+
+                   /**
+                    * A {@link Collections.ResultMap | ResultMap} with a {@link Collections.ResultMapValidator | validator}
+                    * property that enables validated use of the underlying map with weakly-typed keys and values.
+                    * @public
+                    */
+                   export declare class ValidatingResultMap<TK extends string = string, TV = unknown> extends ResultMap<TK, TV> implements IReadOnlyValidatingResultMap<TK, TV> {
+                       /**
+                        * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values
+                        * before inserting them into this collection.
+                        */
+                       readonly validate: ResultMapValidator<TK, TV>;
+                       /**
+                        * Constructs a new {@link Collections.ValidatingResultMap | ValidatingResultMap}.
+                        * @param params - Required parameters for constructing the map.
+                        */
+                       constructor(params: IValidatingResultMapConstructorParams<TK, TV>);
+                       /**
+                        * Creates a new {@link Collections.ValidatingResultMap | ValidatingResultMap} instance.
+                        * @param params - Required parameters for constructing the map.
+                        * @returns `Success` with the new map if successful, `Failure` otherwise.
+                        * @public
+                        */
+                       static createValidating<TK extends string = string, TV = unknown>(params: IValidatingResultMapConstructorParams<TK, TV>): Result<ValidatingResultMap<TK, TV>>;
+                       /**
+                        * {@inheritdoc Collections.ResultMap.add}
+                        */
+                       add(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+                       /**
+                        * {@inheritdoc Collections.ResultMap.getOrAdd}
+                        */
+                       getOrAdd(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+                       set(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+                       /**
+                        * {@inheritdoc Collections.ResultMap.update}
+                        */
+                       update(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+                       /**
+                        * Gets a read-only version of this map.
+                        */
+                       toReadOnly(): IReadOnlyValidatingResultMap<TK, TV>;
+                   }
 
                    declare namespace Validation {
                        export {
@@ -2741,17 +3221,28 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                            ValidatorTraits,
                            ValidatorOptions,
                            Constraint,
+                           ValidationErrorFormatter,
                            Validator
                        }
                    }
                    export { Validation }
 
+                   /**
+                    * Formats an incoming error message and value that failed validation.
+                    * @param val - The value that failed validation.
+                    * @param message - The default error message, if any.
+                    * @param context - Optional validation context.
+                    * @returns The formatted error message.
+                    * @public
+                    */
+                   declare type ValidationErrorFormatter<TC = unknown> = (val: unknown, message?: string, context?: TC) => string;
+
                    /**
                     * In-place validation that a supplied unknown matches some
                     * required characteristics (type, values, etc).
                     * @public
                     */
-                   export declare interface Validator<T, TC = undefined> {
+                   export declare interface Validator<T, TC = unknown> {
                        /**
                         * {@link Validation.ValidatorTraits | Traits} describing this validation.
                         */
@@ -2818,13 +3309,21 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                            * @param brand - The brand to be applied.
                            */
                           withBrand<B extends string>(brand: B): Validator<Brand<T, B>, TC>;
+                          /**
+                           * Creates a new {@link Validation.Validator | in-place validator} which
+                           * is derived from this one but which returns an error message supplied
+                           * by the provided formatter if an error occurs.
+                           * @param formatter - The error message formatter to be applied.
+                           * @returns A new {@link Validation.Validator | Validator}.
+                           */
+                          withFormattedError(formatter: ValidationErrorFormatter<TC>): Validator<T, TC>;
                          }
 
                          /**
                           * Abstract base helper class for specific validator implementations
                           * @internal
                           */
-                         declare abstract class ValidatorBase<T, TC = undefined> extends GenericValidator<T, TC> {
+                         declare abstract class ValidatorBase<T, TC = unknown> extends GenericValidator<T, TC> {
                              /**
                               * Inner constructor
                               * @param params - Initialization params.