schema-dsl 1.2.5 → 2.0.1

package/src/core/ErrorCodes.ts

@@ -0,0 +1,38 @@
+import type { ErrorCodeMap } from '../types/error.js'
+
+/**
+ * Error code constants.
+ * Defines all built-in error codes used by ErrorFormatter and Locale.
+ */
+export const ErrorCodes: ErrorCodeMap = {
+  // Validation errors
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  INVALID_SCHEMA: 'INVALID_SCHEMA',
+  // Configuration errors
+  INVALID_CONFIG: 'INVALID_CONFIG',
+  INVALID_LOCALE: 'INVALID_LOCALE',
+  // Plugin errors
+  PLUGIN_INSTALL_ERROR: 'PLUGIN_INSTALL_ERROR',
+  PLUGIN_NOT_FOUND: 'PLUGIN_NOT_FOUND',
+}
+
+/**
+ * Error type → short code mapping (maps AJV keywords to schema-dsl shorthand).
+ */
+export const KEYWORD_MAP: Record<string, string> = {
+  minLength: 'min',
+  maxLength: 'max',
+  minimum: 'min',
+  maximum: 'max',
+  minItems: 'min',
+  maxItems: 'max',
+  exclusiveMinimum: 'min',
+  exclusiveMaximum: 'max',
+  pattern: 'pattern',
+  format: 'format',
+  required: 'required',
+  enum: 'enum',
+  type: 'type',
+  uniqueItems: 'uniqueItems',
+  additionalProperties: 'additionalProperties',
+}

package/src/core/ErrorFormatter.ts

@@ -0,0 +1,271 @@
+import type { ValidationErrorItem } from '../types/validate.js'
+import type { ErrorMessages } from '../types/error.js'
+import { renderTemplate } from './TemplateEngine.js'
+import { KEYWORD_MAP } from './ErrorCodes.js'
+import { getMessages } from '../locales/index.js'
+import type { LocaleMessage } from '../locales/types.js'
+import { DEFAULT_LOCALE } from './Locale.js'
+
+type AjvRawError = {
+  keyword: string
+  instancePath: string
+  schemaPath?: string
+  params: Record<string, unknown>
+  message?: string
+  data?: unknown
+  parentSchema?: Record<string, unknown>
+  schema?: unknown
+}
+
+/**
+ * Error formatter.
+ * Delegates template interpolation to TemplateEngine.renderTemplate() (fix CORE-03).
+ * Maintains full v1 API compatibility.
+ */
+export class ErrorFormatter {
+  private messages: ErrorMessages
+  private _locale: string
+  private readonly _constructorCustomMessages: ErrorMessages
+
+  constructor(locale = DEFAULT_LOCALE, messages: ErrorMessages | Record<string, LocaleMessage | string | undefined> = {}) {
+    this._locale = locale
+    // Load locale messages as defaults; constructor-level custom messages override them
+    const rawLocaleMessages = getMessages(locale)
+    const localeMessages: ErrorMessages = Object.fromEntries(
+      Object.entries(rawLocaleMessages).map(([k, v]: [string, LocaleMessage]) => [
+        k,
+        typeof v === 'string' ? v : (v as { message: string }).message,
+      ])
+    )
+    // Normalise caller-supplied messages: LocaleMessage objects → plain string
+    const normMessages: ErrorMessages = Object.fromEntries(
+      Object.entries(messages).map(([k, v]) => [
+        k,
+        v == null ? undefined : typeof v === 'string' ? v : (v as { message: string }).message,
+      ])
+    )
+    this._constructorCustomMessages = normMessages
+    this.messages = { ...localeMessages, ...normMessages }
+  }
+
+  get locale(): string {
+    return this._locale
+  }
+
+  /**
+   * Format a single error object → message string (v1 API).
+   */
+  format(error: AjvRawError | Record<string, unknown>, locale?: string): string {
+    // If locale differs, reload messages for that locale
+    let msgs = this.messages
+    if (locale && locale !== this._locale) {
+      const rawLocaleMessages = getMessages(locale)
+      const localeMessages: ErrorMessages = Object.fromEntries(
+        Object.entries(rawLocaleMessages).map(([k, v]: [string, LocaleMessage]) => [
+          k,
+          typeof v === 'string' ? v : (v as { message: string }).message,
+        ])
+      )
+      // Preserve constructor-level custom messages across locale switches (R-01 fix)
+      msgs = { ...localeMessages, ...this._constructorCustomMessages }
+    }
+
+    // Convert simple { type, path } format to AJV-like error
+    const raw = error as Record<string, unknown>
+    const ajvError = {
+      keyword: (raw['keyword'] as string) ?? (raw['type'] as string) ?? 'validation',
+      instancePath: (raw['instancePath'] as string) ?? ('/' + (raw['path'] ?? '')),
+      params: (raw['params'] as Record<string, unknown>) ?? {},
+      parentSchema: raw['parentSchema'] as Record<string, unknown> | undefined,
+    } as AjvRawError
+    const item = this._formatOne(ajvError, msgs, locale)
+    return item.message
+  }
+
+  /**
+   * Format an AJV raw error array → ValidationErrorItem[].
+   *
+   * @param alreadyMerged - when true, customMessages is already a fully merged locale+custom result;
+   *   skip `{ ...this.messages, ...customMessages }` spread (avoids 100+ key cold-spread overhead).
+   */
+  formatDetailed(
+    errors: AjvRawError[],
+    locale?: string,
+    customMessages?: ErrorMessages,
+    alreadyMerged = false
+  ): ValidationErrorItem[] {
+    const msgs = customMessages
+      ? (alreadyMerged ? customMessages : { ...this.messages, ...customMessages })
+      : this.messages
+
+    // Filter wrapper errors (if/anyOf/oneOf) when concrete field errors are present
+    const hasConcreteErrors = errors.some(
+      e => e.keyword !== 'if' && e.keyword !== 'anyOf' && e.keyword !== 'oneOf' && e.keyword !== 'error'
+    )
+    const filtered = hasConcreteErrors
+      ? errors.filter(e => e.keyword !== 'if' && e.keyword !== 'anyOf' && e.keyword !== 'oneOf')
+      : errors
+
+    return filtered.map(err => this._formatOne(err, msgs, locale))
+  }
+
+  /**
+   * Format a single error entry into a ValidationErrorItem.
+   */
+  private _formatOne(
+    err: AjvRawError,
+    messages: ErrorMessages,
+    _locale?: string
+  ): ValidationErrorItem {
+    const keyword = err.keyword ?? 'validation'
+    const instancePath = err.instancePath ?? ''
+    const params = err.params ?? {} as Record<string, unknown>
+
+    // Field path calculation (required errors get special handling)
+    let fieldName: string
+    if (keyword === 'required' && params['missingProperty']) {
+      const parentPath = instancePath.replace(/^\//, '')
+      const missing = String(params['missingProperty'])
+      fieldName = parentPath ? `${parentPath}/${missing}` : missing
+    } else {
+      fieldName = instancePath.replace(/^\//, '') || 'value'
+    }
+
+    // Label resolution
+    const schema = (err.parentSchema ?? {}) as Record<string, unknown>
+    let label: string | undefined
+
+    // For required errors, get label from the specific property schema
+    if (keyword === 'required' && params['missingProperty']) {
+      const missingProp = String(params['missingProperty'])
+      const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined
+      if (properties && properties[missingProp]) {
+        label = properties[missingProp]['_label'] as string | undefined
+      }
+    }
+
+    // Fallback to parent schema label
+    if (!label) {
+      label = schema['_label'] as string | undefined
+    }
+
+    // If _label is set, try to translate it as a locale key reference
+    if (label) {
+      label = (messages[label] != null ? String(messages[label]) : undefined) ?? label
+    }
+
+    if (!label) {
+      let labelKey: string
+      if (keyword === 'required' && params['missingProperty']) {
+        labelKey = String(params['missingProperty'])
+      } else {
+        const parts = fieldName.split('/')
+        labelKey = parts[parts.length - 1] ?? fieldName
+      }
+      const autoKey = `label.${labelKey.replace(/\//g, '.')}`
+      label = messages[autoKey] ?? labelKey
+    }
+
+    // Schema-level custom messages
+    let schemaCustomMessages = (schema['_customMessages'] ?? {}) as ErrorMessages
+
+    // For required errors, also check field-level custom messages
+    if (keyword === 'required' && params['missingProperty']) {
+      const missingProp = String(params['missingProperty'])
+      const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined
+      if (properties && properties[missingProp] && properties[missingProp]['_customMessages']) {
+        schemaCustomMessages = { ...schemaCustomMessages, ...(properties[missingProp]['_customMessages'] as ErrorMessages) }
+      }
+    }
+
+    // Performance: reuse `messages` directly when schemaCustomMessages is empty (99 % of calls)
+    const hasCustomMessages = Object.keys(schemaCustomMessages).length > 0
+    const mergedMessages = hasCustomMessages ? { ...messages, ...schemaCustomMessages } : messages
+    const mappedKeyword = KEYWORD_MAP[keyword] ?? keyword
+    const schemaType = typeof schema['type'] === 'string' ? schema['type'] : 'string'
+
+    // Message lookup order: schema custom > type+keyword > keyword > fallback
+    let message: string | undefined = hasCustomMessages
+      ? (schemaCustomMessages[keyword] ?? schemaCustomMessages[mappedKeyword])
+      : undefined
+
+    if (message) {
+      // May be a key reference — try to resolve from mergedMessages
+      message = mergedMessages[message] ?? message
+    } else {
+      // Special handling for format.email etc.
+      if (mappedKeyword === 'format' && params['format']) {
+        let fmt = String(params['format'])
+        if (fmt === 'uri') fmt = 'url'
+        message = mergedMessages[`format.${fmt}`]
+      }
+      message ??=
+        mergedMessages[`${schemaType}.${keyword}`] ??
+        mergedMessages[`${schemaType}.${mappedKeyword}`] ??
+        mergedMessages[mappedKeyword] ??
+        mergedMessages[keyword] ??
+        mergedMessages['default'] ??
+        err.message ??
+        'Validation error'
+    }
+
+    // Interpolation params: spread AJV params first, then override fixed keys
+    const limit = params['limit'] ?? params['limitLength'] ?? params['comparison'] ?? ''
+    const allowedVals = Array.isArray(params['allowedValues'])
+      ? (params['allowedValues'] as unknown[]).join(', ')
+      : undefined
+    const interpolateData: Record<string, unknown> = {
+      ...params,
+      path: label,
+      label,
+      value: err.data !== undefined ? err.data : '',
+      limit,
+      min: limit,
+      max: limit,
+      expected: params['type'],
+      actual:
+        err.data === null
+          ? 'null'
+          : err.data === undefined
+            ? 'undefined'
+            : Array.isArray(err.data)
+              ? 'array'
+              : typeof err.data,
+      valids: allowedVals,
+      allowed: allowedVals,
+      key: params['additionalProperty'],
+    }
+
+    const rendered = renderTemplate(message, interpolateData)
+
+    return {
+      path: fieldName,
+      message: rendered,
+      keyword,
+      params,
+      field: fieldName,
+      type: keyword,
+      expected: params['type'] !== undefined ? String(params['type']) : undefined,
+    }
+  }
+
+  setLocale(locale: string): void {
+    this._locale = locale
+    const rawLocaleMessages = getMessages(locale)
+    const localeMessages: ErrorMessages = Object.fromEntries(
+      Object.entries(rawLocaleMessages).map(([k, v]: [string, LocaleMessage]) => [
+        k,
+        typeof v === 'string' ? v : (v as { message: string }).message,
+      ])
+    )
+    this.messages = { ...localeMessages, ...this._constructorCustomMessages }
+  }
+
+  addMessage(type: string, template: string): void {
+    this.messages[type] = template
+  }
+
+  addMessages(messages: ErrorMessages): void {
+    Object.assign(this.messages, messages)
+  }
+}

package/src/core/JSONSchemaCore.ts

@@ -0,0 +1,65 @@
+import type { JSONSchema } from '../types/schema.js'
+import { Validator } from './Validator.js'
+
+/**
+ * JSONSchemaCore — v1 compatibility facade.
+ *
+ * The v2 internals have been split into DslParser / SchemaCompiler / Validator; this class
+ * restores the commonly-used chainable entry points from the v1 public API so that users
+ * who import from the main entry point do not encounter errors.
+ */
+export class JSONSchemaCore {
+  schema: JSONSchema
+
+  constructor(schema: JSONSchema = {}) {
+    this.schema = { ...schema }
+  }
+
+  type(typeName: string): this {
+    this.schema.type = typeName
+    return this
+  }
+
+  property(name: string, schema: JSONSchema): this {
+    if (!this.schema.properties) this.schema.properties = {}
+    this.schema.properties[name] = schema
+    return this
+  }
+
+  properties(properties: Record<string, JSONSchema>): this {
+    this.schema.properties = { ...(this.schema.properties ?? {}), ...properties }
+    return this
+  }
+
+  required(fields: string[] | string): this {
+    this.schema.required = Array.isArray(fields) ? fields : [fields]
+    return this
+  }
+
+  format(formatName: string): this {
+    this.schema.format = formatName
+    return this
+  }
+
+  pattern(pattern: RegExp | string): this {
+    this.schema.pattern = pattern instanceof RegExp ? pattern.source : pattern
+    return this
+  }
+
+  items(schema: JSONSchema): this {
+    this.schema.items = schema
+    return this
+  }
+
+  toSchema(): JSONSchema {
+    return this.schema
+  }
+
+  getSchema(): JSONSchema {
+    return this.toSchema()
+  }
+
+  validate(data: unknown): ReturnType<Validator['validate']> {
+    return new Validator().validate(this.schema, data)
+  }
+}

package/src/core/Locale.ts

@@ -0,0 +1,187 @@
+import type { LocaleKey, LocaleMessage } from '../locales/types.js'
+import { getMessage, getMessages, isSupportedLocale, getSupportedLocales } from '../locales/index.js'
+
+export interface LocaleResolvedMessage {
+  code: string | number
+  message: string
+}
+
+/**
+ * Locale — global locale manager (static class).
+ *
+ * v1 compatibility semantics:
+ *   - getMessage() → returns { code, message } for every resolved message
+ *   - getMessageText() → always returns final message text (used internally by v2)
+ *   - getMessageConfig() → returns raw LocaleMessage (may contain code object; used by I18nError)
+ */
+export const DEFAULT_LOCALE = 'en-US'
+
+export class Locale {
+  private static _currentLocale: string = DEFAULT_LOCALE
+  private static _customMessages: Record<string, LocaleMessage> = {}
+
+  /** v1 compat: expose custom messages */
+  static get customMessages(): Record<string, LocaleMessage> {
+    return this._customMessages
+  }
+
+  /** v1 compat: expose all locales as { locale: messages } map */
+  static get locales(): Record<string, Record<string, LocaleMessage>> {
+    const result: Record<string, Record<string, LocaleMessage>> = {}
+    // Built-in locales
+    for (const locale of getSupportedLocales()) {
+      result[locale] = getMessages(locale) as Record<string, LocaleMessage>
+    }
+    // Custom locales added via addLocale
+    for (const key of Object.keys(this._customMessages)) {
+      if (key.includes(':')) {
+        const colonIdx = key.indexOf(':')
+        const locale = key.substring(0, colonIdx)
+        const msgKey = key.substring(colonIdx + 1)
+        if (!result[locale]) result[locale] = {}
+        result[locale][msgKey] = this._customMessages[key]
+      }
+    }
+    return result
+  }
+
+  // ─── Locale Switching ─────────────────────────────────────────────────────
+
+  static setLocale(locale: string): void {
+    this._currentLocale = locale
+  }
+
+  static getLocale(): string {
+    return this._currentLocale
+  }
+
+  // ─── Custom Messages (global override) ───────────────────────────────────
+
+  static setMessages(messages: Record<string, LocaleMessage>): void {
+    this._customMessages = { ...this._customMessages, ...messages }
+  }
+
+  static addLocale(locale: string, messages: Record<string, LocaleMessage>): void {
+    // Dynamically add a locale pack at runtime (merged into existing entries).
+    // Records into customMessages and takes priority during lookup.
+    for (const [k, v] of Object.entries(messages)) {
+      this._customMessages[`${locale}:${k}`] = v
+    }
+  }
+
+  static getAvailableLocales(): string[] {
+    return getSupportedLocales()
+  }
+
+  static isSupportedLocale(locale: string): boolean {
+    return isSupportedLocale(locale)
+  }
+
+  // ─── Core Query Methods ───────────────────────────────────────────────────
+
+  /**
+   * Get a resolved message (v1 compat: returns { code, message } on hit).
+   *
+   * Priority: custom messages > locale pack > key itself.
+   */
+  static getMessage(
+    type: string,
+    customMessages: Record<string, LocaleMessage> = {},
+    locale: string | null = null
+  ): LocaleResolvedMessage | string {
+    const resolved = this._resolveMessage(type, customMessages, locale)
+    if (!resolved) return type
+    return this._normalizeResolvedMessage(type, resolved)
+  }
+
+  /**
+   * Get the final message text (used internally by v2 to avoid "[object Object]" in message field).
+   */
+  static getMessageText(
+    type: string,
+    customMessages: Record<string, LocaleMessage> = {},
+    locale: string | null = null
+  ): string {
+    const resolved = this.getMessage(type, customMessages, locale)
+    return typeof resolved === 'string' ? resolved : resolved.message
+  }
+
+  /**
+   * Get raw message config (used by I18nError; may include a numeric code).
+   */
+  static getMessageConfig(
+    type: string,
+    customMessages: Record<string, LocaleMessage> = {},
+    locale: string | null = null
+  ): LocaleMessage {
+    return this._resolveMessage(type, customMessages, locale) ?? { code: type, message: type }
+  }
+
+  /**
+   * Get the full message table for the given locale (built-in + custom).
+   */
+  static getMessages(locale?: string): Record<string, LocaleMessage> {
+    const targetLocale = locale ?? this._currentLocale
+    const builtinMessages = getMessages(targetLocale) as Record<string, LocaleMessage>
+    // Merge custom messages added via addLocale/setMessages for this locale
+    const customForLocale: Record<string, LocaleMessage> = {}
+    for (const [k, v] of Object.entries(this._customMessages)) {
+      if (k.startsWith(`${targetLocale}:`)) {
+        customForLocale[k.slice(targetLocale.length + 1)] = v
+      } else if (!k.includes(':')) {
+        // Global custom messages (no locale prefix)
+        customForLocale[k] = v
+      }
+    }
+    return { ...builtinMessages, ...customForLocale }
+  }
+
+  /**
+   * Reset to defaults (for testing).
+   */
+  static reset(): void {
+    this._currentLocale = DEFAULT_LOCALE
+    this._customMessages = {}
+  }
+
+  // ─── Private Helpers ──────────────────────────────────────────────────────
+
+  private static _normalizeResolvedMessage(type: string, msg: LocaleMessage): LocaleResolvedMessage {
+    if (typeof msg === 'string') {
+      return { code: type, message: msg }
+    }
+    return {
+      code: msg.code ?? type,
+      message: msg.message,
+    }
+  }
+
+  private static _resolveMessage(
+    type: string,
+    customMessages: Record<string, LocaleMessage>,
+    locale: string | null
+  ): LocaleMessage | null {
+    const targetLocale = locale ?? this._currentLocale
+
+    const callerMsg = customMessages[type]
+    if (callerMsg !== undefined) return callerMsg
+
+    const globalMsg = this._customMessages[type]
+    if (globalMsg !== undefined) return globalMsg
+
+    const globalLocaleMsg = this._customMessages[`${targetLocale}:${type}`]
+    if (globalLocaleMsg !== undefined) return globalLocaleMsg
+
+    if (this._isLocaleKey(type)) {
+      return getMessage(type as LocaleKey, targetLocale)
+    }
+
+    return null
+  }
+
+  private static _isLocaleKey(key: string): boolean {
+    // All predefined locale keys are defined in language pack files
+    const msgs = getMessages()
+    return key in msgs
+  }
+}

package/src/core/MessageTemplate.ts

@@ -0,0 +1,42 @@
+import { renderTemplate } from './TemplateEngine.js'
+
+/**
+ * MessageTemplate — wraps a template string for rendering.
+ * Delegates to TemplateEngine.renderTemplate() (fix CORE-03).
+ * Maintains full v1 API compatibility (constructor + render + static render + static renderBatch).
+ */
+export class MessageTemplate {
+  private readonly template: string
+
+  constructor(template: string) {
+    this.template = template
+  }
+
+  /**
+   * Render the template with the given context.
+   */
+  render(context: Record<string, unknown> = {}): string {
+    return renderTemplate(this.template, context)
+  }
+
+  /**
+   * Statically render a template string with the given context.
+   */
+  static render(template: string, context: Record<string, unknown> = {}): string {
+    return renderTemplate(template, context)
+  }
+
+  /**
+   * Statically render multiple templates in batch.
+   */
+  static renderBatch(
+    templates: Record<string, string>,
+    context: Record<string, unknown> = {}
+  ): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const [key, tmpl] of Object.entries(templates)) {
+      result[key] = renderTemplate(tmpl, context)
+    }
+    return result
+  }
+}

package/src/core/ObjectDslBuilder.ts

@@ -0,0 +1,64 @@
+/**
+ * ObjectDslBuilder — v1 compat: dsl(object) returns a chainable builder.
+ *
+ * BC-2 fix: in v1, the schema returned by dsl({...}) / parseObject() supported .strict() /
+ * .requireAll() and other chain decorators, and implemented the toSchema() duck-type interface
+ * (Validator passes through internal schema). After v2 refactor, parseObject() returned plain
+ * JSONSchema, losing all chain API. This class wraps the DslParser.parseObject() result and
+ * exposes v1-equivalent chain methods:
+ *   - toSchema()     — return internal JSONSchema (Validator duck-type entry point)
+ *   - toJsonSchema() — return clean JSON Schema (internal schema-dsl keywords stripped)
+ *   - strict()       — disallow extra properties
+ *   - requireAll()   — require all defined properties to be present
+ *   - toString()     — serialize to JSON string
+ */
+
+import type { JSONSchema } from '../types/schema.js'
+import { TypeRegistry } from '../parser/TypeRegistry.js'
+
+export class ObjectDslBuilder {
+  readonly _isDslBuilder = true as const
+  readonly _isObjectDsl = true as const
+
+  private _schema: JSONSchema
+
+  constructor(schema: JSONSchema) {
+    this._schema = schema
+  }
+
+  // ==================== Output Methods ====================
+
+  /** Return internal JSONSchema (Validator.validate() duck-type entry point). */
+  toSchema(): JSONSchema {
+    return this._schema
+  }
+
+  /** Return clean JSON Schema (internal schema-dsl keywords stripped; safe for serialization or external tools). */
+  toJsonSchema(): JSONSchema {
+    return TypeRegistry.toJsonSchema(this._schema)
+  }
+
+  toString(): string {
+    return JSON.stringify(this.toJsonSchema())
+  }
+
+  // ==================== Chain Decorator Methods ====================
+
+  /**
+   * strict() — disallow extra properties (v1 compat).
+   * Equivalent to setting strictSchema: true on the compiled schema.
+   */
+  strict(): this {
+    ; (this._schema as Record<string, unknown>)['strictSchema'] = true
+    return this
+  }
+
+  /**
+   * requireAll() — require all defined properties to be present (v1 compat).
+   * Equivalent to setting requiredAll: true on the compiled schema.
+   */
+  requireAll(): this {
+    ; (this._schema as Record<string, unknown>)['requiredAll'] = true
+    return this
+  }
+}