feat: lazy validator

src/lib/Shapes.ts

@@ -20,6 +20,7 @@ import {
 	TupleValidator,
 	UnionValidator
 } from '../validators/imports';
+import { LazyValidator } from '../validators/LazyValidator';
 import { NativeEnumLike, NativeEnumValidator } from '../validators/NativeEnumValidator';
 import { TypedArrayValidator } from '../validators/TypedArrayValidator';
 import type { Constructor, MappedObjectValidator } from './util-types';
@@ -161,4 +162,8 @@ export class Shapes {
 	public map<T, U>(keyValidator: BaseValidator<T>, valueValidator: BaseValidator<U>) {
 		return new MapValidator(keyValidator, valueValidator);
 	}
+
+	public lazy<T extends BaseValidator<unknown>>(validator: (value: unknown) => T) {
+		return new LazyValidator(validator);
+	}
 }

src/validators/LazyValidator.ts

@@ -0,0 +1,20 @@
+import type { Result } from '../lib/Result';
+import type { IConstraint, Unwrap } from '../type-exports';
+import { BaseValidator, ValidatorError } from './imports';
+
+export class LazyValidator<T extends BaseValidator<unknown>, R = Unwrap<T>> extends BaseValidator<R> {
+	private readonly validator: (value: unknown) => T;
+
+	public constructor(validator: (value: unknown) => T, constraints: readonly IConstraint<R>[] = []) {
+		super(constraints);
+		this.validator = validator;
+	}
+
+	protected override clone(): this {
+		return Reflect.construct(this.constructor, [this.validator, this.constraints]);
+	}
+
+	protected handle(values: unknown): Result<R, ValidatorError> {
+		return this.validator(values).run(values) as Result<R, ValidatorError>;
+	}
+}

tests/validators/lazy.test.ts

@@ -0,0 +1,75 @@
+import { CombinedPropertyError, ExpectedConstraintError, MissingPropertyError, s, SchemaOf, ValidationError } from '../../src';
+import { expectError } from '../common/macros/comparators';
+
+describe('LazyValidator', () => {
+	const predicate = s.lazy((value) => {
+		if (typeof value === 'boolean') return s.boolean.true;
+		return s.string;
+	});
+
+	test.each([true, 'hello'])('GIVEN %j THEN returns the given value', (input) => {
+		expect<true | string>(predicate.parse(input)).toBe(input);
+	});
+
+	test('GIVEN an invalid value THEN throw ValidationError', () => {
+		expectError(() => predicate.parse(123), new ValidationError('s.string', 'Expected a string primitive', 123));
+	});
+});
+
+describe('NestedLazyValidator', () => {
+	const predicate = s.lazy((value) => {
+		if (typeof value === 'boolean') return s.boolean.true;
+		return s.lazy((value) => {
+			if (typeof value === 'string') return s.string.lengthEqual(5);
+			return s.number;
+		});
+	});
+
+	test.each([true, 'hello', 123])('GIVEN %j THEN returns the given value', (input) => {
+		expect<true | string | number>(predicate.parse(input)).toBe(input);
+	});
+
+	test('GIVEN an invalid value THEN throw ValidationError', () => {
+		expectError(
+			() => predicate.parse('Sapphire'),
+			new ExpectedConstraintError('s.string.lengthEqual', 'Invalid string length', 'Sapphire', 'expected.length === 5')
+		);
+	});
+});
+
+describe('CircularLazyValidator', () => {
+	interface PredicateSchema {
+		id: string;
+		items: PredicateSchema;
+	}
+
+	const predicate: SchemaOf<PredicateSchema> = s.object({
+		id: s.string,
+		items: s.lazy<SchemaOf<PredicateSchema>>(() => predicate)
+	});
+
+	test('GIVEN circular schema THEN throw ', () => {
+		expectError(
+			() => predicate.parse({ id: 'Hello', items: { id: 'Hello', items: { id: 'Hello' } } }),
+			new CombinedPropertyError([
+				['items', new CombinedPropertyError([['items', new CombinedPropertyError([['items', new MissingPropertyError('items')]])]])]
+			])
+		);
+	});
+});
+
+describe('PassingCircularLazyValidator', () => {
+	interface PredicateSchema {
+		id: string;
+		items?: PredicateSchema;
+	}
+
+	const predicate: SchemaOf<PredicateSchema> = s.object({
+		id: s.string,
+		items: s.lazy<SchemaOf<PredicateSchema>>(() => predicate).optional
+	});
+
+	test('GIVEN circular schema THEN return given value', () => {
+		expect(predicate.parse({ id: 'Sapphire', items: { id: 'Hello' } })).toStrictEqual({ id: 'Sapphire', items: { id: 'Hello' } });
+	});
+});