@fgv/ts-utils 5.0.0-22 → 5.0.0-23

package/src/packlets/conversion/defaultingConverter.ts

@@ -1,188 +0,0 @@
-/*
- * 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.
- */
-
-import { Brand, Result, Success, succeed } from '../base';
-import { ConstraintOptions, ConversionErrorFormatter, Converter, DefaultingConverter } from './converter';
-
-/**
- * Generic {@link Conversion.DefaultingConverter | DefaultingConverter}, which wraps another converter
- * to substitute a supplied default value for any errors returned by the inner converter.
- * @public
- */
-export class GenericDefaultingConverter<T, TD = T, TC = unknown> implements DefaultingConverter<T, TD, TC> {
-  private _converter: Converter<T, TC>;
-
-  /**
-   * {@inheritdoc Conversion.DefaultingConverter.defaultValue}
-   */
-  public defaultValue: TD;
-
-  /**
-   * {@inheritdoc Converter.isOptional}
-   */
-  public get isOptional(): boolean {
-    return this._converter.isOptional;
-  }
-
-  /**
-   * {@inheritdoc Converter.isOptional}
-   */
-  public get brand(): string | undefined {
-    return this._converter.brand;
-  }
-
-  /**
-   * 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.
-   */
-  public constructor(converter: Converter<T, TC>, defaultValue: TD) {
-    this.defaultValue = defaultValue;
-    this._converter = converter;
-  }
-
-  /**
-   * {@inheritdoc Converter.convert}
-   */
-  public convert(from: unknown, ctx?: TC | undefined): Success<T | TD> {
-    return this._applyDefault(this._converter.convert(from, ctx));
-  }
-
-  /**
-   * {@inheritdoc Converter.convertOptional}
-   */
-  public convertOptional(
-    from: unknown,
-    context?: TC | undefined,
-    onError?: ('failOnError' | 'ignoreErrors') | undefined
-  ): Result<T | TD | undefined> {
-    const converted = this._converter.convertOptional(from, context, onError);
-    if (converted.isFailure()) {
-      return succeed(this.defaultValue);
-    }
-    return converted;
-  }
-
-  /**
-   * {@inheritdoc Converter.optional}
-   */
-  public optional(onError?: ('failOnError' | 'ignoreErrors') | undefined): Converter<T | TD | undefined, TC> {
-    // need to let the inner converter do its optional thing first or our default
-    // steps on everything
-    return this._converter.optional(onError).withAction((result) => this._applyDefault(result));
-  }
-
-  /**
-   * {@inheritdoc Converter.map}
-   */
-  public map<T2>(mapper: (from: T | TD) => Result<T2>): Converter<T2, TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).map(mapper);
-  }
-
-  /**
-   * {@inheritdoc Converter.mapConvert}
-   */
-  public mapConvert<T2>(mapConverter: Converter<T2, unknown>): Converter<T2, TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).mapConvert(mapConverter);
-  }
-
-  /**
-   * {@inheritdoc Converter.mapItems}
-   */
-  public mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).mapItems(mapper);
-  }
-
-  /**
-   * {@inheritdoc Converter.mapConvertItems}
-   */
-  public mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).mapConvertItems(mapConverter);
-  }
-
-  /**
-   * {@inheritdoc Converter.withAction}
-   */
-  public withAction<T2>(action: (result: Result<T | TD>) => Result<T2>): Converter<T2, TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).withAction(action);
-  }
-
-  /**
-   * {@inheritdoc Converter.withTypeGuard}
-   */
-  public withTypeGuard<TI>(
-    guard: (from: unknown) => from is TI,
-    message?: string | undefined
-  ): Converter<TI, TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).withTypeGuard(guard);
-  }
-
-  /**
-   * {@inheritdoc Converter.withItemTypeGuard}
-   */
-  public withItemTypeGuard<TI>(
-    guard: (from: unknown) => from is TI,
-    message?: string | undefined
-  ): Converter<TI[], TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).withItemTypeGuard(guard);
-  }
-
-  /**
-   * {@inheritdoc Converter.withConstraint}
-   */
-  public withConstraint(
-    constraint: (val: T | TD) => boolean | Result<T | TD>,
-    options?: ConstraintOptions | undefined
-  ): Converter<T | TD, TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).withConstraint(constraint);
-  }
-
-  /**
-   * {@inheritdoc Converter.withBrand}
-   */
-  public withBrand<B extends string>(brand: B): Converter<Brand<T | TD, B>, TC> {
-    return this._converter.withAction((result) => this._applyDefault(result)).withBrand(brand);
-  }
-
-  /**
-   * {@inheritdoc Converter.withFormattedError}
-   */
-  public withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T | TD, TC> {
-    // 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
-   * than failing.
-   *
-   * Note that the supplied default value *overrides* the default value of this
-   * {@link Conversion.DefaultingConverter | DefaultingConverter}.
-   */
-  public withDefault<TD2 = T>(dflt: TD2): DefaultingConverter<T, TD2, TC> {
-    return new GenericDefaultingConverter(this._converter, dflt);
-  }
-
-  private _applyDefault<T2 = T>(converted: Result<T2>): Success<T2 | TD> {
-    return converted.success ? converted : succeed(this.defaultValue);
-  }
-}

package/src/packlets/conversion/index.ts

@@ -1,30 +0,0 @@
-/*
- * Copyright (c) 2023 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.
- */
-
-import * as Converters from './converters';
-
-export * from './baseConverter';
-export * from './converter';
-export * from './defaultingConverter';
-export * from './objectConverter';
-export * from './stringConverter';
-export { Converters };

package/src/packlets/conversion/objectConverter.ts

@@ -1,259 +0,0 @@
-/*
- * Copyright (c) 2023 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.
- */
-
-import { fail, isKeyOf, Result, succeed } from '../base';
-import { Validator } from '../validation';
-import { BaseConverter } from './baseConverter';
-import { Converter } from './converter';
-import { field, optionalField } from './converters';
-
-/**
- * Options for an {@link Conversion.ObjectConverter | ObjectConverter}.
- * @public
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export interface ObjectConverterOptions<T> {
-  /**
-   * If present, lists optional fields. Missing non-optional fields cause an error.
-   */
-  optionalFields?: (keyof T)[];
-  /**
-   * If true, unrecognized fields yield an error.  If false or undefined (default),
-   * unrecognized fields are ignored.
-   */
-  strict?: boolean;
-  /**
-   * Optional description to be included in error messages.
-   */
-  description?: string;
-
-  /**
-   * Optional modifier to apply to the converter.
-   */
-  modifier?: 'partial' | 'required';
-}
-
-/**
- * Per-property converters or validators for each of the properties in type T.
- * @remarks
- * Used to construct a {@link Conversion.ObjectConverter | ObjectConverter}
- * @public
- */
-export type FieldConverters<T, TC = unknown> = {
-  [key in keyof T]: Converter<T[key], TC | unknown> | Validator<T[key], TC>;
-};
-
-/**
- * A {@link Converter | Converter} which converts an object of type `<T>` without changing shape, given
- * a {@link Conversion.FieldConverters | FieldConverters<T>} for the fields in the object.
- * @remarks
- * By default, if all of the required fields exist and can be converted, returns a new object with
- * the converted values under the original key names.  If any required fields do not exist or cannot
- * be converted, the entire conversion fails. See {@link Conversion.ObjectConverterOptions | ObjectConverterOptions}
- * for other conversion options.
- * @public
- */
-export class ObjectConverter<T, TC = unknown> extends BaseConverter<T, TC> {
-  /**
-   * Fields converted by this {@link Conversion.ObjectConverter | ObjectConverter}.
-   */
-  public readonly fields: FieldConverters<T, TC>;
-  /**
-   * Options used to initialize this {@link Conversion.ObjectConverter | ObjectConverter}.
-   */
-  public readonly options: ObjectConverterOptions<T>;
-
-  /**
-   * Constructs a new {@link Conversion.ObjectConverter | ObjectConverter<T, TC>} using options
-   * supplied in a {@link Conversion.ObjectConverterOptions | ObjectConverterOptions<T>}.
-   * @param fields - A {@link Conversion.FieldConverters | FieldConverters<T>} containing
-   * a {@link Converter} for each field
-   * @param options - An optional @see ObjectConverterOptions to configure the conversion
-   * {@label WITH_OPTIONS}
-   */
-  public constructor(fields: FieldConverters<T, TC>, options?: ObjectConverterOptions<T>);
-
-  /**
-   * Constructs a new {@link Conversion.ObjectConverter | ObjectConverter<T, TC>} with optional
-   * properties specified as an array of `keyof T`.
-   * @param fields - A {@link Conversion.FieldConverters | FieldConverters<T>} containing
-   * a {@link Converter} for each field.
-   * @param optional - An array of `keyof T` listing fields that are not required.
-   * {@label WITH_KEYS}
-   * @deprecated Use {@link Conversion.Converter.optional | .optional()} on the individual
-   * fields, or pass {@link Conversion.ObjectConverterOptions | ObjectConverterOptions<T>} to the constructor.
-   */
-  public constructor(fields: FieldConverters<T, TC>, optional?: (keyof T)[]);
-  /**
-   * Concrete implementation of {@link Converters.(ObjectConverter:constructor)}
-   * @internal
-   */
-  public constructor(fields: FieldConverters<T, TC>, opt?: ObjectConverterOptions<T> | (keyof T)[]) {
-    const options = Array.isArray(opt) ? { optionalFields: opt } : opt ?? { optionalFields: [] };
-
-    super((from: unknown, __self, context?: TC) => ObjectConverter._convert(from, context, fields, options));
-
-    this.fields = fields;
-    this.options = options;
-  }
-
-  /**
-   * Converts the supplied object using the {@link Conversion.ObjectConverter | ObjectConverter}
-   * with all fields optional.
-   * @param from - The object to be converted.
-   * @param context - An optional context object passed to the field converters.
-   * @returns A {@link Result} containing the converted object or an error message.
-   */
-  public convertPartial(from: unknown, context?: TC): Result<Partial<T>> {
-    const options: ObjectConverterOptions<T> = { ...this.options, modifier: 'partial' };
-    return ObjectConverter._convert(from, context, this.fields, options);
-  }
-
-  /**
-   * Converts the supplied object using the {@link Conversion.ObjectConverter | ObjectConverter}
-   * with all fields required.
-   * @param from - The object to be converted.
-   * @param context - An optional context object passed to the field converters.
-   * @returns A {@link Result} containing the converted object or an error message.
-   */
-  public convertRequired(from: unknown, context?: TC): Result<Required<T>> {
-    const options: ObjectConverterOptions<T> = { ...this.options, modifier: 'required' };
-    return ObjectConverter._convert(from, context, this.fields, options) as Result<Required<T>>;
-  }
-
-  /**
-   * Creates a new {@link Conversion.ObjectConverter | ObjectConverter} derived from this one but with
-   * all properties optional.
-   * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} with the additional optional source properties.
-   * {@label WITHOUT_OPTIONS}
-   */
-  public partial(): ObjectConverter<Partial<T>, TC>;
-
-  /**
-   * Creates a new {@link Conversion.ObjectConverter | ObjectConverter} derived from this one but with
-   * new optional properties as specified by a supplied {@link Conversion.ObjectConverterOptions | ObjectConverterOptions<T>}.
-   * @param options - The {@link Conversion.ObjectConverterOptions | options} to be applied to the new
-   * converter.
-   * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} with the additional optional source properties.
-   * {@label WITH_OPTIONS}
-   * @deprecated Pass just the keys to be made optional.
-   */
-  public partial(options: ObjectConverterOptions<T>): ObjectConverter<Partial<T>, TC>;
-
-  /**
-   * Creates a new {@link Conversion.ObjectConverter | ObjectConverter} derived from this one but with
-   * new optional properties as specified by a supplied array of `keyof T`.
-   * @param optional - The keys of the source object properties to be made optional.
-   * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} with the additional optional source
-   * properties.
-   * {@label WITH_KEYS}
-   */
-  public partial(optional: (keyof T)[]): ObjectConverter<Partial<T>, TC>;
-
-  /**
-   * Concrete implementation of
-   * {@link Conversion.ObjectConverter.(partial:1) | ObjectConverter.partial(ObjectConverterOptions)} and
-   * {@link Conversion.ObjectConverter.(partial:2) | ObjectConverter.partial((keyof T))[]}.
-   * @internal
-   */
-  public partial(opt?: ObjectConverterOptions<T> | (keyof T)[]): ObjectConverter<Partial<T>, TC> {
-    const options: ObjectConverterOptions<Partial<T>> =
-      opt === undefined
-        ? { ...this.options, modifier: 'partial' }
-        : Array.isArray(opt)
-        ? { ...this.options, optionalFields: [...opt] }
-        : (opt as ObjectConverterOptions<Partial<T>>);
-    return new ObjectConverter<Partial<T>, TC>(this.fields as FieldConverters<Partial<T>, TC>, options)._with(
-      this._traits()
-    );
-  }
-
-  /**
-   * Creates a new {@link Conversion.ObjectConverter | ObjectConverter} derived from this one but with
-   * new optional properties as specified by a supplied array of `keyof T`.
-   * @param addOptionalProperties - The keys to be made optional.
-   * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} with the additional optional source
-   * properties.
-   */
-  public addPartial(addOptionalProperties: (keyof T)[]): ObjectConverter<Partial<T>, TC> {
-    /* c8 ignore next 1 - coverage having a bad day */
-    const myOptional = this.options.optionalFields ?? [];
-    const optional = [...myOptional, ...addOptionalProperties];
-    return this.partial(optional)._with(this._traits());
-  }
-
-  /**
-   * Creates a new {@link Conversion.ObjectConverter | ObjectConverter} derived from this one but with
-   * all properties required.
-   * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} with the additional required source properties.
-   */
-  public required(): ObjectConverter<Required<T>, TC> {
-    const options: ObjectConverterOptions<Required<T>> = { ...this.options, modifier: 'required' };
-    return new ObjectConverter<Required<T>, TC>(
-      this.fields as FieldConverters<Required<T>, TC>,
-      options
-    )._with(this._traits());
-  }
-
-  private static _convert<T, TC>(
-    from: unknown,
-    context: TC | undefined,
-    fields: FieldConverters<T, TC>,
-    options: ObjectConverterOptions<T>
-  ): Result<T> {
-    // eslint bug thinks key is used before defined
-    // eslint-disable-next-line no-use-before-define
-    const converted = {} as { [key in keyof T]: T[key] };
-    const errors: string[] = [];
-    for (const key in fields) {
-      if (fields[key]) {
-        const isOptional =
-          options.modifier === 'partial' ||
-          (options.modifier !== 'required' &&
-            (fields[key].isOptional === true || options.optionalFields?.includes(key) === true));
-        const result = isOptional
-          ? optionalField(key, fields[key]).convert(from, context)
-          : field(key, fields[key]).convert(from, context);
-        if (result.isSuccess() && result.value !== undefined) {
-          converted[key] = result.value;
-        } else if (result.isFailure()) {
-          errors.push(result.message);
-        }
-      }
-    }
-
-    if (options.strict === true) {
-      if (typeof from === 'object' && !Array.isArray(from)) {
-        for (const key in from) {
-          if (from.hasOwnProperty(key) && (!isKeyOf(key, fields) || fields[key] === undefined)) {
-            errors.push(`${key}: unexpected property in source object`);
-          }
-        }
-      } else {
-        errors.push('source is not an object');
-      }
-    }
-    return errors.length === 0
-      ? succeed(converted)
-      : fail(options.description ? `${options.description}: ${errors.join('\n')}` : errors.join('\n'));
-  }
-}

package/src/packlets/conversion/stringConverter.ts

@@ -1,165 +0,0 @@
-/*
- * Copyright (c) 2023 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.
- */
-
-import { Result, fail, succeed } from '../base';
-import { BaseConverter } from './baseConverter';
-import { Converter, ConverterTraits } from './converter';
-
-/**
- * Options for {@link Conversion.StringConverter | StringConverter}
- * matching method
- * @public
- */
-
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export interface StringMatchOptions {
-  /**
-   * An optional message to be displayed if a non-matching string
-   * is encountered.
-   */
-  message?: string;
-}
-
-/**
- * The {@link Conversion.StringConverter | StringConverter} class extends
- * {@link Conversion.BaseConverter | BaseConverter} to provide string-specific
- * helper methods.
- * @public
- */
-export 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.
-   * @param traits - Optional traits to be applied to the conversion.
-   * @param converter - Optional conversion function to be used for the conversion.
-   */
-  public constructor(
-    defaultContext?: TC,
-    traits?: ConverterTraits,
-    converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T> = StringConverter._convert
-  ) {
-    super(converter, defaultContext, traits);
-  }
-
-  /**
-   * @internal
-   */
-  protected static _convert<T extends string>(from: unknown): Result<T> {
-    return typeof from === 'string' ? succeed(from as T) : fail(`Not a string: ${JSON.stringify(from)}`);
-  }
-
-  /**
-   * @internal
-   */
-  protected static _wrap<T extends string, TC>(
-    wrapped: StringConverter<T, TC>,
-    converter: (from: T) => Result<T>,
-    traits?: ConverterTraits
-  ): StringConverter<T, TC> {
-    return new StringConverter<T, TC>(undefined, undefined, (from: unknown) => {
-      return wrapped.convert(from).onSuccess(converter);
-    })._with(wrapped._traits(traits));
-  }
-
-  /**
-   * Returns a {@link Conversion.StringConverter | StringConverter} which constrains the result to match
-   * a supplied string.
-   * @param match - The string to be matched
-   * @param options - Optional {@link Conversion.StringMatchOptions} for this conversion.
-   * @returns {@link Success} with a matching string or {@link Failure} with an informative
-   * error if the string does not match.
-   * {@label WITH_STRING}
-   */
-  public matching(match: string, options?: Partial<StringMatchOptions>): StringConverter<T, TC>;
-
-  /**
-   * Returns a {@link Conversion.StringConverter | StringConverter} which constrains the result to match
-   * one of a supplied array of strings.
-   * @param match - The array of allowed strings.
-   * @param options - Optional {@link Conversion.StringMatchOptions} for this conversion.
-   * @returns {@link Success} with a matching string or {@link Failure} with an informative
-   * error if the string does not match.
-   * {@label WITH_ARRAY}
-   */
-  public matching(match: string[], options?: Partial<StringMatchOptions>): StringConverter<T, TC>;
-
-  /**
-   * Returns a {@link Conversion.StringConverter | StringConverter} which constrains the result to match
-   * one of a supplied `Set` of strings.
-   * @param match - The `Set` of allowed strings.
-   * @param options - Optional {@link Conversion.StringMatchOptions} for this conversion.
-   * @returns {@link Success} with a matching string or {@link Failure} with an informative
-   * error if the string does not match.
-   * {@label WITH_SET}
-   */
-  public matching(match: Set<T>, options?: Partial<StringMatchOptions>): StringConverter<T, TC>;
-
-  /**
-   * Returns a {@link Conversion.StringConverter | StringConverter} which constrains the result to match
-   * a supplied regular expression.
-   * @param match - The regular expression to be used as a constraint.
-   * @param options - Optional {@link Conversion.StringMatchOptions} for this conversion
-   * @returns {@link Success} with a matching string or {@link Failure} with an informative
-   * error if the string does not match.
-   * {@label WITH_REGEXP}
-   */
-  public matching(match: RegExp, options?: Partial<StringMatchOptions>): StringConverter<T, TC>;
-
-  /**
-   * Concrete implementation of {@link Conversion.StringConverter.matching#string | StringConverter.matching(string)},
-   * {@link Conversion.StringConverter.matching#array | StringConverter.matching(string[])},
-   * {@link Conversion.StringConverter.matching#set | StringConverter.matching(Set<string>)}, and
-   * {@link Conversion.StringConverter.matching#regexp | StringConverter.matching(RegExp)}.
-   * @internal
-   */
-  public matching(
-    match: string | string[] | Set<T> | RegExp,
-    options?: Partial<StringMatchOptions>
-  ): StringConverter<T, TC> {
-    const message = options?.message;
-    if (typeof match === 'string') {
-      return StringConverter._wrap<T, TC>(this, (from: T) => {
-        return match === from
-          ? succeed(from as T)
-          : fail(message ? `"${from}": ${message}` : `"${from}": does not match "${match}"`);
-      });
-    } else if (match instanceof RegExp) {
-      return StringConverter._wrap<T, TC>(this, (from: T) => {
-        return match.test(from)
-          ? succeed(from as T)
-          : fail(message ? `"${from}": ${message}` : `"${from}": does not match "${match}"`);
-      });
-    } else if (match instanceof Set) {
-      return StringConverter._wrap<T, TC>(this, (from: T) => {
-        return match.has(from)
-          ? succeed(from as T)
-          : fail(message ? `"${from}": ${message}` : `"${from}": not found in set`);
-      });
-    } else {
-      return StringConverter._wrap<T, TC>(this, (from: T) => {
-        return match.includes(from)
-          ? succeed(from as T)
-          : fail(message ? `"${from}": ${message}` : `"${from}": not found in [${match.join(',')}]`);
-      });
-    }
-  }
-}