schema-dsl 1.2.4 → 2.0.0

package/dist/DslBuilder-DQDN0ZxZ.d.cts

@@ -0,0 +1,341 @@
+import { J as JSONSchema, V as ValidationResult, D as DslConfigOptions } from './plugin-CIKtTMtS.cjs';
+
+/**
+ * IConditionalBuilder interface (shape definition).
+ * Implementation class is in src/core/ConditionalBuilder.ts (Phase 8).
+ */
+
+interface IConditionalBuilder {
+    and(condition: (data: unknown) => boolean): this;
+    or(condition: (data: unknown) => boolean): this;
+    /** then/else accept string DSL, JSONSchema, or null (no-op). */
+    then(schema: string | JSONSchema | null): this;
+    else(schema: string | JSONSchema | null): this;
+    elseIf(condition: (data: unknown) => boolean): this;
+    message(msg: string): this;
+    /** Serialise to a JSON Schema object (internal conditional marker). */
+    toSchema(): JSONSchema;
+    /** Alias for toSchema(). */
+    build(): JSONSchema;
+    /** Synchronous assertion; throws ValidationError on failure. */
+    assert(data: unknown, options?: Record<string, unknown>): unknown;
+    /** Synchronous validation; returns ValidationResult. */
+    validate(data: unknown, options?: Record<string, unknown>): ValidationResult<unknown>;
+    /** Async validation; returns Promise<ValidationResult>. */
+    validateAsync(data: unknown, options?: Record<string, unknown>): Promise<ValidationResult<unknown>>;
+    /** Quick boolean check (no error details). */
+    check(data: unknown): boolean;
+}
+
+/**
+ * DslBuilder interface definition (chainable API shape).
+ * Implementation class is in src/core/DslBuilder.ts (Phase 7).
+ */
+interface IDslBuilder {
+    min(n: number): this;
+    max(n: number): this;
+    label(text: string): this;
+    description(text: string): this;
+    pattern(regex: RegExp | string, message?: string): this;
+    enum(...values: unknown[]): this;
+    optional(): this;
+    required(): this;
+    default(value: unknown): this;
+    error(messages: Record<string, string>): this;
+    messages(msgs: Record<string, string>): this;
+    format(fmt: string): this;
+    custom(validatorFn: (value: unknown) => unknown): this;
+    length(n: number): this;
+    alphanum(): this;
+    trim(): this;
+    lowercase(): this;
+    uppercase(): this;
+    ip(): this;
+    base64(): this;
+    jwt(): this;
+    json(): this;
+    domain(): this;
+    slug(): this;
+    after(date: string): this;
+    before(date: string): this;
+    dateGreater(date: string): this;
+    dateLess(date: string): this;
+    dateFormat(fmt: string): this;
+    username(preset?: string | {
+        minLength?: number;
+        maxLength?: number;
+        allowUnderscore?: boolean;
+        allowNumber?: boolean;
+    }): this;
+    password(preset?: string): this;
+    phone(country?: string): this;
+    phoneNumber(country?: string): this;
+    idCard(country?: string): this;
+    creditCard(type?: string): this;
+    licensePlate(country?: string): this;
+    postalCode(country?: string): this;
+    passport(country?: string): this;
+    precision(n: number): this;
+    multiple(n: number): this;
+    port(): this;
+    requireAll(): this;
+    strict(): this;
+    noSparse(): this;
+    includesRequired(items: unknown[]): this;
+    toJsonSchema(): JSONSchema;
+    toSchema(): JSONSchema;
+    toString(): string;
+    readonly _isDslBuilder: true;
+}
+/**
+ * DSL object definition (key → field mapping).
+ * ⚠️ Must be an interface rather than a type alias to support recursive DslField ↔ DslDefinition references.
+ */
+interface DslDefinition {
+    [key: string]: DslField;
+}
+/**
+ * v1 conditional field marker (created by dsl.if / dsl.match; compiled to allOf conditional schema during parseObject).
+ */
+interface DslConditionMarker {
+    _isIf?: true;
+    _isMatch?: true;
+    condition?: string;
+    field?: string;
+    then?: unknown;
+    else?: unknown;
+    map?: Record<string, unknown>;
+}
+/**
+ * DSL field type (recursive definition).
+ * String | DslBuilder instance | nested object.
+ */
+type DslField = string | IDslBuilder | DslDefinition | DslConditionMarker;
+/**
+ * DslBuilder constructor input (string or nested definition).
+ */
+type DslInput = string | DslDefinition;
+/**
+ * if/conditional function types.
+ */
+type DslIfFn = (condition: (data: unknown) => boolean) => IConditionalBuilder;
+type DslFieldIfFn = (condition: string, thenSchema: unknown, elseSchema?: unknown) => DslConditionMarker;
+/**
+ * dsl.error namespace.
+ */
+interface DslErrorNamespace {
+    readonly [code: string]: string;
+}
+/**
+ * DslFn interface (function overloads + namespace attachments).
+ * ⚠️ Uses function overloads rather than union return types to ensure TypeScript type narrowing works correctly.
+ */
+interface DslFn {
+    (def: string): IDslBuilder;
+    (def: DslDefinition): JSONSchema;
+    config: (options?: Partial<DslConfigOptions>) => void;
+    if: DslIfFn & DslFieldIfFn;
+    _if: DslIfFn & DslFieldIfFn;
+    match: (value: unknown, cases: Record<string, unknown>) => DslConditionMarker;
+    error: DslErrorNamespace;
+}
+
+/**
+ * DslBuilder — chainable DSL builder.
+ *
+ * v2 changes:
+ *   - Constructor delegates to DslParser.parseString() (fixes DA-01/DA-02/DA-03)
+ *   - Custom type registration delegates to TypeRegistry (fixes DB-01/DB-02: unifies three type lists)
+ *   - _customMessages merges instead of overwriting (fixes v1 overwrite bug)
+ *   - Implements IDslBuilder interface (error/optional/required/enum chain methods)
+ */
+
+type CustomValidatorFn = (value: unknown) => unknown;
+declare class DslBuilder implements IDslBuilder {
+    readonly _isDslBuilder: true;
+    /** schema-dsl custom validation keyword set (stripped during toJsonSchema). */
+    static readonly _internalKeys: ReadonlySet<string>;
+    /** Custom type cache (BC with v1 DslBuilder._customTypes). */
+    private static readonly _customTypes;
+    private _baseSchema;
+    private _required;
+    private _optional;
+    private _customMessages;
+    private _label;
+    private _description;
+    private _customValidators;
+    private _whenConditions;
+    constructor(dslString: string);
+    /**
+     * Parse DSL body (without ! or ?).
+     * Delegates to the unified parser so string and builder DSL parsing stay in lockstep.
+     */
+    private static _parseBody;
+    /**
+     * Register a custom type (delegates to TypeRegistry).
+     */
+    static registerType(name: string, schema: JSONSchema | (() => JSONSchema)): void;
+    /** Check whether a type is registered (built-in or custom). */
+    static hasType(type: string): boolean;
+    /** Get all registered custom type names. */
+    static getCustomTypes(): string[];
+    /** Clear all custom types (primarily for testing). */
+    static clearCustomTypes(): void;
+    /**
+     * Validate schema nesting depth.
+     * @param schema - JSON Schema to validate
+     * @param maxDepth - maximum allowed depth (default 3)
+     */
+    static validateNestingDepth(schema: JSONSchema, maxDepth?: number): {
+        valid: boolean;
+        depth: number;
+        path: string;
+        message: string;
+    };
+    private _assertType;
+    private _assertStringType;
+    private _assertNumberType;
+    private _assertObjectType;
+    private _assertArrayType;
+    /**
+     * Set format.
+     */
+    format(fmt: string): this;
+    /**
+     * Add regex validation.
+     */
+    pattern(regex: RegExp | string, message?: string): this;
+    /**
+     * Custom error messages (IDslBuilder: error; BC alias: messages).
+     */
+    messages(msgs: Record<string, string>): this;
+    /** IDslBuilder.error — alias for messages() */
+    error(msgs: Record<string, string>): this;
+    /**
+     * Set field label (used in error messages).
+     */
+    label(text: string): this;
+    /**
+     * Set description.
+     */
+    description(text: string): this;
+    /**
+     * Set default value.
+     */
+    default(value: unknown): this;
+    /**
+     * Set allowed enum values (IDslBuilder).
+     */
+    enum(...values: unknown[]): this;
+    /**
+     * Mark field as optional.
+     */
+    optional(): this;
+    /**
+     * Mark field as required.
+     */
+    required(): this;
+    /**
+     * Add a custom validator function.
+     */
+    custom(validatorFn: CustomValidatorFn): this;
+    /** String minimum length. */
+    min(n: number): this;
+    /** String maximum length. */
+    max(n: number): this;
+    /** String exact length (→ exactLength custom keyword). */
+    length(n: number): this;
+    /** String: only alphanumeric characters allowed. */
+    alphanum(): this;
+    /** String: no leading/trailing whitespace. */
+    trim(): this;
+    /** String: must be lowercase. */
+    lowercase(): this;
+    /** String: must be uppercase. */
+    uppercase(): this;
+    /** String: must be a valid JSON string. */
+    json(): this;
+    /** String date format validation. */
+    dateFormat(fmt: string): this;
+    /** String: must be after the given date. */
+    after(date: string): this;
+    /** String: must be before the given date. */
+    before(date: string): this;
+    /** v1.0.2 alias: dateGreater. */
+    dateGreater(date: string): this;
+    /** v1.0.2 alias: dateLess. */
+    dateLess(date: string): this;
+    /** String slug format validation. */
+    slug(): this;
+    /** String domain validation. */
+    domain(): this;
+    /** String IP address validation (IPv4 or IPv6). */
+    ip(): this;
+    /** String Base64 encoding validation. */
+    base64(): this;
+    /** String JWT token validation. */
+    jwt(): this;
+    /** Phone number validation (auto-corrects number → string). */
+    phone(country?: string): this;
+    /** phone() alias (BC). */
+    phoneNumber(country?: string): this;
+    /** National ID (idCard) validation. */
+    idCard(country?: string): this;
+    /** URL slug validation. */
+    slugChain(): this;
+    /** Credit card number validation. */
+    creditCard(type?: string): this;
+    /** Vehicle license plate validation. */
+    licensePlate(country?: string): this;
+    /** Postal code validation. */
+    postalCode(country?: string): this;
+    /** Passport number validation. */
+    passport(country?: string): this;
+    /**
+     * Username validation.
+     * @param preset - 'short'(3-16) | 'medium'(3-32) | 'long'(3-64) | 'N-M' | object
+     */
+    username(preset?: string | {
+        minLength?: number;
+        maxLength?: number;
+        allowUnderscore?: boolean;
+        allowNumber?: boolean;
+    }): this;
+    /**
+     * Password strength validation.
+     * @param strength - 'weak' | 'medium' | 'strong' | 'veryStrong'
+     */
+    password(strength?: string): this;
+    /** Number decimal places limit. */
+    precision(n: number): this;
+    /** Number multiple-of validation (standard JSON Schema multipleOf). */
+    multiple(n: number): this;
+    /** Number port validation (1–65535). */
+    port(): this;
+    /** Object: all defined properties are required. */
+    requireAll(): this;
+    /** Object strict mode: no additional properties allowed. */
+    strict(): this;
+    /** Array: sparse arrays are not allowed. */
+    noSparse(): this;
+    /** Array: must contain the specified element. */
+    includesRequired(items: unknown[]): this;
+    /**
+     * Convert to a schema with schema-dsl internal fields (for use by Validator).
+     */
+    toSchema(): JSONSchema;
+    /**
+     * Output a clean JSON Schema (strips all schema-dsl internal fields and custom keywords).
+     * Can be embedded directly in OpenAPI / standard JSON Schema documents.
+     */
+    toJsonSchema(): JSONSchema;
+    toString(): string;
+    /**
+     * Validate data (BC with v1).
+     * @param data - data to validate
+     */
+    private _validator;
+    validate(data: unknown): Promise<ValidationResult<unknown>>;
+}
+
+export { DslBuilder as D, type IConditionalBuilder as I, type IDslBuilder as a, type DslDefinition as b, type DslConditionMarker as c, type DslErrorNamespace as d, type DslField as e, type DslFn as f, type DslIfFn as g, type DslInput as h };

package/dist/DslBuilder-DkLaOo9Q.d.ts

@@ -0,0 +1,341 @@
+import { J as JSONSchema, V as ValidationResult, D as DslConfigOptions } from './plugin-CIKtTMtS.js';
+
+/**
+ * IConditionalBuilder interface (shape definition).
+ * Implementation class is in src/core/ConditionalBuilder.ts (Phase 8).
+ */
+
+interface IConditionalBuilder {
+    and(condition: (data: unknown) => boolean): this;
+    or(condition: (data: unknown) => boolean): this;
+    /** then/else accept string DSL, JSONSchema, or null (no-op). */
+    then(schema: string | JSONSchema | null): this;
+    else(schema: string | JSONSchema | null): this;
+    elseIf(condition: (data: unknown) => boolean): this;
+    message(msg: string): this;
+    /** Serialise to a JSON Schema object (internal conditional marker). */
+    toSchema(): JSONSchema;
+    /** Alias for toSchema(). */
+    build(): JSONSchema;
+    /** Synchronous assertion; throws ValidationError on failure. */
+    assert(data: unknown, options?: Record<string, unknown>): unknown;
+    /** Synchronous validation; returns ValidationResult. */
+    validate(data: unknown, options?: Record<string, unknown>): ValidationResult<unknown>;
+    /** Async validation; returns Promise<ValidationResult>. */
+    validateAsync(data: unknown, options?: Record<string, unknown>): Promise<ValidationResult<unknown>>;
+    /** Quick boolean check (no error details). */
+    check(data: unknown): boolean;
+}
+
+/**
+ * DslBuilder interface definition (chainable API shape).
+ * Implementation class is in src/core/DslBuilder.ts (Phase 7).
+ */
+interface IDslBuilder {
+    min(n: number): this;
+    max(n: number): this;
+    label(text: string): this;
+    description(text: string): this;
+    pattern(regex: RegExp | string, message?: string): this;
+    enum(...values: unknown[]): this;
+    optional(): this;
+    required(): this;
+    default(value: unknown): this;
+    error(messages: Record<string, string>): this;
+    messages(msgs: Record<string, string>): this;
+    format(fmt: string): this;
+    custom(validatorFn: (value: unknown) => unknown): this;
+    length(n: number): this;
+    alphanum(): this;
+    trim(): this;
+    lowercase(): this;
+    uppercase(): this;
+    ip(): this;
+    base64(): this;
+    jwt(): this;
+    json(): this;
+    domain(): this;
+    slug(): this;
+    after(date: string): this;
+    before(date: string): this;
+    dateGreater(date: string): this;
+    dateLess(date: string): this;
+    dateFormat(fmt: string): this;
+    username(preset?: string | {
+        minLength?: number;
+        maxLength?: number;
+        allowUnderscore?: boolean;
+        allowNumber?: boolean;
+    }): this;
+    password(preset?: string): this;
+    phone(country?: string): this;
+    phoneNumber(country?: string): this;
+    idCard(country?: string): this;
+    creditCard(type?: string): this;
+    licensePlate(country?: string): this;
+    postalCode(country?: string): this;
+    passport(country?: string): this;
+    precision(n: number): this;
+    multiple(n: number): this;
+    port(): this;
+    requireAll(): this;
+    strict(): this;
+    noSparse(): this;
+    includesRequired(items: unknown[]): this;
+    toJsonSchema(): JSONSchema;
+    toSchema(): JSONSchema;
+    toString(): string;
+    readonly _isDslBuilder: true;
+}
+/**
+ * DSL object definition (key → field mapping).
+ * ⚠️ Must be an interface rather than a type alias to support recursive DslField ↔ DslDefinition references.
+ */
+interface DslDefinition {
+    [key: string]: DslField;
+}
+/**
+ * v1 conditional field marker (created by dsl.if / dsl.match; compiled to allOf conditional schema during parseObject).
+ */
+interface DslConditionMarker {
+    _isIf?: true;
+    _isMatch?: true;
+    condition?: string;
+    field?: string;
+    then?: unknown;
+    else?: unknown;
+    map?: Record<string, unknown>;
+}
+/**
+ * DSL field type (recursive definition).
+ * String | DslBuilder instance | nested object.
+ */
+type DslField = string | IDslBuilder | DslDefinition | DslConditionMarker;
+/**
+ * DslBuilder constructor input (string or nested definition).
+ */
+type DslInput = string | DslDefinition;
+/**
+ * if/conditional function types.
+ */
+type DslIfFn = (condition: (data: unknown) => boolean) => IConditionalBuilder;
+type DslFieldIfFn = (condition: string, thenSchema: unknown, elseSchema?: unknown) => DslConditionMarker;
+/**
+ * dsl.error namespace.
+ */
+interface DslErrorNamespace {
+    readonly [code: string]: string;
+}
+/**
+ * DslFn interface (function overloads + namespace attachments).
+ * ⚠️ Uses function overloads rather than union return types to ensure TypeScript type narrowing works correctly.
+ */
+interface DslFn {
+    (def: string): IDslBuilder;
+    (def: DslDefinition): JSONSchema;
+    config: (options?: Partial<DslConfigOptions>) => void;
+    if: DslIfFn & DslFieldIfFn;
+    _if: DslIfFn & DslFieldIfFn;
+    match: (value: unknown, cases: Record<string, unknown>) => DslConditionMarker;
+    error: DslErrorNamespace;
+}
+
+/**
+ * DslBuilder — chainable DSL builder.
+ *
+ * v2 changes:
+ *   - Constructor delegates to DslParser.parseString() (fixes DA-01/DA-02/DA-03)
+ *   - Custom type registration delegates to TypeRegistry (fixes DB-01/DB-02: unifies three type lists)
+ *   - _customMessages merges instead of overwriting (fixes v1 overwrite bug)
+ *   - Implements IDslBuilder interface (error/optional/required/enum chain methods)
+ */
+
+type CustomValidatorFn = (value: unknown) => unknown;
+declare class DslBuilder implements IDslBuilder {
+    readonly _isDslBuilder: true;
+    /** schema-dsl custom validation keyword set (stripped during toJsonSchema). */
+    static readonly _internalKeys: ReadonlySet<string>;
+    /** Custom type cache (BC with v1 DslBuilder._customTypes). */
+    private static readonly _customTypes;
+    private _baseSchema;
+    private _required;
+    private _optional;
+    private _customMessages;
+    private _label;
+    private _description;
+    private _customValidators;
+    private _whenConditions;
+    constructor(dslString: string);
+    /**
+     * Parse DSL body (without ! or ?).
+     * Delegates to the unified parser so string and builder DSL parsing stay in lockstep.
+     */
+    private static _parseBody;
+    /**
+     * Register a custom type (delegates to TypeRegistry).
+     */
+    static registerType(name: string, schema: JSONSchema | (() => JSONSchema)): void;
+    /** Check whether a type is registered (built-in or custom). */
+    static hasType(type: string): boolean;
+    /** Get all registered custom type names. */
+    static getCustomTypes(): string[];
+    /** Clear all custom types (primarily for testing). */
+    static clearCustomTypes(): void;
+    /**
+     * Validate schema nesting depth.
+     * @param schema - JSON Schema to validate
+     * @param maxDepth - maximum allowed depth (default 3)
+     */
+    static validateNestingDepth(schema: JSONSchema, maxDepth?: number): {
+        valid: boolean;
+        depth: number;
+        path: string;
+        message: string;
+    };
+    private _assertType;
+    private _assertStringType;
+    private _assertNumberType;
+    private _assertObjectType;
+    private _assertArrayType;
+    /**
+     * Set format.
+     */
+    format(fmt: string): this;
+    /**
+     * Add regex validation.
+     */
+    pattern(regex: RegExp | string, message?: string): this;
+    /**
+     * Custom error messages (IDslBuilder: error; BC alias: messages).
+     */
+    messages(msgs: Record<string, string>): this;
+    /** IDslBuilder.error — alias for messages() */
+    error(msgs: Record<string, string>): this;
+    /**
+     * Set field label (used in error messages).
+     */
+    label(text: string): this;
+    /**
+     * Set description.
+     */
+    description(text: string): this;
+    /**
+     * Set default value.
+     */
+    default(value: unknown): this;
+    /**
+     * Set allowed enum values (IDslBuilder).
+     */
+    enum(...values: unknown[]): this;
+    /**
+     * Mark field as optional.
+     */
+    optional(): this;
+    /**
+     * Mark field as required.
+     */
+    required(): this;
+    /**
+     * Add a custom validator function.
+     */
+    custom(validatorFn: CustomValidatorFn): this;
+    /** String minimum length. */
+    min(n: number): this;
+    /** String maximum length. */
+    max(n: number): this;
+    /** String exact length (→ exactLength custom keyword). */
+    length(n: number): this;
+    /** String: only alphanumeric characters allowed. */
+    alphanum(): this;
+    /** String: no leading/trailing whitespace. */
+    trim(): this;
+    /** String: must be lowercase. */
+    lowercase(): this;
+    /** String: must be uppercase. */
+    uppercase(): this;
+    /** String: must be a valid JSON string. */
+    json(): this;
+    /** String date format validation. */
+    dateFormat(fmt: string): this;
+    /** String: must be after the given date. */
+    after(date: string): this;
+    /** String: must be before the given date. */
+    before(date: string): this;
+    /** v1.0.2 alias: dateGreater. */
+    dateGreater(date: string): this;
+    /** v1.0.2 alias: dateLess. */
+    dateLess(date: string): this;
+    /** String slug format validation. */
+    slug(): this;
+    /** String domain validation. */
+    domain(): this;
+    /** String IP address validation (IPv4 or IPv6). */
+    ip(): this;
+    /** String Base64 encoding validation. */
+    base64(): this;
+    /** String JWT token validation. */
+    jwt(): this;
+    /** Phone number validation (auto-corrects number → string). */
+    phone(country?: string): this;
+    /** phone() alias (BC). */
+    phoneNumber(country?: string): this;
+    /** National ID (idCard) validation. */
+    idCard(country?: string): this;
+    /** URL slug validation. */
+    slugChain(): this;
+    /** Credit card number validation. */
+    creditCard(type?: string): this;
+    /** Vehicle license plate validation. */
+    licensePlate(country?: string): this;
+    /** Postal code validation. */
+    postalCode(country?: string): this;
+    /** Passport number validation. */
+    passport(country?: string): this;
+    /**
+     * Username validation.
+     * @param preset - 'short'(3-16) | 'medium'(3-32) | 'long'(3-64) | 'N-M' | object
+     */
+    username(preset?: string | {
+        minLength?: number;
+        maxLength?: number;
+        allowUnderscore?: boolean;
+        allowNumber?: boolean;
+    }): this;
+    /**
+     * Password strength validation.
+     * @param strength - 'weak' | 'medium' | 'strong' | 'veryStrong'
+     */
+    password(strength?: string): this;
+    /** Number decimal places limit. */
+    precision(n: number): this;
+    /** Number multiple-of validation (standard JSON Schema multipleOf). */
+    multiple(n: number): this;
+    /** Number port validation (1–65535). */
+    port(): this;
+    /** Object: all defined properties are required. */
+    requireAll(): this;
+    /** Object strict mode: no additional properties allowed. */
+    strict(): this;
+    /** Array: sparse arrays are not allowed. */
+    noSparse(): this;
+    /** Array: must contain the specified element. */
+    includesRequired(items: unknown[]): this;
+    /**
+     * Convert to a schema with schema-dsl internal fields (for use by Validator).
+     */
+    toSchema(): JSONSchema;
+    /**
+     * Output a clean JSON Schema (strips all schema-dsl internal fields and custom keywords).
+     * Can be embedded directly in OpenAPI / standard JSON Schema documents.
+     */
+    toJsonSchema(): JSONSchema;
+    toString(): string;
+    /**
+     * Validate data (BC with v1).
+     * @param data - data to validate
+     */
+    private _validator;
+    validate(data: unknown): Promise<ValidationResult<unknown>>;
+}
+
+export { DslBuilder as D, type IConditionalBuilder as I, type IDslBuilder as a, type DslDefinition as b, type DslConditionMarker as c, type DslErrorNamespace as d, type DslField as e, type DslFn as f, type DslIfFn as g, type DslInput as h };