schema-dsl 1.2.5 → 2.0.1

package/src/core/Validator.ts

@@ -0,0 +1,448 @@
+import { Ajv } from 'ajv'
+import type { ValidateFunction, KeywordDefinition, Format } from 'ajv'
+import addFormats from 'ajv-formats'
+import type { JSONSchema } from '../types/schema.js'
+import type { ValidateOptions, ValidationResult, ValidationErrorItem } from '../types/validate.js'
+import type { ErrorMessages } from '../types/error.js'
+import { CacheManager } from './CacheManager.js'
+import type { CacheStats } from './CacheManager.js'
+import { ErrorFormatter } from './ErrorFormatter.js'
+import { CustomKeywords } from '../validators/CustomKeywords.js'
+import { Locale } from './Locale.js'
+import { ConditionalValidator, type ConditionalInternalSchema } from './ConditionalValidator.js'
+
+// Non-AJV custom option keys (V-Y01 fix: filter before passing to new Ajv())
+const NON_AJV_KEYS = new Set([
+  'cache', 'smartCoerce', 'locale', 'messages', 'format',
+  'strict',  // v2 redefines this as strictSchema; do not forward to AJV
+])
+
+// AJV ValidateFunction type
+type AjvValidateFn = ValidateFunction
+type KeywordDefinitionInput = KeywordDefinition | ({ keyword?: string;[key: string]: unknown })
+
+// Schema with _removeAdditional or _isConditional internal markers
+type InternalSchema = JSONSchema & {
+  _removeAdditional?: boolean
+  _isConditional?: boolean
+  _runtimeOnlyConditional?: boolean
+} & ConditionalInternalSchema
+
+// Performance: share empty array on valid path to avoid `{ errors: [] }` allocation every time
+const EMPTY_ERRORS: ValidationErrorItem[] = []
+
+/**
+ * ValidatorOptions — constructor options for Validator (extends AJV base options).
+ */
+export interface ValidatorOptions {
+  allErrors?: boolean
+  useDefaults?: boolean
+  coerceTypes?: boolean | 'array'
+  removeAdditional?: boolean | 'all' | 'failing'
+  verbose?: boolean
+  cache?: boolean | {
+    maxSize?: number
+    ttl?: number
+    enabled?: boolean
+    statsEnabled?: boolean
+  }
+  [key: string]: unknown
+}
+
+/**
+ * Validator — AJV-backed validator (v2).
+ *
+ * Fixes:
+ *   V-Y01: filter non-AJV options before new Ajv() to prevent unknown-option warnings
+ *   V-02:  sync cleanSchema.required when conditional fields are removed (v1 missed this)
+ *   V-Y03: _removeAdditional mode reuses cached internal Ajv instance (v1 created new Validator each time)
+ *   V-Y07: static quickValidate reuses a singleton Ajv (v1 created new Ajv each time)
+ */
+export class Validator {
+  private readonly _ajvOptions: Record<string, unknown>
+  private readonly _ajv: InstanceType<typeof Ajv>
+  private readonly _cache: CacheManager
+  private readonly _errorFormatter: ErrorFormatter
+
+  // WeakMap: schema object → unique cacheKey (avoids JSON.stringify)
+  private readonly _schemaMap = new WeakMap<object, string>()
+  private _schemaKeyCounter = 0
+
+  // Performance: cache whether a schema has any conditional fields (avoids traversing properties on every validation)
+  private readonly _conditionalFlagCache = new WeakMap<object, boolean>()
+  private readonly _conditionalValidator = new ConditionalValidator({
+    validateSchema: <T>(schema: JSONSchema, data: T, options: ValidateOptions): ValidationResult<T> => this._validateInternal(schema, data, options),
+    internalError: <T>(error: unknown, data: T): ValidationResult<T> => this._internalError(error, data),
+  })
+
+  // V-Y03 fix: cached removeAdditional Ajv instance (no longer new Validator each time)
+  private _removeAdditionalAjv: InstanceType<typeof Ajv> | null = null
+
+  // V-Y07 fix: static singleton Ajv
+  private static _quickValidateAjv: InstanceType<typeof Ajv> | null = null
+
+  constructor(options: ValidatorOptions = {}) {
+    // V-Y01 fix: filter non-AJV options
+    const ajvOptions: Record<string, unknown> = {
+      allErrors: options.allErrors !== false,
+      useDefaults: options.useDefaults !== false,
+      coerceTypes: options.coerceTypes ?? false,
+      removeAdditional: options.removeAdditional ?? false,
+      verbose: true, // verbose mode: enables parentSchema access on error objects
+    }
+
+    // Forward remaining valid AJV options
+    for (const [k, v] of Object.entries(options)) {
+      if (!NON_AJV_KEYS.has(k) && !(k in ajvOptions)) {
+        ajvOptions[k] = v
+      }
+    }
+
+    this._ajvOptions = ajvOptions
+    this._ajv = new Ajv(ajvOptions)
+      ; (addFormats as unknown as (a: InstanceType<typeof Ajv>) => void)(this._ajv)
+    CustomKeywords.registerAll(this._ajv)
+
+    const cacheOpts = options.cache === false
+      ? { enabled: false }
+      : options.cache === true || options.cache == null
+        ? {}
+        : options.cache
+
+    this._cache = new CacheManager({
+      ...(cacheOpts.maxSize !== undefined ? { maxSize: cacheOpts.maxSize } : {}),
+      ...(cacheOpts.ttl !== undefined ? { ttl: cacheOpts.ttl } : {}),
+      ...(cacheOpts.enabled !== undefined ? { enabled: cacheOpts.enabled } : {}),
+      ...(cacheOpts.statsEnabled !== undefined ? { statsEnabled: cacheOpts.statsEnabled } : {}),
+    })
+
+    this._errorFormatter = new ErrorFormatter()
+  }
+
+  get ajvOptions(): Record<string, unknown> {
+    return this._ajvOptions
+  }
+
+  // ─── Public API ────────────────────────────────────────────────────────
+
+  /**
+   * Compile a schema → AJV validate function (with cache).
+   */
+  compile(schema: JSONSchema, cacheKey?: string | null): AjvValidateFn {
+    const key = cacheKey ?? null
+
+    if (key) {
+      const cached = this._cache.get(key) as AjvValidateFn | null
+      if (cached !== null) return cached
+    }
+
+    try {
+      const validate = this._ajv.compile(schema)
+      if (key) this._cache.set(key, validate as unknown as object)
+      return validate
+    } catch (error) {
+      throw new Error(`Schema compilation failed: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  /**
+   * Synchronous validation.
+   */
+  validate<T = unknown>(schema: JSONSchema | AjvValidateFn, data: T, options: ValidateOptions = {}): ValidationResult<T> {
+    return this._validateInternal(schema, data, options)
+  }
+
+  /**
+   * Async validation (throws ValidationError on failure).
+   * V-Y02 fix: v1 validateAsync lacked smartCoerceTypes; v2 routes through _validateInternal uniformly.
+   * BC-6 fix: validateAsync runs async custom validators (sync AJV pass skips async fn; this method runs the full set).
+   */
+  async validateAsync<T = unknown>(schema: JSONSchema | AjvValidateFn, data: T, options: ValidateOptions = {}): Promise<T> {
+    // Resolve DslBuilder/ObjectDslBuilder duck type to raw schema (mirrors _validateInternal logic)
+    // so _runCustomValidators can access schema._customValidators
+    let resolvedSchema = schema as JSONSchema
+    if (typeof (schema as Record<string, unknown>)['toSchema'] === 'function') {
+      const obj = schema as Record<string, unknown>
+      resolvedSchema = (obj['toSchema'] as () => JSONSchema)()
+    }
+
+    const result = this._validateInternal(schema, data, options)
+    if (!result.valid) {
+      const { ValidationError } = await import('../errors/ValidationError.js')
+      throw new ValidationError(result.errors ?? [], data)
+    }
+
+    // BC-6: run async custom validators (sync AJV pass skips Promise-returning validators)
+    const customErr = await this._runCustomValidators(resolvedSchema, data)
+    if (customErr) {
+      const { ValidationError } = await import('../errors/ValidationError.js')
+      throw new ValidationError([customErr], data)
+    }
+
+    return result.data as T
+  }
+
+  /**
+   * BC-6: run all validators in schema._customValidators (including async).
+   * AJV's sync keyword skips Promise-returning validators; this method runs the complete set in validateAsync.
+   * Returns the first failing ValidationErrorItem, or null if all pass.
+   */
+  private async _runCustomValidators(schema: JSONSchema, data: unknown): Promise<ValidationErrorItem | null> {
+    const validators = (schema as Record<string, unknown>)['_customValidators'] as Array<(v: unknown) => unknown> | undefined
+    if (!validators?.length) return null
+
+    for (const fn of validators) {
+      try {
+        const result = await Promise.resolve(fn(data))
+        if (result === false) {
+          return { message: Locale.getMessageText('CUSTOM_VALIDATION_FAILED'), path: '', keyword: '_customValidators', params: {} }
+        }
+        if (typeof result === 'string') {
+          return { message: result, path: '', keyword: '_customValidators', params: {} }
+        }
+        if (result !== null && typeof result === 'object' && (result as Record<string, unknown>)['error']) {
+          const r = result as { error: unknown; message?: string }
+          return {
+            message: r.message ?? Locale.getMessageText('CUSTOM_VALIDATION_FAILED'),
+            path: '',
+            keyword: '_customValidators',
+            params: {},
+          }
+        }
+      } catch (err) {
+        return {
+          message: err instanceof Error ? err.message : String(err),
+          path: '',
+          keyword: '_customValidators',
+          params: {},
+        }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Batch validation (compile once, reuse for each item).
+   */
+  validateBatch<T = unknown>(schema: JSONSchema, dataArray: T[]): ValidationResult<T>[] {
+    if (!Array.isArray(dataArray)) throw new Error('Data must be an array')
+    const cacheKey = this._generateCacheKey(schema)
+    const validate = this.compile(schema, cacheKey)
+    return dataArray.map(data => this.validate(validate, data))
+  }
+
+  /**
+   * Add a custom keyword.
+   */
+  addKeyword(keyword: string, definition: KeywordDefinitionInput): this {
+    try {
+      this._ajv.addKeyword({
+        ...definition,
+        keyword,
+      })
+      return this
+    } catch (error) {
+      throw new Error(`Failed to add keyword '${keyword}': ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  /**
+   * Add a custom format.
+   */
+  addFormat(name: string, validator: Format): this {
+    this._ajv.addFormat(name, validator)
+    return this
+  }
+
+  /**
+   * Add a schema reference.
+   */
+  addSchema(uri: string, schema: JSONSchema): this {
+    this._ajv.addSchema(schema, uri)
+    return this
+  }
+
+  /**
+   * Remove a schema reference.
+   */
+  removeSchema(uri: string): this {
+    this._ajv.removeSchema(uri)
+    return this
+  }
+
+  getAjv(): InstanceType<typeof Ajv> { return this._ajv }
+  get cache(): CacheManager { return this._cache }
+  clearCache(): void { this._cache.clear() }
+  getCacheStats(): CacheStats { return this._cache.getStats() }
+
+  // ─── Static Factory ────────────────────────────────────────────────────
+
+  static create(options?: ValidatorOptions): Validator {
+    return new Validator(options)
+  }
+
+  /**
+   * Quick validate (V-Y07 fix: reuses singleton Ajv instead of creating new Ajv each time).
+   */
+  static quickValidate(schema: JSONSchema, data: unknown): boolean {
+    if (!Validator._quickValidateAjv) {
+      Validator._quickValidateAjv = new Ajv()
+        ; (addFormats as unknown as (a: InstanceType<typeof Ajv>) => void)(Validator._quickValidateAjv)
+      CustomKeywords.registerAll(Validator._quickValidateAjv)
+    }
+    try {
+      return Validator._quickValidateAjv.validate(schema, data) as boolean
+    } catch {
+      return false
+    }
+  }
+
+  // ─── Internal Implementation ───────────────────────────────────────────
+
+  private _validateInternal<T>(
+    schema: JSONSchema | AjvValidateFn,
+    data: T,
+    options: ValidateOptions = {}
+  ): ValidationResult<T> {
+    const shouldFormat = options.format !== false
+    const locale = options.locale ?? Locale.getLocale()
+    const messages = (options.messages ?? {}) as ErrorMessages
+
+    // DslBuilder/ObjectDslBuilder/ConditionalBuilder duck type.
+    // Builders are mutable, so their toSchema() result must be re-materialized on every call.
+    if (typeof (schema as Record<string, unknown>)['toSchema'] === 'function') {
+      const obj = schema as Record<string, unknown>
+      schema = (obj['toSchema'] as () => JSONSchema)()
+    }
+
+    const internalSchema = schema as InternalSchema
+
+    // ConditionalBuilder (top-level)
+    if (internalSchema._isConditional) {
+      return this._conditionalValidator.validateConditional(internalSchema, data as Record<string, unknown>, null, data, options)
+    }
+
+    // Object schema containing ConditionalBuilder properties (including arbitrary nesting depth)
+    if (internalSchema.properties) {
+      // Performance: cache conditional detection result to avoid traversing properties on every validation
+      let hasConditionals = this._conditionalFlagCache.get(internalSchema as object)
+      if (hasConditionals === undefined) {
+        hasConditionals = this._conditionalValidator.hasAnyConditional(internalSchema)
+        this._conditionalFlagCache.set(internalSchema as object, hasConditionals)
+      }
+      if (hasConditionals) {
+        return this._conditionalValidator.validateWithConditionals(internalSchema, data, options)
+      }
+    }
+
+    // V-Y03 fix: _removeAdditional reuses internal Ajv instance
+    if (internalSchema._removeAdditional) {
+      if (!this._removeAdditionalAjv) {
+        this._removeAdditionalAjv = new Ajv({ ...this._ajvOptions, removeAdditional: true })
+          ; (addFormats as unknown as (a: InstanceType<typeof Ajv>) => void)(this._removeAdditionalAjv)
+        CustomKeywords.registerAll(this._removeAdditionalAjv)
+      }
+
+      const cleanSchema: JSONSchema = JSON.parse(JSON.stringify(schema)) as JSONSchema
+      delete (cleanSchema as InternalSchema)._removeAdditional
+
+      try {
+        const validate = this._removeAdditionalAjv.compile(cleanSchema)
+        const valid = validate(data) as boolean
+        if (valid) return { valid: true, data, errors: EMPTY_ERRORS }
+        const fmtErrors = this._formatErrors(validate.errors ?? [], messages, locale, shouldFormat)
+        return { valid: false, data, errors: fmtErrors, errorMessage: fmtErrors[0]?.message }
+      } catch (error) {
+        return this._internalError(error, data)
+      }
+    }
+
+    try {
+      let validate: AjvValidateFn
+      if (typeof schema === 'function') {
+        validate = schema as AjvValidateFn
+      } else {
+        // Performance: merge _generateCacheKey + compile() into a single WeakMap lookup
+        const schemaObj = schema as object
+        let cacheKey = this._schemaMap.get(schemaObj)
+        if (!cacheKey) {
+          cacheKey = `s${++this._schemaKeyCounter}`
+          this._schemaMap.set(schemaObj, cacheKey)
+        }
+        const cached = this._cache.get(cacheKey) as AjvValidateFn | null
+        if (cached !== null) {
+          validate = cached
+        } else {
+          try {
+            validate = this._ajv.compile(schema as JSONSchema)
+            this._cache.set(cacheKey, validate as unknown as object)
+          } catch (error) {
+            throw new Error(`Schema compilation failed: ${error instanceof Error ? error.message : String(error)}`)
+          }
+        }
+      }
+
+      const valid = validate(data) as boolean
+      if (valid) return { valid: true, data, errors: EMPTY_ERRORS }
+      const fmtErrors2 = this._formatErrors(validate.errors ?? [], messages, locale, shouldFormat)
+      return { valid: false, data, errors: fmtErrors2, errorMessage: fmtErrors2[0]?.message }
+    } catch (error) {
+      return this._internalError(error, data)
+    }
+  }
+
+  // ─── Helper methods ─────────────────────────────────────────────────────
+
+  private _generateCacheKey(schema: object): string {
+    if (!this._schemaMap.has(schema)) {
+      this._schemaMap.set(schema, `schema_${++this._schemaKeyCounter}`)
+    }
+    return this._schemaMap.get(schema)!
+  }
+
+  // Performance: cache flattened locale messages (key = locale, value = flat ErrorMessages)
+  // to avoid re-running Locale.getMessages + Object.entries.map on every validation failure
+  private readonly _flatLocaleCache = new Map<string, ErrorMessages>()
+
+  private _getFlatLocaleMessages(locale: string): ErrorMessages {
+    let flat = this._flatLocaleCache.get(locale)
+    if (!flat) {
+      const raw = Locale.getMessages(locale)
+      flat = Object.fromEntries(
+        Object.entries(raw).map(([k, v]) => [
+          k,
+          typeof v === 'string' ? v : (v as { message: string }).message,
+        ])
+      ) as ErrorMessages
+      this._flatLocaleCache.set(locale, flat)
+    }
+    return flat
+  }
+
+  private _formatErrors(
+    rawErrors: unknown[],
+    messages: ErrorMessages,
+    locale: string,
+    shouldFormat: boolean
+  ): ValidationErrorItem[] {
+    if (!shouldFormat) return rawErrors as ValidationErrorItem[]
+    const localeMessages = this._getFlatLocaleMessages(locale)
+    // Only merge when there are custom messages (avoid unnecessary object spread)
+    const mergedMessages: ErrorMessages =
+      Object.keys(messages).length === 0
+        ? localeMessages
+        : { ...localeMessages, ...messages }
+    // alreadyMerged=true: mergedMessages already contains locale+custom, skip re-expansion inside formatDetailed
+    return this._errorFormatter.formatDetailed(rawErrors as Parameters<ErrorFormatter['formatDetailed']>[0], locale, mergedMessages, true)
+  }
+
+  private _internalError<T>(error: unknown, data: T): ValidationResult<T> {
+    const message = `Validation error: ${error instanceof Error ? error.message : String(error)}`
+    return {
+      valid: false,
+      data,
+      errors: [{ message, path: '', keyword: 'error', params: {} }],
+      errorMessage: message,
+    }
+  }
+}

package/src/errors/I18nError.ts

@@ -0,0 +1,159 @@
+import { renderTemplate } from '../core/TemplateEngine.js'
+import { Locale } from '../core/Locale.js'
+
+// V8/Node.js extension
+type ErrorWithCaptureStackTrace = typeof Error & {
+  captureStackTrace?: (target: object, ctor: unknown) => void
+}
+const ErrorCtor = Error as ErrorWithCaptureStackTrace
+
+type ParamsOrLocale = Record<string, unknown> | string | null | undefined
+
+function normalizeParams(
+  paramsOrLocale: ParamsOrLocale,
+  statusCode?: unknown,
+  locale?: unknown
+): { params: Record<string, unknown>; statusCode: number; locale: string | null } {
+  let params: Record<string, unknown> = {}
+  let actualStatusCode = 400
+  let actualLocale: string | null = null
+
+  if (typeof paramsOrLocale === 'string') {
+    actualLocale = paramsOrLocale
+    actualStatusCode = typeof statusCode === 'number' ? statusCode : 400
+  } else if (paramsOrLocale && typeof paramsOrLocale === 'object' && !Array.isArray(paramsOrLocale)) {
+    params = paramsOrLocale
+    actualStatusCode = typeof statusCode === 'number' ? statusCode : 400
+    actualLocale = typeof locale === 'string' ? locale : null
+  } else {
+    actualStatusCode = typeof statusCode === 'number' ? statusCode : 400
+    actualLocale = typeof locale === 'string' ? locale : null
+  }
+
+  return { params, statusCode: actualStatusCode, locale: actualLocale }
+}
+
+/**
+ * Internationalised error class.
+ * Maintains full v1 API compatibility: create / throw / assert / is / toJSON / toString
+ */
+export class I18nError extends Error {
+  readonly name = 'I18nError' as const
+  readonly originalKey: string
+  readonly code: string | number
+  readonly params: Record<string, unknown>
+  readonly statusCode: number
+  readonly locale: string | null
+
+  constructor(
+    key: string,
+    params: Record<string, unknown> = {},
+    statusCode = 400,
+    locale: string | null = null,
+    /** Internal: pre-resolved message template, bypasses Locale lookup (used to decouple init ordering). */
+    _resolvedTemplate?: string,
+    _resolvedCode?: string | number
+  ) {
+    const targetLocale = locale ?? Locale.getLocale()
+    const normalizedParams: Record<string, unknown> = (params !== null && params !== undefined) ? params : {}
+
+    // Look up locale message config if not pre-resolved
+    let template: string
+    let resolvedCode: string | number
+    if (_resolvedTemplate !== undefined) {
+      template = _resolvedTemplate
+      resolvedCode = _resolvedCode ?? key
+    } else {
+      const msgConfig = Locale.getMessageConfig(key, {}, targetLocale)
+      if (typeof msgConfig === 'object' && msgConfig !== null && 'message' in msgConfig) {
+        template = (msgConfig as { message: string }).message
+        resolvedCode = (msgConfig as { code?: string | number }).code ?? key
+      } else if (typeof msgConfig === 'string') {
+        template = msgConfig
+        resolvedCode = key
+      } else {
+        template = key
+        resolvedCode = key
+      }
+    }
+
+    const message = renderTemplate(template, normalizedParams)
+
+    super(message)
+
+    this.originalKey = key
+    this.code = resolvedCode
+    this.params = normalizedParams
+    this.statusCode = statusCode
+    this.locale = targetLocale
+
+    if (ErrorCtor.captureStackTrace) {
+      ErrorCtor.captureStackTrace(this, I18nError)
+    }
+  }
+
+  /** Factory method — create an error instance. */
+  static create(
+    code: string,
+    paramsOrLocale?: ParamsOrLocale,
+    statusCode?: number,
+    locale?: string
+  ): I18nError {
+    const normalized = normalizeParams(paramsOrLocale, statusCode, locale)
+    return new I18nError(code, normalized.params, normalized.statusCode, normalized.locale)
+  }
+
+  /** Factory method — create and throw an error. */
+  static throw(
+    code: string,
+    paramsOrLocale?: ParamsOrLocale,
+    statusCode?: number,
+    locale?: string
+  ): never {
+    const normalized = normalizeParams(paramsOrLocale, statusCode, locale)
+    throw new I18nError(code, normalized.params, normalized.statusCode, normalized.locale)
+  }
+
+  /** Assert — throw when condition is falsy. */
+  static assert(
+    condition: unknown,
+    code: string,
+    paramsOrLocale?: ParamsOrLocale,
+    statusCode?: number,
+    locale?: string
+  ): asserts condition {
+    if (!condition) {
+      const normalized = normalizeParams(paramsOrLocale, statusCode, locale)
+      throw new I18nError(code, normalized.params, normalized.statusCode, normalized.locale)
+    }
+  }
+
+  /** Check whether the error matches the given code or original key. */
+  is(codeOrKey: string | number): boolean {
+    return this.code === codeOrKey || this.originalKey === codeOrKey
+  }
+
+  toJSON(): {
+    error: string
+    originalKey: string
+    code: string | number
+    message: string
+    params: Record<string, unknown>
+    statusCode: number
+    locale: string | null
+  } {
+    return {
+      error: this.name,
+      originalKey: this.originalKey,
+      code: this.code,
+      message: this.message,
+      params: this.params,
+      statusCode: this.statusCode,
+      locale: this.locale,
+    }
+  }
+
+  toString(): string {
+    return `${this.name} [${this.code}]: ${this.message}`
+  }
+}