@fgv/ts-utils 5.0.2 → 5.1.0-0

package/lib/packlets/conversion/baseConverter.js

@@ -47,25 +47,25 @@ class BaseConverter {
         this._brand = traits === null || traits === void 0 ? void 0 : traits.brand;
     }
     /**
-     * {@inheritdoc Converter.isOptional}
+     * {@inheritDoc Converter.isOptional}
      */
     get isOptional() {
         return this._isOptional;
     }
     /**
-     * {@inheritdoc Converter.brand}
+     * {@inheritDoc Converter.brand}
      */
     get brand() {
         return this._brand;
     }
     /**
-     * {@inheritdoc Converter.convert}
+     * {@inheritDoc Converter.convert}
      */
     convert(from, context) {
         return this._converter(from, this, context !== null && context !== void 0 ? context : this._defaultContext);
     }
     /**
-     * {@inheritdoc Converter.convertOptional}
+     * {@inheritDoc Converter.convertOptional}
      */
     convertOptional(from, context, onError) {
         const result = this._converter(from, this, this._context(context));
@@ -76,7 +76,7 @@ class BaseConverter {
         return result;
     }
     /**
-     * {@inheritdoc Converter.optional}
+     * {@inheritDoc Converter.optional}
      */
     optional(onError) {
         return new BaseConverter((from, __self, context) => {
@@ -85,7 +85,7 @@ class BaseConverter {
         })._with(this._traits({ isOptional: true }));
     }
     /**
-     * {@inheritdoc Converter.map}
+     * {@inheritDoc Converter.map}
      */
     map(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -97,7 +97,7 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.mapConvert}
+     * {@inheritDoc Converter.mapConvert}
      */
     mapConvert(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -109,7 +109,7 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.mapItems}
+     * {@inheritDoc Converter.mapItems}
      */
     mapItems(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -122,7 +122,7 @@ class BaseConverter {
         });
     }
     /**
-     * {@inheritdoc Converter.mapConvertItems}
+     * {@inheritDoc Converter.mapConvertItems}
      */
     mapConvertItems(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -135,7 +135,7 @@ class BaseConverter {
         });
     }
     /**
-     * {@inheritdoc Converter.withAction}
+     * {@inheritDoc Converter.withAction}
      */
     withAction(action) {
         return new BaseConverter((from, __self, context) => {
@@ -143,7 +143,7 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.withTypeGuard}
+     * {@inheritDoc Converter.withTypeGuard}
      */
     withTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -156,7 +156,7 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.withItemTypeGuard}
+     * {@inheritDoc Converter.withItemTypeGuard}
      */
     withItemTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -174,7 +174,7 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.withConstraint}
+     * {@inheritDoc Converter.withConstraint}
      */
     withConstraint(constraint, options) {
         return new BaseConverter((from, __self, context) => {
@@ -193,7 +193,7 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.withBrand}
+     * {@inheritDoc Converter.withBrand}
      */
     withBrand(brand) {
         if (this._brand) {
@@ -206,11 +206,18 @@ class BaseConverter {
         })._with(this._traits({ brand }));
     }
     /**
-     * {@inheritdoc Converter.withDefault}
+     * {@inheritDoc Converter.withDefault}
      */
     withDefault(defaultValue) {
         return new defaultingConverter_1.GenericDefaultingConverter(this, defaultValue);
     }
+    or(other) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onFailure(() => {
+                return other.convert(from, this._context(context));
+            });
+        });
+    }
     /**
      * @internal
      */
@@ -218,7 +225,7 @@ class BaseConverter {
         return supplied !== null && supplied !== void 0 ? supplied : this._defaultContext;
     }
     /**
-     * {@inheritdoc Converter.withFormattedError}
+     * {@inheritDoc Converter.withFormattedError}
      */
     withFormattedError(formatter) {
         return new BaseConverter((from, __self, context) => {

package/lib/packlets/conversion/basicConverters.d.ts

@@ -0,0 +1,470 @@
+import { TypeGuardWithContext, Validator } from '../validation';
+import { ConverterFunc } from './baseConverter';
+import { Converter, OnError } from './converter';
+import { FieldConverters, ObjectConverter, ObjectConverterOptions } from './objectConverter';
+import { StringConverter } from './stringConverter';
+/**
+ * Action to take on conversion failures (deprecated - use Conversion.OnError)
+ * @public
+ * @deprecated use Conversion.OnError.
+ */
+export { OnError };
+/**
+ * A converter to convert unknown to string. Values of type
+ * string succeed.  Anything else fails.
+ * @public
+ */
+export declare const string: StringConverter;
+/**
+ * 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 | Converter} returning `<T>`.
+ * @public
+ */
+export declare function enumeratedValue<T>(values: ReadonlyArray<T>): Converter<T, ReadonlyArray<T>>;
+/**
+ * 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'`,
+ * `'true'`, `1` and `true` can all map to boolean `true`)
+ * @param map - An array of tuples describing the mapping. The first element of each tuple is the result
+ * 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 | Converter} which applies the mapping and yields `<T>` on success.
+ * @public
+ */
+export declare function mappedEnumeratedValue<T, TC = unknown>(map: ReadonlyArray<[T, ReadonlyArray<TC>]>, message?: string): Converter<T, ReadonlyArray<TC>>;
+/**
+ * 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 | Converter} which returns the supplied value on success.
+ * @public
+ */
+export declare function literal<T, TC = unknown>(value: T): Converter<T, TC>;
+/**
+ * Deprecated alias for @see literal
+ * @param value - The value to be compared.
+ * @deprecated Use {@link Converters.literal} instead.
+ * @internal
+ */
+export declare const value: typeof literal;
+/**
+ * A {@link Converter | Converter} which converts `unknown` to a `number`.
+ * @remarks
+ * Numbers and strings with a numeric format succeed. Anything else fails.
+ * @public
+ */
+export declare const number: Converter<number, unknown>;
+/**
+ * A {@link Converter | Converter} which converts `unknown` to `boolean`.
+ * @remarks
+ * Boolean values or the case-insensitive strings `'true'` and `'false'` succeed.
+ * Anything else fails.
+ * @public
+ */
+export declare const boolean: Converter<boolean, unknown>;
+/**
+ * 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
+ */
+export declare const optionalString: Converter<string | undefined, unknown>;
+/**
+ * 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 | Converter} returning `string[]`.
+ * @public
+ */
+export declare function delimitedString(delimiter: string, options?: 'filtered' | 'all'): Converter<string[], string>;
+/**
+ * Determines if a supplied {@link Conversion.Converter | Converter} or {@link Validation.Validator | Validator} is
+ * a {@link Validation.Validator | Validator}.
+ * @param converterOrValidator - The {@link Conversion.Converter | Converter} or {@link Validation.Validator | Validator} to be tested.
+ * @returns `true` if `converterOrValidator` is a {@link Validation.Validator | Validator}, `false` otherwise.
+ * @public
+ */
+export declare function isValidator<T, TC>(converterOrValidator: Converter<T, TC> | Validator<T, TC>): converterOrValidator is Validator<T, TC>;
+/**
+ * Helper function to create a {@link Converter | Converter} from any {@link Validation.Validator}
+ * @param converterOrValidator - the {@link Validation.Validator} to be wrapped or {@link Converter | Converter}
+ * to be used directly.
+ * @returns A {@link Converter | Converter} which uses the supplied validator.
+ * @public
+ */
+export declare function validated<T, TC = unknown>(converterOrValidator: Validator<T, TC> | Converter<T, TC>): Converter<T, TC>;
+/**
+ * Helper function to create a {@link Validation.Validator | Validator} from any {@link Conversion.Converter | Converter}
+ * or {@link Validation.Validator | Validator}.
+ * @param converterOrValidator - the {@link Conversion.Converter | Converter} to be wrappped or {@link Validation.Validator | Validator} to be used directly.
+ * @returns A {@link Validation.Validator | Validator} which uses the supplied converter or validator.
+ * @public
+ */
+export declare function asValidator<T, TC = unknown>(converterOrValidator: Converter<T, TC> | Validator<T, TC>): Validator<T, TC>;
+/**
+ * Helper function to create a {@link Converter | Converter} from a supplied {@link Conversion.ConverterFunc | ConverterFunc}.
+ * @param convert - the function to be wrapped
+ * @returns A {@link Converter | Converter} which uses the supplied function.
+ * @public
+ */
+export declare function generic<T, TC = unknown>(convert: ConverterFunc<T, TC>): Converter<T, TC>;
+/**
+ * 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 | Converter} which validates the values using the supplied type guard
+ * and returns them in place.
+ * @public
+ */
+export declare function isA<T, TC = unknown>(description: string, guard: TypeGuardWithContext<T, TC>): Converter<T, TC>;
+/**
+ * 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 | Success} with value `undefined`.
+ * @public
+ */
+export declare const optionalNumber: Converter<number | undefined, unknown>;
+/**
+ * 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 | Success}
+ * with value `undefined`.
+ * @public
+ */
+export declare const optionalBoolean: Converter<boolean | undefined, unknown>;
+/**
+ * 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} or {@link Validator | validators}
+ * to be considered.
+ * @param onError - Specifies treatment of unconvertible elements.
+ * @returns A new {@link Converter | Converter} which yields a value from the union of the types returned
+ * by the wrapped converters.
+ * @public
+ */
+export declare function oneOf<T, TC = unknown>(converters: Array<Converter<T, TC> | Validator<T, TC>>, onError?: OnError): Converter<T, TC>;
+/**
+ * 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 | Converter} or {@link Validator | Validator} used to convert each
+ * item in the array.
+ * @param onError - Specifies treatment of unconvertible elements.
+ * @returns A {@link Converter | Converter} which returns an array of `<T>`.
+ * @public
+ */
+export declare function arrayOf<T, TC = unknown>(converter: Converter<T, TC> | Validator<T, TC>, onError?: OnError): Converter<T[], TC>;
+/**
+ * {@link Converter | Converter} to convert an `unknown` to an array of `string`.
+ * @remarks
+ * 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
+ */
+export declare const stringArray: Converter<string[], unknown>;
+/**
+ * {@link Converter | Converter} to convert an `unknown` to an array of `number`.
+ * @remarks
+ * Returns {@link Success | Success} with the the supplied value if it as an array
+ * of numbers, returns {@link Failure | Failure} with an error message otherwise.
+ * @public
+ */
+export declare const numberArray: Converter<number[], unknown>;
+/**
+ * Options for {@link recordOf} and
+ * {@link mapOf}
+ * helper functions.
+ * @public
+ */
+export 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.
+     */
+    onError?: 'fail' | 'ignore';
+    /**
+     * If present, `keyConverter` is used to convert the source object property names to
+     * keys in the resulting map or record.
+     * @remarks
+     * Can be used to coerce key names to supported values and/or strong types.
+     */
+    keyConverter?: Converter<T, TC> | Validator<T, TC>;
+}
+/**
+ * A helper function to create a {@link Converter | Converter} which converts the `string`-keyed
+ * 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.
+ * @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
+ */
+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, 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
+ * cannot be converted.  If `onError` is `'ignore'`, failing elements are silently ignored.
+ * @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
+ */
+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, 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
+ * converter for keys and/or control the handling of elements that fail conversion.
+ * @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 | Converter} which returns `Record<TK, T>`.
+ * {@label WITH_OPTIONS}
+ * @public
+ */
+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, TC>} 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 | 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
+ */
+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, 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
+ * cannot be converted.  If `onError` is `'ignore'`, failing elements are silently ignored.
+ * @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
+ */
+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, 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
+ * converter for keys and/or control the handling of elements that fail conversion.
+ * @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 | Converter} which returns `Map<TK,T>`.
+ * {@label WITH_OPTIONS}
+ * @public
+ */
+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>;
+/**
+ * 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 | 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.
+ * @returns A new {@link Converter | Converter<T, TC>} which applies the supplied validation.
+ * @public
+ */
+export declare function validateWith<T, TC = unknown>(validator: (from: unknown) => from is T, description?: string): Converter<T, TC>;
+/**
+ * A helper function to create a {@link Converter | Converter} which extracts and converts an element from an array.
+ * @remarks
+ * 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 | Converter} or {@link Validator | Validator} for the extracted element.
+ * @returns A {@link Converter | Converter<T, TC>} which extracts the specified element from an array.
+ * @public
+ */
+export declare function element<T, TC = unknown>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
+/**
+ * A helper function to create a {@link Converter | Converter} which extracts and converts an optional element from an array.
+ * @remarks
+ * 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 | Converter} or {@link Validator | Validator} used for the extracted element.
+ * @returns A {@link Converter | Converter<T, TC>} which extracts the specified element from an array.
+ * @public
+ */
+export 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
+ * by name from an object.
+ * @remarks
+ * 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 | Converter}  or {@link Validator | Validator} to use for the extracted
+ * field.
+ * @public
+ */
+export declare function field<T, TC = unknown>(name: string, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
+/**
+ * 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 | 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 | Converter} or {@link Validator | Validator} to use for the extracted field.
+ * @public
+ */
+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, 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}
+ * 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 | Failure} with additional
+ * error information.
+ *
+ * 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, 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.
+ * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} which applies the specified conversions.
+ * {@label WITH_OPTIONS}
+ * @public
+ */
+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, 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}
+ * 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 | Failure} with additional
+ * error information.
+ *
+ * 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, 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}
+ * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} which applies the specified conversions.
+ * @public
+ * @deprecated Use {@link Converters.(object:1) | Converters.object(fields, options)} instead.
+ */
+export declare function object<T, TC = unknown>(properties: FieldConverters<T, TC>, optional: (keyof T)[]): ObjectConverter<T, TC>;
+/**
+ * Options for the {@link strictObject} helper function.
+ * @public
+ */
+export type StrictObjectConverterOptions<T> = Omit<ObjectConverterOptions<T>, 'strict'>;
+/**
+ * Helper function to create a {@link Conversion.ObjectConverter | ObjectConverter} which converts an object
+ * without changing shape, a {@link Conversion.FieldConverters | FieldConverters<T, TC>} and an optional
+ * {@link Converters.StrictObjectConverterOptions | StrictObjectConverterOptions<T>} to further refine
+ * conversion behavior.
+ *
+ * @remarks
+ * Fields that succeed but convert to undefined are omitted from the result object but do not
+ * fail the conversion.
+ *
+ * The conversion fails if any unexpected fields are encountered.
+ *
+ * @param properties - An object containing defining the shape and converters to be applied.
+ * @param options - An optional @see StrictObjectConverterOptions<T> containing options for the object converter.
+ * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} which applies the specified conversions.
+ * {@label WITH_OPTIONS}
+ * @public
+ */
+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, TC>} and an optional
+ * {@link Converters.StrictObjectConverterOptions | StrictObjectConverterOptions<T>} to further refine
+ * conversion behavior.
+ *
+ * @remarks
+ * Fields that succeed but convert to undefined are omitted from the result object but do not
+ * fail the conversion.
+ *
+ * The conversion fails if any unexpected fields are encountered.
+ *
+ * @param properties - An object containing defining the shape and converters to be applied.
+ * @param optional - An array of `keyof T` containing keys to be considered optional.
+ * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} which applies the specified conversions.
+ * {@label WITH_KEYS}
+ * @deprecated Use {@link Converters.strictObject | Converters.strictObject(options)} instead.
+ * @public
+ */
+export declare function strictObject<T, TC = unknown>(properties: FieldConverters<T, TC>, optional: (keyof T)[]): ObjectConverter<T, TC>;
+/**
+ * A string-keyed `Record<string, Converter>` which maps specific {@link Converter | converters} or
+ * {@link Validator | Validators} to the value of a discriminator property.
+ * @public
+ */
+export type DiscriminatedObjectConverters<T, TD extends string = string, TC = unknown> = Record<TD, Converter<T, TC> | Validator<T, TC>>;
+/**
+ * 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 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 | Failure} with more information.
+ * @param discriminatorProp - Name of the property used to discriminate types.
+ * @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
+ */
+export declare function discriminatedObject<T, TD extends string = string, TC = unknown>(discriminatorProp: string, converters: DiscriminatedObjectConverters<T, TD>): Converter<T, TC>;
+//# sourceMappingURL=basicConverters.d.ts.map