schema-dsl 1.2.5 → 2.0.1

package/src/parser/TypeRegistry.ts

@@ -0,0 +1,250 @@
+import type { JSONSchema } from '../types/schema.js'
+
+/**
+ * Type definition (structure of each entry in TypeRegistry)
+ */
+export interface TypeDefinition {
+  /** Base JSON Schema fragment for this type */
+  baseSchema: Partial<JSONSchema>
+  /** Custom messages associated with this type (e.g., error key for phone type) */
+  customMessages?: Record<string, string>
+  /** Whether this type uses a pattern (keys are standard JSON Schema fields, not stripped in toJsonSchema) */
+  isPattern?: boolean
+}
+
+/** Known internal key set (stripped from output during toJsonSchema) */
+const INTERNAL_KEYS: ReadonlySet<string> = new Set([
+  '_label',
+  '_customMessages',
+  '_description',
+  '_required',
+  '_isConditional',
+  '_runtimeOnlyConditional',
+  'conditions',
+  '_evaluateCondition',
+  // Custom AJV keywords (non-standard JSON Schema fields, stripped on output)
+  'exactLength',
+  'alphanum',
+  'lowercase',
+  'uppercase',
+  'trim',
+  'jsonString',
+  'port',
+  'requiredAll',
+  'strictSchema',
+  'noSparse',
+  'includesRequired',
+  'dateFormat',
+  'dateGreater',
+  'dateLess',
+  'precision',
+  // ⚠️ multipleOf is a standard JSON Schema field and is NOT in this list (fix DB-01)
+])
+
+/**
+ * Built-in type registry
+ * 33 types covering v1 DslAdapter.typeMap + DslBuilder type lists (fixes inconsistencies DB-02, DA-01)
+ */
+const BUILTIN_TYPES: Map<string, TypeDefinition> = new Map([
+  // --- Primitive types ---
+  ['string', { baseSchema: { type: 'string' } }],
+  ['number', { baseSchema: { type: 'number' } }],
+  ['integer', { baseSchema: { type: 'integer' } }],
+  ['boolean', { baseSchema: { type: 'boolean' } }],
+  ['object', { baseSchema: { type: 'object' } }],
+  ['array', { baseSchema: { type: 'array' } }],
+  ['null', { baseSchema: { type: 'null' } }],
+  ['any', { baseSchema: {} }],
+
+  // --- Format types ---
+  ['email', { baseSchema: { type: 'string', format: 'email' } }],
+  ['url', { baseSchema: { type: 'string', format: 'uri' } }],
+  ['uri', { baseSchema: { type: 'string', format: 'uri' } }],
+  ['uuid', { baseSchema: { type: 'string', format: 'uuid' } }],
+  ['ipv4', { baseSchema: { type: 'string', format: 'ipv4' } }],
+  ['ipv6', { baseSchema: { type: 'string', format: 'ipv6' } }],
+  ['ip', { baseSchema: { anyOf: [{ type: 'string', format: 'ipv4' }, { type: 'string', format: 'ipv6' }] } }],
+  ['hostname', { baseSchema: { type: 'string', format: 'hostname' } }],
+  ['date', { baseSchema: { type: 'string', format: 'date' } }],
+  ['datetime', { baseSchema: { type: 'string', format: 'date-time' } }],
+  ['time', { baseSchema: { type: 'string', format: 'time' } }],
+
+  // --- Special string types ---
+  ['binary', { baseSchema: { type: 'string', contentEncoding: 'base64' } }],
+  ['objectId', { baseSchema: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }, customMessages: { pattern: 'pattern.objectId' } }],
+  ['hexColor', { baseSchema: { type: 'string', pattern: '^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$' }, customMessages: { pattern: 'pattern.hexColor' } }],
+  ['macAddress', {
+    baseSchema: { type: 'string', pattern: '^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$' },
+    customMessages: { pattern: 'pattern.macAddress' },
+  }],
+  ['cron', {
+    baseSchema: {
+      type: 'string',
+      pattern:
+        '^(\\*|([0-9]|1[0-9]|2[0-9]|3[0-9]|4[0-9]|5[0-9])|\\*\\/([0-9]|1[0-9]|2[0-9]|3[0-9]|4[0-9]|5[0-9])) ' +
+        '(\\*|([0-9]|1[0-9]|2[0-3])|\\*\\/([0-9]|1[0-9]|2[0-3])) ' +
+        '(\\*|([1-9]|1[0-9]|2[0-9]|3[0-1])|\\*\\/([1-9]|1[0-9]|2[0-9]|3[0-1])) ' +
+        '(\\*|([1-9]|1[0-2])|\\*\\/([1-9]|1[0-2])) ' +
+        '(\\*|([0-6])|\\*\\/([0-6]))$',
+    },
+    customMessages: { pattern: 'pattern.cron' },
+  }],
+
+  // --- slug (fix DB-02: v1 DslAdapter was missing slug type definition) ---
+  ['slug', {
+    baseSchema: { type: 'string', pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' },
+    customMessages: { pattern: 'pattern.slug' },
+  }],
+
+  // --- CJK / Chinese ---
+  ['chineseName', {
+    baseSchema: { type: 'string', pattern: '^[\\u4e00-\\u9fa5]{2,10}$' },
+    customMessages: { pattern: 'chineseName' },
+  }],
+  ['chinese', {
+    baseSchema: { type: 'string', pattern: '^[\\u4e00-\\u9fa5]+$' },
+  }],
+
+  // --- Domain-related (handled by CustomKeywords; only baseSchema registered here) ---
+  ['emailDomain', { baseSchema: { type: 'string', format: 'email' } }],
+
+  // --- v1 extension types (DslBuilder v1.0.2) ---
+  ['alphanum', { baseSchema: { type: 'string', alphanum: true } }],
+  ['lower', { baseSchema: { type: 'string', lowercase: true } }],
+  ['upper', { baseSchema: { type: 'string', uppercase: true } }],
+  ['json', { baseSchema: { type: 'string', jsonString: true } }],
+  ['port', { baseSchema: { type: 'integer', port: true } }],
+])
+
+/**
+ * Custom type registry (populated via registerType)
+ */
+const CUSTOM_TYPES: Map<string, TypeDefinition> = new Map()
+const DYNAMIC_TYPES: Map<string, () => JSONSchema> = new Map()
+
+let _strictMode = false
+
+/**
+ * TypeRegistry — unified type registration and resolution
+ *
+ * Replaces the three inconsistent type lists in v1 (fixes DB-01/DB-02/DA-01)
+ */
+export const TypeRegistry = {
+  /**
+   * Resolve a type name to its TypeDefinition.
+   * Built-in types take priority; custom types may override non-primitive built-ins.
+   */
+  resolve(typeName: string): TypeDefinition {
+    // Dynamic types: call factory function each time
+    const dynamicFn = DYNAMIC_TYPES.get(typeName)
+    if (dynamicFn) {
+      return { baseSchema: dynamicFn() as Partial<JSONSchema> }
+    }
+
+    const custom = CUSTOM_TYPES.get(typeName)
+    if (custom) return custom
+
+    const builtin = BUILTIN_TYPES.get(typeName)
+    if (builtin) return builtin
+
+    // Unknown type: throw in strict mode, otherwise warn and fall back to string
+    if (_strictMode) {
+      throw new Error(`[schema-dsl] Unknown type "${typeName}"`)
+    }
+    console.warn(`[schema-dsl] Unknown type "${typeName}", falling back to string`)
+    return { baseSchema: { type: 'string' } }
+  },
+
+  /**
+   * Register a custom type (delegated from DslBuilder.registerType)
+   */
+  register(name: string, def: TypeDefinition | Partial<JSONSchema>): void {
+    if (!name || typeof name !== 'string') {
+      throw new Error('[schema-dsl] TypeRegistry.register: name must be a non-empty string')
+    }
+    // Accept a raw Partial<JSONSchema> and wrap it automatically
+    const normalized: TypeDefinition =
+      'baseSchema' in def ? (def as TypeDefinition) : { baseSchema: def as Partial<JSONSchema> }
+    CUSTOM_TYPES.set(name, normalized)
+  },
+
+  /**
+   * Register a dynamic type (factory function invoked on every resolve call)
+   */
+  registerDynamic(name: string, factory: () => JSONSchema): void {
+    if (!name || typeof name !== 'string') {
+      throw new Error('[schema-dsl] TypeRegistry.registerDynamic: name must be a non-empty string')
+    }
+    DYNAMIC_TYPES.set(name, factory)
+  },
+
+  /**
+   * Unregister a custom type
+   */
+  unregister(name: string): void {
+    CUSTOM_TYPES.delete(name)
+    DYNAMIC_TYPES.delete(name)
+  },
+
+  /**
+   * Clear all custom and dynamic types (primarily for testing; called by DslBuilder.clearCustomTypes).
+   * Built-in types are unaffected.
+   */
+  clearCustomTypes(): void {
+    CUSTOM_TYPES.clear()
+    DYNAMIC_TYPES.clear()
+  },
+
+  /**
+   * Enable or disable strict mode for type resolution.
+   * In strict mode, resolving an unknown type throws instead of warning and falling back to string.
+   */
+  setStrict(flag: boolean): void {
+    _strictMode = flag
+  },
+
+  /**
+   * Check whether a type is registered (built-in or custom)
+   */
+  has(typeName: string): boolean {
+    return BUILTIN_TYPES.has(typeName) || CUSTOM_TYPES.has(typeName) || DYNAMIC_TYPES.has(typeName)
+  },
+
+  /**
+   * Return an iterator over all registered types (built-in + custom; custom overrides same-name built-in)
+   * BC-4 compat: consumed by the DslAdapter.typeMap getter
+   */
+  entries(): IterableIterator<[string, TypeDefinition]> {
+    const merged: Map<string, TypeDefinition> = new Map([...BUILTIN_TYPES, ...CUSTOM_TYPES])
+    return merged.entries()
+  },
+
+  /**
+   * Return the internal key set (used to strip non-standard fields during toJsonSchema)
+   */
+  getInternalKeys(): ReadonlySet<string> {
+    return INTERNAL_KEYS
+  },
+
+  /**
+   * Strip internal keys from a schema and return a clean JSON Schema.
+   *
+   * Special case for exactLength: translated to standard minLength + maxLength
+   * instead of being stripped. This preserves v1 DslBuilder string:N behavior
+   * (output {minLength:N, maxLength:N}) while keeping AJV's exactLength Unicode
+   * code-point counting advantage internally (CK-Y04).
+   */
+  toJsonSchema(schema: JSONSchema): JSONSchema {
+    const result: JSONSchema = {}
+    for (const [k, v] of Object.entries(schema)) {
+      if (k === 'exactLength' && typeof v === 'number') {
+        // BC-compat: exactLength (AJV custom keyword) → standard JSON Schema minLength + maxLength
+        result.minLength = v
+        result.maxLength = v
+      } else if (!INTERNAL_KEYS.has(k)) {
+        result[k] = v
+      }
+    }
+    return result
+  },
+} as const

package/src/parser/index.ts

@@ -0,0 +1,6 @@
+export { TypeRegistry } from './TypeRegistry.js'
+export type { TypeDefinition } from './TypeRegistry.js'
+export { ConstraintParser } from './ConstraintParser.js'
+export { SchemaCompiler } from './SchemaCompiler.js'
+export type { AfterCompileHook } from './SchemaCompiler.js'
+export { DslParser } from './DslParser.js'

package/src/plugins/custom-format.ts

@@ -0,0 +1,124 @@
+import type { Plugin } from '../types/plugin.js'
+import { DslBuilder } from '../core/DslBuilder.js'
+import type { Validator } from '../core/Validator.js'
+
+interface FormatConfig {
+  pattern?: RegExp
+  validate?: (value: string) => boolean
+  schema: Record<string, unknown>
+}
+
+const FORMATS: Record<string, FormatConfig> = {
+  'phone-cn': {
+    pattern: /^1[3-9]\d{9}$/,
+    schema: { type: 'string', pattern: /^1[3-9]\d{9}$/.source, minLength: 11, maxLength: 11 },
+  },
+  'postal-code-cn': {
+    pattern: /^\d{6}$/,
+    schema: { type: 'string', pattern: /^\d{6}$/.source, minLength: 6, maxLength: 6 },
+  },
+  'ipv4-custom': {
+    pattern: /^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/,
+    schema: { type: 'string', format: 'ipv4' },
+  },
+  'wechat': {
+    pattern: /^[a-zA-Z][-_a-zA-Z0-9]{5,19}$/,
+    schema: { type: 'string', pattern: /^[a-zA-Z][-_a-zA-Z0-9]{5,19}$/.source, minLength: 6, maxLength: 20 },
+  },
+  'qq': {
+    pattern: /^[1-9][0-9]{4,10}$/,
+    schema: { type: 'string', pattern: /^[1-9][0-9]{4,10}$/.source, minLength: 5, maxLength: 11 },
+  },
+  'bank-card': {
+    validate: (value: string) => {
+      if (!/^\d{16,19}$/.test(value)) return false
+
+      let sum = 0
+      let shouldDouble = false
+
+      for (let i = value.length - 1; i >= 0; i -= 1) {
+        let digit = Number.parseInt(value[i], 10)
+
+        if (shouldDouble) {
+          digit *= 2
+          if (digit > 9) digit -= 9
+        }
+
+        sum += digit
+        shouldDouble = !shouldDouble
+      }
+
+      return sum % 10 === 0
+    },
+    schema: { type: 'string', minLength: 16, maxLength: 19, pattern: /^\d{16,19}$/.source },
+  },
+  'license-plate': {
+    pattern: /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-HJ-NP-Z0-9]{4,5}[A-HJ-NP-Z0-9挂学警港澳]$/,
+    schema: {
+      type: 'string',
+      pattern: /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-HJ-NP-Z0-9]{4,5}[A-HJ-NP-Z0-9挂学警港澳]$/.source,
+    },
+  },
+  'credit-code': {
+    pattern: /^[0-9A-HJ-NPQRTUWXY]{2}\d{6}[0-9A-HJ-NPQRTUWXY]{10}$/,
+    schema: {
+      type: 'string',
+      pattern: /^[0-9A-HJ-NPQRTUWXY]{2}\d{6}[0-9A-HJ-NPQRTUWXY]{10}$/.source,
+      minLength: 18,
+      maxLength: 18,
+    },
+  },
+  'passport-cn': {
+    pattern: /^[EG]\d{8}$/,
+    schema: { type: 'string', pattern: /^[EG]\d{8}$/.source, minLength: 9, maxLength: 9 },
+  },
+  'hk-macao-pass': {
+    pattern: /^[HM]\d{8,10}$/,
+    schema: { type: 'string', pattern: /^[HM]\d{8,10}$/.source, minLength: 9, maxLength: 11 },
+  },
+}
+
+function getAjvLike(core: unknown): {
+  addFormat: (name: string, definition: RegExp | { validate: RegExp | ((value: string) => boolean) }) => void
+} {
+  const coreRecord = core as { getDefaultValidator?: () => Validator }
+  const validator = coreRecord.getDefaultValidator?.()
+  if (!validator) {
+    throw new Error('getDefaultValidator() is not available. Please provide schema-dsl core object.')
+  }
+  return validator.getAjv() as {
+    addFormat: (name: string, definition: RegExp | { validate: RegExp | ((value: string) => boolean) }) => void
+  }
+}
+
+function getDslBuilderLike(core: unknown): typeof DslBuilder {
+  const coreRecord = core as { DslBuilder?: typeof DslBuilder }
+  return coreRecord.DslBuilder ?? DslBuilder
+}
+
+export const customFormatPlugin: Plugin & {
+  addCustomFormats: (ajv: { addFormat: (name: string, definition: { validate: RegExp | ((value: string) => boolean) }) => void }, dslBuilder: typeof DslBuilder) => void
+} = {
+  name: 'custom-format',
+  version: '2.0.0',
+  description: 'Custom format validation plugin (with DSL type registration)',
+  install(core, _options = {}, _context) {
+    const ajv = getAjvLike(core)
+    const dslBuilder = getDslBuilderLike(core)
+    this.addCustomFormats(ajv, dslBuilder)
+  },
+  uninstall() {
+  },
+  addCustomFormats(ajv, dslBuilder) {
+    for (const [name, config] of Object.entries(FORMATS)) {
+      ajv.addFormat(name, {
+        validate: config.validate ?? config.pattern!,
+      })
+      dslBuilder.registerType(name, config.schema)
+    }
+  },
+}
+
+export default customFormatPlugin
+
+

package/src/plugins/custom-type-example.ts

@@ -0,0 +1,106 @@
+import type { Plugin } from '../types/plugin.js'
+import { DslBuilder } from '../core/DslBuilder.js'
+
+export const customTypeExamplePlugin: Plugin & {
+  registerCustomTypes: (dslBuilder: typeof DslBuilder) => void
+} = {
+  name: 'custom-type-example',
+  version: '1.0.0',
+  description: 'Custom type registration example plugin',
+  install(core, _options = {}, _context) {
+    const coreRecord = core as { DslBuilder?: typeof DslBuilder }
+    const builder = coreRecord.DslBuilder ?? DslBuilder
+
+    if (!builder || typeof builder.registerType !== 'function') {
+      throw new Error('DslBuilder.registerType is not available. Please upgrade to schema-dsl v1.1.0+')
+    }
+
+    this.registerCustomTypes(builder)
+  },
+  uninstall() {
+  },
+  registerCustomTypes(dslBuilder) {
+    dslBuilder.registerType('order-id', {
+      type: 'string',
+      pattern: /^ORD[0-9]{12}$/.source,
+      minLength: 15,
+      maxLength: 15,
+      _customMessages: {
+        pattern: 'Invalid order ID format; must be 15 characters starting with ORD',
+      },
+    })
+
+    dslBuilder.registerType('sku', {
+      type: 'string',
+      pattern: /^SKU-[A-Z0-9]{6,10}$/.source,
+      minLength: 10,
+      maxLength: 14,
+      _customMessages: {
+        pattern: 'Invalid SKU format; must be SKU- followed by 6–10 alphanumeric characters',
+      },
+    })
+
+    dslBuilder.registerType('price', {
+      type: 'number',
+      minimum: 0,
+      multipleOf: 0.01,
+      _customMessages: {
+        minimum: 'Price cannot be negative',
+        multipleOf: 'Price can have at most 2 decimal places',
+      },
+    })
+
+    dslBuilder.registerType('rating', {
+      type: 'integer',
+      minimum: 1,
+      maximum: 5,
+      _customMessages: {
+        minimum: 'Rating cannot be lower than 1 star',
+        maximum: 'Rating cannot exceed 5 stars',
+      },
+    })
+
+    dslBuilder.registerType('color-code', {
+      oneOf: [
+        { type: 'string', pattern: /^#[0-9A-Fa-f]{6}$/.source },
+        { type: 'string', pattern: /^#[0-9A-Fa-f]{3}$/.source },
+        { type: 'string', pattern: /^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/.source },
+        { type: 'string', pattern: /^rgba\(\d{1,3},\s*\d{1,3},\s*\d{1,3},\s*(0|1|0?\.\d+)\)$/.source },
+      ],
+    })
+
+    dslBuilder.registerType('semver', {
+      type: 'string',
+      pattern: /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/.source,
+      _customMessages: {
+        pattern: 'Invalid version format; must follow semantic versioning (e.g. 1.0.0, 2.1.3-beta.1)',
+      },
+    })
+
+    dslBuilder.registerType('dynamic-age', () => {
+      const currentYear = new Date().getFullYear()
+      return {
+        type: 'integer',
+        minimum: 0,
+        maximum: currentYear - 1900,
+        _customMessages: {
+          minimum: 'Age cannot be negative',
+          maximum: `Age cannot exceed ${currentYear - 1900} years`,
+        },
+      }
+    })
+
+    dslBuilder.registerType('phone-intl', {
+      type: 'string',
+      pattern: /^\+?[1-9]\d{1,14}$/.source,
+      minLength: 8,
+      maxLength: 15,
+      _customMessages: {
+        pattern: 'Please enter a valid international phone number (E.164 format)',
+      },
+    })
+  },
+}
+
+export default customTypeExamplePlugin
+

package/src/plugins/custom-validator.ts

@@ -0,0 +1,138 @@
+import type { KeywordDefinition } from 'ajv'
+import type { Plugin } from '../types/plugin.js'
+import type { Validator } from '../core/Validator.js'
+
+function getValidator(core: unknown): Validator {
+  const coreRecord = core as { getDefaultValidator?: () => Validator }
+  const validator = coreRecord.getDefaultValidator?.()
+  if (!validator) {
+    throw new Error('getDefaultValidator() is not available. Please provide schema-dsl core object.')
+  }
+  return validator
+}
+
+function getPluginBucket(): Record<string, unknown> {
+  const globalRecord = globalThis as typeof globalThis & {
+    __schemaDsl_plugins?: Record<string, unknown>
+  }
+  if (!globalRecord.__schemaDsl_plugins) {
+    globalRecord.__schemaDsl_plugins = {}
+  }
+  return globalRecord.__schemaDsl_plugins
+}
+
+export const customValidatorPlugin: Plugin & {
+  addCustomKeywords: (validator: Validator) => void
+  _validateIdCardChecksum: (idCard: string) => boolean
+} = {
+  name: 'custom-validator',
+  version: '1.0.0',
+  description: 'Custom validator plugin — adds business-specific validation rules',
+  install(core, _options = {}, _context) {
+    const validator = getValidator(core)
+    this.addCustomKeywords(validator)
+    getPluginBucket()['custom-validator'] = this
+  },
+  uninstall() {
+    delete getPluginBucket()['custom-validator']
+  },
+  addCustomKeywords(validator) {
+    const ajv = validator.getAjv() as {
+      getKeyword?: (name: string) => unknown
+    }
+
+    if (!ajv.getKeyword?.('unique')) {
+      validator.addKeyword('unique', {
+        async: true,
+        type: 'string',
+        validate: async function validateUnique(schema: unknown) {
+          if (!schema) return true
+          const { table, field } = schema as { table?: string; field?: string }
+          const exists = false
+          if (exists) {
+            ;(validateUnique as typeof validateUnique & { errors?: unknown[] }).errors = [{
+              keyword: 'unique',
+              message: `${field} already exists in ${table}`,
+              params: { table, field },
+            }]
+            return false
+          }
+          return true
+        },
+      } as unknown as KeywordDefinition)
+    }
+
+    if (!ajv.getKeyword?.('passwordStrength')) {
+      validator.addKeyword('passwordStrength', {
+        type: 'string',
+        validate: function validatePasswordStrength(schema: unknown, data: unknown) {
+          if (!schema) return true
+
+          const strength = String(schema)
+          const value = String(data ?? '')
+          const rules: Record<string, RegExp> = {
+            weak: /^.{6,}$/,
+            medium: /^(?=.*[a-z])(?=.*[A-Z]).{8,}$/,
+            strong: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{10,}$/,
+          }
+
+          const pattern = rules[strength]
+          if (!pattern) return true
+
+          if (!pattern.test(value)) {
+            ;(validatePasswordStrength as typeof validatePasswordStrength & { errors?: unknown[] }).errors = [{
+              keyword: 'passwordStrength',
+              message: `Password does not meet ${strength} strength requirements`,
+              params: { strength },
+            }]
+            return false
+          }
+
+          return true
+        },
+      } as unknown as KeywordDefinition)
+    }
+
+    if (!ajv.getKeyword?.('idCard')) {
+      validator.addKeyword('idCard', {
+        type: 'string',
+        validate: (schema: unknown, data: unknown) => {
+          if (!schema) return true
+
+          const value = String(data ?? '')
+          const pattern = /^[1-9]\d{5}(19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$/
+
+          if (!pattern.test(value)) {
+            return false
+          }
+
+          return customValidatorPlugin._validateIdCardChecksum(value)
+        },
+      } as unknown as KeywordDefinition)
+    }
+  },
+  _validateIdCardChecksum(idCard: string) {
+    const weights = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2]
+    const checksums = ['1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2']
+
+    let sum = 0
+    for (let i = 0; i < 17; i += 1) {
+      sum += Number.parseInt(idCard[i], 10) * weights[i]
+    }
+
+    const checksum = checksums[sum % 11]
+    return idCard[17].toUpperCase() === checksum
+  },
+  hooks: {
+    onBeforeValidate() {},
+    onAfterValidate() {},
+    onError(error) {
+      console.error('[custom-validator] Error:', (error as Error).message)
+    },
+  },
+}
+
+export default customValidatorPlugin
+
+
+

package/src/types/conditional.ts

@@ -0,0 +1,28 @@
+/**
+ * IConditionalBuilder interface (shape definition).
+ * Implementation class is in src/core/ConditionalBuilder.ts (Phase 8).
+ */
+import type { JSONSchema } from './schema.js'
+import type { ValidationResult } from './validate.js'
+
+export 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
+}