@oxog/vld 2.0.3 → 2.1.0

package/dist/validators/array.js

@@ -0,0 +1,279 @@
+import { VldBase, VLD_VALIDATOR_TYPES } from './base.js';
+import { getMessages } from '../locales/runtime.js';
+import { V as VldError } from '../chunks/errors-core-BeiFUtZM.js';
+
+function createArrayError(message) {
+    return new VldError([{ code: 'invalid_array', path: [], message }]);
+}
+/**
+ * Immutable array validator with chainable methods
+ */
+class VldArray extends VldBase {
+    /**
+     * Private constructor to enforce immutability
+     */
+    constructor(config) {
+        super(VLD_VALIDATOR_TYPES.ARRAY);
+        this.config = config;
+        this._simpleItemMode = this.getSimpleItemMode(config.itemValidator);
+    }
+    getSimpleItemMode(itemValidator) {
+        if (itemValidator.isSimple !== true) {
+            return undefined;
+        }
+        switch (itemValidator.validatorType) {
+            case VLD_VALIDATOR_TYPES.STRING:
+                return 'string';
+            case VLD_VALIDATOR_TYPES.NUMBER:
+                return 'number';
+            case VLD_VALIDATOR_TYPES.BOOLEAN:
+                return 'boolean';
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Create a new array validator
+     */
+    static create(itemValidator) {
+        return new VldArray({ itemValidator });
+    }
+    /**
+     * Parse and validate an array value
+     */
+    parse(value) {
+        if (!Array.isArray(value)) {
+            throw new Error(this.config.errorMessage || getMessages().invalidArray);
+        }
+        return this.parseArrayValue(value);
+    }
+    /**
+     * Parse a value that has already passed the array type guard.
+     * @internal Used by object validators to avoid duplicate hot-path checks.
+     */
+    parseKnownArray(value) {
+        return this.parseArrayValue(value);
+    }
+    parseArrayValue(value) {
+        // Validate length constraints
+        if (this.config.exactLength !== undefined && value.length !== this.config.exactLength) {
+            throw new Error(this.config.errorMessage || getMessages().arrayLength(this.config.exactLength));
+        }
+        if (this.config.minLength !== undefined && value.length < this.config.minLength) {
+            throw new Error(this.config.errorMessage || getMessages().arrayMin(this.config.minLength));
+        }
+        if (this.config.maxLength !== undefined && value.length > this.config.maxLength) {
+            throw new Error(this.config.errorMessage || getMessages().arrayMax(this.config.maxLength));
+        }
+        const length = value.length;
+        const result = new Array(length);
+        const simpleItemMode = this._simpleItemMode;
+        if (simpleItemMode !== undefined) {
+            for (let i = 0; i < length; i++) {
+                const item = value[i];
+                switch (simpleItemMode) {
+                    case 'string':
+                        if (typeof item !== 'string') {
+                            throw new Error(getMessages().arrayItem(i, getMessages().invalidString));
+                        }
+                        result[i] = item;
+                        break;
+                    case 'number':
+                        if (typeof item !== 'number' || isNaN(item)) {
+                            throw new Error(getMessages().arrayItem(i, getMessages().invalidNumber));
+                        }
+                        result[i] = item;
+                        break;
+                    case 'boolean':
+                        if (typeof item !== 'boolean') {
+                            throw new Error(getMessages().arrayItem(i, getMessages().invalidBoolean));
+                        }
+                        result[i] = item;
+                        break;
+                }
+            }
+            if (this.config.unique) {
+                this.checkUnique(result);
+            }
+            return result;
+        }
+        // Validate each item without allocating a ParseResult object per element.
+        for (let i = 0; i < length; i++) {
+            try {
+                result[i] = this.config.itemValidator.parse(value[i]);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(getMessages().arrayItem(i, message));
+            }
+        }
+        // Check uniqueness if required - optimized with Map-based approach
+        if (this.config.unique) {
+            this.checkUnique(result);
+        }
+        return result;
+    }
+    /**
+     * Safely parse and validate an array value
+     */
+    safeParse(value) {
+        try {
+            return { success: true, data: this.parse(value) };
+        }
+        catch (error) {
+            return { success: false, error: createArrayError(error.message) };
+        }
+    }
+    /**
+     * Optimized uniqueness check using Map-based approach
+     * Avoids repeated stableStringify calls by caching serialized values
+     */
+    checkUnique(items) {
+        const seen = new Set(); // Set of seen keys
+        const objectKeys = new WeakMap(); // Cache for object->string mappings
+        for (const item of items) {
+            let key;
+            if (typeof item === 'object' && item !== null) {
+                // Check if we've already serialized this object reference
+                const cached = objectKeys.get(item);
+                if (cached !== undefined) {
+                    key = cached;
+                }
+                else {
+                    // Serialize and cache
+                    const serialized = this.stableStringify(item);
+                    key = serialized;
+                    objectKeys.set(item, serialized);
+                }
+            }
+            else {
+                // Primitives can be used directly as keys
+                key = item;
+            }
+            if (seen.has(key)) {
+                throw new Error('Array must contain unique items');
+            }
+            seen.add(key);
+        }
+    }
+    /**
+     * Create a stable string representation of an object for hashing
+     * Handles circular references and deep nesting gracefully
+     * BUG-006 FIX: Added depth limit to prevent stack overflow
+     * BUG-NEW-003 FIX: Fixed depth tracking to properly track recursion depth
+     */
+    stableStringify(obj) {
+        const seen = new WeakSet();
+        const MAX_DEPTH = 100; // Reasonable depth limit to prevent stack overflow
+        // Helper function to sort keys and create stable representation
+        const sortedStringify = (value, depth = 0) => {
+            // Check depth limit
+            if (depth > MAX_DEPTH) {
+                return '"[Max Depth Exceeded]"';
+            }
+            // Handle primitives
+            if (value === null)
+                return 'null';
+            if (value === undefined)
+                return 'undefined';
+            if (typeof value !== 'object')
+                return JSON.stringify(value);
+            // Handle circular references
+            if (seen.has(value)) {
+                return '"[Circular]"';
+            }
+            seen.add(value);
+            try {
+                // Handle arrays
+                if (Array.isArray(value)) {
+                    const items = value.map(item => sortedStringify(item, depth + 1));
+                    return `[${items.join(',')}]`;
+                }
+                // Handle objects - sort keys for stability
+                const keys = Object.keys(value).sort();
+                const pairs = keys.map(key => {
+                    const serializedKey = JSON.stringify(key);
+                    const serializedValue = sortedStringify(value[key], depth + 1);
+                    return `${serializedKey}:${serializedValue}`;
+                });
+                return `{${pairs.join(',')}}`;
+            }
+            finally {
+                // Clean up seen set for this branch
+                seen.delete(value);
+            }
+        };
+        try {
+            return sortedStringify(obj);
+        }
+        catch {
+            // Fallback to safe representation if stringify fails
+            return String(obj);
+        }
+    }
+    /**
+     * Create a new validator with minimum length constraint
+     */
+    min(length, message) {
+        return new VldArray({
+            ...this.config,
+            minLength: length,
+            errorMessage: message || getMessages().arrayMin(length)
+        });
+    }
+    /**
+     * Create a new validator with maximum length constraint
+     */
+    max(length, message) {
+        return new VldArray({
+            ...this.config,
+            maxLength: length,
+            errorMessage: message || getMessages().arrayMax(length)
+        });
+    }
+    /**
+     * Create a new validator with exact length constraint
+     */
+    length(length, message) {
+        return new VldArray({
+            ...this.config,
+            exactLength: length,
+            minLength: undefined,
+            maxLength: undefined,
+            errorMessage: message || getMessages().arrayLength(length)
+        });
+    }
+    /**
+     * Create a new validator that ensures array is not empty
+     */
+    nonempty(message) {
+        return new VldArray({
+            ...this.config,
+            minLength: 1,
+            errorMessage: message || getMessages().arrayEmpty
+        });
+    }
+    /**
+     * Create a new validator that ensures array contains unique items
+     */
+    unique(message) {
+        return new VldArray({
+            ...this.config,
+            unique: true,
+            errorMessage: message || 'Array must contain unique items'
+        });
+    }
+    /**
+     * Create a new validator with a range constraint for length
+     */
+    between(min, max, message) {
+        return new VldArray({
+            ...this.config,
+            minLength: min,
+            maxLength: max,
+            errorMessage: message || `Array length must be between ${min} and ${max}`
+        });
+    }
+}
+
+export { VldArray };

package/dist/validators/base.d.ts

@@ -1,3 +1,4 @@
+import type { SchemaRegistry } from '../registry.js';
 /**
  * Base result type for validation
  */
@@ -8,6 +9,108 @@ export type ParseResult<T> = {
     readonly success: false;
     readonly error: Error;
 };
+export interface StandardTypedV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardTypedV1Props<Input, Output>;
+}
+export interface StandardTypedV1Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly types?: StandardTypedV1Types<Input, Output> | undefined;
+}
+export interface StandardTypedV1Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+}
+export interface StandardSchemaV1<Input = unknown, Output = Input> extends StandardTypedV1<Input, Output> {
+    readonly '~standard': StandardSchemaV1Props<Input, Output>;
+}
+export interface StandardSchemaV1Props<Input = unknown, Output = Input> extends StandardTypedV1Props<Input, Output> {
+    readonly validate: (value: unknown, options?: StandardSchemaV1Options | undefined) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+}
+export interface StandardSchemaV1Options {
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+}
+export type StandardSchemaV1Result<Output> = StandardSchemaV1SuccessResult<Output> | StandardSchemaV1FailureResult;
+export interface StandardSchemaV1SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+}
+export interface StandardSchemaV1FailureResult {
+    readonly issues: ReadonlyArray<StandardSchemaV1Issue>;
+}
+export interface StandardSchemaV1Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | StandardSchemaV1PathSegment> | undefined;
+}
+export interface StandardSchemaV1PathSegment {
+    readonly key: PropertyKey;
+}
+/**
+ * Validator type constants for O(1) dispatch
+ * Used by VldObject to replace instanceof chains with Map lookups
+ */
+export declare const VLD_VALIDATOR_TYPES: {
+    readonly STRING: "string";
+    readonly STRING_FORMAT: "stringFormat";
+    readonly STRING_BOOL: "stringBool";
+    readonly NUMBER: "number";
+    readonly BOOLEAN: "boolean";
+    readonly DATE: "date";
+    readonly BIGINT: "bigint";
+    readonly UNDEFINED: "undefined";
+    readonly NULL: "null";
+    readonly UNKNOWN: "unknown";
+    readonly ANY: "any";
+    readonly VOID: "void";
+    readonly NEVER: "never";
+    readonly SYMBOL: "symbol";
+    readonly NAN: "nan";
+    readonly HEX: "hex";
+    readonly BASE64: "base64";
+    readonly UINT8_ARRAY: "uint8Array";
+    readonly COERCE_STRING: "coerceString";
+    readonly COERCE_NUMBER: "coerceNumber";
+    readonly COERCE_BOOLEAN: "coerceBoolean";
+    readonly COERCE_DATE: "coerceDate";
+    readonly COERCE_BIGINT: "coerceBigint";
+    readonly OBJECT: "object";
+    readonly ARRAY: "array";
+    readonly TUPLE: "tuple";
+    readonly SET: "set";
+    readonly MAP: "map";
+    readonly RECORD: "record";
+    readonly UNION: "union";
+    readonly DISCRIMINATED_UNION: "discriminatedUnion";
+    readonly INTERSECTION: "intersection";
+    readonly XOR: "xor";
+    readonly ENUM: "enum";
+    readonly LITERAL: "literal";
+    readonly LAZY: "lazy";
+    readonly CUSTOM: "custom";
+    readonly FUNCTION: "function";
+    readonly FILE: "file";
+    readonly JSON: "json";
+    readonly TEMPLATE_LITERAL: "templateLiteral";
+    readonly PROMISE: "promise";
+    readonly OPTIONAL: "optional";
+    readonly NULLABLE: "nullable";
+    readonly NULLISH: "nullish";
+    readonly EXACT_OPTIONAL: "exactOptional";
+    readonly DEFAULT: "default";
+    readonly CATCH: "catch";
+    readonly REFINE: "refine";
+    readonly TRANSFORM: "transform";
+    readonly PIPE: "pipe";
+    readonly PREPROCESS: "preprocess";
+    readonly SUPER_REFINE: "superRefine";
+    readonly BRAND: "brand";
+    readonly READONLY: "readonly";
+    readonly META: "meta";
+    readonly PREFAULT: "prefault";
+    readonly PREFault: "prefault";
+    readonly CODEC: "codec";
+};
+export type ValidatorType = typeof VLD_VALIDATOR_TYPES[keyof typeof VLD_VALIDATOR_TYPES];
 /**
  * Context for superRefine - allows adding multiple issues
  */
@@ -18,11 +121,32 @@ export interface SuperRefineContext {
     }): void;
     path: (string | number)[];
 }
+export type ErrorMap = (issue: {
+    code?: string;
+    input?: unknown;
+    path?: (string | number)[];
+}) => string | undefined;
+export type ErrorParam = string | {
+    error?: string | ErrorMap;
+    message?: string;
+};
+export declare function resolveErrorMessage(error: ErrorParam | undefined, fallback: string): string;
 /**
  * Abstract base class for all validators
  * Implements immutable pattern to prevent memory leaks and race conditions
  */
 export declare abstract class VldBase<TInput, TOutput = TInput> {
+    /**
+     * Runtime type identifier for O(1) dispatch
+     * Used by VldObject instead of instanceof chains
+     */
+    readonly validatorType: ValidatorType;
+    /**
+     * Constructor with runtime type identifier
+     * @param validatorType The runtime type identifier
+     */
+    constructor(validatorType?: ValidatorType);
+    get '~standard'(): StandardSchemaV1Props<unknown, TOutput>;
     /**
      * Parse and validate a value, throwing an error if invalid
      * @param value The value to validate
@@ -36,6 +160,8 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @returns A result object with either success and data, or failure and error
      */
     abstract safeParse(value: unknown): ParseResult<TOutput>;
+    parseAsync(value: unknown): Promise<TOutput>;
+    safeParseAsync(value: unknown): Promise<ParseResult<TOutput>>;
     /**
      * Check if a value is valid according to this validator
      * @param value The value to check
@@ -57,7 +183,7 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @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, message?: string): VldRefine<TInput, TOutput, TOutput>;
+    refine(predicate: (value: TOutput) => boolean | Promise<boolean>, message?: string): VldRefine<TInput, TOutput, TOutput>;
     /**
      * Advanced refinement with context for adding multiple issues
      * @param refinement The refinement function with context
@@ -69,7 +195,7 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @param transformer The transformation function
      * @returns A new transformed validator
      */
-    transform<TTransformed>(transformer: (value: TOutput) => TTransformed): VldTransform<TInput, TOutput, TTransformed>;
+    transform<TTransformed>(transformer: (value: TOutput) => TTransformed | Promise<TTransformed>): VldTransform<TInput, TOutput, TTransformed>;
     /**
      * Create a new validator with a default value for undefined inputs
      * @param defaultValue The default value
@@ -149,7 +275,7 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @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, message?: string): VldRefine<TInput, TOutput, TOutput>;
+    check(predicate: (value: TOutput) => boolean | Promise<boolean>, message?: string): VldRefine<TInput, TOutput, TOutput>;
     /**
      * Get metadata for this schema
      * Zod 4 API parity - allows attaching OpenAPI/JSON Schema metadata
@@ -163,6 +289,12 @@ export declare abstract class VldBase<TInput, TOutput = TInput> {
      * @returns A new validator with the metadata
      */
     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
+     * immutability.
+     */
+    register<TMetadata extends Record<string, unknown>>(targetRegistry: SchemaRegistry<TMetadata>, metadata: TMetadata): this;
     /**
      * Add a description to this schema
      * Zod 4 API parity - convenience method for .meta({ description: ... })
@@ -198,6 +330,9 @@ export declare class VldMeta<TInput, TOutput> extends VldBase<TInput, TOutput> {
      * Get the metadata
      */
     getMeta(): Readonly<Partial<SchemaMetadata>>;
+    meta(): SchemaMetadata | undefined;
+    meta(data: Partial<SchemaMetadata>): VldMeta<TInput, TOutput>;
+    describe(description: string): VldMeta<TInput, TOutput>;
 }
 /**
  * Readonly validator - marks output as readonly
@@ -231,9 +366,10 @@ export declare class VldRefine<TInput, TBase, TOutput extends TBase = TBase> ext
     private readonly baseValidator;
     private readonly predicate;
     private readonly customMessage?;
-    constructor(baseValidator: VldBase<TInput, TBase>, predicate: (value: TBase) => boolean, customMessage?: string | undefined);
+    constructor(baseValidator: VldBase<TInput, TBase>, predicate: (value: TBase) => boolean | Promise<boolean>, customMessage?: string | undefined);
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
+    parseAsync(value: unknown): Promise<TOutput>;
 }
 /**
  * Transform validator - transforms data after validation
@@ -241,9 +377,10 @@ export declare class VldRefine<TInput, TBase, TOutput extends TBase = TBase> ext
 export declare class VldTransform<TInput, TBase, TOutput> extends VldBase<TInput, TOutput> {
     private readonly baseValidator;
     private readonly transformer;
-    constructor(baseValidator: VldBase<TInput, TBase>, transformer: (value: TBase) => TOutput);
+    constructor(baseValidator: VldBase<TInput, TBase>, transformer: (value: TBase) => TOutput | Promise<TOutput>);
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
+    parseAsync(value: unknown): Promise<TOutput>;
 }
 /**
  * Default validator - provides default value for undefined
@@ -283,6 +420,7 @@ export declare class VldPrefault<TInput, TOutput> extends VldBase<TInput | undef
 export declare class VldCatch<TInput, TOutput> extends VldBase<TInput, TOutput> {
     private readonly baseValidator;
     private readonly fallbackValue;
+    private readonly simpleMode;
     constructor(baseValidator: VldBase<TInput, TOutput>, fallbackValue: TOutput);
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
@@ -292,7 +430,9 @@ export declare class VldCatch<TInput, TOutput> extends VldBase<TInput, TOutput>
  */
 export declare class VldOptional<TInput, TOutput> extends VldBase<TInput | undefined, TOutput | undefined> {
     private readonly baseValidator;
+    private readonly simpleMode;
     constructor(baseValidator: VldBase<TInput, TOutput>);
+    private parseSimpleValue;
     static create<TInput, TOutput>(baseValidator: VldBase<TInput, TOutput>): VldOptional<TInput, TOutput>;
     parse(value: unknown): TOutput | undefined;
     safeParse(value: unknown): ParseResult<TOutput | undefined>;
@@ -306,6 +446,7 @@ export declare class VldOptional<TInput, TOutput> extends VldBase<TInput | undef
  */
 export declare class VldExactOptional<TInput, TOutput> extends VldBase<TInput | undefined, TOutput | undefined> {
     private readonly baseValidator;
+    private readonly simpleMode;
     constructor(baseValidator: VldBase<TInput, TOutput>);
     static create<TInput, TOutput>(baseValidator: VldBase<TInput, TOutput>): VldExactOptional<TInput, TOutput>;
     parse(value: unknown): TOutput | undefined;
@@ -317,6 +458,7 @@ export declare class VldExactOptional<TInput, TOutput> extends VldBase<TInput |
  */
 export declare class VldNullable<TInput, TOutput> extends VldBase<TInput | null, TOutput | null> {
     private readonly baseValidator;
+    private readonly simpleMode;
     constructor(baseValidator: VldBase<TInput, TOutput>);
     static create<TInput, TOutput>(baseValidator: VldBase<TInput, TOutput>): VldNullable<TInput, TOutput>;
     parse(value: unknown): TOutput | null;
@@ -328,6 +470,7 @@ export declare class VldNullable<TInput, TOutput> extends VldBase<TInput | null,
  */
 export declare class VldNullish<TInput, TOutput> extends VldBase<TInput | null | undefined, TOutput | null | undefined> {
     private readonly baseValidator;
+    private readonly simpleMode;
     constructor(baseValidator: VldBase<TInput, TOutput>);
     static create<TInput, TOutput>(baseValidator: VldBase<TInput, TOutput>): VldNullish<TInput, TOutput>;
     parse(value: unknown): TOutput | null | undefined;
@@ -353,6 +496,8 @@ export declare class VldSuperRefine<TInput, TOutput> extends VldBase<TInput, TOu
     constructor(_inner: VldBase<TInput, TOutput>, _refinement: (value: TOutput, ctx: SuperRefineContext) => void | Promise<void>);
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
+    parseAsync(value: unknown): Promise<TOutput>;
+    safeParseAsync(value: unknown): Promise<ParseResult<TOutput>>;
 }
 /**
  * Preprocess validator - transforms input before validation
@@ -365,4 +510,3 @@ export declare class VldPreprocess<TInput, TOutput> extends VldBase<unknown, TOu
     parse(value: unknown): TOutput;
     safeParse(value: unknown): ParseResult<TOutput>;
 }
-//# sourceMappingURL=base.d.ts.map