@fgv/ts-utils 3.0.0-alpha.1 → 3.0.1-alpha.0

package/dist/ts-utils.d.ts

@@ -9,16 +9,17 @@
 export declare function allSucceed<T>(results: Iterable<Result<unknown>>, successValue: T): Result<T>;
 
 /**
- * A helper function to create a {@link Converter} which converts `unknown` to an array of `<T>`.
+ * A helper function to create a {@link Converter | Converter} which converts `unknown` to an array of `<T>`.
  * @remarks
  * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
- * @param converter - {@link Converter} used to convert each item in the array.
+ * @param converter - {@link Converter | Converter} or {@link Validator | Validator} used to convert each
+ * item in the array.
  * @param ignoreErrors - Specifies treatment of unconvertible elements.
- * @returns A {@link Converter} which returns an array of `<T>`.
+ * @returns A {@link Converter | Converter} which returns an array of `<T>`.
  * @public
  */
-declare function arrayOf<T, TC = undefined>(converter: Converter<T, TC>, onError?: OnError_2): Converter<T[], TC>;
+declare function arrayOf<T, TC = undefined>(converter: Converter<T, TC> | Validator<T, TC>, onError?: OnError): Converter<T[], TC>;
 
 /**
  * Helper function to create a {@link Validation.Classes.ArrayValidator | ArrayValidator} which
@@ -114,6 +115,10 @@ declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
      * {@inheritdoc Converter.convert}
      */
     convert(from: unknown, context?: TC): Result<T>;
+    /**
+     * {@inheritdoc Converter.convalidate}
+     */
+    convalidate(from: unknown, context?: TC): Result<T>;
     /**
      * {@inheritdoc Converter.convertOptional}
      */
@@ -138,6 +143,10 @@ declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
      * {@inheritdoc Converter.mapConvertItems}
      */
     mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
+    /**
+     * {@inheritdoc Converter.withAction}
+     */
+    withAction<TI>(action: (result: Result<T>) => Result<TI>): Converter<TI, TC>;
     /**
      * {@inheritdoc Converter.withTypeGuard}
      */
@@ -154,6 +163,10 @@ declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
      * {@inheritdoc Converter.withBrand}
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
+    /**
+     * {@inheritdoc Converter.withDefault}
+     */
+    withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC>;
     /**
      * @internal
      */
@@ -169,7 +182,7 @@ declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
 }
 
 /**
- * A {@link Converter} which converts `unknown` to `boolean`.
+ * A {@link Converter | Converter} which converts `unknown` to `boolean`.
  * @remarks
  * Boolean values or the case-insensitive strings `'true'` and `'false'` succeed.
  * Anything else fails.
@@ -276,15 +289,39 @@ declare interface ConstraintOptions {
  */
 declare type ConstraintTrait = FunctionConstraintTrait;
 
+/**
+ * Helper interface to make it easy to use validators and converters interchangeably.
+ * @public
+ */
+declare interface Convalidator<T, TC = unknown> {
+    /**
+     * Indicates whether the corresponding property can be omitted.
+     */
+    readonly isOptional: boolean;
+    /**
+     * Converts or validates from `unknown` to `<T>`.  For objects and arrays, makes no
+     * guarantees wrt in-place validation or unrecognized properties.
+     * @param from - The `unknown` to be converted or validated.
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the operation.
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
+     */
+    convalidate(from: unknown, context?: TC): Result<T>;
+}
+
 declare namespace Conversion {
     export {
         Converters,
-        ConverterTraits,
-        ConstraintOptions,
-        Converter,
         Infer,
         ConvertedToType,
         BaseConverter,
+        OnError,
+        ConverterTraits,
+        ConstraintOptions,
+        Converter,
+        DefaultingConverter,
+        GenericDefaultingConverter,
         ObjectConverterOptions,
         FieldConverters,
         ObjectConverter,
@@ -307,7 +344,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 = undefined> extends ConverterTraits, Convalidator<T, TC> {
     /**
      * Indicates whether this element is explicitly optional.
      */
@@ -317,7 +354,8 @@ export declare interface Converter<T, TC = undefined> extends ConverterTraits {
      */
     readonly brand?: string;
     /**
-     * Converts from `unknown` to `<T>`.
+     * Converts from `unknown` to `<T>`.  For objects and arrays, is guaranteed
+     * to return a new entity, with any unrecognized properties removed.
      * @param from - The `unknown` to be converted
      * @param context - An optional conversion context of type `<TC>` to be used in
      * the conversion.
@@ -325,6 +363,10 @@ export declare interface Converter<T, TC = undefined> extends ConverterTraits {
      * {@link Failure} with a a message on failure.
      */
     convert(from: unknown, context?: TC): Result<T>;
+    /**
+     * {@inheritdoc Validation.Convalidator.convalidate}
+     */
+    convalidate(from: unknown, context?: TC): Result<T>;
     /**
      * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
      *
@@ -399,6 +441,13 @@ export declare interface Converter<T, TC = undefined> extends ConverterTraits {
      * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
+    /**
+     * Creates a {@link Converter | Converter} which applies a supplied action after
+     * conversion.  The supplied action is always called regardless of success or failure
+     * of the base conversion and is allowed to mutate the return type.
+     * @param action - The action to be applied.
+     */
+    withAction<T2>(action: (result: Result<T>) => Result<T2>): Converter<T2, TC>;
     /**
      * Creates a {@link Converter} which applies a supplied type guard to the conversion
      * result.
@@ -438,6 +487,10 @@ export declare interface Converter<T, TC = undefined> extends ConverterTraits {
      * @returns A {@link Converter} returning `Brand<T, B>`.
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
+    /**
+     * Returns a Converter which always succeeds with a default value rather than failing.
+     */
+    withDefault<TD = T>(dflt: TD): DefaultingConverter<T, TD, TC>;
 }
 
 declare namespace Converters {
@@ -463,7 +516,7 @@ declare namespace Converters {
         discriminatedObject,
         transform,
         transformObject,
-        OnError_2 as OnError,
+        OnError,
         string,
         value,
         number,
@@ -502,6 +555,27 @@ declare class Crc32Normalizer extends HashingNormalizer {
     static crc32Hash(parts: string[]): string;
 }
 
+/**
+ * @public
+ */
+declare interface DefaultingConverter<T, TD = T, TC = undefined> extends Converter<T | TD, TC> {
+    /**
+     * Default value to use if the conversion fails.
+     */
+    readonly defaultValue: TD;
+    /**
+     * Convert the supplied `unknown` to `Success<T>` or to the `Success` with the default value
+     * if conversion is not possible.
+     * @param from - the value to be converted.
+     * @param ctx - optional context for the conversion.
+     */
+    convert(from: unknown, ctx?: TC): Success<T | TD>;
+    /**
+     * {@inheritdoc Converter.convalidate}
+     */
+    convalidate(from: unknown, ctx?: TC): Success<T | TD>;
+}
+
 /**
  * Default {@link Validation.ValidatorTraitValues | validation traits}.
  * @public
@@ -509,12 +583,12 @@ declare class Crc32Normalizer extends HashingNormalizer {
 declare const defaultValidatorTraits: ValidatorTraitValues;
 
 /**
- * Helper function to create a {@link Converter} which converts any `string` into an
+ * Helper function to create a {@link Converter | Converter} which converts any `string` into an
  * array of `string`, by separating at a supplied delimiter.
  * @remarks
  * Delimiter may also be supplied as context at conversion time.
  * @param delimiter - The delimiter at which to split.
- * @returns A new {@link Converter} returning `string[]`.
+ * @returns A new {@link Converter | Converter} returning `string[]`.
  * @public
  */
 declare function delimitedString(delimiter: string, options?: 'filtered' | 'all'): Converter<string[], string>;
@@ -646,41 +720,41 @@ export declare class DetailedSuccess<T, TD> extends Success<T> {
 export declare type DetailedSuccessContinuation<T, TD, TN> = (value: T, detail?: TD) => DetailedResult<TN, TD>;
 
 /**
- * Helper to create a {@link Converter} which converts a discriminated object without changing shape.
+ * Helper to create a {@link Converter | Converter} which converts a discriminated object without changing shape.
  * @remarks
  * Takes the name of the discriminator property and a
- * {@link Converters.DiscriminatedObjectConverters | string-keyed Record of converters}. During conversion,
- * the resulting {@link Converter} invokes the converter from `converters` that corresponds to the value of
+ * {@link Converters.DiscriminatedObjectConverters | string-keyed Record of converters and validators}. During conversion,
+ * the resulting {@link Converter | Converter} invokes the converter from `converters` that corresponds to the value of
  * the discriminator property in the source object.
  *
  * If the source is not an object, the discriminator property is missing, or the discriminator has
- * a value not present in the converters, conversion fails and returns {@link Failure} with more information.
+ * a value not present in the converters, conversion fails and returns {@link Failure | Failure} with more information.
  * @param discriminatorProp - Name of the property used to discriminate types.
- * @param converters - {@link Converters.DiscriminatedObjectConverters | String-keyed record of converters} to
- * invoke, where each key corresponds to a value of the discriminator property.
- * @returns A {@link Converter} which converts the corresponding discriminated object.
+ * @param converters - {@link Converters.DiscriminatedObjectConverters | String-keyed record of converters and validators}
+ * to invoke, where each key corresponds to a value of the discriminator property.
+ * @returns A {@link Converter | Converter} which converts the corresponding discriminated object.
  * @public
  */
 declare function discriminatedObject<T, TD extends string = string, TC = unknown>(discriminatorProp: string, converters: DiscriminatedObjectConverters<T, TD>): Converter<T, TC>;
 
 /**
- * A string-keyed `Record<string, Converter>` which maps specific {@link Converter | converters} to the
- * value of a discriminator property.
+ * A string-keyed `Record<string, Converter>` which maps specific {@link Converter | converters} or
+ * {@link Validator | Validators} to the value of a discriminator property.
  * @public
  */
-declare type DiscriminatedObjectConverters<T, TD extends string = string, TC = unknown> = Record<TD, Converter<T, TC>>;
+declare type DiscriminatedObjectConverters<T, TD extends string = string, TC = unknown> = Record<TD, Converter<T, TC> | Validator<T, TC>>;
 
 /**
- * A helper function to create a {@link Converter} which extracts and converts an element from an array.
+ * A helper function to create a {@link Converter | Converter} which extracts and converts an element from an array.
  * @remarks
- * The returned {@link Converter} returns {@link Success} with the converted value if the element exists
- * in the supplied array and can be converted. Returns {@link Failure} with an error message otherwise.
+ * The returned {@link Converter | Converter} returns {@link Success | Success} with the converted value if the element exists
+ * 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} used to convert the extracted element.
+ * @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.
  * @public
  */
-declare function element<T, TC = undefined>(index: number, converter: Converter<T, TC>): Converter<T, TC>;
+declare function element<T, TC = undefined>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
 
 /**
  * @internal
@@ -688,13 +762,13 @@ declare function element<T, TC = undefined>(index: number, converter: Converter<
 declare type Entry<T> = [string | number | symbol, T];
 
 /**
- * Helper function to create a {@link Converter} which converts `unknown` to one of a set of supplied
+ * Helper function to create a {@link Converter | Converter} which converts `unknown` to one of a set of supplied
  * enumerated values. Anything else fails.
  *
  * @remarks
  * Allowed enumerated values can also be supplied as context at conversion time.
  * @param values - Array of allowed values.
- * @returns A new {@link Converter} returning `<T>`.
+ * @returns A new {@link Converter | Converter} returning `<T>`.
  * @public
  */
 declare function enumeratedValue<T>(values: T[]): Converter<T, T[]>;
@@ -809,26 +883,27 @@ export declare type FailureContinuation<T> = (message: string) => Result<T>;
 export declare function failWithDetail<T, TD>(message: string, detail: TD): DetailedFailure<T, TD>;
 
 /**
- * A helper function to create a {@link Converter} which extracts and convert a property specified
+ * A helper function to create a {@link Converter | Converter} which extracts and convert a property specified
  * by name from an object.
  * @remarks
- * The resulting {@link Converter} returns {@link Success} with the converted value of the corresponding
- * object property if the field exists and can be converted. Returns {@link Failure} with an error message
+ * The resulting {@link Converter | Converter} returns {@link Success | Success} with the converted value of the corresponding
+ * object property if the field exists and can be converted. Returns {@link Failure | Failure} with an error message
  * otherwise.
  * @param name - The name of the field to be extracted.
- * @param converter - {@link Converter} used to convert the extracted field.
+ * @param converter - {@link Converter | Converter}  or {@link Validator | Validator} to use for the extracted
+ * field.
  * @public
  */
-declare function field<T, TC = undefined>(name: string, converter: Converter<T, TC>): Converter<T, TC>;
+declare function field<T, TC = undefined>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
 
 /**
- * Per-property converters for each of the properties in type T.
+ * Per-property converters or validators for each of the properties in type T.
  * @remarks
  * Used to construct a {@link Conversion.ObjectConverter | ObjectConverter}
  * @public
  */
 declare type FieldConverters<T, TC = unknown> = {
-    [key in keyof T]: Converter<T[key], TC>;
+    [key in keyof T]: Converter<T[key], TC> | Validator<T[key], TC>;
 };
 
 /**
@@ -848,13 +923,13 @@ export declare type FieldInitializers<T> = {
 declare type FieldTransformers<TSRC, TDEST, TC = unknown> = {
     [key in keyof TDEST]: {
         /**
-         * The name of the property in the source object to be converter.
+         * The name of the property in the source object to be converted.
          */
         from: keyof TSRC;
         /**
-         * The converter used to convert the property.
+         * The converter or validator used to convert the property.
          */
-        converter: Converter<TDEST[key], TC>;
+        converter: Converter<TDEST[key], TC> | Validator<TDEST[key], TC>;
         /**
          * If `true` then a missing source property is ignored.  If `false` or omitted
          * then a missing source property causes an error.
@@ -881,6 +956,94 @@ declare interface FunctionConstraintTrait {
     type: 'function';
 }
 
+/**
+ * Generic {@link Conversion.DefaultingConverter | DefaultingConverter}, which wraps another converter
+ * 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> {
+    private _converter;
+    /**
+     * {@inheritdoc Conversion.DefaultingConverter.defaultValue}
+     */
+    defaultValue: TD;
+    /**
+     * {@inheritdoc Converter.isOptional}
+     */
+    get isOptional(): boolean;
+    /**
+     * {@inheritdoc Converter.isOptional}
+     */
+    get brand(): string | undefined;
+    /**
+     * Constructs a new {@link Conversion.GenericDefaultingConverter | generic defaulting converter}.
+     * @param converter - inner {@link Converter | Converter} used for the base conversion.
+     * @param defaultValue - default value to be supplied if the inner conversion fails.
+     */
+    constructor(converter: Converter<T, TC>, defaultValue: TD);
+    /**
+     * {@inheritdoc Converter.convert}
+     */
+    convert(from: unknown, ctx?: TC | undefined): Success<T | TD>;
+    /**
+     * {@inheritdoc Converter.convalidate}
+     */
+    convalidate(from: unknown, ctx?: TC | undefined): Success<T | TD>;
+    /**
+     * {@inheritdoc Converter.convertOptional}
+     */
+    convertOptional(from: unknown, context?: TC | undefined, onError?: ('failOnError' | 'ignoreErrors') | undefined): Result<T | TD | undefined>;
+    /**
+     * {@inheritdoc Converter.optional}
+     */
+    optional(onError?: ('failOnError' | 'ignoreErrors') | undefined): Converter<T | TD | undefined, TC>;
+    /**
+     * {@inheritdoc Converter.map}
+     */
+    map<T2>(mapper: (from: T | TD) => Result<T2>): Converter<T2, TC>;
+    /**
+     * {@inheritdoc Converter.mapConvert}
+     */
+    mapConvert<T2>(mapConverter: Converter<T2, unknown>): Converter<T2, TC>;
+    /**
+     * {@inheritdoc Converter.mapItems}
+     */
+    mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC>;
+    /**
+     * {@inheritdoc Converter.mapConvertItems}
+     */
+    mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
+    /**
+     * {@inheritdoc Converter.withAction}
+     */
+    withAction<T2>(action: (result: Result<T | TD>) => Result<T2>): Converter<T2, TC>;
+    /**
+     * {@inheritdoc Converter.withTypeGuard}
+     */
+    withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string | undefined): Converter<TI, TC>;
+    /**
+     * {@inheritdoc Converter.withItemTypeGuard}
+     */
+    withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string | undefined): Converter<TI[], TC>;
+    /**
+     * {@inheritdoc Converter.withConstraint}
+     */
+    withConstraint(constraint: (val: T | TD) => boolean | Result<T | TD>, options?: ConstraintOptions | undefined): Converter<T | TD, TC>;
+    /**
+     * {@inheritdoc Converter.withBrand}
+     */
+    withBrand<B extends string>(brand: B): Converter<Brand<T | TD, B>, TC>;
+    /**
+     * Returns a Converter which always succeeds with the supplied default value rather
+     * than failing.
+     *
+     * Note that the supplied default value *overrides* the default value of this
+     * {@link Conversion.DefaultingConverter | DefaultingConverter}.
+     */
+    withDefault<TD2 = T>(dflt: TD2): DefaultingConverter<T, TD2, TC>;
+    private _applyDefault;
+}
+
 /**
  * Generic base implementation for an in-place {@link Validation.Validator | Validator}.
  * @public
@@ -916,6 +1079,10 @@ declare class GenericValidator<T, TC = undefined> implements Validator<T, TC> {
      * {@inheritdoc Validation.Validator.validate}
      */
     validate(from: unknown, context?: TC): Result<T>;
+    /**
+     * {@inheritdoc Validation.Validator.convalidate}
+     */
+    convalidate(from: unknown, context?: TC): Result<T>;
     /**
      * {@inheritdoc Validation.Validator.validateOptional}
      */
@@ -1176,10 +1343,10 @@ export declare interface IResultLogger {
 }
 
 /**
- * Helper function to create a {@link Converter} from a supplied type guard function.
+ * 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
  * @param guard - a {@link Validation.TypeGuardWithContext} which performs the validation.
- * @returns A new {@link Converter} which validates the values using the supplied type guard
+ * @returns A new {@link Converter | Converter} which validates the values using the supplied type guard
  * and returns them in place.
  * @public
  */
@@ -1207,7 +1374,7 @@ 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;
 
 /**
- * A {@link Converter} which converts an iso formatted string, a number or a `Date` object to
+ * A {@link Converter | Converter} which converts an iso formatted string, a number or a `Date` object to
  * a `Date` object.
  * @public
  */
@@ -1231,7 +1398,7 @@ declare interface KeyedConverterOptions<T extends string = string, TC = undefine
      * @remarks
      * Can be used to coerce key names to supported values and/or strong types.
      */
-    keyConverter?: Converter<T, TC>;
+    keyConverter?: Converter<T, TC> | Validator<T, TC>;
 }
 
 /**
@@ -1241,10 +1408,10 @@ declare interface KeyedConverterOptions<T extends string = string, TC = undefine
 declare type KeyedThingFactory<TS, TD, TK extends string = string> = (key: TK, thing: TS) => Result<TD>;
 
 /**
- * Helper function to create a {@link Converter} which converts `unknown` to some supplied literal value. Succeeds with
+ * 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.
  * @param value - The value to be compared.
- * @returns A {@link Converter} which returns the supplied value on success.
+ * @returns A {@link Converter | Converter} which returns the supplied value on success.
  * @public
  */
 declare function literal<T>(value: T): Converter<T, unknown>;
@@ -1326,48 +1493,53 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
  export declare function mapFailures<T>(results: Iterable<Result<T>>): string[];
 
  /**
-  * A helper function to create a {@link Converter} which converts the `string`-keyed properties
-  * using a supplied {@link Converter | Converter<T>} to produce a `Map<string, T>`.
+  * 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
+  * `Map<string, T>`.
   * @remarks
   * The resulting converter fails conversion if any element cannot be converted.
-  * @param converter - {@link Converter} used to convert each item in the source object.
-  * @returns A {@link Converter} which returns `Map<string, T>`.
+  * @param converter - {@link Converter | Converter} | {@link Validator | Validator} used for each item in
+  * the source object.
+  * @returns A {@link Converter | Converter} which returns `Map<string, T>`.
   * {@label WITH_DEFAULT}
   * @public
   */
- declare function mapOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC>): Converter<Map<TK, T>, TC>;
+ declare function mapOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>): Converter<Map<TK, T>, TC>;
 
  /**
-  * A helper function to create a {@link Converter} which converts the `string`-keyed properties
-  * using a supplied {@link Converter | Converter<T>} to produce a `Map<string, T>` and optionally
-  * specified handling of elements that cannot be converted.
+  * 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
+  * `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
   * cannot be converted.  If `onError` is `'ignore'`, failing elements are silently ignored.
-  * @param converter - {@link Converter} used to convert each item in the source object.
-  * @returns A {@link Converter} which returns `Map<string, T>`.
+  * @param converter - {@link Converter | Converter} or {@link Validator | Validator} used for
+  * each item in the source object.
+  * @returns A {@link Converter | Converter} which returns `Map<string, T>`.
   * {@label WITH_ON_ERROR}
   * @public
   */
- declare function mapOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC>, onError: 'fail' | 'ignore'): Converter<Map<TK, T>, TC>;
+ 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>;
 
  /**
-  * A helper function to create a {@link Converter} which converts the `string`-keyed properties
-  * using a supplied {@link Converter | Converter<T>} to produce a `Map<TK, T>`.
+  * 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 `Map<TK,T>`.
   * @remarks
   * If present, the supplied {@link Converters.KeyedConverterOptions | options} can provide a strongly-typed
   * converter for keys and/or control the handling of elements that fail conversion.
-  * @param converter - {@link Converter} used to convert each item in the source object.
+  * @param converter - {@link Converter | Converter} or {@link Validator | Validator} used for each item
+  * in the source object.
   * @param options - Optional {@link Converters.KeyedConverterOptions | KeyedConverterOptions<TK, TC>} which
   * supplies a key converter and/or error-handling options.
-  * @returns A {@link Converter} which returns `Map<TK, T>`.
+  * @returns A {@link Converter | Converter} which returns `Map<TK,T>`.
   * {@label WITH_OPTIONS}
   * @public
   */
- declare function mapOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC>, options: KeyedConverterOptions<TK, TC>): Converter<Map<TK, T>, TC>;
+ 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>;
 
  /**
-  * Helper function to create a {@link Converter} which converts `unknown` to one of a set of supplied enumerated
+  * Helper function to create a {@link Converter | Converter} which converts `unknown` to one of a set of supplied enumerated
   * values, mapping any of multiple supplied values to the enumeration.
   * @remarks
   * Enables mapping of multiple input values to a consistent internal representation (so e.g. `'y'`, `'yes'`,
@@ -1376,7 +1548,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
   * value, the second is the set of values that map to the result.  Tuples are evaluated in the order
   * supplied and are not checked for duplicates.
   * @param message - An optional error message.
-  * @returns A {@link Converter} which applies the mapping and yields `<T>` on success.
+  * @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>;
@@ -1458,7 +1630,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
    }
 
    /**
-    * A {@link Converter} which converts `unknown` to a `number`.
+    * A {@link Converter | Converter} which converts `unknown` to a `number`.
     * @remarks
     * Numbers and strings with a numeric format succeed. Anything else fails.
     * @public
@@ -1511,9 +1683,9 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
     * without changing shape, given a {@link Conversion.FieldConverters | FieldConverters<T>} 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}
+    * By default, if all of the requested fields exist and can be converted, returns {@link Success | Success}
     * with a new object that contains the converted values under the original key names.  If any required properties
-    * do not exist or cannot be converted, the entire conversion fails, returning {@link Failure} with additional
+    * do not exist or cannot be converted, the entire conversion fails, returning {@link Failure | Failure} with additional
     * error information.
     *
     * Fields that succeed but convert to undefined are omitted from the result object but do not
@@ -1533,9 +1705,9 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
     * without changing shape, given a {@link Conversion.FieldConverters | FieldConverters<T>} and a set of
     * optional properties.
     * @remarks
-    * By default, if all of the requested fields exist and can be converted, returns {@link Success}
+    * By default, if all of the requested fields exist and can be converted, returns {@link Success | Success}
     * with a new object that contains the converted values under the original key names.  If any required properties
-    * do not exist or cannot be converted, the entire conversion fails, returning {@link Failure} with additional
+    * do not exist or cannot be converted, the entire conversion fails, returning {@link Failure | Failure} with additional
     * error information.
     *
     * Fields that succeed but convert to undefined are omitted from the result object but do not
@@ -1767,22 +1939,24 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
    export declare function omit<T extends object, K extends keyof T>(from: T, exclude: K[]): Omit<T, K>;
 
    /**
-    * A helper function to create a {@link Converter} for polymorphic values.  Returns a
-    * converter which Invokes the wrapped converters in sequence, returning the first successful
-    * result.  Returns an error if none of the supplied converters can convert the value.
+    * A helper function to create a {@link Converter | Converter} for polymorphic values.
+    * Returns a converter which invokes the wrapped converters in sequence, returning the
+    * first successful result.  Returns an error if none of the supplied converters can
+    * convert the value.
     * @remarks
     * If `onError` is `ignoreErrors` (default), then errors from any of the
     * converters are ignored provided that some converter succeeds.  If
     * onError is `failOnError`, then an error from any converter fails the entire
     * conversion.
     *
-    * @param converters - An ordered list of {@link Converter | converters} to be considered.
+    * @param converters - An ordered list of {@link Converter | converters} or {@link Validator | validators}
+    * to be considered.
     * @param onError - Specifies treatment of unconvertible elements.
-    * @returns A new {@link Converter} which yields a value from the union of the types returned
+    * @returns A new {@link Converter | Converter} which yields a value from the union of the types returned
     * by the wrapped converters.
     * @public
     */
-   declare function oneOf<T, TC = unknown>(converters: Array<Converter<T, TC>>, onError?: OnError_2): Converter<T, TC>;
+   declare function oneOf<T, TC = unknown>(converters: Array<Converter<T, TC> | Validator<T, TC>>, onError?: OnError): Converter<T, TC>;
 
    /**
     * Helper function to create a {@link Validation.Validator | Validator} which validates one
@@ -1832,51 +2006,49 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
        validators: Validator<T, TC>[];
    }
 
-   declare type OnError = 'failOnError' | 'ignoreErrors';
-
    /**
     * Action to take on conversion failures.
     * @public
     */
-   declare type OnError_2 = 'failOnError' | 'ignoreErrors';
+   declare type OnError = 'failOnError' | 'ignoreErrors';
 
    /**
-    * A {@link Converter} to convert an optional `boolean` value.
+    * A {@link Converter | Converter} to convert an optional `boolean` value.
     * @remarks
     * Values of type `boolean` or strings that match (case-insensitive) `'true'`
-    * or `'false'` are converted and returned.  Anything else returns {@link Success}
+    * or `'false'` are converted and returned.  Anything else returns {@link Success | Success}
     * with value `undefined`.
     * @public
     */
    declare const optionalBoolean: Converter<boolean | undefined>;
 
    /**
-    * A helper function to create a {@link Converter} which extracts and converts an optional element from an array.
+    * A helper function to create a {@link Converter | Converter} which extracts and converts an optional element from an array.
     * @remarks
-    * The resulting {@link Converter} returns {@link Success} with the converted value if the element exists
-    * in the supplied array and can be converted. Returns {@link Success} with value `undefined` if the parameter
-    * is an array but the index is out of range. Returns {@link Failure} with a message if the supplied parameter
+    * The resulting {@link Converter | Converter} returns {@link Success | Success} with the converted value if the element exists
+    * in the supplied array and can be converted. Returns {@link Success | Success} with value `undefined` if the parameter
+    * is an array but the index is out of range. Returns {@link Failure | Failure} with a message if the supplied parameter
     * 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} used to convert the extracted element.
+    * @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.
     * @public
     */
-   declare function optionalElement<T, TC = undefined>(index: number, converter: Converter<T, TC>): Converter<T | undefined, TC>;
+   declare function optionalElement<T, TC = undefined>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, TC>;
 
    /**
-    * A helper function to create a {@link Converter} which extracts and convert a property specified
+    * A helper function to create a {@link Converter | Converter} which extracts and convert a property specified
     * by name from an object.
     * @remarks
-    * The resulting {@link Converter} returns {@link Success} with the converted value of the corresponding
-    * object property if the field exists and can be converted. Returns {@link Success} with value `undefined`
-    * if the supplied parameter is an object but the named field is not present.  Returns {@link Failure} with
-    * an error message otherwise.
+    * The resulting {@link Converter | Converter} returns {@link Success | Success} with the converted value of
+    * the corresponding object property if the field exists and can be converted. Returns {@link Success | Success}
+    * with `undefined` if the supplied parameter is an object but the named field is not present.
+    * Returns {@link Failure | Failure} with an error message otherwise.
     * @param name - The name of the field to be extracted.
-    * @param converter - {@link Converter} used to convert the extracted field.
+    * @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>): Converter<T | undefined, TC>;
+   declare function optionalField<T, TC = undefined>(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>`
@@ -1899,10 +2071,10 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
      export declare function optionalMapToRecord<TS, TD, TK extends string = string>(src: ReadonlyMap<TK, TS> | undefined, factory: KeyedThingFactory<TS, TD, TK>): Result<Record<TK, TD> | undefined>;
 
      /**
-      * A {@link Converter} which converts an optional `number` value.
+      * A {@link Converter | Converter} which converts an optional `number` value.
       * @remarks
       * Values of type `number` or numeric strings are converted and returned.
-      * Anything else returns {@link Success} with value `undefined`.
+      * Anything else returns {@link Success | Success} with value `undefined`.
       * @public
       */
      declare const optionalNumber: Converter<number | undefined>;
@@ -1928,8 +2100,8 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
        export declare function optionalRecordToPossiblyEmptyMap<TS, TD, TK extends string = string>(src: Record<TK, TS> | undefined, factory: KeyedThingFactory<TS, TD, TK>): Result<Map<TK, TD>>;
 
        /**
-        * A {@link Converter} which converts an optional `string` value. Values of type
-        * `string` are returned.  Anything else returns {@link Success} with value `undefined`.
+        * A {@link Converter | Converter} which converts an optional `string` value. Values of type
+        * `string` are returned.  Anything else returns {@link Success | Success} with value `undefined`.
         * @public
         */
        declare const optionalString: Converter<string | undefined, unknown>;
@@ -2006,45 +2178,49 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
        export declare function propagateWithDetail<T, TD>(result: Result<T>, detail: TD, successDetail?: TD): DetailedResult<T, TD>;
 
        /**
-        * A helper function to create a {@link Converter} which converts the `string`-keyed properties
-        * using a supplied {@link Converter | Converter<T>} to produce a `Record<string, T>`.
+        * 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 `Record<string, T>`.
         * @remarks
         * The resulting converter fails conversion if any element cannot be converted.
-        * @param converter - {@link Converter} used to convert each item in the source object.
-        * @returns A {@link Converter} which returns `Record<string, T>`.
+        * @param converter - {@link Converter | Converter} or {@link Validator | Validator} used for each
+        * item in the source object.
+        * @returns A {@link Converter | Converter} which returns `Record<string, T>`.
         * {@label WITH_DEFAULT}
         * @public
         */
-       declare function recordOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC>): Converter<Record<TK, T>, TC>;
+       declare function recordOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>): Converter<Record<TK, T>, TC>;
 
        /**
-        * A helper function to create a {@link Converter} which converts the `string`-keyed properties
-        * using a supplied {@link Converter | Converter<T>} to produce a `Record<string, T>` and optionally
-        * specified handling of elements that cannot be converted.
+        * 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
+        * `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
         * cannot be converted.  If `onError` is `'ignore'`, failing elements are silently ignored.
-        * @param converter - {@link Converter} used to convert each item in the source object.
-        * @returns A {@link Converter} which returns `Record<string, T>`.
+        * @param converter - {@link Converter | Converter} or {@link Validator | Validator} for each item in
+        * the source object.
+        * @returns A {@link Converter | Converter} which returns `Record<string, T>`.
         * {@label WITH_ON_ERROR}
         * @public
         */
-       declare function recordOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC>, onError: 'fail' | 'ignore'): Converter<Record<TK, T>, TC>;
+       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>;
 
        /**
-        * A helper function to create a {@link Converter} which converts the `string`-keyed properties
-        * using a supplied {@link Converter | Converter<T>} to produce a `Record<TK, T>`.
+        * 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
+        * `Record<TK, T>`.
         * @remarks
         * If present, the supplied {@link Converters.KeyedConverterOptions | options} can provide a strongly-typed
         * converter for keys and/or control the handling of elements that fail conversion.
-        * @param converter - {@link Converter} used to convert each item in the source object.
+        * @param converter - {@link Converter | Converter} or {@link Validator | Validator} used for each item in the source object.
         * @param options - Optional {@link Converters.KeyedConverterOptions | KeyedConverterOptions<TK, TC>} which
         * supplies a key converter and/or error-handling options.
-        * @returns A {@link Converter} which returns `Record<TK, T>`.
+        * @returns A {@link Converter | Converter} which returns `Record<TK, T>`.
         * {@label WITH_OPTIONS}
         * @public
         */
-       declare function recordOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC>, options: KeyedConverterOptions<TK, TC>): Converter<Record<TK, T>, TC>;
+       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>;
 
        /**
         * Applies a factory method to convert a `Record<TK, TS>` into a `Map<TK, TD>`.
@@ -2138,10 +2314,10 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
         declare const string_2: Validator<string>;
 
         /**
-         * {@link Converter} to convert an `unknown` to an array of `string`.
+         * {@link Converter | Converter} to convert an `unknown` to an array of `string`.
          * @remarks
-         * Returns {@link Success} with the the supplied value if it as an array
-         * of strings, returns {@link Failure} with an error message otherwise.
+         * Returns {@link Success | Success} with the the supplied value if it as an array
+         * of strings, returns {@link Failure | Failure} with an error message otherwise.
          * @public
          */
         declare const stringArray: Converter<string[]>;
@@ -2152,7 +2328,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
          * helper methods.
          * @public
          */
-        declare class StringConverter<T extends string = string, TC = unknown> extends BaseConverter<T, TC> {
+        export declare class StringConverter<T extends string = string, TC = unknown> extends BaseConverter<T, TC> {
             /**
              * Construct a new {@link Conversion.StringConverter | StringConverter}.
              * @param defaultContext - Optional context used by the conversion.
@@ -2352,19 +2528,19 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                 * @remarks
                 * Template conversions are applied using `mustache` syntax.
                 * @param defaultContext - Optional default context to use for template values.
-                * @returns A new {@link Converter} returning `string`.
+                * @returns A new {@link Converter | Converter} returning `string`.
                 * @public
                 */
                declare function templateString(defaultContext?: unknown): StringConverter<string, unknown>;
 
                /**
-                * Helper to create a {@link Converter} which converts a source object to a new object with a
+                * Helper to create a {@link Converter | Converter} which converts a source object to a new object with a
                 * different shape.
                 *
                 * @remarks
-                * On successful conversion, the resulting {@link Converter} returns {@link Success} with a new
+                * On successful conversion, the resulting {@link Converter | Converter} returns {@link Success | Success} with a new
                 * object, which contains the converted values under the key names specified at initialization time.
-                * It returns {@link Failure} with an error message if any fields to be extracted do not exist
+                * It returns {@link Failure | Failure} with an error message if any fields to be extracted do not exist
                 * or cannot be converted.
                 *
                 * Fields that succeed but convert to undefined are omitted from the result object but do not
@@ -2373,29 +2549,29 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                 * @param properties - An object with key names that correspond to the target object and an
                 * appropriate {@link Conversion.FieldConverters | FieldConverter} which extracts and converts
                 * a single filed from the source object.
-                * @returns A {@link Converter} with the specified conversion behavior.
+                * @returns A {@link Converter | Converter} with the specified conversion behavior.
                 * @public
                 */
                declare function transform<T, TC = unknown>(properties: FieldConverters<T, TC>): Converter<T, TC>;
 
                /**
-                * Helper to create a strongly-typed {@link Converter} which converts a source object to a
+                * Helper to create a strongly-typed {@link Converter | Converter} which converts a source object to a
                 * new object with a different shape.
                 *
                 * @remarks
-                * On successful conversion, the resulting {@link Converter} returns {@link Success} with a new
+                * On successful conversion, the resulting {@link Converter | Converter} returns {@link Success | Success} with a new
                 * object, which contains the converted values under the key names specified at initialization time.
                 *
-                * It returns {@link Failure} with an error message if any fields to be extracted do not exist
+                * It returns {@link Failure | Failure} with an error message if any fields to be extracted do not exist
                 * or cannot be converted.
                 *
                 * @param destinationFields - An object with key names that correspond to the target object and an
                 * appropriate {@link Converters.FieldTransformers | FieldTransformers} which specifies the name
-                * of the corresponding property in the source object, the converter used to convert the source
-                * property and any configuration to guide the conversion.
+                * of the corresponding property in the source object, the converter or validator used for each source
+                * property and any other configuration to guide the conversion.
                 * @param options - Options which affect the transformation.
                 *
-                * @returns A {@link Converter} with the specified conversion behavior.
+                * @returns A {@link Converter | Converter} with the specified conversion behavior.
                 * @public
                 */
                declare function transformObject<TSRC, TDEST, TC = unknown>(destinationFields: FieldTransformers<TSRC, TDEST, TC>, options?: TransformObjectOptions<TSRC>): Converter<TDEST, TC>;
@@ -2469,19 +2645,19 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                declare type TypeGuardWithContext<T, TC = unknown> = (from: unknown, context?: TC) => from is T;
 
                /**
-                * Helper function to create a {@link Converter} from any {@link Validation.Validator}
+                * Helper function to create a {@link Converter | Converter} from any {@link Validation.Validator}
                 * @param validator - the validator to be wrapped
-                * @returns A {@link Converter} which uses the supplied validator.
+                * @returns A {@link Converter | Converter} which uses the supplied validator.
                 * @public
                 */
                declare function validated<T, TC = unknown>(validator: Validator<T, TC>): Converter<T, TC>;
 
                /**
-                * Helper function to create  a {@link Converter} which validates that a supplied value is
+                * Helper function to create  a {@link Converter | Converter} which validates that a supplied value is
                 * of a type validated by a supplied validator function and returns it.
                 * @remarks
-                * If `validator` succeeds, this {@link Converter} returns {@link Success} with the supplied
-                * value of `from` coerced to type `<T>`.  Returns a {@link Failure} with additional
+                * If `validator` succeeds, this {@link Converter | Converter} returns {@link Success | Success} with the supplied
+                * value of `from` coerced to type `<T>`.  Returns a {@link Failure | Failure} with additional
                 * 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.
@@ -2496,6 +2672,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                        Classes,
                        Validators,
                        TypeGuardWithContext,
+                       Convalidator,
                        FunctionConstraintTrait,
                        ConstraintTrait,
                        ValidatorTraitValues,
@@ -2513,7 +2690,7 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                 * required characteristics (type, values, etc).
                 * @public
                 */
-               export declare interface Validator<T, TC = undefined> {
+               export declare interface Validator<T, TC = undefined> extends Convalidator<T, TC> {
                    /**
                     * {@link Validation.ValidatorTraits | Traits} describing this validation.
                     */
@@ -2527,14 +2704,18 @@ declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
                     */
                    readonly brand: string | undefined;
                    /**
-                    * Tests to see if a supplied `unknown` value matches this
-                    * validation.
+                    * Tests to see if a supplied `unknown` value matches this validation.  All
+                    * validate calls are guaranteed to return the entity passed in on Success.
                     * @param from - The `unknown` value to be tested.
                     * @param context - Optional validation context.
                     * @returns {@link Success} with the typed, validated value,
                         * or {@link Failure} with an error message if validation fails.
                         */
                     validate(from: unknown, context?: TC): Result<T>;
+                    /**
+                     * {@inheritdoc Validation.Convalidator.convalidate}
+                     */
+                    convalidate(from: unknown, context?: TC): Result<T>;
                     /**
                      * Tests to see if a supplied `unknown` value matches this
                      * validation.  Accepts `undefined`.