schema-dsl 1.2.5 → 2.0.1

package/src/core/CacheManager.ts

@@ -0,0 +1,169 @@
+import { MemoryCache } from 'cache-hub'
+import { CACHE } from '../config/constants.js'
+
+type CacheValue = unknown
+
+export interface CacheStats {
+  hits: number
+  misses: number
+  sets: number
+  deletes: number
+  evictions: number
+  clears: number
+  hitRate: string
+  size: number
+  maxSize: number
+  enabled: boolean
+}
+
+/**
+ * CacheManager — LRU cache for compiled AJV schemas.
+ *
+ * v2 delegates to cache-hub's MemoryCache (fix BD-04: miss returns undefined → normalized to null).
+ *
+ * cache-hub MemoryCache actual API:
+ *   get(key) → value | undefined
+ *   set(key, value, opts?) — opts.ttl in ms
+ *   del(key) → boolean           ← note: del, not delete
+ *   has(key) → boolean
+ *   clear() → void
+ *   keys() → string[]
+ *   getStats() → { hits, misses, hitRate, entries, sets, deletes, evictions, memoryUsage }
+ */
+export class CacheManager {
+  private _enabled: boolean
+  private _maxSize: number
+  private _ttl: number
+  private _cache: MemoryCache
+  private _statsEnabled: boolean = true
+  private _clears = 0
+
+  constructor(options: {
+    maxSize?: number
+    ttl?: number
+    enabled?: boolean
+    statsEnabled?: boolean
+  } = {}) {
+    this._maxSize = options.maxSize ?? CACHE.SCHEMA_CACHE.MAX_SIZE
+    this._ttl = options.ttl ?? CACHE.SCHEMA_CACHE.TTL
+    this._enabled = options.enabled !== false
+    this._cache = new MemoryCache({ maxEntries: this._maxSize })
+    this._statsEnabled = options.statsEnabled !== false
+  }
+
+  get options(): { maxSize: number; ttl: number; enabled: boolean; statsEnabled: boolean } {
+    return {
+      maxSize: this._maxSize,
+      ttl: this._ttl,
+      enabled: this._enabled,
+      statsEnabled: this._statsEnabled,
+    }
+  }
+
+  set options(opts: Partial<{ maxSize: number; ttl: number; enabled: boolean; statsEnabled: boolean }>) {
+    if (opts.maxSize !== undefined && opts.maxSize !== this._maxSize) {
+      this._maxSize = opts.maxSize
+      // Rebuild MemoryCache so the new capacity actually takes effect
+      const oldKeys = this._cache.keys()
+      const newCache = new MemoryCache({ maxEntries: this._maxSize })
+      for (const key of oldKeys) {
+        const val = this._cache.get(key)
+        if (val !== undefined) newCache.set(key, val)
+      }
+      this._cache = newCache
+    }
+    if (opts.ttl !== undefined) this._ttl = opts.ttl
+    if (opts.enabled !== undefined) this._enabled = opts.enabled
+    if (opts.statsEnabled !== undefined) this._statsEnabled = opts.statsEnabled
+  }
+
+  /**
+   * Retrieve a cached AJV compile function.
+   * @returns cached compile function, or null on miss (BD-04: undefined → null)
+   */
+  get(key: string): CacheValue | null {
+    if (!this._enabled || key == null) return null
+    try {
+      const result = this._cache.get(String(key)) as CacheValue | undefined
+      return result !== undefined ? result : null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Write a value to the cache.
+   */
+  set(key: string, value: CacheValue, ttl?: number): void {
+    if (!this._enabled || key == null) return
+    try {
+      this._cache.set(String(key), value, ttl ?? this._ttl)
+    } catch {
+      // Silently ignore invalid keys for v1 compat
+    }
+  }
+
+  /**
+   * Delete a single cache entry.
+   */
+  delete(key: string): boolean {
+    return this._cache.del(key)
+  }
+
+  /**
+   * Check whether a key exists in the cache.
+   */
+  has(key: string): boolean {
+    if (!this._enabled) return false
+    return this._cache.has(key)
+  }
+
+  /**
+   * Clear all cache entries.
+   */
+  clear(): void {
+    this._cache.clear()
+    this._clears++
+  }
+
+  /**
+   * Return the current number of cache entries.
+   */
+  size(): number {
+    return this._cache.keys().length
+  }
+
+  /**
+   * Return cache statistics.
+   */
+  getStats(): CacheStats {
+    if (!this._statsEnabled) {
+      return {
+        hits: 0, misses: 0, sets: 0, deletes: 0, evictions: 0,
+        clears: 0, hitRate: '0.00', size: 0, maxSize: this._maxSize, enabled: this._enabled,
+      }
+    }
+    const inner = this._cache.getStats()
+    const total = inner.hits + inner.misses
+    return {
+      hits: inner.hits,
+      misses: inner.misses,
+      sets: inner.sets,
+      deletes: inner.deletes,
+      evictions: (inner as unknown as Record<string, unknown>).evictions as number ?? 0,
+      clears: this._clears,
+      hitRate: total > 0 ? ((inner.hits / total) * 100).toFixed(2) : '0.00',
+      size: inner.entries,
+      maxSize: this._maxSize,
+      enabled: this._enabled,
+    }
+  }
+
+  /**
+   * Reset all hit/miss/eviction counters.
+   */
+  resetStats(): void {
+    this._cache.resetStats()
+    this._clears = 0
+  }
+}

package/src/core/ConditionalBuilder.ts

@@ -0,0 +1,382 @@
+/**
+ * ConditionalBuilder — chainable condition builder.
+ *
+ * v2 fixes:
+ *   C-03: assert() throws ValidationError instead of plain Error
+ *   C-Y01: elseIf semantics correct
+ *   C-Y02: build() as toSchema() alias (IConditionalBuilder interface compat)
+ */
+
+import type { JSONSchema } from '../types/schema.js'
+import type { IConditionalBuilder } from '../types/conditional.js'
+import type { ValidateOptions, ValidationResult } from '../types/validate.js'
+import { ValidationError } from '../errors/ValidationError.js'
+import { Validator } from './Validator.js'
+import { Locale } from './Locale.js'
+import { attachConditionalRuntime } from './ConditionalRuntime.js'
+
+const RUNTIME_ONLY_VALIDATE_OPTION_KEYS = new Set(['locale', 'messages', 'format'])
+
+// ==================== Internal Data Structures ====================
+
+type ConditionFn = (data: unknown) => boolean
+
+interface CombinedCondition {
+  op: 'root' | 'and' | 'or'
+  fn: ConditionFn
+  message: string | null
+}
+
+interface ConditionEntry {
+  type: 'if' | 'elseIf'
+  condition: ConditionFn
+  combinedConditions: CombinedCondition[]
+  message?: string
+  action?: 'throw'
+  then?: string | JSONSchema | null
+}
+
+interface EvaluateResult {
+  result: boolean
+  failedMessage: string | null
+  requirementFailed?: boolean
+}
+
+// ==================== ConditionalBuilder ====================
+
+export class ConditionalBuilder implements IConditionalBuilder {
+  private _conditions: ConditionEntry[]
+  private _elseSchema: string | JSONSchema | null | undefined
+
+  constructor() {
+    this._conditions = []
+    this._elseSchema = undefined
+  }
+
+  // ==================== Condition Chain Methods ====================
+
+  if(conditionFn: ConditionFn | string): this {
+    // v1 compat: accept string field name and convert to function
+    if (typeof conditionFn === 'string') {
+      const fieldName = conditionFn
+      conditionFn = ((data: unknown) => Boolean((data as Record<string, unknown>)[fieldName])) as ConditionFn
+    }
+    if (typeof conditionFn !== 'function') {
+      throw new Error('[schema-dsl] Condition must be a function')
+    }
+    this._conditions.push({
+      type: 'if',
+      condition: conditionFn,
+      combinedConditions: [{ op: 'root', fn: conditionFn, message: null }],
+    })
+    return this
+  }
+
+  and(conditionFn: ConditionFn): this {
+    if (typeof conditionFn !== 'function') {
+      throw new Error('[schema-dsl] Condition must be a function')
+    }
+    const last = this._conditions[this._conditions.length - 1]
+    if (!last) throw new Error('[schema-dsl] .and() must follow .if() or .elseIf()')
+    last.combinedConditions.push({ op: 'and', fn: conditionFn, message: null })
+    return this
+  }
+
+  /**
+   * require(field) — v1 compat: require the specified field to be truthy.
+   * Equivalent to .and(data => Boolean(data[field])).
+   * BC-5 fix.
+   */
+  require(field: string): this {
+    return this.and((data: unknown) => Boolean((data as Record<string, unknown>)[field]))
+  }
+
+  or(conditionFn: ConditionFn): this {
+    if (typeof conditionFn !== 'function') {
+      throw new Error('[schema-dsl] Condition must be a function')
+    }
+    const last = this._conditions[this._conditions.length - 1]
+    if (!last) throw new Error('[schema-dsl] .or() must follow .if() or .elseIf()')
+    last.combinedConditions.push({ op: 'or', fn: conditionFn, message: null })
+    return this
+  }
+
+  elseIf(conditionFn: ConditionFn): this {
+    if (typeof conditionFn !== 'function') {
+      throw new Error('[schema-dsl] Condition must be a function')
+    }
+    if (this._conditions.length === 0) {
+      throw new Error('[schema-dsl] .elseIf() must follow .if()')
+    }
+    this._conditions.push({
+      type: 'elseIf',
+      condition: conditionFn,
+      combinedConditions: [{ op: 'root', fn: conditionFn, message: null }],
+    })
+    return this
+  }
+
+  message(msg: string): this {
+    if (typeof msg !== 'string') {
+      throw new Error('[schema-dsl] Message must be a string')
+    }
+    const last = this._conditions[this._conditions.length - 1]
+    if (!last) throw new Error('[schema-dsl] .message() must follow .if() or .elseIf()')
+
+    const lastCombined = last.combinedConditions[last.combinedConditions.length - 1]
+    if (lastCombined) {
+      lastCombined.message = msg
+    }
+    last.message = msg
+    last.action = 'throw'
+    return this
+  }
+
+  then(schema: string | JSONSchema | null): this {
+    const last = this._conditions[this._conditions.length - 1]
+    if (!last) throw new Error('[schema-dsl] .then() must follow .if() or .elseIf()')
+    last.then = schema
+    return this
+  }
+
+  else(schema: string | JSONSchema | null): this {
+    this._elseSchema = schema
+    return this
+  }
+
+  // ==================== Output Methods ====================
+
+  /**
+   * Produce a schema object carrying serialisable conditional metadata plus non-enumerable runtime state.
+   */
+  toSchema(): JSONSchema {
+    return attachConditionalRuntime({
+      _isConditional: true,
+      _runtimeOnlyConditional: true,
+      else: this._elseSchema,
+    } as unknown as JSONSchema, {
+      conditions: this._conditions,
+      elseSchema: this._elseSchema,
+      evaluateCondition: (conditionObj: unknown, data: unknown) =>
+        this._evaluateCondition(conditionObj as ConditionEntry, data),
+    }) as unknown as JSONSchema
+  }
+
+  /**
+   * build() — alias for toSchema() (IConditionalBuilder interface compat).
+   */
+  build(): JSONSchema {
+    return this.toSchema()
+  }
+
+  // ==================== Validation Methods ====================
+
+  private readonly _validatorCache = new Map<string, Validator>()
+  private static readonly _VALIDATOR_CACHE_MAX = 20
+
+  validate(data: unknown, options: Record<string, unknown> = {}): ValidationResult<unknown> {
+    const validator = this._getValidator(options)
+    return validator.validate(this.toSchema(), data, options)
+  }
+
+  async validateAsync(data: unknown, options: Record<string, unknown> = {}): Promise<ValidationResult<unknown>> {
+    const validator = this._getValidator(options)
+    // validator.validateAsync() throws ValidationError on failure and returns data on success.
+    // Adapt to the ValidationResult contract expected by ConditionalBuilder callers.
+    try {
+      const resultData = await validator.validateAsync(this.toSchema(), data, options)
+      return { valid: true, data: resultData as unknown, errors: [] }
+    } catch (err) {
+      if (err instanceof ValidationError) {
+        return { valid: false, errors: err.errors, data: undefined }
+      }
+      throw err
+    }
+  }
+
+  /**
+   * assert() — synchronous assertion; throws ValidationError on failure (fixes C-03: v1 threw plain Error).
+   * Evaluates conditions synchronously without going through Validator (which is async).
+   */
+  assert(data: unknown, options: Record<string, unknown> = {}): unknown {
+    const locale = (options.locale as string) ?? null
+    for (const cond of this._conditions) {
+      const { result: matched, failedMessage } = this._evaluateCondition(cond, data)
+      if (matched && cond.action === 'throw') {
+        const rawMsg = failedMessage ?? cond.message ?? 'Condition failed'
+        const message = Locale.getMessageText(rawMsg, {}, locale)
+        throw new ValidationError(
+          [{ message, path: '', keyword: 'conditional', params: {} }],
+          data,
+        )
+      }
+    }
+    return data
+  }
+
+  check(data: unknown): boolean {
+    try {
+      const conditions = this._conditions
+      for (const cond of conditions) {
+        const { result: matched } = this._evaluateCondition(cond, data)
+        if (matched && cond.action === 'throw') return false
+      }
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  // ==================== Static Factory Methods ====================
+
+  static start(conditionFn: ConditionFn | string): ConditionalBuilder {
+    return new ConditionalBuilder().if(conditionFn)
+  }
+
+  // ==================== Internal Evaluation Logic ====================
+
+  private _evaluateCondition(conditionObj: ConditionEntry, data: unknown): EvaluateResult {
+    try {
+      const isMessageMode = conditionObj.action === 'throw'
+      const hasOrConditions = conditionObj.combinedConditions.some(c => c.op === 'or')
+
+      // Chain check mode (v1 compat): message mode + root has own message
+      // Each condition checked left-to-right, first TRUE = fail with its message
+      const rootHasMessage = conditionObj.combinedConditions[0]?.message !== null
+      const isChainCheckMode = isMessageMode && rootHasMessage
+
+      if (isChainCheckMode) {
+        for (const combined of conditionObj.combinedConditions) {
+          try {
+            const conditionResult = combined.fn(data)
+            if (conditionResult) {
+              return { result: true, failedMessage: combined.message ?? conditionObj.message ?? null }
+            }
+          } catch {
+            // Condition threw — treat as not matched
+          }
+        }
+        return { result: false, failedMessage: null }
+      }
+
+      // Message mode with AND only (no OR, shared message, root has no own message):
+      // ALL conditions must be true to trigger
+      if (isMessageMode && !hasOrConditions && conditionObj.combinedConditions.length > 1) {
+        let allTrue = true
+        for (const combined of conditionObj.combinedConditions) {
+          if (!combined.fn(data)) {
+            allTrue = false
+            break
+          }
+        }
+        if (allTrue) {
+          return { result: true, failedMessage: conditionObj.message ?? null }
+        }
+        return { result: false, failedMessage: null }
+      }
+
+      // Message mode with OR (and possibly AND, shared message): AND/OR boolean with precedence
+      if (isMessageMode && hasOrConditions) {
+        let andGroupResult = true
+        let finalResult = false
+        for (const combined of conditionObj.combinedConditions) {
+          const conditionResult = combined.fn(data)
+          if (combined.op === 'root' || combined.op === 'and') {
+            andGroupResult = andGroupResult && conditionResult
+          } else if (combined.op === 'or') {
+            finalResult = finalResult || andGroupResult
+            andGroupResult = conditionResult
+          }
+        }
+        finalResult = finalResult || andGroupResult
+        if (finalResult) {
+          return { result: true, failedMessage: conditionObj.message ?? null }
+        }
+        return { result: false, failedMessage: null }
+      }
+
+      // Message mode without AND/OR (single condition)
+      if (isMessageMode) {
+        const root = conditionObj.combinedConditions[0]
+        if (root && root.fn(data)) {
+          return { result: true, failedMessage: root.message ?? conditionObj.message ?? null }
+        }
+        return { result: false, failedMessage: null }
+      }
+
+      // Non-message (then/else) mode: standard AND/OR boolean evaluation
+      let andGroupResult = true
+      let finalResult = false
+      for (const combined of conditionObj.combinedConditions) {
+        const conditionResult = combined.fn(data)
+        if (combined.op === 'root' || combined.op === 'and') {
+          andGroupResult = andGroupResult && conditionResult
+        } else if (combined.op === 'or') {
+          finalResult = finalResult || andGroupResult
+          andGroupResult = conditionResult
+        }
+      }
+      const result = finalResult || andGroupResult
+      return { result, failedMessage: null }
+    } catch {
+      return { result: false, failedMessage: null }
+    }
+  }
+
+  private _getValidator(options: Record<string, unknown>): Validator {
+    const constructorOptions = this._getConstructorOptions(options)
+    const cacheKey = this._getValidatorCacheKey(constructorOptions)
+
+    let validator = this._validatorCache.get(cacheKey)
+    if (!validator) {
+      if (this._validatorCache.size >= ConditionalBuilder._VALIDATOR_CACHE_MAX) {
+        const firstKey = this._validatorCache.keys().next().value
+        if (firstKey !== undefined) this._validatorCache.delete(firstKey)
+      }
+      validator = new Validator(constructorOptions)
+      this._validatorCache.set(cacheKey, validator)
+    }
+
+    return validator
+  }
+
+  private _getConstructorOptions(options: Record<string, unknown>): ValidateOptions {
+    const constructorOptions: Record<string, unknown> = {}
+
+    for (const [key, value] of Object.entries(options)) {
+      if (!RUNTIME_ONLY_VALIDATE_OPTION_KEYS.has(key)) {
+        constructorOptions[key] = value
+      }
+    }
+
+    return constructorOptions as ValidateOptions
+  }
+
+  private _getValidatorCacheKey(options: ValidateOptions): string {
+    return JSON.stringify(this._normalizeOptionValue(options))
+  }
+
+  private _normalizeOptionValue(value: unknown): unknown {
+    if (Array.isArray(value)) {
+      return value.map(item => this._normalizeOptionValue(item))
+    }
+
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value as Record<string, unknown>)
+          .sort(([left], [right]) => left.localeCompare(right))
+          .map(([key, nestedValue]) => [key, this._normalizeOptionValue(nestedValue)])
+      )
+    }
+
+    if (typeof value === 'function') {
+      return `__fn__:${value.name || 'anonymous'}`
+    }
+
+    if (typeof value === 'bigint') {
+      return `__bigint__:${value.toString()}`
+    }
+
+    return value
+  }
+}

package/src/core/ConditionalRuntime.ts

@@ -0,0 +1,28 @@
+import type { JSONSchema } from '../types/schema.js'
+
+export const CONDITIONAL_RUNTIME_STATE: unique symbol = Symbol('schema-dsl.conditionalRuntimeState')
+
+export interface ConditionalRuntimeState {
+    conditions: unknown[]
+    elseSchema: string | JSONSchema | null | undefined
+    evaluateCondition: (conditionObj: unknown, data: unknown) => {
+        result: boolean
+        failedMessage?: string | null
+        requirementFailed?: boolean
+    }
+}
+
+export type ConditionalRuntimeSchema = JSONSchema & {
+    [CONDITIONAL_RUNTIME_STATE]?: ConditionalRuntimeState
+}
+
+export function attachConditionalRuntime(schema: JSONSchema, state: ConditionalRuntimeState): ConditionalRuntimeSchema {
+    Object.defineProperty(schema, CONDITIONAL_RUNTIME_STATE, {
+        value: state,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    })
+
+    return schema as ConditionalRuntimeSchema
+}