valrs 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,710 @@
+/**
+ * Base schema class providing the fluent API wrapper around Standard Schema.
+ *
+ * This module provides the `ValSchema` base class that all schema types extend.
+ * It wraps the internal Standard Schema implementation and exposes Zod-like methods.
+ */
+import type { StandardSchemaV1, StandardJSONSchemaV1, ValidationResult, JsonSchemaOptions, PathSegment } from './types';
+import { ValError } from './error';
+/**
+ * Context object passed to superRefine callbacks.
+ * Allows adding multiple validation issues.
+ */
+export interface RefinementContext {
+    /**
+     * Adds a validation issue.
+     */
+    addIssue(issue: {
+        code: string;
+        message: string;
+        path?: ReadonlyArray<PathSegment>;
+        fatal?: boolean;
+    }): void;
+}
+/**
+ * Options for refine method.
+ */
+export interface RefinementOptions {
+    message?: string;
+    path?: ReadonlyArray<PathSegment>;
+}
+/**
+ * Transform function type - can be sync or async.
+ */
+export type TransformFn<Input, Output> = (value: Input) => Output | Promise<Output>;
+/**
+ * Refinement predicate function type - can be sync or async.
+ */
+export type RefinePredicate<T> = (value: T) => boolean | Promise<boolean>;
+/**
+ * SuperRefine function type - can be sync or async.
+ */
+export type SuperRefineFn<T> = (value: T, ctx: RefinementContext) => void | Promise<void>;
+/**
+ * The result of a successful `safeParse()` call.
+ */
+export interface SafeParseSuccess<T> {
+    readonly success: true;
+    readonly data: T;
+    readonly error?: undefined;
+}
+/**
+ * The result of a failed `safeParse()` call.
+ */
+export interface SafeParseError {
+    readonly success: false;
+    readonly error: ValError;
+    readonly data?: undefined;
+}
+/**
+ * The result of a `safeParse()` call.
+ */
+export type SafeParseResult<T> = SafeParseSuccess<T> | SafeParseError;
+/**
+ * Type guard to check if a SafeParseResult is successful.
+ */
+export declare function isSafeParseSuccess<T>(result: SafeParseResult<T>): result is SafeParseSuccess<T>;
+/**
+ * Type guard to check if a SafeParseResult is a failure.
+ */
+export declare function isSafeParseError<T>(result: SafeParseResult<T>): result is SafeParseError;
+/**
+ * Internal validation function type.
+ */
+type ValidateFn<T> = (value: unknown) => ValidationResult<T>;
+/**
+ * Internal JSON Schema function type.
+ */
+type JsonSchemaFn = (target: string) => Record<string, unknown>;
+/**
+ * Base schema class that provides the Zod-compatible API.
+ *
+ * All schema types extend this class, inheriting methods like `parse()`,
+ * `safeParse()`, and maintaining Standard Schema compliance via `~standard`.
+ *
+ * @template Input - The expected input type
+ * @template Output - The validated output type (defaults to Input)
+ *
+ * @example
+ * ```typescript
+ * const schema = v.string();
+ *
+ * // Throws ValError on failure
+ * const value = schema.parse('hello');
+ *
+ * // Returns { success, data } or { success, error }
+ * const result = schema.safeParse('hello');
+ * if (result.success) {
+ *   console.log(result.data);
+ * }
+ * ```
+ */
+export declare class ValSchema<Input = unknown, Output = Input> implements StandardJSONSchemaV1<Input, Output> {
+    /**
+     * Standard Schema interface for interoperability.
+     *
+     * This property makes ValSchema compatible with any library that
+     * supports the Standard Schema specification.
+     */
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: 'valrs';
+        readonly validate: (value: unknown) => ValidationResult<Output>;
+        readonly jsonSchema: {
+            readonly input: (options: JsonSchemaOptions) => Record<string, unknown>;
+            readonly output: (options: JsonSchemaOptions) => Record<string, unknown>;
+        };
+    };
+    /**
+     * Compiled validator for fast boolean checks.
+     * Lazily initialized on first check() call.
+     */
+    private _compiledCheck?;
+    /**
+     * Whether this schema or any of its children contain transforms.
+     * When true, validation must go through WASM to apply transforms.
+     */
+    protected _hasTransforms: boolean;
+    /**
+     * Returns whether this schema contains transforms.
+     * Used internally to determine validation path.
+     */
+    hasTransforms(): boolean;
+    /**
+     * Creates a new ValSchema wrapping a validation function.
+     *
+     * @param validateFn - Function that validates input values
+     * @param inputJsonSchemaFn - Function that generates JSON Schema for input type
+     * @param outputJsonSchemaFn - Function that generates JSON Schema for output type
+     */
+    constructor(validateFn: ValidateFn<Output>, inputJsonSchemaFn: JsonSchemaFn, outputJsonSchemaFn?: JsonSchemaFn);
+    /**
+     * Parses the input and returns the validated value.
+     *
+     * Throws a `ValError` if validation fails.
+     *
+     * @param data - The value to validate
+     * @returns The validated value with the correct type
+     * @throws {ValError} If validation fails
+     *
+     * @example
+     * ```typescript
+     * const name = v.string().parse('Alice'); // 'Alice'
+     * const age = v.number().parse('42');     // throws ValError
+     * ```
+     */
+    parse(data: unknown): Output;
+    /**
+     * Parses the input and returns a result object.
+     *
+     * Never throws. Returns `{ success: true, data }` on success,
+     * or `{ success: false, error }` on failure.
+     *
+     * @param data - The value to validate
+     * @returns A result object indicating success or failure
+     *
+     * @example
+     * ```typescript
+     * const result = v.string().safeParse(input);
+     *
+     * if (result.success) {
+     *   console.log(result.data); // The validated string
+     * } else {
+     *   console.log(result.error.issues); // Array of validation issues
+     * }
+     * ```
+     */
+    safeParse(data: unknown): SafeParseResult<Output>;
+    /**
+     * Alias for `safeParse()` that matches Standard Schema naming.
+     */
+    validate(data: unknown): SafeParseResult<Output>;
+    /**
+     * Returns the JSON Schema for this schema's input type.
+     *
+     * @param target - The JSON Schema version (e.g., 'draft-2020-12', 'draft-07', 'openapi-3.0')
+     * @returns A JSON Schema object
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string();
+     * const jsonSchema = schema.toJsonSchema('draft-2020-12');
+     * // { type: 'string' }
+     * ```
+     */
+    toJsonSchema(target?: string): Record<string, unknown>;
+    /**
+     * Fast boolean check using JS-compiled validator.
+     *
+     * Returns true if the data passes validation, false otherwise.
+     * Does NOT apply transforms - use safeParse() for that.
+     *
+     * @param data - The value to check
+     * @returns true if valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string();
+     * schema.check('hello'); // true
+     * schema.check(42);      // false
+     * ```
+     */
+    check(data: unknown): boolean;
+    /**
+     * Checks if the schema is optional.
+     *
+     * Override in subclasses that support optionality.
+     */
+    isOptional(): boolean;
+    /**
+     * Checks if the schema is nullable.
+     *
+     * Override in subclasses that support nullability.
+     */
+    isNullable(): boolean;
+    /**
+     * Makes the schema accept undefined values.
+     *
+     * @returns A new schema that accepts T | undefined
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().optional();
+     * schema.parse(undefined); // undefined
+     * schema.parse('hello');   // 'hello'
+     * ```
+     */
+    optional(): ValOptional<this>;
+    /**
+     * Makes the schema accept null values.
+     *
+     * @returns A new schema that accepts T | null
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().nullable();
+     * schema.parse(null);    // null
+     * schema.parse('hello'); // 'hello'
+     * ```
+     */
+    nullable(): ValNullable<this>;
+    /**
+     * Makes the schema accept null or undefined values.
+     *
+     * @returns A new schema that accepts T | null | undefined
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().nullish();
+     * schema.parse(null);      // null
+     * schema.parse(undefined); // undefined
+     * schema.parse('hello');   // 'hello'
+     * ```
+     */
+    nullish(): ValNullish<this>;
+    /**
+     * Provides a default value when the input is undefined.
+     *
+     * @param defaultValue - The default value or a function that returns it
+     * @returns A new schema that uses the default when input is undefined
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().default('anonymous');
+     * schema.parse(undefined); // 'anonymous'
+     * schema.parse('hello');   // 'hello'
+     * ```
+     */
+    default(defaultValue: Output | (() => Output)): ValDefault<this, Output>;
+    /**
+     * Provides a fallback value when parsing fails.
+     *
+     * @param catchValue - The fallback value or a function that returns it
+     * @returns A new schema that uses the fallback on parse error
+     *
+     * @example
+     * ```typescript
+     * const schema = v.number().catch(0);
+     * schema.parse('not a number'); // 0
+     * schema.parse(42);             // 42
+     * ```
+     */
+    catch(catchValue: Output | (() => Output)): ValCatch<this, Output>;
+    /**
+     * Creates an array schema with this schema as the element type.
+     *
+     * This is an alternative syntax for `v.array(schema)`.
+     *
+     * @returns A new array schema
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().array();
+     * schema.parse(['a', 'b', 'c']); // ['a', 'b', 'c']
+     *
+     * type Arr = v.infer<typeof schema>; // string[]
+     * ```
+     */
+    array(): ValArray<this>;
+    /**
+     * Creates a union of this schema with another schema.
+     *
+     * @param other - The other schema to union with
+     * @returns A new union schema
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().or(v.number());
+     * schema.parse('hello'); // 'hello'
+     * schema.parse(42);      // 42
+     *
+     * type T = v.infer<typeof schema>; // string | number
+     * ```
+     */
+    or<T extends ValSchema<unknown, unknown>>(other: T): ValUnion<readonly [this, T]>;
+    /**
+     * Creates an intersection of this schema with another schema.
+     *
+     * @param other - The other schema to intersect with
+     * @returns A new intersection schema
+     *
+     * @example
+     * ```typescript
+     * const A = v.object({ a: v.string() });
+     * const B = v.object({ b: v.number() });
+     * const AB = A.and(B);
+     *
+     * type AB = v.infer<typeof AB>; // { a: string } & { b: number }
+     * ```
+     */
+    and<T extends ValSchema<unknown, unknown>>(other: T): ValIntersection<this, T>;
+    /**
+     * Transforms the output value after validation.
+     *
+     * Changes the output type of the schema.
+     *
+     * @param fn - Transform function that receives validated value
+     * @returns A new schema with transformed output type
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().transform(s => parseInt(s, 10));
+     * schema.parse('42'); // 42 (number)
+     *
+     * type Input = v.input<typeof schema>;   // string
+     * type Output = v.output<typeof schema>; // number
+     * ```
+     */
+    transform<NewOutput>(fn: TransformFn<Output, NewOutput>): ValTransformed<Input, Output, NewOutput>;
+    /**
+     * Adds a custom validation refinement.
+     *
+     * Does not change the output type.
+     *
+     * @param predicate - Function that returns true if valid, false otherwise
+     * @param messageOrOptions - Error message or options object
+     * @returns A new schema with the refinement
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().refine(
+     *   s => s.length > 0,
+     *   'Required'
+     * );
+     *
+     * const schemaWithPath = v.string().refine(
+     *   s => s.includes('@'),
+     *   { message: 'Must contain @', path: ['email'] }
+     * );
+     * ```
+     */
+    refine(predicate: RefinePredicate<Output>, messageOrOptions?: string | RefinementOptions): ValRefined<Input, Output>;
+    /**
+     * Adds advanced refinement that can add multiple issues.
+     *
+     * Provides a context object for adding validation issues.
+     *
+     * @param fn - Refinement function with context
+     * @returns A new schema with the refinement
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().superRefine((val, ctx) => {
+     *   if (val.length < 5) {
+     *     ctx.addIssue({
+     *       code: 'custom',
+     *       message: 'Too short',
+     *       path: [],
+     *     });
+     *   }
+     *   if (val.length > 100) {
+     *     ctx.addIssue({
+     *       code: 'custom',
+     *       message: 'Too long',
+     *       path: [],
+     *     });
+     *   }
+     * });
+     * ```
+     */
+    superRefine(fn: SuperRefineFn<Output>): ValSuperRefined<Input, Output>;
+    /**
+     * Pipes the output of this schema into another schema.
+     *
+     * Useful for chaining transforms with additional validation.
+     *
+     * @param schema - The schema to pipe into
+     * @returns A new schema that validates with both schemas
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string()
+     *   .transform(s => parseInt(s, 10))
+     *   .pipe(v.number().positive());
+     *
+     * schema.parse('42');  // 42
+     * schema.parse('-5');  // throws (not positive)
+     * ```
+     */
+    pipe<NextOutput>(schema: ValSchema<Output, NextOutput>): ValPiped<Input, Output, NextOutput>;
+    /**
+     * Asynchronously parses the input value.
+     *
+     * Required when using async transforms or refinements.
+     *
+     * @param data - The value to validate
+     * @returns Promise resolving to the validated value
+     * @throws {ValError} If validation fails
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().refine(async (s) => {
+     *   return await checkIfExists(s);
+     * }, 'Not found');
+     *
+     * const value = await schema.parseAsync('test');
+     * ```
+     */
+    parseAsync(data: unknown): Promise<Output>;
+    /**
+     * Asynchronously parses the input and returns a result object.
+     *
+     * Never throws. Required when using async transforms or refinements.
+     *
+     * @param data - The value to validate
+     * @returns Promise resolving to result object
+     *
+     * @example
+     * ```typescript
+     * const schema = v.string().transform(async (s) => {
+     *   return await lookupValue(s);
+     * });
+     *
+     * const result = await schema.safeParseAsync('key');
+     * if (result.success) {
+     *   console.log(result.data);
+     * }
+     * ```
+     */
+    safeParseAsync(data: unknown): Promise<SafeParseResult<Output>>;
+}
+/**
+ * Extracts the output type from a ValSchema.
+ */
+type InferOutput<T extends ValSchema<unknown, unknown>> = T extends ValSchema<unknown, infer O> ? O : never;
+/**
+ * Extracts the input type from a ValSchema.
+ */
+type InferInput<T extends ValSchema<unknown, unknown>> = T extends ValSchema<infer I, unknown> ? I : never;
+/**
+ * Validator type for arrays.
+ */
+type ArrayValidator<T> = (value: ReadonlyArray<T>) => {
+    issues: Array<{
+        message: string;
+    }>;
+} | null;
+/**
+ * Schema for array values with validation methods.
+ *
+ * Supports chainable methods like `.min()`, `.max()`, `.length()`, `.nonempty()`.
+ * Each method returns a new schema instance (immutable).
+ *
+ * @template S - The element schema type
+ *
+ * @example
+ * ```typescript
+ * const schema = v.array(v.string());
+ * schema.parse(['a', 'b', 'c']); // ['a', 'b', 'c']
+ *
+ * const nonEmpty = v.array(v.number()).nonempty();
+ * nonEmpty.parse([1, 2]); // [1, 2]
+ * nonEmpty.parse([]);     // throws
+ * ```
+ */
+export declare class ValArray<S extends ValSchema<unknown, unknown>> extends ValSchema<ReadonlyArray<InferInput<S>>, Array<InferOutput<S>>> {
+    readonly element: S;
+    private readonly validators;
+    constructor(elementSchema: S, validators?: ReadonlyArray<ArrayValidator<InferOutput<S>>>);
+    /**
+     * Creates a copy of this schema with additional validators.
+     */
+    private clone;
+    /**
+     * Requires array to have at least `length` elements.
+     */
+    min(length: number, message?: string): ValArray<S>;
+    /**
+     * Requires array to have at most `length` elements.
+     */
+    max(length: number, message?: string): ValArray<S>;
+    /**
+     * Requires array to have exactly `len` elements.
+     */
+    length(len: number, message?: string): ValArray<S>;
+    /**
+     * Requires array to be non-empty (at least 1 element).
+     */
+    nonempty(message?: string): ValArray<S>;
+}
+/**
+ * Infers union input type from an array of schemas.
+ */
+type InferUnionInput<T extends ReadonlyArray<ValSchema<unknown, unknown>>> = T[number] extends ValSchema<infer I, unknown> ? I : never;
+/**
+ * Infers union output type from an array of schemas.
+ */
+type InferUnionOutput<T extends ReadonlyArray<ValSchema<unknown, unknown>>> = T[number] extends ValSchema<unknown, infer O> ? O : never;
+/**
+ * Schema for union types (one of multiple schemas).
+ *
+ * @template T - Array of member schemas
+ *
+ * @example
+ * ```typescript
+ * const schema = v.union([v.string(), v.number()]);
+ * schema.parse('hello'); // 'hello'
+ * schema.parse(42);      // 42
+ *
+ * type U = v.infer<typeof schema>; // string | number
+ * ```
+ */
+export declare class ValUnion<T extends ReadonlyArray<ValSchema<unknown, unknown>>> extends ValSchema<InferUnionInput<T>, InferUnionOutput<T>> {
+    readonly options: T;
+    constructor(options: T);
+}
+/**
+ * Schema for intersection types (all of multiple schemas).
+ *
+ * @template L - Left schema
+ * @template R - Right schema
+ *
+ * @example
+ * ```typescript
+ * const A = v.object({ a: v.string() });
+ * const B = v.object({ b: v.number() });
+ * const AB = v.intersection(A, B);
+ *
+ * type AB = v.infer<typeof AB>; // { a: string } & { b: number }
+ * ```
+ */
+export declare class ValIntersection<L extends ValSchema<unknown, unknown>, R extends ValSchema<unknown, unknown>> extends ValSchema<InferInput<L> & InferInput<R>, InferOutput<L> & InferOutput<R>> {
+    readonly left: L;
+    readonly right: R;
+    constructor(left: L, right: R);
+}
+/**
+ * Schema wrapper that makes the inner schema optional (accepts undefined).
+ */
+export declare class ValOptional<T extends ValSchema<unknown, unknown>> extends ValSchema<InferInput<T> | undefined, InferOutput<T> | undefined> {
+    private readonly innerSchema;
+    constructor(schema: T);
+    isOptional(): boolean;
+    /**
+     * Returns the inner schema (unwrapped).
+     */
+    unwrap(): T;
+}
+/**
+ * Schema wrapper that makes the inner schema nullable (accepts null).
+ */
+export declare class ValNullable<T extends ValSchema<unknown, unknown>> extends ValSchema<InferInput<T> | null, InferOutput<T> | null> {
+    private readonly innerSchema;
+    constructor(schema: T);
+    isNullable(): boolean;
+    /**
+     * Returns the inner schema (unwrapped).
+     */
+    unwrap(): T;
+}
+/**
+ * Schema wrapper that makes the inner schema nullish (accepts null or undefined).
+ */
+export declare class ValNullish<T extends ValSchema<unknown, unknown>> extends ValSchema<InferInput<T> | null | undefined, InferOutput<T> | null | undefined> {
+    private readonly innerSchema;
+    constructor(schema: T);
+    isOptional(): boolean;
+    isNullable(): boolean;
+    /**
+     * Returns the inner schema (unwrapped).
+     */
+    unwrap(): T;
+}
+/**
+ * Schema wrapper that provides a default value when input is undefined.
+ */
+export declare class ValDefault<T extends ValSchema<unknown, unknown>, D> extends ValSchema<InferInput<T> | undefined, InferOutput<T>> {
+    private readonly innerSchema;
+    constructor(schema: T, defaultValue: D | (() => D));
+    /**
+     * Removes the default wrapper.
+     */
+    removeDefault(): T;
+}
+/**
+ * Schema wrapper that provides a catch value when parsing fails.
+ */
+export declare class ValCatch<T extends ValSchema<unknown, unknown>, C> extends ValSchema<unknown, InferOutput<T>> {
+    private readonly innerSchema;
+    constructor(schema: T, catchValue: C | (() => C));
+    /**
+     * Removes the catch wrapper.
+     */
+    removeCatch(): T;
+}
+/**
+ * Schema that applies a transform function after validation.
+ *
+ * Changes the output type of the schema.
+ *
+ * @template Input - The original input type
+ * @template Middle - The intermediate validated type
+ * @template Output - The final transformed output type
+ */
+export declare class ValTransformed<Input, Middle, Output> extends ValSchema<Input, Output> {
+    constructor(schema: ValSchema<Input, Middle>, fn: TransformFn<Middle, Output>);
+}
+/**
+ * Schema that adds a refinement predicate.
+ *
+ * Does not change the output type.
+ *
+ * @template Input - The input type
+ * @template Output - The output type
+ */
+export declare class ValRefined<Input, Output> extends ValSchema<Input, Output> {
+    constructor(schema: ValSchema<Input, Output>, predicate: RefinePredicate<Output>, options: RefinementOptions);
+}
+/**
+ * Schema that applies a superRefine function for advanced validation.
+ *
+ * Allows adding multiple issues via the context.
+ *
+ * @template Input - The input type
+ * @template Output - The output type
+ */
+export declare class ValSuperRefined<Input, Output> extends ValSchema<Input, Output> {
+    constructor(schema: ValSchema<Input, Output>, fn: SuperRefineFn<Output>);
+}
+/**
+ * Schema that pipes the output of one schema into another.
+ *
+ * Useful for chaining transforms with additional validation.
+ *
+ * @template Input - The original input type
+ * @template Middle - The intermediate validated type
+ * @template Output - The final output type from the second schema
+ */
+export declare class ValPiped<Input, Middle, Output> extends ValSchema<Input, Output> {
+    constructor(first: ValSchema<Input, Middle>, second: ValSchema<Middle, Output>);
+}
+/**
+ * Schema that preprocesses input before validation.
+ *
+ * Useful for coercing input types before validation.
+ *
+ * @template Input - The preprocessed input type
+ * @template Output - The validated output type
+ */
+export declare class ValPreprocessed<Input, Output> extends ValSchema<unknown, Output> {
+    constructor(preprocessFn: (value: unknown) => Input, schema: ValSchema<Input, Output>);
+}
+/**
+ * Creates a ValSchema from an existing Standard Schema object.
+ *
+ * Useful for wrapping schemas created with the factory functions.
+ *
+ * @param standardSchema - A Standard Schema compliant object
+ * @returns A ValSchema instance
+ */
+export declare function fromStandardSchema<Input, Output>(standardSchema: StandardJSONSchemaV1<Input, Output>): ValSchema<Input, Output>;
+/**
+ * Creates a ValSchema from a simple Standard Schema (without JSON Schema support).
+ *
+ * @param standardSchema - A Standard Schema compliant object
+ * @param jsonSchemaFn - Function to generate JSON Schema
+ * @returns A ValSchema instance
+ */
+export declare function fromSimpleStandardSchema<T>(standardSchema: StandardSchemaV1<T, T>, jsonSchemaFn: JsonSchemaFn): ValSchema<T, T>;
+export {};
+//# sourceMappingURL=schema.d.ts.map