@orkestrel/validator 0.0.1

package/dist/guards.d.ts

@@ -0,0 +1,297 @@
+import type { AnyConstructor, Guard, GuardType, GuardsShape, IntersectionFromGuards, ShapeGuardResult, TupleFromGuards } from './types.js';
+/**
+ * Build an array guard from an element guard or predicate.
+ *
+ * @param elementGuard - Guard or predicate for each array element.
+ * @returns A guard for arrays whose values all satisfy the provided guard.
+ * @example
+ * ```ts
+ * const isStrings = arrayOf(isString)
+ * ```
+ */
+export declare function arrayOf<T>(elementGuard: Guard<T>): Guard<readonly T[]>;
+export declare function arrayOf(elementGuard: (value: unknown) => boolean): Guard<readonly unknown[]>;
+/**
+ * Build a fixed-length tuple guard from per-index guards.
+ *
+ * @param guards - Guards applied by tuple index.
+ * @returns A guard for a tuple that matches the provided index guards.
+ * @example
+ * ```ts
+ * const isPair = tupleOf(isString, isNumber)
+ * ```
+ */
+export declare function tupleOf<const Gs extends Array<Guard<unknown>>>(...guards: Gs): Guard<TupleFromGuards<Gs>>;
+export declare function tupleOf(...guards: Array<(value: unknown) => boolean>): Guard<readonly unknown[]>;
+/**
+ * Build an exact object guard from a guard shape.
+ *
+ * @param shape - Guards per property.
+ * @param optional - Optional keys, or `true` to make every key optional.
+ * @returns A guard for an exact object matching the provided shape.
+ * @example
+ * ```ts
+ * const isUser = objectOf({ id: isString, age: isNumber })
+ * ```
+ */
+export declare function objectOf<S extends GuardsShape>(shape: S): Guard<ShapeGuardResult<S, undefined>>;
+export declare function objectOf<S extends GuardsShape, const K extends Array<keyof S & string>>(shape: S, optional: K): Guard<ShapeGuardResult<S, K>>;
+export declare function objectOf<S extends GuardsShape>(shape: S, optional: true): Guard<ShapeGuardResult<S, true>>;
+/**
+ * Create a guard that accepts one of the provided literal values.
+ *
+ * @param literals - Literal values to accept.
+ * @returns A guard for the provided literal union.
+ * @example
+ * ```ts
+ * const isRole = literalOf('user', 'admin')
+ * ```
+ */
+export declare function literalOf<const Literals extends Array<string | number | boolean>>(...literals: Literals): Guard<Literals[number]>;
+/**
+ * Create a guard using `instanceof`.
+ *
+ * @param constructor - Constructor used for the `instanceof` check.
+ * @returns A guard that narrows to instances of the provided constructor.
+ * @example
+ * ```ts
+ * const isDateInstance = instanceOf(Date)
+ * ```
+ */
+export declare function instanceOf<C extends AnyConstructor>(constructor: C): Guard<InstanceType<C>>;
+/**
+ * Create a guard from an enum-like object.
+ *
+ * @param enumeration - Enum object or enum-like map.
+ * @returns A guard that accepts enum values.
+ * @example
+ * ```ts
+ * const isStatus = enumOf({ ok: 'OK', fail: 'FAIL' })
+ * ```
+ */
+export declare function enumOf<E extends Record<string, string | number>>(enumeration: E): Guard<E[keyof E]>;
+/**
+ * Build a Set guard from an element guard or predicate.
+ *
+ * @param elementGuard - Guard or predicate for each set element.
+ * @returns A guard for sets whose elements all satisfy the provided guard.
+ * @example
+ * ```ts
+ * const isNumberSet = setOf(isNumber)
+ * ```
+ */
+export declare function setOf<T>(elementGuard: Guard<T>): Guard<ReadonlySet<T>>;
+export declare function setOf(elementGuard: (value: unknown) => boolean): Guard<ReadonlySet<unknown>>;
+/**
+ * Build a Map guard from key and value guards.
+ *
+ * @param keyGuard - Guard or predicate for each key.
+ * @param valueGuard - Guard or predicate for each value.
+ * @returns A guard for maps whose keys and values satisfy the provided guards.
+ * @example
+ * ```ts
+ * const isScores = mapOf(isString, isNumber)
+ * ```
+ */
+export declare function mapOf<K, V>(keyGuard: Guard<K>, valueGuard: Guard<V>): Guard<ReadonlyMap<K, V>>;
+export declare function mapOf(keyGuard: (value: unknown) => boolean, valueGuard: (value: unknown) => boolean): Guard<ReadonlyMap<unknown, unknown>>;
+/**
+ * Build an exact record guard from a guard shape.
+ *
+ * @param shape - Guards per property.
+ * @param optional - Optional keys, or `true` to make every key optional.
+ * @returns A guard for an exact record matching the provided shape.
+ * @example
+ * ```ts
+ * const isUser = recordOf({ id: isString, age: isNumber })
+ * ```
+ */
+export declare function recordOf<S extends GuardsShape>(shape: S): Guard<ShapeGuardResult<S, undefined>>;
+export declare function recordOf<S extends GuardsShape, const K extends Array<keyof S & string>>(shape: S, optional: K): Guard<ShapeGuardResult<S, K>>;
+export declare function recordOf<S extends GuardsShape>(shape: S, optional: true): Guard<ShapeGuardResult<S, true>>;
+/**
+ * Build an iterable guard from an element guard or predicate.
+ *
+ * @param elementGuard - Guard or predicate applied to each iterated value.
+ * @returns A guard for iterables whose yielded values satisfy the provided guard.
+ * @example
+ * ```ts
+ * const isNumbers = iterableOf(isNumber)
+ * ```
+ */
+export declare function iterableOf<T>(elementGuard: Guard<T>): Guard<Iterable<T>>;
+export declare function iterableOf(elementGuard: (value: unknown) => boolean): Guard<Iterable<unknown>>;
+/**
+ * Create a guard for keys of the provided object.
+ *
+ * @param value - Object whose keys form the allowed key set.
+ * @returns A guard that accepts keys present on the provided object.
+ * @example
+ * ```ts
+ * const isKey = keyOf({ id: 1, name: 2 })
+ * ```
+ */
+export declare function keyOf<const O extends Readonly<Record<PropertyKey, unknown>>>(value: O): Guard<keyof O>;
+/**
+ * Build a new guard shape by picking specific keys.
+ *
+ * @param shape - Source shape.
+ * @param keys - Keys to keep.
+ * @returns A new shape containing only the selected keys.
+ * @example
+ * ```ts
+ * const picked = pickOf({ id: isString, age: isNumber }, ['id'])
+ * ```
+ */
+export declare function pickOf<S extends GuardsShape, const K extends Array<keyof S & string>>(shape: S, keys: K): Pick<S, K[number]>;
+/**
+ * Build a new guard shape by omitting specific keys.
+ *
+ * @param shape - Source shape.
+ * @param keys - Keys to remove.
+ * @returns A new shape without the omitted keys.
+ * @example
+ * ```ts
+ * const omitted = omitOf({ id: isString, age: isNumber }, ['age'])
+ * ```
+ */
+export declare function omitOf<S extends GuardsShape, const K extends Array<keyof S & string>>(shape: S, keys: K): Omit<S, K[number]>;
+/**
+ * Combine two guards or predicates with logical AND.
+ *
+ * @param left - First guard or predicate.
+ * @param right - Second guard or predicate.
+ * @returns A guard that requires both inputs to pass.
+ * @example
+ * ```ts
+ * const isNonEmptyString = andOf(isString, (value: string) => value.length > 0)
+ * ```
+ */
+export declare function andOf<A, B>(left: Guard<A>, right: Guard<B>): Guard<A & B>;
+export declare function andOf<T, U extends T>(left: Guard<T>, right: (value: T) => value is U): Guard<U>;
+export declare function andOf<T>(left: Guard<T>, right: (value: T) => boolean): Guard<T>;
+export declare function andOf(left: (value: unknown) => boolean, right: (value: unknown) => boolean): Guard<unknown>;
+/**
+ * Combine two guards or predicates with logical OR.
+ *
+ * @param left - First guard or predicate.
+ * @param right - Second guard or predicate.
+ * @returns A guard that accepts values from either side.
+ * @example
+ * ```ts
+ * const isLetter = orOf(literalOf('a'), literalOf('b'))
+ * ```
+ */
+export declare function orOf<A, B>(left: Guard<A>, right: Guard<B>): Guard<A | B>;
+export declare function orOf(left: (value: unknown) => boolean, right: (value: unknown) => boolean): Guard<unknown>;
+/**
+ * Negate a guard or predicate.
+ *
+ * @param guard - Guard or predicate to negate.
+ * @returns A guard that passes when the provided guard fails.
+ * @example
+ * ```ts
+ * const isNotString = notOf(isString)
+ * ```
+ */
+export declare function notOf(guard: (value: unknown) => boolean): Guard<unknown>;
+/**
+ * Exclude a narrower guard from a broader one.
+ *
+ * @param base - Base guard describing the larger set.
+ * @param excluded - Guard describing the subset to exclude.
+ * @returns A guard that accepts the base type minus the excluded subset.
+ * @example
+ * ```ts
+ * const isNonEmpty = complementOf(isString, (value: string): value is '' => value === '')
+ * ```
+ */
+export declare function complementOf<TBase, TExcluded extends TBase>(base: Guard<TBase>, excluded: Guard<TExcluded> | ((value: TBase) => value is TExcluded)): Guard<Exclude<TBase, TExcluded>>;
+/**
+ * Create a union guard from multiple guards or predicates.
+ *
+ * @param guards - Guards or predicates to union.
+ * @returns A guard that accepts any value matching one of the inputs.
+ * @example
+ * ```ts
+ * const isRole = unionOf(literalOf('user'), literalOf('admin'))
+ * ```
+ */
+export declare function unionOf<const Gs extends Array<Guard<unknown>>>(...guards: Gs): Guard<GuardType<Gs[number]>>;
+export declare function unionOf(...guards: Array<(value: unknown) => boolean>): Guard<unknown>;
+/**
+ * Create an intersection guard from multiple guards or predicates.
+ *
+ * @param guards - Guards or predicates to intersect.
+ * @returns A guard that requires every input guard to pass.
+ * @example
+ * ```ts
+ * const isShortString = intersectionOf(isString, (value): value is string => isString(value) && value.length < 5)
+ * ```
+ */
+export declare function intersectionOf<const Gs extends Array<Guard<unknown>>>(...guards: Gs): Guard<IntersectionFromGuards<Gs>>;
+export declare function intersectionOf(...guards: Array<(value: unknown) => boolean>): Guard<unknown>;
+/**
+ * Compose multiple guards through logical AND.
+ *
+ * @param guards - Guards or predicates to compose.
+ * @returns A guard that passes only when every input guard passes.
+ * @example
+ * ```ts
+ * const isAlphaTwo = composedOf(
+ *     (value): value is string => isString(value) && /^[A-Za-z]+$/.test(value),
+ *     (value): value is string => isString(value) && value.length === 2,
+ * )
+ * ```
+ */
+export declare function composedOf<const Gs extends Array<Guard<unknown>>>(...guards: Gs): Guard<IntersectionFromGuards<Gs>>;
+export declare function composedOf(...guards: Array<(value: unknown) => boolean>): Guard<unknown>;
+/**
+ * Refine a base guard with an additional predicate.
+ *
+ * @param base - Base guard checked first.
+ * @param predicate - Predicate evaluated after the base guard succeeds.
+ * @returns A guard preserving the base type while enforcing the predicate.
+ * @example
+ * ```ts
+ * const isNonEmptyString = whereOf(isString, (value) => value.length > 0)
+ * ```
+ */
+export declare function whereOf<T>(base: Guard<T>, predicate: (value: T) => boolean): Guard<T>;
+export declare function whereOf<T, U extends T>(base: Guard<T>, predicate: (value: T) => value is U): Guard<U>;
+/**
+ * Defer guard creation until runtime.
+ *
+ * @param thunk - Function that returns the real guard.
+ * @returns A lazily resolved guard.
+ * @example
+ * ```ts
+ * const isTree = lazyOf(() => objectOf({ value: isNumber }))
+ * ```
+ */
+export declare function lazyOf<T>(thunk: () => Guard<T>): Guard<T>;
+/**
+ * Validate a projected value after a base guard passes.
+ *
+ * @param base - Base guard checked first.
+ * @param project - Projection applied after the base guard succeeds.
+ * @param target - Guard or predicate evaluated against the projected value.
+ * @returns A guard that validates the original input through the projected value.
+ * @example
+ * ```ts
+ * const hasLength = transformOf(isString, (value) => value.length, (value): value is number => typeof value === 'number' && value > 0)
+ * ```
+ */
+export declare function transformOf<T, U>(base: Guard<T>, project: (value: T) => U, target: Guard<U>): Guard<T>;
+export declare function transformOf<T>(base: Guard<T>, project: (value: T) => unknown, target: (value: unknown) => boolean): Guard<T>;
+/**
+ * Extend a guard to also allow `null`.
+ *
+ * @param guard - Base guard.
+ * @returns A guard that accepts `null` or values passing the base guard.
+ * @example
+ * ```ts
+ * const isNullableString = nullableOf(isString)
+ * ```
+ */
+export declare function nullableOf<T>(guard: Guard<T>): Guard<T | null>;

package/dist/helpers.d.ts

@@ -0,0 +1,223 @@
+import type { GuardsShape, ValidationError, ValidationResult, ValidationRuleName, ValidationRuleValue, ValidationRules, ValidatorFunction } from './types.js';
+/**
+ * Read a property value from a record-like object.
+ *
+ * @param record - Object to read from.
+ * @param key - Property key to resolve.
+ * @returns The resolved property value.
+ * @example
+ * ```ts
+ * recordValue({ id: 'u1' }, 'id')
+ * ```
+ */
+export declare function recordValue(record: object, key: PropertyKey): unknown;
+/**
+ * Resolve a named validation rule from a rule object.
+ *
+ * @param rules - Rule object to read from.
+ * @param ruleName - Rule name to resolve.
+ * @returns The configured rule value, or `undefined` when not configured.
+ * @example
+ * ```ts
+ * ruleValue({ required: true }, 'required')
+ * ```
+ */
+export declare function ruleValue(rules: ValidationRules, ruleName: ValidationRuleName): ValidationRuleValue | undefined;
+/**
+ * Check whether a validation rule value is a boolean rule configuration.
+ *
+ * @param value - Value to test.
+ * @returns `true` when the value is `undefined`, a boolean, or a validator function.
+ * @example
+ * ```ts
+ * isBooleanRuleValue(true)
+ * ```
+ */
+export declare function isBooleanRuleValue(value: unknown): boolean;
+/**
+ * Check whether a validation rule value is a number rule configuration.
+ *
+ * @param value - Value to test.
+ * @returns `true` when the value is `undefined`, a non-negative integer, or a validator function.
+ * @example
+ * ```ts
+ * isNumberRuleValue(3)
+ * ```
+ */
+export declare function isNumberRuleValue(value: unknown): boolean;
+/**
+ * Check whether a validation rule value is a pattern rule configuration.
+ *
+ * @param value - Value to test.
+ * @returns `true` when the value is `undefined`, a string pattern, or a validator function.
+ * @example
+ * ```ts
+ * isPatternRuleValue('^a+$')
+ * ```
+ */
+export declare function isPatternRuleValue(value: unknown): boolean;
+/**
+ * Check whether a value is valid for a specific validation rule.
+ *
+ * @param ruleName - Rule name controlling the accepted value kind.
+ * @param value - Value to test.
+ * @returns `true` when the value is valid for the given rule name.
+ * @example
+ * ```ts
+ * isRuleValue('minimum', 3)
+ * ```
+ */
+export declare function isRuleValue(ruleName: ValidationRuleName, value: unknown): boolean;
+/**
+ * Count enumerable symbol keys on an object.
+ *
+ * @param value - Object to inspect.
+ * @returns The number of enumerable symbol properties.
+ * @example
+ * ```ts
+ * enumerableSymbolCount({ [Symbol('x')]: true })
+ * ```
+ */
+export declare function enumerableSymbolCount(value: object): number;
+/**
+ * Assert that a partial shape result matches a picked guard shape.
+ *
+ * @param value - Value to refine.
+ * @param shape - Source shape.
+ * @param keys - Picked keys.
+ * @returns Nothing. Refines `value` for the caller.
+ * @example
+ * ```ts
+ * const value: unknown = {}
+ * ensurePickedShape(value, { id: isString }, ['id'])
+ * ```
+ */
+export declare function ensurePickedShape<S extends GuardsShape, K extends Array<keyof S & string>>(value: unknown, shape: S, keys: K): asserts value is Pick<S, K[number]>;
+/**
+ * Assert that a partial shape result matches an omitted guard shape.
+ *
+ * @param value - Value to refine.
+ * @param shape - Source shape.
+ * @param keys - Omitted keys.
+ * @returns Nothing. Refines `value` for the caller.
+ * @example
+ * ```ts
+ * const value: unknown = {}
+ * ensureOmittedShape(value, { id: isString }, [])
+ * ```
+ */
+export declare function ensureOmittedShape<S extends GuardsShape, K extends Array<keyof S & string>>(value: unknown, shape: S, keys: K): asserts value is Omit<S, K[number]>;
+/**
+ * Narrow an unknown value to a validator callback.
+ *
+ * @param value - Value to test.
+ * @returns `true` when the value is a validator callback.
+ * @example
+ * ```ts
+ * isValidatorFunction((input) => input.length > 0)
+ * ```
+ */
+export declare function isValidatorFunction(value: unknown): value is ValidatorFunction;
+/**
+ * Narrow an unknown value to `ValidationRuleName`.
+ *
+ * @param value - Value to test.
+ * @returns `true` when the value is a supported rule name.
+ * @example
+ * ```ts
+ * isValidationRuleName('required')
+ * ```
+ */
+export declare function isValidationRuleName(value: unknown): value is ValidationRuleName;
+/**
+ * Narrow an unknown value to `ValidationRules`.
+ *
+ * @param value - Value to test.
+ * @returns `true` when the value is a valid validation rule object.
+ * @example
+ * ```ts
+ * isValidationRules({ required: true, minimum: 3 })
+ * ```
+ */
+export declare function isValidationRules(value: unknown): value is ValidationRules;
+/**
+ * Narrow an unknown value to `ValidationError`.
+ *
+ * @param value - Value to test.
+ * @returns `true` when the value is a validation error object.
+ * @example
+ * ```ts
+ * isValidationError({ rule: 'required', message: 'Missing' })
+ * ```
+ */
+export declare function isValidationError(value: unknown): value is ValidationError;
+/**
+ * Narrow an unknown value to `ValidationResult`.
+ *
+ * @param value - Value to test.
+ * @returns `true` when the value is a validation result object.
+ * @example
+ * ```ts
+ * isValidationResult({ valid: true, errors: [] })
+ * ```
+ */
+export declare function isValidationResult(value: unknown): value is ValidationResult;
+/**
+ * Assert that a validation rule object is well-formed.
+ *
+ * @param rules - Rules to validate.
+ * @returns Nothing. Throws when the rules are invalid.
+ * @example
+ * ```ts
+ * assertValidationRules({ required: true })
+ * ```
+ */
+export declare function assertValidationRules(rules: unknown): asserts rules is ValidationRules;
+/**
+ * Clone a validation rule object.
+ *
+ * @param rules - Rules to clone.
+ * @returns A shallow cloned rule object.
+ * @example
+ * ```ts
+ * const rules = cloneValidationRules({ required: true })
+ * ```
+ */
+export declare function cloneValidationRules(rules: ValidationRules): ValidationRules;
+/**
+ * Evaluate a single validation rule against input.
+ *
+ * @param ruleName - Rule being evaluated.
+ * @param check - Rule value to evaluate.
+ * @param input - Input value to validate.
+ * @returns An error message when the rule fails, otherwise `undefined`.
+ * @example
+ * ```ts
+ * evaluateRule('required', true, '')
+ * ```
+ */
+export declare function evaluateRule(ruleName: ValidationRuleName, check: ValidationRuleValue, input: string): string | undefined;
+/**
+ * Validate input against all configured validation rules.
+ *
+ * @param input - Input string to validate.
+ * @param rules - Rules to evaluate.
+ * @returns A structured validation result.
+ * @example
+ * ```ts
+ * validateInput('', { required: true })
+ * ```
+ */
+export declare function validateInput(input: string, rules: ValidationRules): ValidationResult;
+/**
+ * Test whether input passes all configured validation rules.
+ *
+ * @param input - Input string to validate.
+ * @param rules - Rules to evaluate.
+ * @returns `true` when the input is valid.
+ * @example
+ * ```ts
+ * testInput('value', { required: true })
+ * ```
+ */
+export declare function testInput(input: string, rules: ValidationRules): boolean;