@fgv/ts-utils 5.0.2 → 5.1.0-1

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

@@ -0,0 +1,170 @@
+import { Validator } from '../validation';
+import { ConverterResultTypes } from './baseConverter';
+import { Converter } from './converter';
+import { FieldConverters } from './objectConverter';
+/**
+ * Represents a composite ID constructed of two strongly-typed string IDs
+ * separated by a delimiter.
+ * @public
+ */
+export interface ICompositeId<TCOLLECTIONID extends string, TITEMID extends string> {
+    readonly collectionId: TCOLLECTIONID;
+    readonly separator: string;
+    readonly itemId: TITEMID;
+}
+/**
+ * Represents a partial composite ID, where separator is optional.
+ * @public
+ */
+export interface IPartialCompositeId<TCOLLECTIONID extends string, TITEMID extends string> {
+    readonly collectionId: TCOLLECTIONID;
+    readonly separator?: string;
+    readonly itemId: TITEMID;
+}
+/**
+ * Creates an {@link ObjectConverter | ObjectConverter} for a strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @param collectionIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns An {@link ObjectConverter | ObjectConverter} for the strongly-typed composite ICompositeId.
+ * @public
+ */
+export declare function compositeIdFromObject<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(collectionIdValidator: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>, separator: string, itemIdValidator: Converter<TITEMID, TC> | Validator<TITEMID, TC>): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>;
+/**
+ * Converts a composite ID string into a strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @public
+ */
+export declare function compositeIdFromString<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>, separator: string, itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>;
+/**
+ * Creates a {@link Converter | Converter} for a strongly-typed {@link Converters.ICompositeId | CompositeId} from
+ * either a string or an object representation.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @public
+ */
+export declare function compositeId<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>, separator: string, itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>;
+/**
+ * Converts a strongly-typed {@link Converters.ICompositeId | CompositeId} into a string.
+ * @param compositeIdConverter - {@link Converter | Converter} or {@link Validator | Validator} that validates/converts the composite ID string.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} which produces a composite ID string.
+ * @public
+ */
+export declare function compositeIdString<T extends string, TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(compositeIdConverter: Validator<T, TC> | Converter<T, TC>, collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>, separator: string, itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>): Converter<T, TC>;
+/**
+ * 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 | 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 | 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
+ * fail the conversion.
+ *
+ * @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 | Converter} with the specified conversion behavior.
+ * @public
+ */
+export declare function transform<T, TC = unknown>(properties: FieldConverters<T, TC>): Converter<T, TC>;
+/**
+ * Per-property converters and configuration for each field in the destination object of
+ * a {@link Converters.transformObject} call.
+ * @public
+ */
+export type FieldTransformers<TSRC, TDEST, TC = unknown> = {
+    [key in keyof TDEST]: {
+        /**
+         * The name of the property in the source object to be converted.
+         */
+        from: keyof TSRC;
+        /**
+         * The converter or validator used to convert the property.
+         */
+        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.
+         */
+        optional?: boolean;
+    };
+};
+/**
+ * Options for a {@link Converters.transformObject} call.
+ * @public
+ */
+export interface TransformObjectOptions<TSRC> {
+    /**
+     * If `strict` is `true` then unused properties in the source object cause
+     * an error, otherwise they are ignored.
+     */
+    strict: true;
+    /**
+     * An optional list of source properties to be ignored when strict mode
+     * is enabled.
+     */
+    ignore?: (keyof TSRC)[];
+    /**
+     * An optional description of this transform to be used for error messages.
+     */
+    description?: string;
+}
+/**
+ * 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 | 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 | 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 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 | Converter} with the specified conversion behavior.
+ * @public
+ */
+export declare function transformObject<TSRC, TDEST, TC = unknown>(destinationFields: FieldTransformers<TSRC, TDEST, TC>, options?: TransformObjectOptions<TSRC>): Converter<TDEST, TC>;
+/**
+ * Creates a {@link Converter | Converter} that converts an array to a strongly-typed tuple,
+ * using the supplied tuple of {@link Converter | Converters} to convert each element.
+ *
+ * @remarks
+ * The resulting {@link Converter | Converter} returns {@link Success | Success} with a tuple
+ * containing the converted values if all conversions succeed. Returns {@link Failure | Failure}
+ * with an error message if the source is not an array, has the wrong number of elements, or
+ * any element conversion fails.
+ *
+ * @example
+ * ```typescript
+ * const converter = tuple([Converters.string, Converters.number, Converters.boolean]);
+ * // Type is Converter<[string, number, boolean]>
+ *
+ * converter.convert(['hello', 42, true]);
+ * // Returns Success with ['hello', 42, true]
+ * ```
+ *
+ * @param converters - A tuple of {@link Converter | Converters} defining the expected types
+ * for each element of the tuple.
+ * @returns A {@link Converter | Converter} that returns a strongly-typed tuple.
+ * @public
+ */
+export declare function tuple<T extends readonly Converter<unknown, TC>[], TC = unknown>(converters: [...T]): Converter<ConverterResultTypes<T>, TC>;
+//# sourceMappingURL=advancedConverters.d.ts.map

package/lib/packlets/conversion/advancedConverters.js

@@ -0,0 +1,258 @@
+"use strict";
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compositeIdFromObject = compositeIdFromObject;
+exports.compositeIdFromString = compositeIdFromString;
+exports.compositeId = compositeId;
+exports.compositeIdString = compositeIdString;
+exports.transform = transform;
+exports.transformObject = transformObject;
+exports.tuple = tuple;
+const base_1 = require("../base");
+const baseConverter_1 = require("./baseConverter");
+const basicConverters_1 = require("./basicConverters");
+const objectConverter_1 = require("./objectConverter");
+/**
+ * Creates an {@link ObjectConverter | ObjectConverter} for a strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @param collectionIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns An {@link ObjectConverter | ObjectConverter} for the strongly-typed composite ICompositeId.
+ * @public
+ */
+function compositeIdFromObject(collectionIdValidator, separator, itemIdValidator) {
+    return new objectConverter_1.ObjectConverter({
+        collectionId: collectionIdValidator,
+        separator: (0, basicConverters_1.literal)(separator).optional(),
+        itemId: itemIdValidator
+    }).map((obj) => {
+        var _a;
+        return base_1.Success.with({
+            collectionId: obj.collectionId,
+            separator: (_a = obj.separator) !== null && _a !== void 0 ? _a : separator,
+            itemId: obj.itemId
+        });
+    });
+}
+/**
+ * Converts a composite ID string into a strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @public
+ */
+function compositeIdFromString(collectionIdConverter, separator, itemIdConverter) {
+    return new baseConverter_1.BaseConverter((from, __self, context) => {
+        if (typeof from !== 'string') {
+            return (0, base_1.fail)(`${from}: invalid non-string composite ID.`);
+        }
+        const parts = from.split(separator);
+        if (parts.length < 2) {
+            return (0, base_1.fail)(`${from}: invalid composite ID - separator '${separator}' not found.`);
+        }
+        else if (parts.length > 2) {
+            return (0, base_1.fail)(`${from}: invalid composite ID - multiple separators '${separator}.' found.`);
+        }
+        return collectionIdConverter.convert(parts[0], context).onSuccess((collectionId) => {
+            return itemIdConverter.convert(parts[1], context).onSuccess((itemId) => {
+                return (0, base_1.succeed)({
+                    collectionId,
+                    separator,
+                    itemId
+                });
+            });
+        });
+    });
+}
+/**
+ * Creates a {@link Converter | Converter} for a strongly-typed {@link Converters.ICompositeId | CompositeId} from
+ * either a string or an object representation.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @public
+ */
+function compositeId(collectionIdConverter, separator, itemIdConverter) {
+    return compositeIdFromObject(collectionIdConverter, separator, itemIdConverter).or(compositeIdFromString(collectionIdConverter, separator, itemIdConverter));
+}
+/**
+ * Converts a strongly-typed {@link Converters.ICompositeId | CompositeId} into a string.
+ * @param compositeIdConverter - {@link Converter | Converter} or {@link Validator | Validator} that validates/converts the composite ID string.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} which produces a composite ID string.
+ * @public
+ */
+function compositeIdString(compositeIdConverter, collectionIdConverter, separator, itemIdConverter) {
+    const objectConverter = compositeIdFromObject(collectionIdConverter, separator, itemIdConverter);
+    return new baseConverter_1.BaseConverter((from, __self, context) => {
+        if (typeof from === 'string') {
+            return compositeIdConverter.convert(from, context);
+        }
+        return objectConverter.convert(from, context).onSuccess((compositeId) => {
+            return compositeIdConverter.convert(`${compositeId.collectionId}${separator}${compositeId.itemId}`);
+        });
+    });
+}
+/**
+ * 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 | 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 | 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
+ * fail the conversion.
+ *
+ * @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 | Converter} with the specified conversion behavior.
+ * @public
+ */
+function transform(properties) {
+    return new baseConverter_1.BaseConverter((from, __self, context) => {
+        // eslint bug thinks key is used before defined
+        const converted = {};
+        const errors = [];
+        for (const key in properties) {
+            if (properties[key]) {
+                const result = properties[key].convert(from, context);
+                if (result.isSuccess() && result.value !== undefined) {
+                    converted[key] = result.value;
+                }
+                else if (result.isFailure()) {
+                    errors.push(result.message);
+                }
+            }
+        }
+        return errors.length === 0 ? (0, base_1.succeed)(converted) : (0, base_1.fail)(errors.join('\n'));
+    });
+}
+/**
+ * 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 | 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 | 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 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 | Converter} with the specified conversion behavior.
+ * @public
+ */
+function transformObject(destinationFields, options) {
+    return new baseConverter_1.BaseConverter((from, __self, context) => {
+        // eslint bug thinks key is used before defined
+        const converted = {};
+        const errors = [];
+        const used = new Set(options === null || options === void 0 ? void 0 : options.ignore);
+        if (typeof from === 'object' && !Array.isArray(from) && from !== null) {
+            for (const destinationKey in destinationFields) {
+                if (destinationFields[destinationKey]) {
+                    const srcKey = destinationFields[destinationKey].from;
+                    const converter = destinationFields[destinationKey].converter;
+                    if ((0, base_1.isKeyOf)(srcKey, from)) {
+                        const result = converter.convert(from[srcKey], context);
+                        if (result.isSuccess() && result.value !== undefined) {
+                            converted[destinationKey] = result.value;
+                        }
+                        else if (result.isFailure()) {
+                            errors.push(`${srcKey}->${destinationKey}: ${result.message}`);
+                        }
+                        used.add(srcKey);
+                    }
+                    else if (destinationFields[destinationKey].optional !== true) {
+                        errors.push(`${String(srcKey)}: required property missing in source object.`);
+                    }
+                }
+            }
+            if ((options === null || options === void 0 ? void 0 : options.strict) === true) {
+                for (const key in from) {
+                    if ((0, base_1.isKeyOf)(key, from) && !used.has(key)) {
+                        errors.push(`${key}: unexpected property in source object`);
+                    }
+                }
+            }
+        }
+        else {
+            errors.push('source is not an object');
+        }
+        return errors.length === 0
+            ? (0, base_1.succeed)(converted)
+            : (0, base_1.fail)((options === null || options === void 0 ? void 0 : options.description) ? `${options.description}:\n  ${errors.join('\n  ')}` : errors.join('\n'));
+    });
+}
+/**
+ * Creates a {@link Converter | Converter} that converts an array to a strongly-typed tuple,
+ * using the supplied tuple of {@link Converter | Converters} to convert each element.
+ *
+ * @remarks
+ * The resulting {@link Converter | Converter} returns {@link Success | Success} with a tuple
+ * containing the converted values if all conversions succeed. Returns {@link Failure | Failure}
+ * with an error message if the source is not an array, has the wrong number of elements, or
+ * any element conversion fails.
+ *
+ * @example
+ * ```typescript
+ * const converter = tuple([Converters.string, Converters.number, Converters.boolean]);
+ * // Type is Converter<[string, number, boolean]>
+ *
+ * converter.convert(['hello', 42, true]);
+ * // Returns Success with ['hello', 42, true]
+ * ```
+ *
+ * @param converters - A tuple of {@link Converter | Converters} defining the expected types
+ * for each element of the tuple.
+ * @returns A {@link Converter | Converter} that returns a strongly-typed tuple.
+ * @public
+ */
+function tuple(converters) {
+    return new baseConverter_1.BaseConverter((from, __self, context) => {
+        if (!Array.isArray(from)) {
+            return (0, base_1.fail)(`Not an array: ${JSON.stringify(from)}`);
+        }
+        if (from.length !== converters.length) {
+            return (0, base_1.fail)(`Expected array of length ${converters.length}, got ${from.length}: ${JSON.stringify(from)}`);
+        }
+        const results = converters.map((converter, index) => {
+            return converter.convert(from[index], context);
+        });
+        return (0, base_1.mapResults)(results);
+    });
+}
+//# sourceMappingURL=advancedConverters.js.map

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

@@ -1,22 +1,37 @@
 import { Brand, Result } from '../base';
 import { ConstraintOptions, ConversionErrorFormatter, Converter, ConverterTraits, DefaultingConverter, OnError } from './converter';
 /**
- * internal
+ * Internal helper that recursively unwraps converter and array types.
+ * @internal
  */
 type InnerInferredType<TCONV> = TCONV extends Converter<infer TTO> ? TTO extends Array<infer TTOELEM> ? InnerInferredType<TTOELEM>[] : TTO : TCONV extends Array<infer TELEM> ? InnerInferredType<TELEM>[] : TCONV;
 /**
- * Infers the type that will be returned by an instantiated converter.  Works
- * for complex as well as simple types.
+ * Infers the type that will be returned by an instantiated converter. Works
+ * for complex as well as simple types, including nested arrays.
  * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`
- * @beta
+ * @public
  */
 export type Infer<TCONV> = TCONV extends Converter<infer TTO, unknown> ? InnerInferredType<TTO> : never;
 /**
- * Deprecated name for Infer<T> retained for compatibility
- * @deprecated use @see Infer instead
- * @internal
+ * Deprecated name for {@link Conversion.Infer | Infer
+ * } retained for compatibility.
+ * @deprecated Use {@link Conversion.Infer | Infer} instead.
+ * @public
  */
 export type ConvertedToType<TCONV> = Infer<TCONV>;
+/**
+ * Helper type to extract the result type from a {@link Converter | Converter}.
+ * For simple single-level extraction. For complex nested types, use {@link Conversion.Infer | Infer}.
+ * @public
+ */
+export type ConverterResultType<C> = C extends Converter<infer T, unknown> ? T : never;
+/**
+ * Helper type to map a tuple of {@link Converter | Converters} to a tuple of their result types.
+ * @public
+ */
+export type ConverterResultTypes<T extends readonly Converter<unknown, unknown>[]> = {
+    [K in keyof T]: T[K] extends Converter<infer R, unknown> ? R : never;
+};
 /**
  * Function signature for a converter function.
  * @public
@@ -49,71 +64,72 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
      */
     constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits);
     /**
-     * {@inheritdoc Converter.isOptional}
+     * {@inheritDoc Converter.isOptional}
      */
     get isOptional(): boolean;
     /**
-     * {@inheritdoc Converter.brand}
+     * {@inheritDoc Converter.brand}
      */
     get brand(): string | undefined;
     /**
-     * {@inheritdoc Converter.convert}
+     * {@inheritDoc Converter.convert}
      */
     convert(from: unknown, context?: TC): Result<T>;
     /**
-     * {@inheritdoc Converter.convertOptional}
+     * {@inheritDoc Converter.convertOptional}
      */
     convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
     /**
-     * {@inheritdoc Converter.optional}
+     * {@inheritDoc Converter.optional}
      */
     optional(onError?: OnError): Converter<T | undefined, TC>;
     /**
-     * {@inheritdoc Converter.map}
+     * {@inheritDoc Converter.map}
      */
     map<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC>;
     /**
-     * {@inheritdoc Converter.mapConvert}
+     * {@inheritDoc Converter.mapConvert}
      */
     mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
     /**
-     * {@inheritdoc Converter.mapItems}
+     * {@inheritDoc Converter.mapItems}
      */
     mapItems<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC>;
     /**
-     * {@inheritdoc Converter.mapConvertItems}
+     * {@inheritDoc Converter.mapConvertItems}
      */
     mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
     /**
-     * {@inheritdoc Converter.withAction}
+     * {@inheritDoc Converter.withAction}
      */
     withAction<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC>;
     /**
-     * {@inheritdoc Converter.withTypeGuard}
+     * {@inheritDoc Converter.withTypeGuard}
      */
     withTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI, TC>;
     /**
-     * {@inheritdoc Converter.withItemTypeGuard}
+     * {@inheritDoc Converter.withItemTypeGuard}
      */
     withItemTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI[], TC>;
     /**
-     * {@inheritdoc Converter.withConstraint}
+     * {@inheritDoc Converter.withConstraint}
      */
     withConstraint(constraint: (val: T, context?: TC) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
     /**
-     * {@inheritdoc Converter.withBrand}
+     * {@inheritDoc Converter.withBrand}
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
     /**
-     * {@inheritdoc Converter.withDefault}
+     * {@inheritDoc Converter.withDefault}
      */
     withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC>;
+    or(other: Converter<T, TC>): Converter<T, TC>;
     /**
      * @internal
      */
     protected _context(supplied?: TC): TC | undefined;
     /**
-     * {@inheritdoc Converter.withFormattedError}
+     * {@inheritDoc Converter.withFormattedError}
      */
     withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC>;
     /**