schema-dsl 1.2.4 → 2.0.0

package/src/types/config.ts

@@ -0,0 +1,59 @@
+import type { ErrorMessages } from './error.js'
+
+/**
+ * Cache configuration options.
+ * @alias CacheConfig — v1 BC alias exported from index
+ */
+export interface CacheOptions {
+  /** Maximum number of cache entries (default 5000). */
+  maxSize?: number
+  /** Cache TTL in milliseconds (0 = no expiry). */
+  ttl?: number
+  /** Whether caching is enabled. */
+  enabled?: boolean
+  /** Whether statistics are enabled (default true). */
+  statsEnabled?: boolean
+}
+
+/**
+ * I18n configuration type.
+ */
+export type I18nConfig =
+  | string                          // Path to locale directory (Node >=18: .js/.cjs/.json/.jsonc/.json5)
+  | Record<string, ErrorMessages>   // Inline locale bundle
+  | { localesPath: string }         // Locale directory — object form (Node >=18: .js/.cjs/.json/.jsonc/.json5)
+  | { locales: Record<string, ErrorMessages> } // v1/doc-compatible wrapper
+
+/**
+ * dsl.config() options.
+ */
+export interface DslConfigOptions {
+  /** Internationalisation config. */
+  i18n?: I18nConfig
+  /** Cache config. */
+  cache?: CacheOptions
+  /** Custom validation rule extensions. */
+  patterns?: {
+    phone?: Record<string, RegExp>
+    idCard?: Record<string, RegExp>
+    creditCard?: Record<string, RegExp>
+    [key: string]: Record<string, RegExp> | undefined
+  }
+  /** Default locale (default 'en-US'). */
+  defaultLocale?: string
+  /** Strict type resolution: throw on unknown types instead of warn + fallback to string. */
+  strict?: boolean
+}
+
+/**
+ * ValidatorOptions (Validator class constructor parameters).
+ */
+export interface ValidatorOptions {
+  allErrors?: boolean
+  verbose?: boolean
+  strict?: boolean
+  coerceTypes?: boolean | 'array'
+  removeAdditional?: boolean | 'all' | 'failing'
+  useDefaults?: boolean
+  cache?: boolean | CacheOptions
+}

package/src/types/dsl.ts

@@ -0,0 +1,131 @@
+import type { JSONSchema } from './schema.js'
+import type { DslConfigOptions } from './config.js'
+import type { IConditionalBuilder } from './conditional.js'
+
+/**
+ * DslBuilder interface definition (chainable API shape).
+ * Implementation class is in src/core/DslBuilder.ts (Phase 7).
+ */
+export interface IDslBuilder {
+  // ── Core constraint methods ──────────────────────────────────
+  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
+
+  // ── String validators ────────────────────────────────────────
+  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
+
+  // ── Number validators ────────────────────────────────────────
+  precision(n: number): this
+  multiple(n: number): this
+  port(): this
+
+  // ── Object validators ────────────────────────────────────────
+  requireAll(): this
+  strict(): this
+
+  // ── Array validators ─────────────────────────────────────────
+  noSparse(): this
+  includesRequired(items: unknown[]): this
+
+  // ── Output ───────────────────────────────────────────────────
+  toJsonSchema(): JSONSchema
+  toSchema(): JSONSchema
+  toString(): string
+
+  // ── Internal marker ──────────────────────────────────────────
+  readonly _isDslBuilder: true
+}
+
+/**
+ * DSL object definition (key → field mapping).
+ * ⚠️ Must be an interface rather than a type alias to support recursive DslField ↔ DslDefinition references.
+ */
+export interface DslDefinition {
+  [key: string]: DslField
+}
+
+/**
+ * v1 conditional field marker (created by dsl.if / dsl.match; compiled to allOf conditional schema during parseObject).
+ */
+export 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.
+ */
+export type DslField = string | IDslBuilder | DslDefinition | DslConditionMarker
+
+/**
+ * DslBuilder constructor input (string or nested definition).
+ */
+export type DslInput = string | DslDefinition
+
+/**
+ * if/conditional function types.
+ */
+export type DslIfFn = (condition: (data: unknown) => boolean) => IConditionalBuilder
+export type DslFieldIfFn = (condition: string, thenSchema: unknown, elseSchema?: unknown) => DslConditionMarker
+
+/**
+ * dsl.error namespace.
+ */
+export 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.
+ */
+export 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
+}

package/src/types/error.ts

@@ -0,0 +1,60 @@
+/**
+ * Error message templates (custom validation error copy).
+ */
+export interface ErrorMessages {
+  // Length / range (v1.0.3+ recommends min/max over minLength/maximum etc.)
+  min?: string
+  max?: string
+  minLength?: string
+  maxLength?: string
+  minimum?: string
+  maximum?: string
+  minItems?: string
+  maxItems?: string
+  // Types
+  type?: string
+  string?: string
+  number?: string
+  integer?: string
+  boolean?: string
+  array?: string
+  object?: string
+  // Formats
+  email?: string
+  url?: string
+  date?: string
+  dateTime?: string
+  uuid?: string
+  ipv4?: string
+  ipv6?: string
+  // Other
+  pattern?: string
+  format?: string
+  required?: string
+  enum?: string
+  uniqueItems?: string
+  // Custom keywords
+  exactLength?: string
+  phone?: string
+  idCard?: string
+  creditCard?: string
+  // Extensible
+  [key: string]: string | undefined
+}
+
+/**
+ * Error code constant type (shape of the ErrorCodes object).
+ */
+export interface ErrorCodeMap {
+  // Validation errors
+  VALIDATION_ERROR: 'VALIDATION_ERROR'
+  INVALID_SCHEMA: 'INVALID_SCHEMA'
+  // Config errors
+  INVALID_CONFIG: 'INVALID_CONFIG'
+  INVALID_LOCALE: 'INVALID_LOCALE'
+  // Plugin errors
+  PLUGIN_INSTALL_ERROR: 'PLUGIN_INSTALL_ERROR'
+  PLUGIN_NOT_FOUND: 'PLUGIN_NOT_FOUND'
+  // Extensible
+  [key: string]: string
+}

package/src/types/index.ts

@@ -0,0 +1,17 @@
+// --- Core types ---
+export type { JSONSchema, SchemaIOOptions } from './schema.js'
+export type {
+  DslFn,
+  DslField,
+  DslDefinition,
+  DslInput,
+  IDslBuilder,
+  DslIfFn,
+  DslErrorNamespace,
+} from './dsl.js'
+export type { ValidateOptions, ValidationResult, ValidationErrorItem, AjvError } from './validate.js'
+export type { DslConfigOptions, I18nConfig, CacheOptions, ValidatorOptions } from './config.js'
+export type { ErrorMessages, ErrorCodeMap } from './error.js'
+export type { Plugin, HookFn, HookName, HookContext, PluginManagerOptions } from './plugin.js'
+export type { IConditionalBuilder } from './conditional.js'
+export type { InferSchema, InferJsonSchema, InferDslDefinition, InferDslString } from './infer.js'

package/src/types/infer.ts

@@ -0,0 +1,128 @@
+type StripMarker<S extends string> = S extends `${infer Base}!` | `${infer Base}?` ? Base : S
+
+type KnownDslType =
+    | 'string'
+    | 'email'
+    | 'url'
+    | 'uri'
+    | 'uuid'
+    | 'ipv4'
+    | 'ipv6'
+    | 'ip'
+    | 'hostname'
+    | 'date'
+    | 'datetime'
+    | 'time'
+    | 'binary'
+    | 'objectId'
+    | 'hexColor'
+    | 'macAddress'
+    | 'cron'
+    | 'slug'
+    | 'chineseName'
+    | 'chinese'
+    | 'emailDomain'
+    | 'alphanum'
+    | 'lower'
+    | 'upper'
+    | 'json'
+    | 'port'
+    | 'number'
+    | 'integer'
+    | 'boolean'
+    | 'object'
+    | 'array'
+    | 'null'
+    | 'any'
+
+type InferPipeMember<S extends string> = StripMarker<S> extends KnownDslType ? InferDslString<S> : StripMarker<S>
+
+type SplitPipe<S extends string> = S extends `${infer Head}|${infer Tail}`
+    ? InferPipeMember<Head> | SplitPipe<Tail>
+    : InferPipeMember<S>
+
+type RequiredDslKeys<T extends Record<string, unknown>> = {
+    [K in keyof T]: K extends string
+    ? K extends `${infer Name}!`
+    ? Name
+    : T[K] extends `${string}!`
+    ? K
+    : never
+    : never
+}[keyof T]
+
+type CleanDslKey<K> = K extends `${infer Name}!` | `${infer Name}?` ? Name : K
+
+type InferJsonSchemaProperties<Properties, RequiredKeys extends PropertyKey> =
+    & {
+        [K in keyof Properties as K extends RequiredKeys ? K : never]-?: InferSchema<Properties[K]>
+    }
+    & {
+        [K in keyof Properties as K extends RequiredKeys ? never : K]?: InferSchema<Properties[K]>
+    }
+
+type InferDslProperties<T extends Record<string, unknown>, RequiredKeys extends PropertyKey = RequiredDslKeys<T>> =
+    & {
+        [K in keyof T as CleanDslKey<K> extends RequiredKeys ? CleanDslKey<K> : never]-?: InferSchema<T[K]>
+    }
+    & {
+        [K in keyof T as CleanDslKey<K> extends RequiredKeys ? never : CleanDslKey<K>]?: InferSchema<T[K]>
+    }
+
+export type InferDslString<T extends string> = StripMarker<T> extends `types:${infer Rest}`
+    ? SplitPipe<Rest>
+    : StripMarker<T> extends `enum:${infer Values}`
+    ? SplitPipe<Values>
+    : StripMarker<T> extends `array<${infer Item}>`
+    ? InferDslString<Item>[]
+    : StripMarker<T> extends `${infer Base}:${string}`
+    ? InferDslString<Base>
+    : StripMarker<T> extends 'number' | 'integer' | 'port'
+    ? number
+    : StripMarker<T> extends 'boolean'
+    ? boolean
+    : StripMarker<T> extends 'object'
+    ? Record<string, unknown>
+    : StripMarker<T> extends 'array'
+    ? unknown[]
+    : StripMarker<T> extends 'null'
+    ? null
+    : StripMarker<T> extends 'any'
+    ? unknown
+    : StripMarker<T> extends `${string}|${string}`
+    ? SplitPipe<StripMarker<T>>
+    : string
+
+export type InferJsonSchema<T> = T extends { oneOf: readonly (infer Variant)[] }
+    ? InferSchema<Variant>
+    : T extends { anyOf: readonly (infer Variant)[] }
+    ? InferSchema<Variant>
+    : T extends { enum: readonly (infer Value)[] }
+    ? Value
+    : T extends { type: 'object'; properties: infer Properties; required?: readonly (infer RequiredKey)[] }
+    ? InferJsonSchemaProperties<Properties, Extract<RequiredKey, keyof Properties>>
+    : T extends { type: 'array'; items: infer Item }
+    ? InferSchema<Item>[]
+    : T extends { type: 'number' | 'integer' }
+    ? number
+    : T extends { type: 'boolean' }
+    ? boolean
+    : T extends { type: 'null' }
+    ? null
+    : T extends { type: 'object' }
+    ? Record<string, unknown>
+    : T extends { type: 'array' }
+    ? unknown[]
+    : T extends { type: 'string' }
+    ? string
+    : unknown
+
+export type InferDslDefinition<T extends Record<string, unknown>> = InferDslProperties<T>
+
+export type InferSchema<T> = T extends string
+    ? InferDslString<T>
+    : T extends { type: unknown } | { properties: unknown } | { oneOf: unknown } | { anyOf: unknown } | { enum: unknown }
+    ? InferJsonSchema<T>
+    : T extends Record<string, unknown>
+    ? InferDslDefinition<T>
+    : unknown

package/src/types/plugin.ts

@@ -0,0 +1,58 @@
+/**
+ * Built-in hook names (pipeline execution phases).
+ */
+export type HookName =
+  | 'beforeParse'
+  | 'afterParse'
+  | 'beforeCompile'
+  | 'afterCompile'
+  | 'beforeValidate'
+  | 'afterValidate'
+  | 'onError'
+
+/**
+ * Hook function type (accepts arbitrary arguments; compatible with v1 custom hook names).
+ */
+export type HookFn = (...args: unknown[]) => unknown | Promise<unknown>
+
+/**
+ * Hook context (passed to built-in hooks).
+ */
+export interface HookContext {
+  /** Current hook phase. */
+  hook: HookName
+  /** Data being processed. */
+  data?: unknown
+  /** DSL definition. */
+  schema?: unknown
+  /** Additional metadata. */
+  meta?: Record<string, unknown>
+}
+
+/**
+ * Plugin interface (backwards-compatible with v1).
+ */
+export interface Plugin {
+  /** Plugin name. */
+  name: string
+  /** Plugin version. */
+  version?: string
+  /** Plugin description. */
+  description?: string
+  /** Plugin options (passed as the second argument to install). */
+  options?: Record<string, unknown>
+  /** Plugin hook map (supports arbitrary hook names for v1 compatibility). */
+  hooks?: Record<string, HookFn>
+  /** Install method. */
+  install?(core: unknown, options?: unknown, context?: unknown): void
+  /** Uninstall method (optional). */
+  uninstall?(core?: unknown, context?: unknown): void
+}
+
+/**
+ * PluginManager configuration.
+ */
+export interface PluginManagerOptions {
+  /** Whether hooks are executed asynchronously (default true). */
+  async?: boolean
+}

package/src/types/safe-regex.d.ts

@@ -0,0 +1,9 @@
+declare module 'safe-regex' {
+  interface SafeRegexOptions {
+    limit?: number
+  }
+
+  export default function safeRegex(pattern: string | RegExp, options?: SafeRegexOptions): boolean
+}
+
+

package/src/types/schema.ts

@@ -0,0 +1,66 @@
+/**
+ * JSON Schema Draft 7 type definitions.
+ * Includes schema-dsl internal keys (prefixed with _; stripped by toJsonSchema()).
+ */
+import type { ErrorMessages } from './error.js'
+
+export interface JSONSchema {
+  // --- Standard JSON Schema Draft 7 fields ---
+  type?: string | string[]
+  properties?: Record<string, JSONSchema>
+  required?: string[]
+  minLength?: number
+  maxLength?: number
+  minimum?: number
+  maximum?: number
+  exclusiveMinimum?: number | boolean
+  exclusiveMaximum?: number | boolean
+  multipleOf?: number
+  pattern?: string
+  format?: string
+  enum?: unknown[]
+  const?: unknown
+  items?: JSONSchema | JSONSchema[]
+  minItems?: number
+  maxItems?: number
+  uniqueItems?: boolean
+  additionalProperties?: boolean | JSONSchema
+  allOf?: JSONSchema[]
+  anyOf?: JSONSchema[]
+  oneOf?: JSONSchema[]
+  not?: JSONSchema
+  if?: JSONSchema
+  then?: JSONSchema
+  else?: JSONSchema
+  title?: string
+  description?: string
+  default?: unknown
+  examples?: unknown[]
+  $ref?: string
+  $schema?: string
+  $id?: string
+  definitions?: Record<string, JSONSchema>
+  $defs?: Record<string, JSONSchema>
+
+  // --- schema-dsl internal keys (used during parsing; stripped on output) ---
+  _label?: string
+  _customMessages?: Record<string, string>
+  _description?: string
+  _required?: boolean
+
+  // Allows custom keyword extensions (AJV custom keywords)
+  [key: string]: unknown
+}
+
+/**
+ * SchemaIO configuration options (backwards-compatible with v1).
+ */
+export interface SchemaIOOptions {
+  allErrors?: boolean
+  verbose?: boolean
+  messages?: ErrorMessages
+  locale?: string
+  cache?: boolean
+  cacheSize?: number
+  [key: string]: unknown
+}

package/src/types/validate.ts

@@ -0,0 +1,71 @@
+/**
+ * Validation options.
+ */
+import type { CacheOptions } from './config.js'
+import type { ErrorMessages } from './error.js'
+
+export interface ValidateOptions {
+  /** Whether to format errors (default true). */
+  format?: boolean
+  /** Whether to return all errors (default false — only the first). */
+  allErrors?: boolean
+  /** Dynamically specify a locale (e.g. 'zh-CN', 'en-US', 'ja-JP', 'es-ES', 'fr-FR'). */
+  locale?: string
+  /** Custom error messages. */
+  messages?: ErrorMessages
+  /** Whether to enable smart type coercion (auto-converts string → number etc.). */
+  smartCoerce?: boolean
+  /** Whether to remove additional properties. */
+  removeAdditional?: boolean | 'all' | 'failing'
+  /** Whether to enable caching. */
+  cache?: boolean | CacheOptions
+  /** Whether to enable strict mode. */
+  strict?: boolean
+  [key: string]: unknown
+}
+
+/**
+ * Validation result.
+ */
+export interface ValidationResult<T = unknown> {
+  /** Whether validation passed. */
+  valid: boolean
+  /** Snapshot of the data after validation (returned on both success and failure; useful for locating input on failure). */
+  data?: T
+  /** Error list (empty array on success; detailed errors on failure). */
+  errors?: ValidationErrorItem[]
+  /** First error message (convenience accessor). */
+  errorMessage?: string
+}
+
+/**
+ * Validation error item (element of ValidationResult.errors).
+ */
+export interface ValidationErrorItem {
+  /** Error message. */
+  message: string
+  /** Error field path (dot-separated, e.g. 'user.email'). */
+  path: string
+  /** Validation keyword (min, max, email, pattern, etc.). */
+  keyword: string
+  /** Validation parameters. */
+  params?: Record<string, unknown>
+  /** Alias for path (backwards compatibility). */
+  field?: string
+  /** Alias for keyword (backwards-compatible with v1 err.type). */
+  type?: string | undefined
+  /** Expected type (backwards-compatible with v1 err.expected; only present for type errors). */
+  expected?: string | undefined
+}
+
+/**
+ * Raw AJV error object type (internal use).
+ */
+export interface AjvError {
+  keyword: string
+  instancePath: string
+  schemaPath: string
+  params: Record<string, unknown>
+  message?: string
+  data?: unknown
+}