@amazon/vinyl-validation 1.0.0

package/dist/types/ts4.7/validation/Validator.d.ts

@@ -0,0 +1,88 @@
+import { type Invariant } from '@amazon/vinyl-util';
+/**
+ * Represents a validation failure.
+ */
+export interface ValidationErrorMessage {
+    readonly message: string;
+    readonly path: readonly string[];
+}
+export interface ValidationOptions {
+    /**
+     * If true, collect all validation errors.
+     * Default: false
+     */
+    readonly all?: boolean;
+}
+/**
+ * A Validator can assert that an input matches this validator's schema.
+ */
+export interface Validator<Output extends Input, in Input = unknown> {
+    /**
+     * Enforces T is in an invariant position.
+     * This prevents a validator with more strict rules is assigned to a less strict type, which
+     * can cause unexpected validation errors.
+     */
+    __type?: Invariant<Output>;
+    /**
+     * A short description of the validator.
+     */
+    readonly description: string;
+    /**
+     * Returns true if the input is valid according to this validator.
+     *
+     * @param input
+     */
+    readonly isValid: (input: Input) => input is Output;
+    /**
+     * Validates the provided input, returning a list of error messages, or an empty array if the
+     * input passes this validator.
+     *
+     * @param input The input to validate.
+     * @param options Validation options.
+     * @param path The current field path to this validator.
+     * @return Returns an array of validation failures. If `options.all` is not true, only the
+     * first error will be returned.
+     */
+    readonly validate: (input: Input, options?: ValidationOptions, path?: readonly string[]) => readonly ValidationErrorMessage[];
+    /**
+     * Validates the given input, asserting that the input is type `T`.
+     * If the input is not valid, a {@link ValidationError} will be thrown.
+     *
+     * @param input The input to validate.
+     * @param origin The error origin. `ErrorOrigin.API` by default.
+     * @param path The current field path to this validator.
+     * @return Returns the input, cast as the validated type T
+     */
+    readonly assert: (input: Input, origin?: string, path?: readonly string[]) => asserts input is Output;
+}
+/**
+ * Creates a message string for a ValidationErrorMessage based on the input and its expectation.
+ *
+ * @param expectationMessage
+ * @param input
+ * @param path
+ * @param inputStringify
+ */
+export declare function createValidationExpectationMessage<Input>(expectationMessage: string, input: Input, path: readonly string[], inputStringify?: (input: Input) => string): string;
+/**
+ * Creates a new basic validator.
+ *
+ * For a deep validator which has sub-fields, use {@link createDeepValidator}.
+ *
+ * @param expectationMessage The message to use to describe what is expected. This will be used in
+ * the error message template.
+ * @param isValid Returns true if the given input is valid.
+ * @param inputStringify Stringifies the input for use as the actual `{actual}` token in the validation
+ * expectation template. Default is `stringifyForPrint` with a 500 character max length.
+ */
+export declare function createValidator<Output extends Input, Input = unknown>(expectationMessage: string, isValid: (input: Input) => boolean, inputStringify?: (input: Input) => string): Validator<Output, Input>;
+/**
+ * Creates a new deep validator.
+ *
+ * For a shallow validator which validates one value, use {@link createValidator}.
+ *
+ * @param description Describes the validator.
+ * @param validate Returns an array of validation failures.
+ */
+export declare function createDeepValidator<Output extends Input, Input = unknown>(description: string, validate: (input: Input, options: ValidationOptions, path: readonly string[]) => readonly ValidationErrorMessage[]): Validator<Output, Input>;
+//# sourceMappingURL=Validator.d.ts.map

package/dist/types/ts4.7/validation/ValidatorWithPartial.d.ts

@@ -0,0 +1,26 @@
+import type { PartialDeep } from '@amazon/vinyl-util';
+import type { Validator } from './Validator';
+export interface ValidatorWithPartial<Output extends Input, Input> extends Validator<Output, Input> {
+    partial(): ValidatorWithPartial<Partial<Output> & Input, Input>;
+    partialDeep(): ValidatorWithPartial<PartialDeep<Output> & Input, Input>;
+}
+/**
+ * Returns true if the given validator is an object validator.
+ * @param validator
+ */
+export declare function isValidatorWithPartial<Output extends Input, Input>(validator: Validator<Output, Input>): validator is ValidatorWithPartial<Output, Input>;
+/**
+ * If the given validator is an object validator, it will be cloned to a deep partial validator,
+ * otherwise returns the validator as is.
+ *
+ * @param validator
+ */
+export declare function maybeToDeepPartial(validator: Validator<any>): Validator<any>;
+/**
+ * If the given validator is an object validator, it will be cloned to a partial validator,
+ * otherwise returns the validator as is.
+ *
+ * @param validator
+ */
+export declare function maybeToPartial(validator: Validator<any>): Validator<any>;
+//# sourceMappingURL=ValidatorWithPartial.d.ts.map

package/dist/types/ts4.7/validation/ValueSchema.d.ts

@@ -0,0 +1,52 @@
+import { SchemaBase } from './SchemaBase';
+import type { Validator } from './Validator';
+export declare const valueValidators: {
+    readonly any: () => Validator<any>;
+    /**
+     * Creates a validator that asserts that the input is nullish.
+     */
+    readonly nullish: () => Validator<null | undefined>;
+    /**
+     * Creates a validator that asserts that the input is strictly null.
+     */
+    readonly null: () => Validator<null>;
+    /**
+     * Creates a validator that asserts that the input is strictly undefined.
+     */
+    readonly undefined: () => Validator<undefined>;
+};
+export declare class ValueSchema<T> extends SchemaBase<T> {
+    /**
+     * Prepends this validator allowing for null or undefined.
+     */
+    maybe(): ValueSchema<T | undefined | null>;
+    /**
+     * Prepends this validator allowing for null.
+     */
+    orNull(): ValueSchema<T | null>;
+    /**
+     * Prepends this validator allowing for undefined.
+     */
+    orUndefined(): ValueSchema<T | undefined>;
+    /**
+     * Returns a validator that asserts if this validator and the next passes.
+     *
+     * @see andValidators
+     *
+     * @param nextValidator The validator to run after the current.
+     * @return Returns a new ValueSchema intersecting this validator and the next.
+     */
+    and<U>(nextValidator: Validator<U>): ValueSchema<T & U>;
+    /**
+     * Returns a validator that asserts if this validator or the next passes.
+     *
+     * Implementation note:
+     * subclasses should not change the schema instance returned unless all chainable validators
+     * accept input type 'unknown'.
+     *
+     * @param nextValidator The validator to run after the current.
+     * @return Returns a new ValueSchema providing the union of this validator and the next.
+     */
+    or<U>(nextValidator: Validator<U, any>): ValueSchema<T | U>;
+}
+//# sourceMappingURL=ValueSchema.d.ts.map

package/dist/types/ts4.7/validation/andValidators.d.ts

@@ -0,0 +1,19 @@
+import type { Validator } from './Validator';
+/**
+ * Validates that all the given validators pass.
+ */
+export declare function andValidators<A extends Input, B, Input>(validatorA: Validator<A, Input>, validatorB: Validator<B, any>): Validator<A & B, Input>;
+/**
+ * Validates that all the given validators pass.
+ */
+export declare function andValidators<A extends Input, B, C, Input>(validatorA: Validator<A, Input>, validatorB: Validator<B, any>, validatorC: Validator<C, any>): Validator<A & B & C, Input>;
+/**
+ * Validates that all the given validators pass.
+ */
+export declare function andValidators<A extends Input, B, C, D, Input>(validatorA: Validator<A, Input>, validatorB: Validator<B, any>, validatorC: Validator<C, any>, validatorD: Validator<D, any>): Validator<A & B & C & D, any>;
+/**
+ * Validates that all the given validators pass.
+ */
+export declare function andValidators<A extends Input, B, C, D, E, Input>(validatorA: Validator<A, Input>, validatorB: Validator<B, any>, validatorC: Validator<C, any>, validatorD: Validator<D, any>, validatorE: Validator<E, any>): Validator<A & B & C & D & E, any>;
+export declare function andValidators(...validators: Validator<any, any>[]): Validator<any, any>;
+//# sourceMappingURL=andValidators.d.ts.map

package/dist/types/ts4.7/validation/orValidators.d.ts

@@ -0,0 +1,19 @@
+import type { Validator } from './Validator';
+/**
+ * Validates that one of the given validators pass.
+ */
+export declare function orValidators<A, B>(validatorA: Validator<A, any>, validatorB: Validator<B, any>): Validator<A | B, any>;
+/**
+ * Validates that one of the given validators pass.
+ */
+export declare function orValidators<A, B, C>(validatorA: Validator<A, any>, validatorB: Validator<B, any>, validatorC: Validator<C, any>): Validator<A | B | C, any>;
+/**
+ * Validates that one of the given validators pass.
+ */
+export declare function orValidators<A, B, C, D>(validatorA: Validator<A, any>, validatorB: Validator<B, any>, validatorC: Validator<C, any>, validatorD: Validator<D, any>): Validator<A | B | C | D, any>;
+/**
+ * Validates that one of the given validators pass.
+ */
+export declare function orValidators<A, B, C, D, E>(validatorA: Validator<A, any>, validatorB: Validator<B, any>, validatorC: Validator<C, any>, validatorD: Validator<D, any>, validatorE: Validator<E, any>): Validator<A | B | C | D | E, any>;
+export declare function orValidators(...validators: Validator<any, any>[]): Validator<any, any>;
+//# sourceMappingURL=orValidators.d.ts.map

package/dist/types/ts4.7/validation/typeOfValidators.d.ts

@@ -0,0 +1,15 @@
+import type { Validator } from './Validator';
+/**
+ * Validators asserting typeof input matches the expected value.
+ *
+ * Note: bigint is omitted; not all supported platforms can use BigInt.
+ */
+export declare const typeOfValidators: {
+    readonly boolean: Validator<boolean, unknown>;
+    readonly func: Validator<import("@amazon/vinyl-util").Fun, unknown>;
+    readonly number: Validator<number, unknown>;
+    readonly object: Validator<object, unknown>;
+    readonly string: Validator<string, unknown>;
+    readonly symbol: Validator<symbol, unknown>;
+};
+//# sourceMappingURL=typeOfValidators.d.ts.map

package/dist/types/ts4.7/validation/validators.d.ts

@@ -0,0 +1,127 @@
+import { type AnyRecord, type Fun, type Primitive, type ReadonlyRecord } from '@amazon/vinyl-util';
+import { ArraySchema } from './ArraySchema';
+import { FunctionSchema } from './FunctionSchema';
+import { SetSchema } from './SetSchema';
+import { ValueSchema } from './ValueSchema';
+import { NumberSchema } from './NumberSchema';
+import { type ExtendedPropertyValidators, ObjectSchema } from './ObjectSchema';
+import { RecordSchema } from './RecordSchema';
+import { StringSchema } from './StringSchema';
+import type { Validator } from './Validator';
+/**
+ * Creates a no-op validator. The value can be any type.
+ */
+export declare function any(): ValueSchema<any>;
+/**
+ * Creates a validator that asserts that the input is an array.
+ */
+export declare function array(): ArraySchema<unknown[]>;
+/**
+ * Creates a validator that asserts that the input is an array and every element passes the
+ * given validator.
+ *
+ * @param elementValidator
+ */
+export declare function array<U>(elementValidator: Validator<U>): ArraySchema<U[]>;
+/**
+ * Creates a validator that asserts that the input is a boolean.
+ */
+export declare function boolean(): ValueSchema<boolean>;
+/**
+ * Creates a validator that asserts that the input is a function.
+ */
+export declare function func(): FunctionSchema<Fun>;
+/**
+ * Validates that the input is an instanceof the given prototype.
+ * @param clazz
+ */
+export declare function instanceOf<T>(clazz: new (...args: any[]) => T): ValueSchema<T>;
+/**
+ * Creates a validator that asserts that the input is nullish or one of the given possible values.
+ *
+ * @param possibleValues
+ */
+export declare function isOneOf<U extends readonly Primitive[]>(...possibleValues: U): ValueSchema<U[number]>;
+/**
+ * Creates a validator that asserts that the input is one of the values of the given enum.
+ *
+ * @param enumObject The enum to validate against.
+ */
+export declare function enumOf<T extends Record<string, Primitive>>(enumObject: T): ValueSchema<T[keyof T]>;
+/**
+ * Creates a validator that asserts that the input is null.
+ */
+export declare function exactlyNull(): Validator<null>;
+/**
+ * Creates a validator that asserts that the input is nullish.
+ */
+export declare function nullish(): Validator<null | undefined>;
+/**
+ * Creates a validator that asserts that the input is a number.
+ */
+export declare function number(): NumberSchema;
+/**
+ * Creates a validator that validates the input has properties that pass their respective
+ * validators.
+ */
+export declare function object<U extends object>(propertyValidators: ExtendedPropertyValidators<AnyRecord, U>): ObjectSchema<U>;
+/**
+ * Returns a validator that asserts that the object's own enumerable properties has keys and
+ * values that match their respective validators.
+ *
+ * Prototype members are not included.
+ * Numeric keys are validated as strings. For example the object `{ [0]: 1 }` will be passed
+ * to the key validator as '0'.
+ *
+ * To assume string keys, use {@link recordValues}
+ *
+ * @param keyValidator Validates each key.
+ * @param valueValidator Validates each value.
+ */
+export declare function record<K extends string | symbol, V>(keyValidator: Validator<K>, valueValidator: Validator<V>): RecordSchema<ReadonlyRecord<K, V>>;
+/**
+ * Returns a validator that asserts that the input object's own enumerable properties has
+ * string keys and values that match the given validator.
+ *
+ * Prototype members are not included.
+ *
+ * @param valueValidator Validates each value.
+ */
+export declare function recordValues<V>(valueValidator: Validator<V>): RecordSchema<Record<string, V>>;
+/**
+ * Returns a validator that asserts the input is a set with elements that match the given
+ * element validator.
+ * @param elementValidator
+ */
+export declare function set<U>(elementValidator: Validator<U>): SetSchema<Set<U>>;
+/**
+ * Creates a validator that asserts that the input is type 'string'.
+ */
+export declare function string(): StringSchema;
+/**
+ * Creates a validator that asserts that the input array is a tuple whose elements match
+ * the given validators.
+ *
+ * @param validators
+ */
+export declare function tuple<U extends readonly any[]>(...validators: {
+    [Index in keyof U]: Validator<U[Index]>;
+}): ArraySchema<{
+    [Index in keyof U]: U[Index];
+}>;
+/**
+ * Creates a validator that asserts that the input is type 'symbol'.
+ */
+export declare function symbol(): ValueSchema<symbol>;
+/**
+ * Creates a validator that asserts that the input is strictly undefined.
+ */
+export declare function exactlyUndefined(): ValueSchema<undefined>;
+/**
+ * Returns a custom
+ * @param expectationMessage
+ * @param isValid
+ * @param inputStringify
+ */
+export declare function custom<T>(expectationMessage: string, isValid: (input: unknown) => boolean, inputStringify?: (input: unknown) => string): ValueSchema<T>;
+//# sourceMappingURL=validators.d.ts.map

package/docs/VALIDATION.md

@@ -0,0 +1,344 @@
+# Validation
+
+A TypeScript-first validation library for runtime type checking and schema
+validation.
+
+## Installation
+
+```bash
+npm install @amazon/vinyl-validation
+```
+
+## Basic Usage
+
+```typescript
+import { string, number, object, array } from '@amazon/vinyl-validation'
+
+// Create validators
+const nameValidator = string().notEmpty()
+const ageValidator = number().gte(0)
+
+// Validate values
+console.log(nameValidator.isValid('John')) // true
+console.log(ageValidator.isValid(-5)) // false
+
+// Get validation errors
+const errors = nameValidator.validate('')
+console.log(errors) // [{ message: 'Expected: not empty, but was: "". At: ', path: [] }]
+```
+
+## Core Validators
+
+### Primitive Types
+
+```typescript
+import { string, number, boolean, symbol, any } from '@amazon/vinyl-validation'
+
+const stringValidator = string()
+const numberValidator = number()
+const booleanValidator = boolean()
+const symbolValidator = symbol()
+const anyValidator = any() // accepts any value
+```
+
+### Null and Undefined
+
+```typescript
+import {
+    exactlyNull,
+    exactlyUndefined,
+    nullish,
+} from '@amazon/vinyl-validation'
+
+const nullValidator = exactlyNull() // only null
+const undefinedValidator = exactlyUndefined() // only undefined
+const nullishValidator = nullish() // null or undefined
+```
+
+### Value Matching
+
+```typescript
+import { isOneOf, instanceOf } from '@amazon/vinyl-validation'
+
+// Literal values
+const statusValidator = isOneOf('active', 'inactive', 'pending')
+
+// Instance checking
+const dateValidator = instanceOf(Date)
+const errorValidator = instanceOf(Error)
+```
+
+## String Validation
+
+```typescript
+import { string } from '@amazon/vinyl-validation'
+
+const validator = string()
+    .notEmpty() // not empty string
+    .minLength(3) // at least 3 characters
+    .maxLength(50) // at most 50 characters
+    .noWhitespace() // no whitespace characters
+    .matches(/^[a-z]+$/) // matches regex pattern
+
+// Usage
+validator.isValid('hello') // true
+validator.isValid('') // false (empty)
+validator.isValid('ab') // false (too short)
+```
+
+## Number Validation
+
+```typescript
+import { number } from '@amazon/vinyl-validation'
+
+const validator = number()
+    .gte(0) // greater than or equal to 0
+    .gt(0) // greater than 0
+    .lte(100) // less than or equal to 100
+    .lt(100) // less than 100
+    .within(1, 99) // between 1 and 99 (inclusive)
+    .safeInteger() // safe integer
+    .finite() // finite number
+
+// Usage
+validator.isValid(50) // true
+validator.isValid(-1) // false (less than 0)
+validator.isValid(Infinity) // false (not finite)
+```
+
+## Object Validation
+
+```typescript
+import { object, string, number } from '@amazon/vinyl-validation'
+
+const userValidator = object({
+    name: string().notEmpty(),
+    age: number().gte(0),
+    email: string().matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
+})
+
+// Usage
+const user = { name: 'John', age: 30, email: 'john@example.com' }
+console.log(userValidator.isValid(user)) // true
+
+// Extend existing schemas
+const adminValidator = userValidator.extend({
+    role: isOneOf('admin', 'superadmin'),
+    permissions: array(string()),
+})
+```
+
+## Array Validation
+
+```typescript
+import { array, string, number, tuple } from '@amazon/vinyl-validation'
+
+// Array of strings
+const stringArrayValidator = array(string())
+
+// Array of numbers with constraints
+const numberArrayValidator = array(number().gte(0))
+    .minLength(1) // at least 1 element
+    .maxLength(10) // at most 10 elements
+    .notEmpty() // not empty array
+
+// Tuple validation (fixed-length array with specific types)
+const coordinateValidator = tuple(number(), number()) // [x, y]
+const personValidator = tuple(string(), number(), boolean()) // [name, age, active]
+
+// Usage
+stringArrayValidator.isValid(['a', 'b', 'c']) // true
+coordinateValidator.isValid([10, 20]) // true
+coordinateValidator.isValid([10, 20, 30]) // false (wrong length)
+```
+
+## Record Validation
+
+```typescript
+import { record, recordValues, string, number } from '@amazon/vinyl-validation'
+
+// Record with string keys and number values
+const scoresValidator = recordValues(number().gte(0))
+
+// Record with specific key and value types
+const configValidator = record(
+    string().matches(/^[A-Z_]+$/), // keys must be uppercase with underscores
+    string().notEmpty() // values must be non-empty strings
+)
+
+// Usage
+scoresValidator.isValid({ alice: 95, bob: 87 }) // true
+configValidator.isValid({ API_KEY: 'secret', DB_URL: 'localhost' }) // true
+```
+
+## Set Validation
+
+```typescript
+import { set, string } from '@amazon/vinyl-validation'
+
+const tagValidator = set(string().notEmpty())
+
+// Usage
+tagValidator.isValid(new Set(['tag1', 'tag2'])) // true
+tagValidator.isValid(new Set(['tag1', ''])) // false (empty string)
+```
+
+## Function Validation
+
+```typescript
+import { func } from '@amazon/vinyl-validation'
+
+const functionValidator = func()
+    .withArity(2) // exactly 2 parameters
+    .withMinArity(1) // at least 1 parameter
+    .withMaxArity(3) // at most 3 parameters
+
+// Usage
+functionValidator.isValid((a, b) => a + b) // true
+functionValidator.isValid(() => 'hello') // false (wrong arity)
+```
+
+## Optional and Nullable Values
+
+```typescript
+import { string, number } from '@amazon/vinyl-validation'
+
+// Optional (allows undefined)
+const optionalName = string().optional()
+
+// Nullable (allows null)
+const nullableName = string().nullable()
+
+// Maybe (allows null or undefined)
+const maybeName = string().maybe()
+
+// Usage
+optionalName.isValid(undefined) // true
+nullableName.isValid(null) // true
+maybeName.isValid(null) // true
+maybeName.isValid(undefined) // true
+```
+
+## Combining Validators
+
+### OR Logic
+
+```typescript
+import { or, string, number } from '@amazon/vinyl-validation'
+
+const stringOrNumber = or(string(), number())
+
+stringOrNumber.isValid('hello') // true
+stringOrNumber.isValid(42) // true
+stringOrNumber.isValid(true) // false
+```
+
+### AND Logic
+
+```typescript
+import { and, string } from '@amazon/vinyl-validation'
+
+const shortUppercaseString = and(
+    string().maxLength(10),
+    string().matches(/^[A-Z]+$/)
+)
+
+shortUppercaseString.isValid('HELLO') // true
+shortUppercaseString.isValid('hello') // false (not uppercase)
+shortUppercaseString.isValid('VERYLONGSTRING') // false (too long)
+```
+
+## Custom Validators
+
+```typescript
+import { custom } from '@amazon/vinyl-validation'
+
+const evenNumberValidator = custom<number>(
+    'even number',
+    (input): input is number => typeof input === 'number' && input % 2 === 0
+)
+
+// With custom stringify function
+const positiveValidator = custom<number>(
+    'positive number',
+    (input): input is number => typeof input === 'number' && input > 0,
+    (input) => `number: ${input}`
+)
+
+// Usage
+evenNumberValidator.isValid(4) // true
+evenNumberValidator.isValid(3) // false
+```
+
+## Validation Options
+
+```typescript
+import { string, object } from '@amazon/vinyl-validation'
+
+const validator = object({
+    name: string().notEmpty(),
+    email: string().matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
+})
+
+// Collect all errors (default: stop at first error)
+const errors = validator.validate({ name: '', email: 'invalid' }, { all: true })
+
+console.log(errors)
+// [
+//   { message: 'Expected: not empty, but was: "". At: name', path: ['name'] },
+//   { message: 'Expected: matches /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/, but was: "invalid". At: email', path: ['email'] }
+// ]
+```
+
+## Error Handling
+
+```typescript
+import { ValidationError } from '@amazon/vinyl-util'
+import { string } from '@amazon/vinyl-validation'
+
+const validator = string().notEmpty()
+
+try {
+    validator.assert('') // throws ValidationError if invalid
+} catch (error) {
+    if (error instanceof ValidationError) {
+        console.log(error.message) // validation error details
+    }
+}
+
+// Or use validate() for non-throwing validation
+const errors = validator.validate('')
+if (errors.length > 0) {
+    console.log('Validation failed:', errors)
+}
+```
+
+## TypeScript Integration
+
+The idiomatic usage is to start with an interface and create a schema for it:
+
+```typescript
+import { object, string, number, array } from '@amazon/vinyl-validation'
+
+// Define your interface first
+interface User {
+    name: string
+    age?: number
+    tags: string[]
+}
+
+// Create a validator that matches the interface
+const userValidator = object<User>({
+    name: string(),
+    age: number().optional(),
+    tags: array(string()),
+})
+
+// Type-safe validation
+function processUser(data: unknown) {
+    if (userValidator.isValid(data)) {
+        // data is now typed as User
+        console.log(data.name) // TypeScript knows this is a string
+    }
+}
+```