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

package/src/packlets/validation/validator.ts

@@ -1,157 +0,0 @@
-/*
- * 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';
-
-/**
- * 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,
-  self?: Validator<T, TC>
-) => boolean | Failure<T>;
-
-/**
- * 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>;
-}

package/src/packlets/validation/validatorBase.ts

@@ -1,66 +0,0 @@
-/*
- * 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 { GenericValidator, GenericValidatorConstructorParams } from './genericValidator';
-
-import { Failure } from '../base';
-
-/**
- * @internal
- */
-export type ValidatorBaseConstructorParams<T, TC> = Omit<
-  GenericValidatorConstructorParams<T, TC>,
-  'validator'
->;
-
-/**
- * Abstract base helper class for specific validator implementations
- * @internal
- */
-export abstract class ValidatorBase<T, TC = unknown> extends GenericValidator<T, TC> {
-  /**
-   * Inner constructor
-   * @param params - Initialization params.
-   * @internal
-   */
-  protected constructor(params: Partial<ValidatorBaseConstructorParams<T, TC>>) {
-    super({
-      validator: (from, context, self) => this._validate(from, context, self),
-      ...params
-    });
-  }
-
-  /**
-   * Abstract validation method to me implemented by derived classes.
-   * @param from - Value to be converted.
-   * @param context - Optional validation context.
-   * @param self - Optional self-reference for recursive validation.
-   * @returns `true` if `from` is valid, {@link Failure | Failure<T>}
-   * with an error message if `from` is invalid.
-   * @internal
-   */
-  protected abstract _validate(
-    from: unknown,
-    context?: TC,
-    self?: import('./validator').Validator<T, TC>
-  ): boolean | Failure<T>;
-}

package/src/packlets/validation/validators.ts

@@ -1,254 +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 { Failure, fail, isKeyOf, MessageAggregator } from '../base';
-import { ArrayValidator, ArrayValidatorConstructorParams } from './array';
-import { FieldValidators, ObjectValidator, ObjectValidatorConstructorParams } from './object';
-import { TypeGuardValidator, TypeGuardValidatorConstructorParams } from './typeGuard';
-
-import { BooleanValidator } from './boolean';
-import { TypeGuardWithContext } from './common';
-import { GenericValidator } from './genericValidator';
-import { NumberValidator } from './number';
-import { OneOfValidator, OneOfValidatorConstructorParams } from './oneOf';
-import { StringValidator } from './string';
-import { Validator, ValidatorFunc } from './validator';
-
-/**
- * A {@link Validation.Classes.StringValidator | StringValidator} which validates a string in place.
- * @public
- */
-export const string: Validator<string> = new StringValidator();
-
-/**
- * A {@link Validation.Classes.NumberValidator | NumberValidator} which validates a number in place.
- * @public
- */
-export const number: Validator<number> = new NumberValidator();
-
-/**
- * A {@link Validation.Classes.BooleanValidator | BooleanValidator} which validates a boolean in place.
- * @public
- */
-export const boolean: Validator<boolean> = new BooleanValidator();
-
-/**
- * Helper function to create a {@link Validation.Classes.ObjectValidator | ObjectValidator} which validates
- * an object in place.
- * @param fields - A {@link Validation.Classes.FieldValidators | field validator definition}
- * describing the validations to be applied.
- * @param params - Optional {@link Validation.Classes.ObjectValidatorConstructorParams | parameters}
- * to refine the behavior of the resulting {@link Validation.Validator | validator}.
- * @returns A new {@link Validation.Validator | Validator} which validates the desired
- * object in place.
- * @public
- */
-export function object<T, TC = unknown>(
-  fields: FieldValidators<T, TC>,
-  params?: Omit<ObjectValidatorConstructorParams<T, TC>, 'fields'>
-): ObjectValidator<T, TC> {
-  return new ObjectValidator({ fields, ...(params ?? {}) });
-}
-
-/**
- * Helper function to create a {@link Validation.Classes.ArrayValidator | ArrayValidator} which
- * validates an array in place.
- * @param validateElement - A {@link Validation.Validator | validator} which validates each element.
- * @returns A new {@link Validation.Classes.ArrayValidator | ArrayValidator } which validates the desired
- * array in place.
- * @public
- */
-export function arrayOf<T, TC>(
-  validateElement: Validator<T, TC>,
-  params?: Omit<ArrayValidatorConstructorParams<T, TC>, 'validateElement'>
-): ArrayValidator<T, TC> {
-  return new ArrayValidator({ validateElement, ...(params ?? {}) });
-}
-
-/**
- * Options for {@link Validators.recordOf} helper function.
- * @public
- */
-export interface IRecordOfValidatorOptions<TK extends string = string, TC = unknown> {
-  /**
-   * If `onError` is `'fail'` (default), then the entire validation fails if any key or element
-   * cannot be validated. If `onError` is `'ignore'`, failing elements are silently ignored.
-   */
-  onError?: 'fail' | 'ignore';
-  /**
-   * If present, `keyValidator` is used to validate the source object property names.
-   * @remarks
-   * Can be used to validate key names to supported values and/or strong types.
-   */
-  keyValidator?: Validator<TK, TC>;
-}
-
-/**
- * A helper function to create a {@link Validation.Validator | Validator} which validates the `string`-keyed properties
- * using a supplied {@link Validation.Validator | Validator<T, TC>} to produce a `Record<TK, T>`.
- * @remarks
- * If present, the supplied {@link Validators.IRecordOfValidatorOptions | options} can provide a strongly-typed
- * validator for keys and/or control the handling of elements that fail validation.
- * @param validator - {@link Validation.Validator | Validator} used for each item in the source object.
- * @param options - Optional {@link Validators.IRecordOfValidatorOptions | IRecordOfValidatorOptions<TK, TC>} which
- * supplies a key validator and/or error-handling options.
- * @returns A {@link Validation.Validator | Validator} which validates `Record<TK, T>`.
- * @public
- */
-export function recordOf<T, TC = unknown, TK extends string = string>(
-  validator: Validator<T, TC>,
-  options?: IRecordOfValidatorOptions<TK, TC>
-): Validator<Record<TK, T>, TC> {
-  const opts: IRecordOfValidatorOptions<TK, TC> = { onError: 'fail', ...options };
-
-  return new GenericValidator({
-    validator: (
-      from: unknown,
-      context?: TC,
-      self?: Validator<Record<TK, T>, TC>
-    ): boolean | Failure<Record<TK, T>> => {
-      if (typeof from !== 'object' || from === null || Array.isArray(from)) {
-        return fail(`Not a string-keyed object: ${JSON.stringify(from)}`);
-      }
-
-      const errors = new MessageAggregator();
-
-      for (const key in from) {
-        if (isKeyOf(key, from)) {
-          // Validate key if keyValidator is provided
-          if (opts.keyValidator) {
-            const keyResult = opts.keyValidator.validate(key, context);
-            if (!keyResult.isSuccess()) {
-              if (opts.onError === 'ignore') {
-                continue;
-              }
-              errors.addMessage(`Key "${key}": ${keyResult.message}`);
-              if (opts.onError === 'fail') {
-                return fail(keyResult.message);
-              }
-            }
-          }
-
-          // Validate value
-          const valueResult = validator.validate(from[key] as unknown, context);
-          if (!valueResult.isSuccess()) {
-            if (opts.onError === 'ignore') {
-              continue;
-            }
-            errors.addMessage(`Property "${key}": ${valueResult.message}`);
-            if (opts.onError === 'fail') {
-              return fail(valueResult.message);
-            }
-          }
-        }
-      }
-
-      /* c8 ignore next 1 - defense in depth */
-      return errors.hasMessages ? fail(errors.toString()) : true;
-    }
-  });
-}
-
-/**
- * Helper function to create a {@link Validation.Validator} which validates an enumerated
- * value in place.
- * @public
- */
-export function enumeratedValue<T extends string>(values: ReadonlyArray<T>): Validator<T, ReadonlyArray<T>> {
-  return new GenericValidator({
-    validator: (
-      from: unknown,
-      context?: ReadonlyArray<T>,
-      self?: Validator<T, ReadonlyArray<T>>
-    ): boolean | Failure<T> => {
-      if (typeof from === 'string') {
-        const v = context ?? values;
-        const index = v.indexOf(from as T);
-        return index >= 0 ? true : fail(`Invalid enumerated value "${from}"  - expected: (${v.join(', ')})`);
-      }
-      return fail(`Not a string: "${JSON.stringify(from, undefined, 2)}`);
-    }
-  });
-}
-
-/**
- * Helper function to create a {@link Validation.Validator} which validates a literal value.
- * @param value - the literal value to be validated
- * @public
- */
-export function literal<T extends string | number | boolean | symbol | null | undefined>(
-  value: T
-): Validator<T> {
-  return new GenericValidator({
-    validator: (from: unknown, context?: unknown, self?: Validator<T>): boolean | Failure<T> => {
-      return from === value
-        ? true
-        : fail(`Expected literal ${String(value)}, found "${JSON.stringify(from, undefined, 2)}`);
-    }
-  });
-}
-
-/**
- * Helper function to create a {@link Validation.Validator | Validator} which validates one
- * of several possible validated values.
- * @param validators - the {@link Validation.Validator | validators} to be considered.
- * @param params - Optional {@link Validation.Classes.OneOfValidatorConstructorParams | params} used to construct the validator.
- * @returns A new {@link Validator | Validator} which validates values that match any of
- * the supplied validators.
- * @public
- */
-export function oneOf<T, TC = unknown>(
-  validators: Array<Validator<T, TC>>,
-  params?: Omit<OneOfValidatorConstructorParams<T, TC>, 'validators'>
-): OneOfValidator<T, TC> {
-  return new OneOfValidator<T, TC>({ ...(params ?? {}), validators });
-}
-
-/**
- * Helper function to create a {@link Validation.Classes.TypeGuardValidator | TypeGuardValidator} which
- * validates a value or object in place.
- * @param description - a description of the thing to be validated for use in error messages
- * @param guard - a {@link Validation.TypeGuardWithContext} which performs the validation.
- * @returns A new {@link Validation.Classes.TypeGuardValidator | TypeGuardValidator } which validates
- * the values using the supplied type guard.
- * @public
- */
-export function isA<T, TC = unknown>(
-  description: string,
-  guard: TypeGuardWithContext<T, TC>,
-  params?: Omit<TypeGuardValidatorConstructorParams<T, TC>, 'description' | 'guard'>
-): TypeGuardValidator<T, TC> {
-  return new TypeGuardValidator({ description, guard, ...(params ?? {}) });
-}
-
-/**
- * Helper function to create a {@link Validation.Validator | Validator} using a
- * supplied {@link Validation.ValidatorFunc | validator function}.
- * @param validator - A {@link Validation.ValidatorFunc | validator function} that a
- * supplied unknown value matches some condition.
- * @returns A new {@link Validation.Validator | Validator} which validates the desired
- * value using the supplied function.
- * @public
- */
-export function generic<T, TC = unknown>(validator: ValidatorFunc<T, TC>): Validator<T, TC> {
-  return new GenericValidator({ validator });
-}