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

package/src/packlets/validation/array.ts

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2022 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.ArrayValidator | ArrayValidator}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface ArrayValidatorConstructorParams<T, TC = unknown>
+  extends ValidatorBaseConstructorParams<T[], TC> {
+  validateElement: Validator<T, TC>;
+}
+
+/**
+ * An in-place {@link Validator | Validator} for arrays of validated
+ * values or objects.
+ * @public
+ */
+export class ArrayValidator<T, TC = unknown> extends ValidatorBase<T[], TC> {
+  /**
+   * {@link Validation.ValidatorOptions | Options} which apply to this
+   * validator.
+   */
+  public readonly options: ValidatorOptions<TC>;
+
+  protected readonly _validateElement: Validator<T, TC>;
+
+  /**
+   * Constructs a new {@link Validation.Classes.ArrayValidator | ArrayValidator}.
+   * @param params - Optional {@link Validation.Classes.ArrayValidatorConstructorParams | init params} for the
+   * new {@link Validation.Classes.ArrayValidator | ArrayValidator}.
+   */
+  public constructor(params: ArrayValidatorConstructorParams<T, TC>) {
+    super(params);
+    this._validateElement = params.validateElement;
+    this.options = params.options ?? {};
+  }
+
+  /**
+   * Static method which validates that a supplied `unknown` value is a `array`
+   * and that every element of the array can be validated by the supplied array
+   * validator.
+   * @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> {
+    if (Array.isArray(from)) {
+      for (const elem of from) {
+        const result = this._validateElement.validate(elem, context);
+        if (!result.isSuccess()) {
+          return fail(result.message);
+        }
+      }
+      return true;
+    }
+    return fail<T>(`"${from}": not an array`);
+  }
+}

package/src/packlets/validation/boolean.ts

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

package/src/packlets/validation/classes.ts

@@ -0,0 +1,38 @@
+/*
+ * 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.
+ */
+
+/* c8 ignore start */
+
+export { ArrayValidator, ArrayValidatorConstructorParams } from './array';
+export { BooleanValidator, BooleanValidatorConstructorParams } from './boolean';
+export { NumberValidator, NumberValidatorConstructorParams } from './number';
+export {
+  FieldValidators,
+  ObjectValidator,
+  ObjectValidatorConstructorParams,
+  ObjectValidatorOptions
+} from './object';
+export { OneOfValidator, OneOfValidatorConstructorParams } from './oneOf';
+export { StringValidator, StringValidatorConstructorParams } from './string';
+export { TypeGuardValidator, TypeGuardValidatorConstructorParams } from './typeGuard';
+
+/* c8 ignore stop */

package/src/packlets/validation/common.ts

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2022 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 } from '../base';
+
+/**
+ * A type guard function which validates a specific type, with an optional context
+ * that can be used to shape the validation.
+ * @public
+ */
+export type TypeGuardWithContext<T, TC = unknown> = (from: unknown, context?: TC) => from is T;
+
+/**
+ * Type for a validation function, which validates that a supplied `unknown`
+ * value is a valid value of type `<T>`, possibly as influenced by
+ * an optionally-supplied validation context of type `<TC>`.
+ * @public
+ */
+export type ValidatorFunc<T, TC> = (from: unknown, context?: TC) => boolean | Failure<T>;

package/src/packlets/validation/field.ts

@@ -0,0 +1,99 @@
+/*
+ * 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 { Failure, fail, isKeyOf } from '../base';
+import { Validator, ValidatorOptions } from './validator';
+import { ValidatorBase } from './validatorBase';
+
+/**
+ * Parameters used to construct a {@link Validation.FieldValidator | FieldValidator}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface FieldValidatorOptions<TC> extends ValidatorOptions<TC> {
+  optional?: boolean;
+}
+
+/**
+ * An in-place {@link Validation.Validator | Validator} for properties
+ * an an object.
+ * @public
+ */
+export class FieldValidator<T, TC = unknown> extends ValidatorBase<T, TC> {
+  /**
+   * The name of the property that this validator should validate.
+   */
+  public readonly fieldName: string;
+  /**
+   * The {@link Validation.Validator | Validator} to be applied against the named property.
+   */
+  public readonly fieldValidator: Validator<T, TC>;
+  /**
+   * @internal
+   */
+  protected readonly _fieldOptions: FieldValidatorOptions<TC>;
+
+  /**
+   * Constructs a new {@link Validation.FieldValidator | FieldValidator.}.
+   * @param fieldName - The name of the property that this validator should validate.
+   * @param fieldValidator - The {@link Validation.Validator | Validator} to be applied
+   * against the named property.
+   * @param options - Additional {@link Validation.FieldValidatorOptions | options} to be
+   * applied to this validation.
+   */
+  public constructor(
+    fieldName: string,
+    fieldValidator: Validator<T, TC>,
+    options?: FieldValidatorOptions<TC>
+  ) {
+    super({ options });
+    this.fieldName = fieldName;
+    this.fieldValidator = fieldValidator;
+    /* c8 ignore next */
+    this._fieldOptions = options ?? {};
+  }
+
+  /**
+   * {@inheritdoc Validation.ValidatorBase._validate}
+   */
+  protected _validate(from: unknown, context?: TC): boolean | Failure<T> {
+    if (typeof from === 'object' && !Array.isArray(from) && from !== null) {
+      const optional = this._fieldOptions.optional === true;
+
+      if (isKeyOf(this.fieldName, from)) {
+        if (!optional || from[this.fieldName] !== undefined) {
+          const result = this.fieldValidator
+            .validate(from[this.fieldName], context)
+            .onFailure((message: string) => {
+              return fail(`${this.fieldName}: ${message}`);
+            });
+
+          return result.success ? true : result;
+        }
+      }
+
+      return optional ? true : fail(`"${this.fieldName}": Field not found in "${JSON.stringify(from)}`);
+    }
+    /* c8 ignore next 2 -- defense in depth */
+    return fail(`Cannot validate field '${this.fieldName}' from non-object "${JSON.stringify(from)}"`);
+  }
+}

package/src/packlets/validation/genericValidator.ts

@@ -0,0 +1,205 @@
+/*
+ * 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, fail, succeed } from '../base';
+import { ConstraintTrait, ValidatorTraits } from './traits';
+import { Constraint, ValidationErrorFormatter, Validator, ValidatorOptions } from './validator';
+
+import { ValidatorFunc } from './common';
+
+/**
+ * @deprecated Use {@link Validation.Common.ValidatorFunc | Validation.Common.ValidatorFunc} instead.
+ */
+export { ValidatorFunc };
+
+/**
+ * Options used to initialize a {@link Validation.Base.GenericValidator | GenericValidator}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface GenericValidatorConstructorParams<T, TC> {
+  options?: ValidatorOptions<TC>;
+  traits?: Partial<ValidatorTraits>;
+  validator?: ValidatorFunc<T, TC>;
+}
+
+/**
+ * Generic base implementation for an in-place {@link Validation.Validator | Validator}.
+ * @public
+ */
+export class GenericValidator<T, TC = unknown> implements Validator<T, TC> {
+  /**
+   * {@inheritdoc Validation.Validator.traits}
+   */
+  public readonly traits: ValidatorTraits;
+
+  /**
+   * @internal
+   */
+  protected readonly _validator: ValidatorFunc<T, TC>;
+  /**
+   * @internal
+   */
+  protected readonly _options: ValidatorOptions<TC>;
+
+  /**
+   * Constructs a new {@link Validation.Base.GenericValidator | GenericValidator<T>}.
+   * @param params - The {@link Validation.Base.GenericValidatorConstructorParams | constructor params}
+   * used to configure validation.
+   */
+  public constructor(params: Partial<GenericValidatorConstructorParams<T, TC>>) {
+    if (!params.validator) {
+      throw new Error('No validator function supplied');
+    }
+    this._validator = params.validator;
+    this._options = params.options ?? {};
+    this.traits = new ValidatorTraits(params.traits);
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.isOptional}
+   */
+  public get isOptional(): boolean {
+    return this.traits.isOptional;
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.brand}
+   */
+  public get brand(): string | undefined {
+    return this.traits.brand;
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.validate}
+   */
+  public validate(from: unknown, context?: TC): Result<T> {
+    const result = this._validator(from, this._context(context));
+    if (typeof result === 'boolean') {
+      return result ? succeed(from as T) : fail<T>('Invalid value');
+    }
+    return result;
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.convert}
+   */
+  public convert(from: unknown, context?: TC): Result<T> {
+    const result = this._validator(from, this._context(context));
+    if (typeof result === 'boolean') {
+      return result ? succeed(from as T) : fail<T>('Invalid value');
+    }
+    return result;
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.validateOptional}
+   */
+  public validateOptional(from: unknown, context?: TC): Result<T | undefined> {
+    return from === undefined ? succeed(undefined) : this.validate(from, context);
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.guard}
+   */
+  public guard(from: unknown, context?: TC): from is T {
+    return this._validator(from, this._context(context)) === true;
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.optional}
+   */
+  public optional(): Validator<T | undefined, TC> {
+    return new GenericValidator({
+      validator: (from: unknown, context?: TC) => {
+        return from === undefined || this._validator(from, this._context(context));
+      },
+      traits: { isOptional: true }
+    });
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.withConstraint}
+   */
+  public withConstraint(constraint: Constraint<T>, trait?: ConstraintTrait): Validator<T, TC> {
+    trait = trait ?? { type: 'function' };
+    return new GenericValidator({
+      validator: (from: unknown, context?: TC): boolean | Failure<T> => {
+        const result = this._validator(from, this._context(context));
+        if (result === true) {
+          const constraintResult = constraint(from as T);
+          if (typeof constraintResult === 'boolean') {
+            return constraintResult
+              ? true
+              : fail(`Invalid value "${JSON.stringify(from)}":  does not meet constraint.`);
+          }
+          return constraintResult;
+        }
+        return result;
+      },
+      traits: { constraints: [trait] }
+    });
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.brand}
+   */
+  public withBrand<B extends string>(brand: B): Validator<Brand<T, B>, TC> {
+    if (this.brand) {
+      throw new Error(`Cannot replace existing brand "${this.brand}" with "${brand}".`);
+    }
+
+    return new GenericValidator<Brand<T, B>, TC>({
+      validator: (from: unknown, context?: TC) => {
+        return this._validator(from, this._context(context)) as boolean | Failure<Brand<T, B>>;
+      },
+      traits: { brand }
+    });
+  }
+
+  /**
+   * {@inheritdoc Validation.Validator.withFormattedError}
+   */
+  public withFormattedError(formatter: ValidationErrorFormatter<TC>): Validator<T, TC> {
+    return new GenericValidator<T, TC>({
+      validator: (from: unknown, context?: TC) => {
+        const result = this._validator(from, this._context(context));
+        if (result === true) {
+          return true;
+        }
+        /* c8 ignore next - defense in depth */
+        const message = result === false ? undefined : result.message;
+        return fail(formatter(from, message, this._context(context)));
+      }
+    });
+  }
+
+  /**
+   * Gets a default or explicit context.
+   * @param explicitContext - Optional explicit context.
+   * @returns The appropriate context to use.
+   * @internal
+   */
+  protected _context(explicitContext?: TC): TC | undefined {
+    return explicitContext ?? this._options.defaultContext;
+  }
+}

package/src/packlets/validation/index.ts

@@ -0,0 +1,31 @@
+/*
+ * 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.
+ */
+
+export * from './common';
+export * from './traits';
+export * from './validator';
+
+import * as Classes from './classes';
+import * as Base from './genericValidator';
+import * as Validators from './validators';
+
+export { Base, Classes, Validators };

package/src/packlets/validation/number.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.NumberValidator | NumberValidator}.
+ * @public
+ */
+export type NumberValidatorConstructorParams<
+  T extends number = number,
+  TC = unknown
+> = GenericValidatorConstructorParams<T, TC>;
+
+/**
+ * An in-place {@link Validation.Validator | Validator} for `number` values.
+ * @public
+ */
+export class NumberValidator<T extends number = number, TC = unknown> extends GenericValidator<T, TC> {
+  /**
+   * Constructs a new {@link Validation.Classes.NumberValidator | NumberValidator}.
+   * @param params - Optional {@link Validation.Classes.NumberValidatorConstructorParams | init params} for the
+   * new {@link Validation.Classes.NumberValidator | NumberValidator}.
+   */
+  public constructor(params?: NumberValidatorConstructorParams<T, TC>) {
+    /* c8 ignore next 1 */
+    params = params ?? {};
+    super({
+      validator: NumberValidator.validateNumber,
+      ...params
+    });
+  }
+
+  /**
+   * Static method which validates that a supplied `unknown` value is a `number`.
+   * @param from - The `unknown` value to be tested.
+   * @returns Returns `true` if `from` is a `number`, or {@link Failure} with an error
+   * message if not.
+   */
+  public static validateNumber<T extends number>(from: unknown): boolean | Failure<T> {
+    if (typeof from === 'number') {
+      return true;
+    }
+    return fail<T>(`"${from}": not a number`);
+  }
+}