@fgv/ts-utils 5.0.0-12 → 5.0.0-14

package/src/packlets/validation/object.ts

@@ -0,0 +1,208 @@
+/*
+ * Copyright (c) 2021 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 { Failure, fail } from '../base';
+import { Validator, ValidatorOptions } from './validator';
+import { ValidatorBase, ValidatorBaseConstructorParams } from './validatorBase';
+
+import { FieldValidator } from './field';
+
+/**
+ * Per-property {@link Validation.Validator | validators} for each of the properties in `<T>`.
+ * @public
+ */
+export type FieldValidators<T, TC = unknown> = { [key in keyof T]: Validator<T[key], TC> };
+
+/**
+ * Options for an {@link Validation.Classes.ObjectValidator | ObjectValidator}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface ObjectValidatorOptions<T, TC> extends ValidatorOptions<TC> {
+  /**
+   * 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;
+}
+
+/**
+ * Options for the {@link Validation.Classes.ObjectValidator | ObjectValidator} constructor.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface ObjectValidatorConstructorParams<T, TC> extends ValidatorBaseConstructorParams<T, TC> {
+  /**
+   * A {@link Validation.Classes.FieldValidators | FieldValidators} object specifying a
+   * {@link Validation.Validator | Validator} for each of the expected properties
+   * of a result object.
+   */
+  fields: FieldValidators<T>;
+  /**
+   * Optional additional {@link Validation.Classes.ObjectValidatorOptions | ValidatorOptions} to
+   * configure validation.
+   */
+  options?: ObjectValidatorOptions<T, TC>;
+}
+
+/**
+ * In-place {@link Validation.Validator | Validator} for an object of type `<T>`.
+ * @remarks
+ * By default, succeeds if all of the required fields exist and are validate, and fails if
+ * any required fields do not exist or are invalid.  See {@link Validation.Classes.ObjectValidatorOptions}
+ * for other validation options.
+ * @public
+ */
+export class ObjectValidator<T, TC = unknown> extends ValidatorBase<T, TC> {
+  /**
+   * A {@link Validation.Classes.FieldValidators | FieldValidators} object specifying a
+   * {@link Validation.Validator | Validator} for each of the expected properties
+   */
+  public readonly fields: FieldValidators<T>;
+  /**
+   * {@link Validation.Classes.ObjectValidatorOptions | Options} which apply to this
+   * validator.
+   */
+  public readonly options: ObjectValidatorOptions<T, TC>;
+  /**
+   * @internal
+   */
+  protected readonly _innerValidators: FieldValidators<T>;
+  /**
+   * @internal
+   */
+  protected readonly _allowedFields?: Set<keyof T>;
+
+  /**
+   * Constructs a new {@link Validation.Classes.ObjectValidator | ObjectValidator<T>}.
+   * @param fields - A {@link Validation.Classes.FieldValidators | FieldValidators<T>} containing
+   * a {@link Validation.Validator | Validator} for each field.
+   * @param options - An optional {@link Validation.Classes.ObjectValidatorOptions} to configure
+   * validation.
+   */
+  public constructor(params: ObjectValidatorConstructorParams<T, TC>) {
+    super(params);
+
+    this.fields = params.fields;
+    this.options = params.options ?? {};
+    this._innerValidators = ObjectValidator._resolveValidators(this.fields, this.options);
+    this._allowedFields =
+      this.options.strict === true ? new Set(Object.keys(this.fields) as (keyof T)[]) : undefined;
+  }
+
+  /**
+   * Creates the actual {@link Validation.Classes.FieldValidators | FieldValidators<T>} to be
+   * used by this converter by applying any options or traits defined in the options
+   * to the field converters passed to the constructor.
+   * @param fields - The base {@link Validation.Classes.FieldValidators | FieldValidators<T>} passed
+   * in to the constructor.
+   * @param options - The {@link Validation.Classes.ObjectValidatorOptions | object validator options}
+   * passed in to the constructor.
+   * @returns A new {@link Validation.Classes.FieldValidators | FieldValidators} with the fully-configured
+   * individual {@link Validation.Validator | field validators} to be applied.
+   * @internal
+   */
+  protected static _resolveValidators<T, TC>(
+    fields: FieldValidators<T, TC>,
+    options?: ObjectValidatorOptions<T, TC>
+  ): FieldValidators<T, TC> {
+    const resolved: Partial<FieldValidators<T, TC>> = {};
+    for (const key in fields) {
+      if (fields[key]) {
+        /* c8 ignore next */
+        const optional = fields[key].isOptional || options?.optionalFields?.includes(key);
+        resolved[key] = new FieldValidator(key, fields[key], { optional });
+      }
+    }
+    return resolved as FieldValidators<T, TC>;
+  }
+
+  /**
+   * Creates a new {@link Validation.Classes.ObjectValidator | ObjectValidator} derived from this one but with
+   * new optional properties as specified by a supplied
+   * {@link Validation.Classes.ObjectValidatorOptions | ObjectValidatorOptions<T>}.
+   * @param options - The {@link Validation.Classes.ObjectValidatorOptions | options} to be applied to the new
+   * {@link Validation.Classes.ObjectValidator | validator}.
+   * @returns A new {@link Validation.Classes.ObjectValidator | ObjectValidator} with the additional optional
+   * source properties.
+   */
+  public partial(options?: ObjectValidatorOptions<T, TC>): ObjectValidator<Partial<T>, TC> {
+    /* c8 ignore next */
+    options = options ?? {};
+    return new ObjectValidator<Partial<T>, TC>({
+      fields: this.fields as FieldValidators<Partial<T>, TC>,
+      options: {
+        ...this.options,
+        ...options
+      },
+      traits: this.traits
+    });
+  }
+
+  /**
+   * Creates a new {@link Validation.Classes.ObjectValidator | ObjectValidator} 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 Validation.Classes.ObjectValidator | ObjectValidator} with the additional optional
+   * source properties.
+   */
+  public addPartial(addOptionalFields: (keyof T)[]): ObjectValidator<Partial<T>, TC> {
+    return this.partial({
+      optionalFields: [...(this.options.optionalFields ?? []), ...addOptionalFields]
+    });
+  }
+
+  /**
+   * {@inheritdoc Validation.ValidatorBase._validate}
+   * @internal
+   */
+  protected _validate(from: unknown, context?: TC): boolean | Failure<T> {
+    if (typeof from !== 'object' || from === null || Array.isArray(from)) {
+      return fail('source is not an object');
+    }
+
+    // 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 this._innerValidators) {
+      if (this._innerValidators[key]) {
+        const result = this._innerValidators[key].validate(from, context);
+        if (result.success && result.value !== undefined) {
+          converted[key] = result.value;
+        } else if (result.isFailure()) {
+          errors.push(result.message);
+        }
+      }
+    }
+
+    if (this._allowedFields) {
+      const invalid = Object.keys(from).filter((k) => !this._allowedFields!.has(k as keyof T));
+      invalid.forEach((key) => errors.push(`${key}: unexpected field in source object.`));
+    }
+    return errors.length === 0 ? true : fail(errors.join('\n'));
+  }
+}

package/src/packlets/validation/oneOf.ts

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2024 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 { Failure, fail } from '../base';
+import { Validator, ValidatorOptions } from './validator';
+import { ValidatorBase, ValidatorBaseConstructorParams } from './validatorBase';
+
+/**
+ * Parameters used to construct a {@link Validation.Classes.OneOfValidator | OneOfValidator}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface OneOfValidatorConstructorParams<T, TC = unknown>
+  extends ValidatorBaseConstructorParams<T, TC> {
+  validators: Validator<T, TC>[];
+}
+
+/**
+ * An in-place {@link Validator | Validator} which validates that a supplied
+ * value matches one of several other validators.
+ * @public
+ */
+export class OneOfValidator<T, TC = unknown> extends ValidatorBase<T, TC> {
+  /**
+   * {@link Validation.ValidatorOptions | Options} which apply to this
+   * validator.
+   */
+  public readonly options: ValidatorOptions<TC>;
+
+  protected readonly _validators: Validator<T, TC>[];
+
+  /**
+   * Constructs a new {@link Validation.Classes.OneOfValidator | OneOfValidator}.
+   * @param params - Optional {@link Validation.Classes.OneOfValidatorConstructorParams | init params} for the
+   * new {@link Validation.Classes.OneOfValidator | OneOfValidator}.
+   */
+  public constructor(params: OneOfValidatorConstructorParams<T, TC>) {
+    super(params);
+    this._validators = params.validators;
+    this.options = params.options ?? {};
+  }
+
+  /**
+   * Static method which validates that a supplied `unknown` value matches at least one
+   * of the configured validators.
+   * @param from - The `unknown` value to be tested.
+   * @param context - Optional validation context will be propagated to element validator.
+   * @returns Returns `true` if `from` is an `array` of valid elements, or
+   * {@link Failure} with an error message if not.
+   */
+  protected _validate<T>(from: unknown, context?: TC): boolean | Failure<T> {
+    const found = this._validators.some((v) => v.validate(from).success);
+    if (found) {
+      return true;
+    }
+    return fail(`value "${from}" does not match any validator.`);
+  }
+}

package/src/packlets/validation/string.ts

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2021 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 { Failure, fail } from '../base';
+import { GenericValidator, GenericValidatorConstructorParams } from './genericValidator';
+
+/**
+ * Parameters used to construct a {@link Validation.Classes.StringValidator | StringValidator}.
+ * @public
+ */
+export type StringValidatorConstructorParams<
+  T extends string = string,
+  TC = unknown
+> = GenericValidatorConstructorParams<T, TC>;
+
+/**
+ * An in-place {@link Validation.Validator | Validator} for `string` values.
+ * @public
+ */
+export class StringValidator<T extends string = string, TC = unknown> extends GenericValidator<T, TC> {
+  /**
+   * Constructs a new {@link Validation.Classes.StringValidator | StringValidator}.
+   * @param params - Optional {@link Validation.Classes.StringValidatorConstructorParams | init params}
+   * for the new {@link Validation.Classes.StringValidator | StringValidator}.
+   */
+  public constructor(params?: StringValidatorConstructorParams<T, TC>) {
+    /* c8 ignore next */
+    params = params ?? {};
+    super({
+      validator: StringValidator.validateString,
+      ...params
+    });
+  }
+
+  /**
+   * Static method which validates that a supplied `unknown` value is a `string`.
+   * @param from - The `unknown` value to be tested.
+   * @returns Returns `true` if `from` is a `string`, or {@link Failure} with an error
+   * message if not.
+   */
+  public static validateString<T extends string>(from: unknown): boolean | Failure<T> {
+    if (typeof from === 'string') {
+      return true;
+    }
+    return fail<T>(`"${from}": not a string`);
+  }
+}

package/src/packlets/validation/traits.ts

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2021 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.
+ */
+
+/**
+ * A {@link Validation.ConstraintTrait | ConstraintTrait} indicating that
+ * a {@link Validation.Constraint | Constraint<T>} function provides an
+ * additional constraint implementation.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface FunctionConstraintTrait {
+  type: 'function';
+}
+
+/**
+ * Union of all supported constraint traits.
+ * @public
+ */
+export type ConstraintTrait = FunctionConstraintTrait;
+
+/**
+ * Interface describing the supported validator traits.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface ValidatorTraitValues {
+  /**
+   * Indicates whether the validator accepts `undefined` as
+   * a valid value.
+   */
+  readonly isOptional: boolean;
+
+  /**
+   * If present, indicates that the result will be branded
+   * with the corresponding brand.
+   */
+  readonly brand?: string;
+
+  /**
+   * Zero or more additional {@link Validation.ConstraintTrait | ConstraintTrait}s
+   * describing additional constraints applied by this {@link Validation.Validator | Validator}.
+   */
+  readonly constraints: ConstraintTrait[];
+}
+
+/**
+ * Default {@link Validation.ValidatorTraitValues | validation traits}.
+ * @public
+ */
+export const defaultValidatorTraits: ValidatorTraitValues = {
+  isOptional: false,
+  constraints: []
+};
+
+/**
+ * Generic implementation of {@link Validation.ValidatorTraitValues | ValidatorTraitValues}.
+ * @public
+ */
+export class ValidatorTraits implements ValidatorTraitValues {
+  /**
+   * {@inheritdoc Validation.ValidatorTraitValues.isOptional}
+   */
+  public readonly isOptional: boolean;
+
+  /**
+   * {@inheritdoc Validation.ValidatorTraitValues.brand}
+   */
+  public readonly brand?: string;
+
+  /**
+   * {@inheritdoc Validation.ValidatorTraitValues.constraints}
+   */
+  public readonly constraints: ConstraintTrait[];
+
+  /**
+   * Constructs a new {@link Validation.ValidatorTraits | ValidatorTraits} optionally
+   * initialized with the supplied base and initial values.
+   * @remarks
+   * Initial values take priority over base values, which fall back to the global default values.
+   * @param init - Partial initial values to be set in the resulting {@link Validation.Validator | Validator}.
+   * @param base - Base values to be used when no initial values are present.
+   */
+  public constructor(init?: Partial<ValidatorTraitValues>, base?: ValidatorTraitValues) {
+    /* c8 ignore next 2 */
+    this.isOptional = init?.isOptional ?? base?.isOptional ?? defaultValidatorTraits.isOptional;
+    this.brand = init?.brand ?? base?.brand ?? defaultValidatorTraits.brand;
+    this.constraints = [
+      ...defaultValidatorTraits.constraints,
+      /* c8 ignore next 1 */
+      ...(base?.constraints ?? []),
+      ...(init?.constraints ?? [])
+    ];
+  }
+}

package/src/packlets/validation/typeGuard.ts

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2021 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 { Failure, fail } from '../base';
+import { ValidatorBase, ValidatorBaseConstructorParams } from './validatorBase';
+
+import { TypeGuardWithContext } from './common';
+import { ValidatorOptions } from './validator';
+
+/**
+ * Parameters used to construct a {@link Validation.Classes.TypeGuardValidator}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface TypeGuardValidatorConstructorParams<T, TC = unknown>
+  extends ValidatorBaseConstructorParams<T, TC> {
+  guard: TypeGuardWithContext<T, TC>;
+  description: string;
+}
+
+/**
+ * An in-place {@link Validation.Validator | Validator} that can be instantiated using a type guard
+ * function.
+ * @public
+ */
+export class TypeGuardValidator<T, TC = unknown> extends ValidatorBase<T, TC> {
+  /**
+   * {@link Validation.ValidatorOptions | Options} which apply to this
+   * validator.
+   */
+  public readonly options: ValidatorOptions<TC>;
+  public readonly description: string;
+
+  protected readonly _guard: TypeGuardWithContext<T, TC>;
+
+  /**
+   * Constructs a new {@link Validation.Classes.TypeGuardValidator | TypeGuardValidator}.
+   * @param params - Optional {@link Validation.Classes.TypeGuardValidatorConstructorParams | init params} for the
+   * new {@link Validation.Classes.TypeGuardValidator | TypeGuardValidator}.
+   */
+  public constructor(params: TypeGuardValidatorConstructorParams<T, TC>) {
+    super(params);
+    this.description = params.description;
+    this._guard = params.guard;
+    this.options = params.options ?? {};
+  }
+
+  /**
+   * Static method which validates that a supplied `unknown` value matches the supplied
+   * type guard, returning a `Failure<T>` containing more information about a failure.
+   * @param from - Value to be converted.
+   * @param context - Optional validation context.
+   * @returns `true` if `from` is valid, {@link Failure | Failure<T>}
+   * with an error message if `from` is invalid.
+   * @internal
+   */
+  protected _validate(from: unknown, context?: TC): boolean | Failure<T> {
+    if (this._guard(from, context)) {
+      return true;
+    }
+    return fail(`invalid ${this.description} (${JSON.stringify(from)})`);
+  }
+}

package/src/packlets/validation/validator.ts

@@ -0,0 +1,145 @@
+/*
+ * Copyright (c) 2021 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, Failure, Result } from '../base';
+import { ConstraintTrait, ValidatorTraits } from './traits';
+
+/**
+ * Options that apply to any {@link Validation.Validator | Validator}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface ValidatorOptions<TC> {
+  defaultContext?: TC;
+}
+
+/**
+ * A {@link Validation.Constraint | Constraint<T>} function returns
+ * `true` if the supplied value meets the constraint. Can return
+ * {@link Failure} with an error message or simply return `false`
+ * for a default message.
+ * @public
+ */
+export type Constraint<T> = (val: T) => boolean | Failure<T>;
+
+/**
+ * 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
+ * required characteristics (type, values, etc).
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface Validator<T, TC = unknown> {
+  /**
+   * {@link Validation.ValidatorTraits | Traits} describing this validation.
+   */
+  readonly traits: ValidatorTraits;
+
+  /**
+   * Indicates whether this element is explicitly optional.
+   */
+  readonly isOptional: boolean;
+
+  /**
+   * The brand for a branded type.
+   */
+  readonly brand: string | undefined;
+
+  /**
+   * Tests to see if a supplied `unknown` value matches this validation.  All
+   * validate calls are guaranteed to return the entity passed in on Success.
+   * @param from - The `unknown` value to be tested.
+   * @param context - Optional validation context.
+   * @returns {@link Success} with the typed, validated value,
+   * or {@link Failure} with an error message if validation fails.
+   */
+  validate(from: unknown, context?: TC): Result<T>;
+
+  /**
+   * Tests to see if a supplied 'unknown' value matches this validation.  In
+   * contrast to {@link Validator.validate | validate}, makes no guarantees
+   * about the identity of the returned value.
+   * @param from - The `unknown` value to be tested.
+   * @param context - Optional validation context.
+   * @returns {@link Success} with the typed, conversion value,
+   * or {@link Failure} with an error message if conversion fails.
+   */
+  convert(from: unknown, context?: TC): Result<T>;
+
+  /**
+   * Tests to see if a supplied `unknown` value matches this
+   * validation.  Accepts `undefined`.
+   * @param from - The `unknown` value to be tested.
+   * @param context - Optional validation context.
+   * @returns {@link Success} with the typed, validated value,
+   * or {@link Failure} with an error message if validation fails.
+   */
+  validateOptional(from: unknown, context?: TC): Result<T | undefined>;
+
+  /**
+   * Non-throwing type guard
+   * @param from - The value to be tested.
+   * @param context - Optional validation context.
+   */
+  guard(from: unknown, context?: TC): from is T;
+
+  /**
+   * Creates an {@link Validation.Validator | in-place validator}
+   * which is derived from this one but which also matches `undefined`.
+   */
+  optional(): Validator<T | undefined, TC>;
+
+  /**
+   * Creates an {@link Validation.Validator | in-place validator}
+   * which is derived from this one but which applies additional constraints.
+   * @param constraint - the constraint to be applied
+   * @param trait - As optional {@link Validation.ConstraintTrait | ConstraintTrait}
+   * to be applied to the resulting {@link Validation.Validator | Validator}.
+   * @returns A new {@link Validation.Validator | Validator}.
+   */
+  withConstraint(constraint: Constraint<T>, trait?: ConstraintTrait): Validator<T, TC>;
+
+  /**
+   * Creates a new {@link Validation.Validator | in-place validator} which
+   * is derived from this one but which matches a branded result.
+   * @param brand - The brand to be applied.
+   */
+  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>;
+}