@fgv/ts-utils - npm Package Compare versions

Comparing version 4.1.0 to 4.2.0

CHANGELOG.json

@@ -5,2 +5,20 @@ {
     {
+      "version": "4.2.0",
+      "tag": "@fgv/ts-utils_v4.2.0",
+      "date": "Mon, 20 Jan 2025 09:46:53 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "add collections packlet and ResultMap class"
+          },
+          {
+            "comment": "add withFormattedError on validator and converter"
+          },
+          {
+            "comment": "clean up type inconsistencies, relax some constraints"
+          }
+        ]
+      }
+    },
+    {
       "version": "4.1.0",
@@ -7,0 +25,0 @@ "tag": "@fgv/ts-utils_v4.1.0",

CHANGELOG.md

 # Change Log - @fgv/ts-utils
 
-This log was last generated on Thu, 09 Jan 2025 05:33:39 GMT and should not be manually modified.
+This log was last generated on Mon, 20 Jan 2025 09:46:53 GMT and should not be manually modified.
 
+## 4.2.0
+Mon, 20 Jan 2025 09:46:53 GMT
+
+### Updates
+
+- add collections packlet and ResultMap class
+- add withFormattedError on validator and converter
+- clean up type inconsistencies, relax some constraints
+
 ## 4.1.0
@@ -6,0 +15,0 @@ Thu, 09 Jan 2025 05:33:39 GMT

lib/index.d.ts

@@ -0,8 +1,10 @@
+import * as Collections from './packlets/collections';
 import * as Conversion from './packlets/conversion';
 import * as Hash from './packlets/hash';
 import * as Validation from './packlets/validation';
+import { IReadOnlyResultMap, ResultMap, ValidatingResultMap } from './packlets/collections';
 import { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';
 import { Validator, Validators } from './packlets/validation';
 export * from './packlets/base';
-export { Conversion, Converter, Converters, Hash, ObjectConverter, StringConverter, Validation, Validator, Validators };
+export { Collections, Conversion, Converter, Converters, Hash, IReadOnlyResultMap, ObjectConverter, ResultMap, StringConverter, ValidatingResultMap, Validation, Validator, Validators };
 //# sourceMappingURL=index.d.ts.map

lib/index.js

@@ -60,3 +60,5 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Validators = exports.Validation = exports.StringConverter = exports.ObjectConverter = exports.Hash = exports.Converters = exports.Conversion = void 0;
+exports.Validators = exports.Validation = exports.ValidatingResultMap = exports.StringConverter = exports.ResultMap = exports.ObjectConverter = exports.Hash = exports.Converters = exports.Conversion = exports.Collections = void 0;
+const Collections = __importStar(require("./packlets/collections"));
+exports.Collections = Collections;
 const Conversion = __importStar(require("./packlets/conversion"));
@@ -68,2 +70,5 @@ exports.Conversion = Conversion;
 exports.Validation = Validation;
+const collections_1 = require("./packlets/collections");
+Object.defineProperty(exports, "ResultMap", { enumerable: true, get: function () { return collections_1.ResultMap; } });
+Object.defineProperty(exports, "ValidatingResultMap", { enumerable: true, get: function () { return collections_1.ValidatingResultMap; } });
 const conversion_1 = require("./packlets/conversion");
@@ -70,0 +75,0 @@ Object.defineProperty(exports, "Converters", { enumerable: true, get: function () { return conversion_1.Converters; } });

lib/packlets/conversion/baseConverter.d.ts

 import { Brand, Result } from '../base';
-import { ConstraintOptions, Converter, ConverterTraits, DefaultingConverter, OnError } from './converter';
+import { ConstraintOptions, ConversionErrorFormatter, Converter, ConverterTraits, DefaultingConverter, OnError } from './converter';
 /**
@@ -13,3 +13,3 @@ * internal
  */
-export type Infer<TCONV> = TCONV extends Converter<infer TTO> ? InnerInferredType<TTO> : never;
+export type Infer<TCONV> = TCONV extends Converter<infer TTO, unknown> ? InnerInferredType<TTO> : never;
 /**
@@ -25,3 +25,3 @@ * Deprecated name for Infer<T> retained for compatibility
  */
-export declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
+export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC> {
     /**
@@ -113,2 +113,6 @@ * @internal
     /**
+     * {@inheritdoc Converter.withFormattedError}
+     */
+    withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC>;
+    /**
      * @internal
@@ -115,0 +119,0 @@ */

lib/packlets/conversion/baseConverter.js

@@ -218,2 +218,12 @@ "use strict";
     /**
+     * {@inheritdoc Converter.withFormattedError}
+     */
+    withFormattedError(formatter) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onFailure((msg) => {
+                return (0, base_1.fail)(formatter(from, msg, this._context(context)));
+            });
+        })._with(this._traits());
+    }
+    /**
      * @internal
@@ -220,0 +230,0 @@ */

lib/packlets/conversion/converter.d.ts

@@ -16,2 +16,11 @@ import { Brand, Result, Success } from '../base';
 /**
+ * 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
+ */
+export type ConversionErrorFormatter<TC = unknown> = (val: unknown, message?: string, context?: TC) => string;
+/**
  * Options for {@link Converter.withConstraint}.
@@ -33,3 +42,3 @@ * @public
  */
-export interface Converter<T, TC = undefined> extends ConverterTraits {
+export interface Converter<T, TC = unknown> extends ConverterTraits {
     /**
@@ -102,3 +111,3 @@ * Indicates whether this element is explicitly optional.
      */
-    mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
+    mapConvert<T2>(mapConverter: Converter<T2, unknown>): Converter<T2, TC>;
     /**
@@ -168,2 +177,9 @@ * Creates a {@link Converter} which maps the individual items of a collection
     /**
+     * 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
@@ -183,3 +199,3 @@ * of simple types.
  */
-export interface DefaultingConverter<T, TD = T, TC = undefined> extends Converter<T | TD, TC> {
+export interface DefaultingConverter<T, TD = T, TC = unknown> extends Converter<T | TD, TC> {
     /**
@@ -186,0 +202,0 @@ * Default value to use if the conversion fails.

lib/packlets/conversion/converters.d.ts

@@ -41,3 +41,3 @@ import { TypeGuardWithContext, Validator } from '../validation';
  */
-export declare function mappedEnumeratedValue<T>(map: [T, unknown[]][], message?: string): Converter<T, undefined>;
+export declare function mappedEnumeratedValue<T, TC = unknown>(map: [T, unknown[]][], message?: string): Converter<T, TC>;
 /**
@@ -50,3 +50,3 @@ * Helper function to create a {@link Converter | Converter} which converts `unknown` to some supplied literal value. Succeeds with
  */
-export declare function literal<T>(value: T): Converter<T, unknown>;
+export declare function literal<T, TC = unknown>(value: T): Converter<T, TC>;
 /**
@@ -65,3 +65,3 @@ * Deprecated alias for @see literal
  */
-export declare const number: Converter<number, undefined>;
+export declare const number: Converter<number, unknown>;
 /**
@@ -74,3 +74,3 @@ * A {@link Converter | Converter} which converts `unknown` to `boolean`.
  */
-export declare const boolean: Converter<boolean, undefined>;
+export declare const boolean: Converter<boolean, unknown>;
 /**
@@ -115,3 +115,3 @@ * A {@link Converter | Converter} which converts an optional `string` value. Values of type
  */
-export declare const optionalNumber: Converter<number | undefined>;
+export declare const optionalNumber: Converter<number | undefined, unknown>;
 /**
@@ -125,3 +125,3 @@ * A {@link Converter | Converter} to convert an optional `boolean` value.
  */
-export declare const optionalBoolean: Converter<boolean | undefined>;
+export declare const optionalBoolean: Converter<boolean | undefined, unknown>;
 /**
@@ -157,3 +157,3 @@ * A helper function to create a {@link Converter | Converter} for polymorphic values.
  */
-export declare function arrayOf<T, TC = undefined>(converter: Converter<T, TC> | Validator<T, TC>, onError?: OnError): Converter<T[], TC>;
+export declare function arrayOf<T, TC = unknown>(converter: Converter<T, TC> | Validator<T, TC>, onError?: OnError): Converter<T[], TC>;
 /**
@@ -166,3 +166,3 @@ * {@link Converter | Converter} to convert an `unknown` to an array of `string`.
  */
-export declare const stringArray: Converter<string[]>;
+export declare const stringArray: Converter<string[], unknown>;
 /**
@@ -175,3 +175,3 @@ * {@link Converter | Converter} to convert an `unknown` to an array of `number`.
  */
-export declare const numberArray: Converter<number[]>;
+export declare const numberArray: Converter<number[], unknown>;
 /**
@@ -183,3 +183,3 @@ * Options for {@link Converters.(recordOf:3) | Converters.recordOf} and
  */
-export interface KeyedConverterOptions<T extends string = string, TC = undefined> {
+export interface KeyedConverterOptions<T extends string = string, TC = unknown> {
     /**
@@ -200,3 +200,3 @@ * if `onError` is `'fail'` (default), then the entire conversion fails if any key or element
  * 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>`.
@@ -211,6 +211,6 @@ * @remarks
  */
-export declare function recordOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>): Converter<Record<TK, T>, TC>;
+export 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.
@@ -226,6 +226,6 @@ * @remarks
  */
-export 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>;
+export 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>`.
@@ -242,6 +242,6 @@ * @remarks
  */
-export 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>;
+export 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>;
 /**
  * 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>`.
@@ -256,6 +256,6 @@ * @remarks
  */
-export declare function mapOf<T, TC = undefined, TK extends string = string>(converter: Converter<T, TC> | Validator<T, TC>): Converter<Map<TK, T>, TC>;
+export 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.
@@ -271,6 +271,6 @@ * @remarks
  */
-export 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>;
+export 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>`.
@@ -288,3 +288,3 @@ * @remarks
  */
-export 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>;
+export 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>;
 /**
@@ -299,6 +299,6 @@ * Helper function to create  a {@link Converter | Converter} which validates that a supplied value is
  * @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
  */
-export declare function validateWith<T, TC = undefined>(validator: (from: unknown) => from is T, description?: string): Converter<T, TC>;
+export declare function validateWith<T, TC = unknown>(validator: (from: unknown) => from is T, description?: string): Converter<T, TC>;
 /**
@@ -311,6 +311,6 @@ * A helper function to create a {@link Converter | Converter} which extracts and converts an element from an array.
  * @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
  */
-export declare function element<T, TC = undefined>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
+export declare function element<T, TC = unknown>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
 /**
@@ -325,6 +325,6 @@ * A helper function to create a {@link Converter | Converter} which extracts and converts an optional element from an array.
  * @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
  */
-export declare function optionalElement<T, TC = undefined>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, TC>;
+export declare function optionalElement<T, TC = unknown>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, TC>;
 /**
@@ -342,3 +342,3 @@ * A helper function to create a {@link Converter | Converter} which extracts and convert a property specified
  */
-export declare function field<T, TC = undefined>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
+export declare function field<T, TC = unknown>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
 /**
@@ -356,6 +356,6 @@ * A helper function to create a {@link Converter | Converter} which extracts and convert a property specified
  */
-export declare function optionalField<T, TC = undefined>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, TC>;
+export declare function optionalField<T, TC = unknown>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T | undefined, 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.
@@ -370,3 +370,3 @@ * @remarks
  * 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.
@@ -379,6 +379,6 @@ * @param options - An {@link Conversion.ObjectConverterOptions | ObjectConverterOptions<T>} containing options
  */
-export declare function object<T>(properties: FieldConverters<T>, options?: ObjectConverterOptions<T>): ObjectConverter<T>;
+export 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.
@@ -393,3 +393,3 @@ * @remarks
  * 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.
@@ -402,3 +402,3 @@ * @param optional - An array of `(keyof T)` listing the keys to be considered optional.
  */
-export declare function object<T>(properties: FieldConverters<T>, optional: (keyof T)[]): ObjectConverter<T>;
+export declare function object<T, TC = unknown>(properties: FieldConverters<T, TC>, optional: (keyof T)[]): ObjectConverter<T, TC>;
 /**
@@ -411,3 +411,3 @@ * Options for the {@link Converters.(strictObject:1)} helper function.
  * 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
@@ -428,6 +428,6 @@ * conversion behavior.
  */
-export declare function strictObject<T>(properties: FieldConverters<T>, options?: StrictObjectConverterOptions<T>): ObjectConverter<T>;
+export 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
@@ -449,3 +449,3 @@ * conversion behavior.
  */
-export declare function strictObject<T>(properties: FieldConverters<T>, optional: (keyof T)[]): ObjectConverter<T>;
+export declare function strictObject<T, TC = unknown>(properties: FieldConverters<T, TC>, optional: (keyof T)[]): ObjectConverter<T, TC>;
 /**
@@ -452,0 +452,0 @@ * A string-keyed `Record<string, Converter>` which maps specific {@link Converter | converters} or

lib/packlets/conversion/converters.js

@@ -308,5 +308,5 @@ "use strict";
 /**
- * Concrete implementation of {@link Converters.(recordOf:1) | Converters.recordOf(Converter<T>)},
- * {@link Converters.(recordOf:2) | Converters.recordOf(Converter<T>, 'fail' or 'ignore')}, and
- * {@link Converters.(recordOf:3) | Converters.recordOf(Converter<T>, KeyedConverterOptions)}.
+ * Concrete implementation of {@link Converters.(recordOf:1) | Converters.recordOf(Converter<T, TC>)},
+ * {@link Converters.(recordOf:2) | Converters.recordOf(Converter<T, TC>, 'fail' or 'ignore')}, and
+ * {@link Converters.(recordOf:3) | Converters.recordOf(Converter<T, TC>, KeyedConverterOptions)}.
  * @internal
@@ -343,5 +343,5 @@ */
 /**
- * Concrete implementation of {@link Converters.(mapOf:1) | Converters.mapOf(Converter<T>)},
- * {@link Converters.(mapOf:2) | Converters.mapOf(Converter<T>, 'fail' or 'ignore')}, and
- * {@link Converters.(mapOf:3) | Converters.mapOf(Converter<T>, KeyedConverterOptions)}.
+ * Concrete implementation of {@link Converters.(mapOf:1) | Converters.mapOf(Converter<T, TC>)},
+ * {@link Converters.(mapOf:2) | Converters.mapOf(Converter<T, TC>, 'fail' or 'ignore')}, and
+ * {@link Converters.(mapOf:3) | Converters.mapOf(Converter<T, TC>, KeyedConverterOptions)}.
  * @internal
@@ -386,3 +386,3 @@ */
  * @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
@@ -405,3 +405,3 @@ */
  * @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
@@ -432,3 +432,3 @@ */
  * @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
@@ -435,0 +435,0 @@ */

lib/packlets/conversion/defaultingConverter.d.ts

 import { Brand, Result, Success } from '../base';
-import { ConstraintOptions, Converter, DefaultingConverter } from './converter';
+import { ConstraintOptions, ConversionErrorFormatter, Converter, DefaultingConverter } from './converter';
 /**
@@ -8,3 +8,3 @@ * Generic {@link Conversion.DefaultingConverter | DefaultingConverter}, which wraps another converter
  */
-export declare class GenericDefaultingConverter<T, TD = T, TC = undefined> implements DefaultingConverter<T, TD, TC> {
+export declare class GenericDefaultingConverter<T, TD = T, TC = unknown> implements DefaultingConverter<T, TD, TC> {
     private _converter;
@@ -78,2 +78,6 @@ /**
     /**
+     * {@inheritdoc Converter.withFormattedError}
+     */
+    withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T | TD, TC>;
+    /**
      * Returns a Converter which always succeeds with the supplied default value rather
@@ -80,0 +84,0 @@ * than failing.

lib/packlets/conversion/defaultingConverter.js

@@ -132,2 +132,9 @@ "use strict";
     /**
+     * {@inheritdoc Converter.withFormattedError}
+     */
+    withFormattedError(formatter) {
+        // formatter should never actually be invoked for a defaulting converter
+        return this._converter.withAction((result) => this._applyDefault(result)).withFormattedError(formatter);
+    }
+    /**
      * Returns a Converter which always succeeds with the supplied default value rather
@@ -134,0 +141,0 @@ * than failing.

lib/packlets/conversion/objectConverter.d.ts

@@ -46,3 +46,3 @@ import { Validator } from '../validation';
      */
-    readonly fields: FieldConverters<T>;
+    readonly fields: FieldConverters<T, TC>;
     /**
@@ -53,3 +53,3 @@ * Options used to initialize this {@link Conversion.ObjectConverter | ObjectConverter}.
     /**
-     * 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>}.
@@ -63,3 +63,3 @@ * @param fields - A {@link Conversion.FieldConverters | FieldConverters<T>} containing
     /**
-     * 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`.
@@ -66,0 +66,0 @@ * @param fields - A {@link Conversion.FieldConverters | FieldConverters<T>} containing

lib/packlets/validation/field.d.ts

@@ -16,3 +16,3 @@ import { Failure } from '../base';
  */
-export declare class FieldValidator<T, TC = undefined> extends ValidatorBase<T, TC> {
+export declare class FieldValidator<T, TC = unknown> extends ValidatorBase<T, TC> {
     /**
@@ -19,0 +19,0 @@ * The name of the property that this validator should validate.

lib/packlets/validation/genericValidator.d.ts

 import { Brand, Failure, Result } from '../base';
 import { ConstraintTrait, ValidatorTraits } from './traits';
-import { Constraint, Validator, ValidatorOptions } from './validator';
+import { Constraint, ValidationErrorFormatter, Validator, ValidatorOptions } from './validator';
 /**
@@ -24,3 +24,3 @@ * Type for a validation function, which validates that a supplied `unknown`
  */
-export declare class GenericValidator<T, TC = undefined> implements Validator<T, TC> {
+export declare class GenericValidator<T, TC = unknown> implements Validator<T, TC> {
     /**
@@ -81,2 +81,6 @@ * {@inheritdoc Validation.Validator.traits}
     /**
+     * {@inheritdoc Validation.Validator.withFormattedError}
+     */
+    withFormattedError(formatter: ValidationErrorFormatter<TC>): Validator<T, TC>;
+    /**
      * Gets a default or explicit context.
@@ -83,0 +87,0 @@ * @param explicitContext - Optional explicit context.

lib/packlets/validation/genericValidator.js

@@ -108,3 +108,4 @@ "use strict";
             validator: (from, context) => {
-                if (this._validator(from, this._context(context)) === true) {
+                const result = this._validator(from, this._context(context));
+                if (result === true) {
                     const constraintResult = constraint(from);
@@ -118,3 +119,3 @@ if (typeof constraintResult === 'boolean') {
                 }
-                return false;
+                return result;
             },
@@ -139,2 +140,18 @@ traits: { constraints: [trait] }
     /**
+     * {@inheritdoc Validation.Validator.withFormattedError}
+     */
+    withFormattedError(formatter) {
+        return new GenericValidator({
+            validator: (from, context) => {
+                const result = this._validator(from, this._context(context));
+                if (result === true) {
+                    return true;
+                }
+                /* c8 ignore next - defense in depth */
+                const message = result === false ? undefined : result.message;
+                return (0, base_1.fail)(formatter(from, message, this._context(context)));
+            }
+        });
+    }
+    /**
      * Gets a default or explicit context.
@@ -141,0 +158,0 @@ * @param explicitContext - Optional explicit context.

lib/packlets/validation/validator.d.ts

@@ -19,2 +19,11 @@ import { Brand, Failure, Result } from '../base';
 /**
+ * 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
+ */
+export type ValidationErrorFormatter<TC = unknown> = (val: unknown, message?: string, context?: TC) => string;
+/**
  * In-place validation that a supplied unknown matches some
@@ -24,3 +33,3 @@ * required characteristics (type, values, etc).
  */
-export interface Validator<T, TC = undefined> {
+export interface Validator<T, TC = unknown> {
     /**
@@ -92,3 +101,11 @@ * {@link Validation.ValidatorTraits | Traits} describing this validation.
     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>;
 }
 //# sourceMappingURL=validator.d.ts.map

lib/packlets/validation/validatorBase.d.ts

@@ -11,3 +11,3 @@ import { GenericValidator, GenericValidatorConstructorParams } from './genericValidator';
  */
-export declare abstract class ValidatorBase<T, TC = undefined> extends GenericValidator<T, TC> {
+export declare abstract class ValidatorBase<T, TC = unknown> extends GenericValidator<T, TC> {
     /**
@@ -14,0 +14,0 @@ * Inner constructor

package.json

 {
   "name": "@fgv/ts-utils",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Assorted Typescript Utilities",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

No alert changes

Improved metrics

Total package byte prevSize

926136

increased by16.69%

Number of package files

175

increased by19.05%

Lines of code

11332

increased by17.16%

No dependency changes