@oxog/vld 2.1.0 → 2.2.7

package/dist/validators/base.d.ts

@@ -1,14 +1,29 @@
 import type { SchemaRegistry } from '../registry.js';
+import { VldError } from '../errors-core.js';
 /**
  * Base result type for validation
  */
 export type ParseResult<T> = {
     readonly success: true;
     readonly data: T;
+    readonly error?: undefined;
 } | {
     readonly success: false;
-    readonly error: Error;
+    readonly error: VldError;
+    readonly data?: undefined;
 };
+export type SafeParseSuccess<T> = {
+    readonly success: true;
+    readonly data: T;
+    readonly error?: undefined;
+};
+export type SafeParseError<_T = unknown> = {
+    readonly success: false;
+    readonly error: VldError;
+    readonly data?: undefined;
+};
+export type SafeParseReturnType<_Input, Output> = SafeParseSuccess<Output> | SafeParseError<_Input>;
+export declare function ensureVldError(error: unknown): VldError;
 export interface StandardTypedV1<Input = unknown, Output = Input> {
     readonly '~standard': StandardTypedV1Props<Input, Output>;
 }
@@ -112,25 +127,59 @@ export declare const VLD_VALIDATOR_TYPES: {
 };
 export type ValidatorType = typeof VLD_VALIDATOR_TYPES[keyof typeof VLD_VALIDATOR_TYPES];
 /**
- * Context for superRefine - allows adding multiple issues
+ * Context for superRefine - allows adding multiple issues with path and code
  */
 export interface SuperRefineContext {
     addIssue(issue: {
         message: string;
         code?: string;
+        path?: (string | number)[];
+        fatal?: boolean;
+        [key: string]: any;
     }): void;
     path: (string | number)[];
 }
+export interface CheckPayload<T> {
+    value: T;
+    issues: Array<{
+        message?: string;
+        code?: string;
+        path?: (string | number)[];
+    }>;
+    aborted?: boolean;
+}
+export type VldCheck<T> = ((payload: CheckPayload<T>) => void | Promise<void>) | {
+    _zod?: {
+        check?: (payload: CheckPayload<T>) => void | Promise<void>;
+    };
+};
+export type CustomErrorParams = {
+    message?: string;
+    path?: (string | number)[];
+    params?: {
+        [k: string]: any;
+    };
+    fatal?: boolean;
+};
 export type ErrorMap = (issue: {
     code?: string;
     input?: unknown;
     path?: (string | number)[];
 }) => string | undefined;
-export type ErrorParam = string | {
+export type ErrorParam = string | CustomErrorParams | ((value: any) => CustomErrorParams | string) | {
     error?: string | ErrorMap;
     message?: string;
 };
 export declare function resolveErrorMessage(error: ErrorParam | undefined, fallback: string): string;
+export declare function isPromiseLike<T = unknown>(value: unknown): value is PromiseLike<T>;
+type ValueOrFactory<T> = T | (() => T);
+interface SchemaCompositionFactories {
+    array<TInput, TOutput>(schema: VldBase<TInput, TOutput>): VldBase<unknown[], TOutput[]>;
+    union<TInput, TOutput, TNext>(left: VldBase<TInput, TOutput>, right: VldBase<any, TNext>): VldBase<unknown, TOutput | TNext>;
+    intersection<TInput, TOutput, TNext>(left: VldBase<TInput, TOutput>, right: VldBase<any, TNext>): VldBase<unknown, TOutput & TNext>;
+    toJSONSchema(schema: VldBase<any, any>, options?: unknown): unknown;
+}
+export declare function configureSchemaCompositionFactories(factories: SchemaCompositionFactories): void;
 /**
  * Abstract base class for all validators
  * Implements immutable pattern to prevent memory leaks and race conditions
@@ -146,6 +195,10 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @param validatorType The runtime type identifier
      */
     constructor(validatorType?: ValidatorType);
+    get type(): string;
+    get _def(): any;
+    get def(): any;
+    get _zod(): any;
     get '~standard'(): StandardSchemaV1Props<unknown, TOutput>;
     /**
      * Parse and validate a value, throwing an error if invalid
@@ -162,6 +215,26 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
     abstract safeParse(value: unknown): ParseResult<TOutput>;
     parseAsync(value: unknown): Promise<TOutput>;
     safeParseAsync(value: unknown): Promise<ParseResult<TOutput>>;
+    /** Strongly typed forward parse aliases from the Zod 4 codec API. */
+    decode(value: TInput): TOutput;
+    safeDecode(value: TInput): ParseResult<TOutput>;
+    decodeAsync(value: TInput): Promise<TOutput>;
+    safeDecodeAsync(value: TInput): Promise<ParseResult<TOutput>>;
+    /**
+     * Backward parse aliases. Primitive and validation-only schemas are
+     * bidirectional; codecs override these methods with their inverse transform.
+     */
+    encode(value: TOutput): TInput;
+    safeEncode(value: TOutput): ParseResult<TInput>;
+    encodeAsync(value: TOutput): Promise<TInput>;
+    safeEncodeAsync(value: TOutput): Promise<ParseResult<TInput>>;
+    /** Zod's short alias for safeParseAsync. */
+    spa(value: unknown): Promise<ParseResult<TOutput>>;
+    /** Compatibility helpers retained by Zod 4. */
+    isOptional(): boolean;
+    isNullable(): boolean;
+    /** VLD validators are immutable, so cloning can safely share the instance. */
+    clone(): this;
     /**
      * Check if a value is valid according to this validator
      * @param value The value to check
@@ -182,8 +255,8 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @param message Optional custom error message
      * @returns A new refined validator
      */
-    refine<TRefined extends TOutput>(predicate: (value: TOutput) => value is TRefined, message?: string): VldRefine<TInput, TOutput, TRefined>;
-    refine(predicate: (value: TOutput) => boolean | Promise<boolean>, message?: string): VldRefine<TInput, TOutput, TOutput>;
+    refine<TRefined extends TOutput>(predicate: (value: TOutput) => value is TRefined, message?: ErrorParam | CustomErrorParams | ((val: TOutput) => CustomErrorParams | string)): VldRefine<TInput, TOutput, TRefined>;
+    refine(predicate: (value: TOutput) => boolean | Promise<boolean>, message?: ErrorParam | CustomErrorParams | ((val: TOutput) => CustomErrorParams | string)): VldRefine<TInput, TOutput, TOutput>;
     /**
      * Advanced refinement with context for adding multiple issues
      * @param refinement The refinement function with context
@@ -201,7 +274,16 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @param defaultValue The default value
      * @returns A new validator with default
      */
-    default(defaultValue: TOutput): VldDefault<TInput, TOutput>;
+    default(defaultValue: ValueOrFactory<TOutput>): VldDefault<TInput, TOutput>;
+    /** Provide an input value before parsing when the input is undefined. */
+    prefault(defaultValue: ValueOrFactory<TInput>): VldPrefault<TInput, TOutput>;
+    nonoptional(message?: ErrorParam): VldRefine<TInput, TOutput, TOutput>;
+    array(): VldBase<unknown[], TOutput[]>;
+    or<TNext>(option: VldBase<any, TNext>): VldBase<unknown, TOutput | TNext>;
+    and<TNext>(incoming: VldBase<any, TNext>): VldBase<unknown, TOutput & TNext>;
+    overwrite(transformer: (value: TOutput) => TOutput): VldTransform<TInput, TOutput, TOutput>;
+    with(...checks: VldCheck<TOutput>[]): VldSuperRefine<TInput, TOutput>;
+    toJSONSchema(options?: unknown): unknown;
     /**
      * Create a new validator that catches errors and returns a fallback
      * @param fallbackValue The fallback value
@@ -236,7 +318,7 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @param next The next validator to pipe into
      * @returns A new piped validator
      */
-    pipe<TNextOutput>(next: VldBase<TOutput, TNextOutput>): VldPipe<TInput, TOutput, TNextOutput>;
+    pipe<TNextOutput>(next: VldBase<any, TNextOutput>): VldPipe<TInput, TOutput, TNextOutput>;
     /**
      * Create a new validator that returns readonly output
      * Zod 4 API parity - marks output as readonly for TypeScript
@@ -266,7 +348,7 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * const withLength = (schema: VldBase<unknown, string>) => schema.transform(s => s.length);
      * const lengthSchema = v.string().apply(withLength); // validates string, returns number
      */
-    apply<TNewOutput>(fn: (schema: this) => VldBase<TInput, TNewOutput>): VldBase<TInput, TNewOutput>;
+    apply<TResult>(fn: (schema: this) => TResult): TResult;
     /**
      * Create a new validator that refines this one with a custom predicate
      * Alias for refine() - check() is the Zod 4 API name
@@ -274,8 +356,8 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @param message Optional custom error message
      * @returns A new refined validator
      */
-    check<TRefined extends TOutput>(predicate: (value: TOutput) => value is TRefined, message?: string): VldRefine<TInput, TOutput, TRefined>;
-    check(predicate: (value: TOutput) => boolean | Promise<boolean>, message?: string): VldRefine<TInput, TOutput, TOutput>;
+    check<TRefined extends TOutput>(predicate: (value: TOutput) => value is TRefined, message?: ErrorParam | CustomErrorParams | ((val: TOutput) => CustomErrorParams | string)): VldRefine<TInput, TOutput, TRefined>;
+    check(predicate: (value: TOutput) => boolean | Promise<boolean>, message?: ErrorParam | CustomErrorParams | ((val: TOutput) => CustomErrorParams | string)): VldRefine<TInput, TOutput, TOutput>;
     /**
      * Get metadata for this schema
      * Zod 4 API parity - allows attaching OpenAPI/JSON Schema metadata
@@ -289,6 +371,11 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @returns A new validator with the metadata
      */
     meta(data: Partial<SchemaMetadata>): VldMeta<TInput, TOutput>;
+    /**
+     * Get or set metadata for this schema
+     */
+    meta(): SchemaMetadata | undefined;
+    meta(data: Partial<SchemaMetadata>): VldMeta<TInput, TOutput>;
     /**
      * Register this schema in a metadata registry and return the same instance.
      * This mirrors Zod 4's registry convenience API without changing validator
@@ -302,6 +389,7 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @returns A new validator with the description
      */
     describe(description: string): VldMeta<TInput, TOutput>;
+    get description(): string | undefined;
 }
 /**
  * Schema metadata interface for OpenAPI/JSON Schema compatibility
@@ -365,11 +453,63 @@ export declare class VldBrand<TInput, TOutput, TBrand extends string> extends Vl
 export declare class VldRefine<TInput, TBase, TOutput extends TBase = TBase> extends VldBase<TInput, TOutput> {
     private readonly baseValidator;
     private readonly predicate;
-    private readonly customMessage?;
-    constructor(baseValidator: VldBase<TInput, TBase>, predicate: (value: TBase) => boolean | Promise<boolean>, customMessage?: string | undefined);
+    private readonly customMessage;
+    private readonly refinePath?;
+    constructor(baseValidator: VldBase<TInput, TBase>, predicate: (value: TBase) => boolean | Promise<boolean>, customMessage?: ErrorParam | CustomErrorParams | ((val: TBase) => CustomErrorParams | string));
+    private _createIssue;
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
     parseAsync(value: unknown): Promise<TOutput>;
+    safeParseAsync(value: unknown): Promise<ParseResult<TOutput>>;
+    private _wrap;
+    min(length: number | Date | bigint | any, message?: ErrorParam): this;
+    max(length: number | Date | bigint | any, message?: ErrorParam): this;
+    length(length: number, message?: ErrorParam): this;
+    email(message?: ErrorParam): this;
+    url(message?: ErrorParam): this;
+    uuid(message?: ErrorParam): this;
+    regex(pattern: RegExp, message?: ErrorParam): this;
+    startsWith(str: string, message?: ErrorParam): this;
+    endsWith(str: string, message?: ErrorParam): this;
+    includes(str: string, message?: ErrorParam): this;
+    ip(message?: ErrorParam): this;
+    ipv4(message?: ErrorParam): this;
+    ipv6(message?: ErrorParam): this;
+    nonempty(message?: ErrorParam): this;
+    trim(): this;
+    toLowerCase(): this;
+    lowercase(): this;
+    toUpperCase(): this;
+    uppercase(): this;
+    positive(message?: ErrorParam): this;
+    negative(message?: ErrorParam): this;
+    nonnegative(message?: ErrorParam): this;
+    nonpositive(message?: ErrorParam): this;
+    int(message?: ErrorParam): this;
+    finite(message?: ErrorParam): this;
+    safe(message?: ErrorParam): this;
+    multipleOf(value: number, message?: ErrorParam): this;
+    step(value: number, message?: ErrorParam): this;
+    gt(value: any, message?: ErrorParam): this;
+    gte(value: any, message?: ErrorParam): this;
+    lt(value: any, message?: ErrorParam): this;
+    lte(value: any, message?: ErrorParam): this;
+    extend<U extends Record<string, any>>(extension: {
+        [K in keyof U]: VldBase<unknown, U[K]>;
+    }): any;
+    merge(other: any): any;
+    pick<K extends keyof TOutput>(...keys: K[]): any;
+    omit<K extends keyof TOutput>(...keys: K[]): any;
+    partial(): any;
+    required(): any;
+    strict(message?: ErrorParam): this;
+    passthrough(): this;
+    strip(): this;
+    catchall(validator: any): this;
+    get shape(): any;
+    get keyof(): any;
+    unwrap(): any;
+    get element(): any;
 }
 /**
  * Transform validator - transforms data after validation
@@ -390,14 +530,16 @@ export declare class VldTransform<TInput, TBase, TOutput> extends VldBase<TInput
 export declare class VldDefault<TInput, TOutput> extends VldBase<TInput | undefined, TOutput> {
     private readonly baseValidator;
     private readonly defaultValue;
-    constructor(baseValidator: VldBase<TInput, TOutput>, defaultValue: TOutput);
+    constructor(baseValidator: VldBase<TInput, TOutput>, defaultValue: ValueOrFactory<TOutput>);
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
     /**
      * Pre-parse default - validates the default value instead of returning it directly
      * This is useful when the default value needs to be validated against the schema
      */
-    prefault(): VldPrefault<TInput, TOutput>;
+    prefault(defaultValue?: ValueOrFactory<TInput>): VldPrefault<TInput, TOutput>;
+    unwrap(): VldBase<TInput, TOutput>;
+    removeDefault(): VldBase<TInput, TOutput>;
 }
 /**
  * Prefault validator - validates the default value instead of returning it directly
@@ -405,13 +547,14 @@ export declare class VldDefault<TInput, TOutput> extends VldBase<TInput | undefi
 export declare class VldPrefault<TInput, TOutput> extends VldBase<TInput | undefined, TOutput> {
     private readonly baseValidator;
     private readonly defaultValue;
-    constructor(baseValidator: VldBase<TInput, TOutput>, defaultValue: TOutput);
+    constructor(baseValidator: VldBase<TInput, TOutput>, defaultValue: ValueOrFactory<TInput>);
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
     /**
      * Calling prefault multiple times should be safe - return self
      */
-    prefault(): VldPrefault<TInput, TOutput>;
+    prefault(defaultValue?: ValueOrFactory<TInput>): VldPrefault<TInput, TOutput>;
+    unwrap(): VldBase<TInput, TOutput>;
 }
 /**
  * Catch validator - provides fallback value on validation error
@@ -483,7 +626,7 @@ export declare class VldNullish<TInput, TOutput> extends VldBase<TInput | null |
 export declare class VldPipe<TInput, TIntermediate, TOutput> extends VldBase<TInput, TOutput> {
     private readonly first;
     private readonly second;
-    constructor(first: VldBase<TInput, TIntermediate>, second: VldBase<TIntermediate, TOutput>);
+    constructor(first: VldBase<TInput, TIntermediate>, second: VldBase<any, TOutput>);
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
 }
@@ -498,6 +641,55 @@ export declare class VldSuperRefine<TInput, TOutput> extends VldBase<TInput, TOu
     safeParse(value: unknown): ParseResult<TOutput>;
     parseAsync(value: unknown): Promise<TOutput>;
     safeParseAsync(value: unknown): Promise<ParseResult<TOutput>>;
+    private _wrap;
+    min(length: number | Date | bigint | any, message?: ErrorParam): this;
+    max(length: number | Date | bigint | any, message?: ErrorParam): this;
+    length(length: number, message?: ErrorParam): this;
+    email(message?: ErrorParam): this;
+    url(message?: ErrorParam): this;
+    uuid(message?: ErrorParam): this;
+    regex(pattern: RegExp, message?: ErrorParam): this;
+    startsWith(str: string, message?: ErrorParam): this;
+    endsWith(str: string, message?: ErrorParam): this;
+    includes(str: string, message?: ErrorParam): this;
+    ip(message?: ErrorParam): this;
+    ipv4(message?: ErrorParam): this;
+    ipv6(message?: ErrorParam): this;
+    nonempty(message?: ErrorParam): this;
+    trim(): this;
+    toLowerCase(): this;
+    lowercase(): this;
+    toUpperCase(): this;
+    uppercase(): this;
+    positive(message?: ErrorParam): this;
+    negative(message?: ErrorParam): this;
+    nonnegative(message?: ErrorParam): this;
+    nonpositive(message?: ErrorParam): this;
+    int(message?: ErrorParam): this;
+    finite(message?: ErrorParam): this;
+    safe(message?: ErrorParam): this;
+    multipleOf(value: number, message?: ErrorParam): this;
+    step(value: number, message?: ErrorParam): this;
+    gt(value: any, message?: ErrorParam): this;
+    gte(value: any, message?: ErrorParam): this;
+    lt(value: any, message?: ErrorParam): this;
+    lte(value: any, message?: ErrorParam): this;
+    extend<U extends Record<string, any>>(extension: {
+        [K in keyof U]: VldBase<unknown, U[K]>;
+    }): any;
+    merge(other: any): any;
+    pick<K extends keyof TOutput>(...keys: K[]): any;
+    omit<K extends keyof TOutput>(...keys: K[]): any;
+    partial(): any;
+    required(): any;
+    strict(message?: ErrorParam): this;
+    passthrough(): this;
+    strip(): this;
+    catchall(validator: any): this;
+    get shape(): any;
+    get keyof(): any;
+    unwrap(): any;
+    get element(): any;
 }
 /**
  * Preprocess validator - transforms input before validation
@@ -510,3 +702,4 @@ export declare class VldPreprocess<TInput, TOutput> extends VldBase<unknown, TOu
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
 }
+export {};