schema-dsl 1.2.5 → 2.0.1

package/src/errors/ValidationError.ts

@@ -0,0 +1,105 @@
+// V8/Node.js extension (not in ES2022 lib; declared explicitly)
+type ErrorWithCaptureStackTrace = typeof Error & {
+  captureStackTrace?: (target: object, ctor: unknown) => void
+}
+const ErrorCtor = Error as ErrorWithCaptureStackTrace
+
+import type { ValidationErrorItem } from '../types/validate.js'
+
+/**
+ * ValidationError — error class thrown when validateAsync() fails.
+ * Fixes v1 bug: malformed message format when errors array is empty.
+ */
+export class ValidationError extends Error {
+  readonly name = 'ValidationError' as const
+  readonly errors: ValidationErrorItem[]
+  readonly data: unknown
+  readonly statusCode: number
+
+  constructor(errors: ValidationErrorItem[], data?: unknown, statusCode = 400) {
+    // Fix: provide friendly message when errors array is empty (v1 bug)
+    const messages =
+      errors.length === 0
+        ? 'Validation failed'
+        : errors
+          .map(e => {
+            if (e.path) {
+              const field = e.path.replace(/^\//, '')
+              return field ? `${field}: ${e.message}` : e.message
+            }
+            return e.message
+          })
+          .join('; ')
+
+    // v1 compat: use " - " separator when no path, ": " otherwise
+    // v1 compat: single conditional error uses message string directly (no prefix)
+    const hasNoPath = errors.every(e => e.path === undefined || e.path === null || e.path === '')
+    const isSingleConditional = errors.length === 1 && errors[0].keyword === 'conditional' && hasNoPath
+    if (isSingleConditional) {
+      super(messages)
+    } else {
+      super(hasNoPath ? `Validation failed - ${messages}` : `Validation failed: ${messages}`)
+    }
+
+    this.errors = errors
+    this.data = data
+    this.statusCode = statusCode
+
+    if (ErrorCtor.captureStackTrace) {
+      ErrorCtor.captureStackTrace(this, ValidationError)
+    }
+  }
+
+  toJSON(): {
+    error: string
+    message: string
+    statusCode: number
+    details: Array<{
+      field: string | null
+      message: string
+      keyword: string
+      params?: Record<string, unknown>
+    }>
+  } {
+    return {
+      error: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.errors.map(e => ({
+        field: e.path ? e.path.replace(/^\//, '') : null,
+        message: e.message,
+        keyword: e.keyword,
+        ...(e.params !== undefined ? { params: e.params } : {}),
+      })),
+    }
+  }
+
+  getFieldError(field: string): ValidationErrorItem | null {
+    const normalized = field.replace(/^\//, '')
+    return (
+      this.errors.find(e => {
+        if (!e.path) return false
+        return e.path.replace(/^\//, '') === normalized
+      }) ?? null
+    )
+  }
+
+  getFieldErrors(): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const e of this.errors) {
+      if (e.path) {
+        const field = e.path.replace(/^\//, '')
+        if (field) result[field] = e.message
+      }
+    }
+    return result
+  }
+
+  hasFieldError(field: string): boolean {
+    return this.getFieldError(field) !== null
+  }
+
+  getErrorCount(): number {
+    return this.errors.length
+  }
+}

package/src/exporters/BaseExporter.ts

@@ -0,0 +1,60 @@
+/**
+ * BaseExporter — Base interface and abstract class for all exporters.
+ *
+ * Provides a unified abstract export() method signature; each exporter subclass implements it.
+ */
+
+import type { JSONSchema } from '../types/schema.js'
+
+// ==================== Common options type ====================
+
+export interface ExporterOptions {
+  [key: string]: unknown
+}
+
+// ==================== BaseExporter ====================
+
+export abstract class BaseExporter<TOptions extends ExporterOptions = ExporterOptions> {
+  protected options: TOptions
+
+  constructor(options: Partial<TOptions> = {}) {
+    this.options = options as TOptions
+  }
+
+  /**
+   * Export a JSON Schema to the target format.
+   * Each subclass must implement this method.
+   */
+  abstract export(...args: unknown[]): unknown
+
+  /**
+   * Assert that the input JSON Schema is a valid object-type schema.
+   * @throws Error if invalid.
+   */
+  protected _assertObjectSchema(jsonSchema: unknown, label = 'JSON Schema'): asserts jsonSchema is JSONSchema & { type: 'object' } {
+    if (!jsonSchema || typeof jsonSchema !== 'object') {
+      throw new Error(`[schema-dsl] ${label} must be an object`)
+    }
+    const s = jsonSchema as JSONSchema
+    if (s.type !== 'object') {
+      throw new Error(`[schema-dsl] ${label} must be an object type (got "${String(s.type)}")`)
+    }
+  }
+
+  /**
+   * Escape SQL single quotes (generic utility).
+   */
+  protected _escapeString(str: string): string {
+    return str.replace(/'/g, "''")
+  }
+
+  /**
+   * Detect the primary key column name in a schema (id / _id preferred).
+   */
+  protected _detectPrimaryKey(schema: JSONSchema): string | null {
+    if (!schema.properties) return null
+    if (schema.properties['id']) return 'id'
+    if (schema.properties['_id']) return '_id'
+    return null
+  }
+}

package/src/exporters/MarkdownExporter.ts

@@ -0,0 +1,305 @@
+/**
+ * MarkdownExporter — Export JSON Schema as human-readable Markdown documentation.
+ *
+ * v2 fix:
+ *   EX-01: required check prefers prop._required, then falls back to schema.required?.includes(key)
+ *          (v1 already had this logic; v2 preserves it with stronger type safety)
+ *
+ * @version 2.0.0
+ */
+
+import type { JSONSchema } from '../types/schema.js'
+import { BaseExporter, type ExporterOptions } from './BaseExporter.js'
+
+// ==================== Type definitions ====================
+
+export interface MarkdownExporterOptions extends ExporterOptions {
+  title?: string
+  locale?: 'zh-CN' | 'en-US' | 'ja-JP' | 'fr-FR' | 'es-ES'
+  includeExample?: boolean
+  includeDescription?: boolean
+}
+
+type Locale = 'zh-CN' | 'en-US' | 'ja-JP' | 'fr-FR' | 'es-ES'
+
+// ==================== MarkdownExporter ====================
+
+export class MarkdownExporter extends BaseExporter<MarkdownExporterOptions> {
+  constructor(options: Partial<MarkdownExporterOptions> = {}) {
+    super({
+      title: 'Schema Documentation',
+      locale: 'zh-CN',
+      includeExample: true,
+      includeDescription: true,
+      ...options,
+    })
+  }
+
+  /**
+   * Export as a Markdown document.
+   */
+  export(schema: JSONSchema, options?: Partial<MarkdownExporterOptions>): string {
+    return MarkdownExporter.export(schema, { ...this.options, ...options })
+  }
+
+  /**
+   * Static method: export directly without instantiation.
+   */
+  static export(schema: JSONSchema, options: Partial<MarkdownExporterOptions> = {}): string {
+    const {
+      title = 'Schema Documentation',
+      locale = 'zh-CN',
+      includeExample = true,
+      includeDescription = true,
+    } = options
+
+    let markdown = `# ${title}\n\n`
+
+    if (includeDescription && schema.description) {
+      markdown += `${schema.description}\n\n`
+    }
+
+    markdown += this._generateFieldsTable(schema, locale)
+
+    if (includeExample) {
+      markdown += '\n' + this._generateExample(schema, locale)
+    }
+
+    markdown += '\n' + this._generateConstraintsSection(schema, locale)
+
+    return markdown
+  }
+
+  // ==================== Private static methods ====================
+
+  private static _i18nFields = {
+    'zh-CN': { fields: '字段列表', name: '字段名', type: '类型', required: '必填', constraints: '约束', description: '说明' },
+    'en-US': { fields: 'Fields', name: 'Field', type: 'Type', required: 'Required', constraints: 'Constraints', description: 'Description' },
+    'ja-JP': { fields: 'フィールド一覧', name: 'フィールド名', type: 'タイプ', required: '必須', constraints: '制約', description: '説明' },
+    'fr-FR': { fields: 'Liste des champs', name: 'Champ', type: 'Type', required: 'Obligatoire', constraints: 'Contraintes', description: 'Description' },
+    'es-ES': { fields: 'Lista de campos', name: 'Campo', type: 'Tipo', required: 'Requerido', constraints: 'Restricciones', description: 'Descripción' },
+  }
+
+  private static _i18nTypes: Record<Locale, Record<string, string>> = {
+    'zh-CN': { string: '字符串', number: '数字', integer: '整数', boolean: '布尔值', array: '数组', object: '对象', email: '邮箱', url: '网址', date: '日期', uuid: 'UUID' },
+    'en-US': { string: 'String', number: 'Number', integer: 'Integer', boolean: 'Boolean', array: 'Array', object: 'Object', email: 'Email', url: 'URL', date: 'Date', uuid: 'UUID' },
+    'ja-JP': { string: '文字列', number: '数値', integer: '整数', boolean: 'ブール値', array: '配列', object: 'オブジェクト', email: 'メールアドレス', url: 'URL', date: '日付', uuid: 'UUID' },
+    'fr-FR': { string: 'Chaîne', number: 'Nombre', integer: 'Entier', boolean: 'Booléen', array: 'Tableau', object: 'Objet', email: 'E-mail', url: 'URL', date: 'Date', uuid: 'UUID' },
+    'es-ES': { string: 'Cadena', number: 'Número', integer: 'Entero', boolean: 'Booleano', array: 'Array', object: 'Objeto', email: 'Correo', url: 'URL', date: 'Fecha', uuid: 'UUID' },
+  }
+
+  private static _i18nConstraints: Record<Locale, Record<string, string>> = {
+    'zh-CN': { length: '长度', range: '范围', pattern: '正则', enum: '枚举', items: '元素数' },
+    'en-US': { length: 'Length', range: 'Range', pattern: 'Pattern', enum: 'Enum', items: 'Items' },
+    'ja-JP': { length: '長さ', range: '範囲', pattern: '正規表現', enum: '列挙', items: '要素数' },
+    'fr-FR': { length: 'Longueur', range: 'Plage', pattern: 'Modèle', enum: 'Énumération', items: 'Éléments' },
+    'es-ES': { length: 'Longitud', range: 'Rango', pattern: 'Patrón', enum: 'Enumeración', items: 'Elementos' },
+  }
+
+  private static _i18nRules: Record<Locale, Record<string, string>> = {
+    'zh-CN': { rules: '约束规则', required: '必填字段', optional: '可选字段' },
+    'en-US': { rules: 'Validation Rules', required: 'Required Fields', optional: 'Optional Fields' },
+    'ja-JP': { rules: '検証ルール', required: '必須フィールド', optional: 'オプションフィールド' },
+    'fr-FR': { rules: 'Règles de validation', required: 'Champs obligatoires', optional: 'Champs facultatifs' },
+    'es-ES': { rules: 'Reglas de validación', required: 'Campos requeridos', optional: 'Campos opcionales' },
+  }
+
+  private static _generateFieldsTable(schema: JSONSchema, locale: Locale): string {
+    const t = this._i18nFields[locale] ?? this._i18nFields['en-US']
+
+    let table = `## ${t.fields}\n\n`
+    table += `| ${t.name} | ${t.type} | ${t.required} | ${t.constraints} | ${t.description} |\n`
+    table += `|--------|------|------|------|------|\n`
+
+    if (schema.properties) {
+      for (const [key, prop] of Object.entries(schema.properties)) {
+        const type = this._escapeTableCell(this._formatType(prop, locale))
+        // EX-01 fix: prefer _required flag, then fall back to schema.required
+        const isRequired = !!(
+          (prop as Record<string, unknown>)['_required'] === true ||
+          schema.required?.includes(key)
+        )
+        const required = isRequired ? '✅' : '❌'
+        const constraints = this._escapeTableCell(this._formatConstraints(prop, locale))
+        const description = this._escapeTableCell(this._getDescription(prop, locale))
+        const fieldName = this._escapeTableCell(key)
+
+        table += `| ${fieldName} | ${type} | ${required} | ${constraints} | ${description} |\n`
+      }
+    }
+
+    return table
+  }
+
+  private static _escapeTableCell(value: string): string {
+    return value
+      .replace(/\|/g, '\\|')
+      .replace(/\r\n|\r|\n/g, '<br>')
+  }
+
+  private static _formatType(prop: JSONSchema, locale: Locale): string {
+    const t = this._i18nTypes[locale] ?? this._i18nTypes['en-US']
+
+    if (prop.format) {
+      return t[prop.format] ?? prop.format
+    }
+
+    if (prop.type === 'array' && prop.items) {
+      const itemType = this._formatType(prop.items as JSONSchema, locale)
+      return `${t['array'] ?? 'array'}<${itemType}>`
+    }
+
+    return t[prop.type as string] ?? String(prop.type ?? 'any')
+  }
+
+  private static _formatConstraints(prop: JSONSchema, locale: Locale): string {
+    const constraints: string[] = []
+    const t = this._i18nConstraints[locale] ?? this._i18nConstraints['en-US']
+
+    if (prop.minLength !== undefined || prop.maxLength !== undefined) {
+      if (prop.minLength !== undefined && prop.maxLength !== undefined) {
+        constraints.push(`${t['length']}: ${prop.minLength}-${prop.maxLength}`)
+      } else if (prop.minLength !== undefined) {
+        constraints.push(`${t['length']}: ≥${prop.minLength}`)
+      } else if (prop.maxLength !== undefined) {
+        constraints.push(`${t['length']}: ≤${prop.maxLength}`)
+      }
+    }
+
+    if (prop.minimum !== undefined || prop.maximum !== undefined) {
+      if (prop.minimum !== undefined && prop.maximum !== undefined) {
+        constraints.push(`${t['range']}: ${prop.minimum}-${prop.maximum}`)
+      } else if (prop.minimum !== undefined) {
+        constraints.push(`${t['range']}: ≥${prop.minimum}`)
+      } else if (prop.maximum !== undefined) {
+        constraints.push(`${t['range']}: ≤${prop.maximum}`)
+      }
+    }
+
+    if (prop.minItems !== undefined || prop.maxItems !== undefined) {
+      if (prop.minItems !== undefined && prop.maxItems !== undefined) {
+        constraints.push(`${t['items']}: ${prop.minItems}-${prop.maxItems}`)
+      } else if (prop.minItems !== undefined) {
+        constraints.push(`${t['items']}: ≥${prop.minItems}`)
+      } else if (prop.maxItems !== undefined) {
+        constraints.push(`${t['items']}: ≤${prop.maxItems}`)
+      }
+    }
+
+    if (prop.pattern) {
+      constraints.push(`${t['pattern']}: \`${prop.pattern}\``)
+    }
+
+    if (prop.enum) {
+      const enumStr = (prop.enum as unknown[]).map(v => `\`${String(v)}\``).join(', ')
+      constraints.push(`${t['enum']}: ${enumStr}`)
+    }
+
+    return constraints.length > 0 ? constraints.join('<br>') : '-'
+  }
+
+  private static _getDescription(prop: JSONSchema, locale: Locale): string {
+    const p = prop as Record<string, unknown>
+
+    if (p['_labelI18n'] && typeof p['_labelI18n'] === 'object') {
+      const i18n = p['_labelI18n'] as Record<string, string>
+      if (i18n[locale]) return i18n[locale]
+    }
+
+    if (p['_label']) return p['_label'] as string
+    if (prop.description) return prop.description
+
+    return '-'
+  }
+
+  private static _generateExample(schema: JSONSchema, locale: Locale): string {
+    const i18n: Record<Locale, { example: string }> = {
+      'zh-CN': { example: '示例数据' },
+      'en-US': { example: 'Example Data' },
+      'ja-JP': { example: 'サンプルデータ' },
+      'fr-FR': { example: "Données d'exemple" },
+      'es-ES': { example: 'Datos de ejemplo' },
+    }
+    const t = i18n[locale] ?? i18n['en-US']
+
+    let example = `## ${t.example}\n\n\`\`\`json\n`
+    example += JSON.stringify(this._buildExample(schema), null, 2)
+    example += '\n```\n'
+    return example
+  }
+
+  private static _buildExample(schema: JSONSchema): unknown {
+    if (schema.properties) {
+      const obj: Record<string, unknown> = {}
+      for (const [key, prop] of Object.entries(schema.properties)) {
+        const isRequired = !!(
+          (prop as Record<string, unknown>)['_required'] === true ||
+          schema.required?.includes(key)
+        )
+        if (isRequired) {
+          obj[key] = this._getExampleValue(prop)
+        }
+      }
+      return obj
+    }
+    return null
+  }
+
+  private static _getExampleValue(prop: JSONSchema): unknown {
+    if (prop.default !== undefined) return prop.default
+    if (prop.enum) return (prop.enum as unknown[])[0]
+
+    switch (prop.type) {
+      case 'string':
+        if (prop.format === 'email') return 'user@example.com'
+        if (prop.format === 'uri' || prop.format === 'url') return 'https://example.com'
+        if (prop.format === 'date') return '2025-12-29'
+        if (prop.format === 'uuid') return '550e8400-e29b-41d4-a716-446655440000'
+        return 'example'
+      case 'number':
+      case 'integer':
+        if (prop.minimum !== undefined) return prop.minimum
+        if (prop.maximum !== undefined) return Math.floor(prop.maximum / 2)
+        return 0
+      case 'boolean':
+        return true
+      case 'array':
+        if (prop.items) return [this._getExampleValue(prop.items as JSONSchema)]
+        return []
+      case 'object':
+        if (prop.properties) return this._buildExample(prop)
+        return {}
+      default:
+        return null
+    }
+  }
+
+  private static _generateConstraintsSection(schema: JSONSchema, locale: Locale): string {
+    if (!schema.properties) return ''
+
+    const t = this._i18nRules[locale] ?? this._i18nRules['en-US']
+    const requiredFields: string[] = []
+    const optionalFields: string[] = []
+
+    for (const [key, prop] of Object.entries(schema.properties)) {
+      const isRequired = !!(
+        (prop as Record<string, unknown>)['_required'] === true ||
+        schema.required?.includes(key)
+      )
+      if (isRequired) requiredFields.push(key)
+      else optionalFields.push(key)
+    }
+
+    let section = `## ${t['rules']}\n\n`
+
+    if (requiredFields.length > 0) {
+      section += `**${t['required']}**: ${requiredFields.map(f => `\`${f}\``).join(', ')}\n\n`
+    }
+
+    if (optionalFields.length > 0) {
+      section += `**${t['optional']}**: ${optionalFields.map(f => `\`${f}\``).join(', ')}\n`
+    }
+
+    return section
+  }
+}

package/src/exporters/MongoDBExporter.ts

@@ -0,0 +1,126 @@
+/**
+ * MongoDBExporter — Export JSON Schema as a MongoDB $jsonSchema validation schema.
+ */
+
+import type { JSONSchema } from '../types/schema.js'
+import { BaseExporter, type ExporterOptions } from './BaseExporter.js'
+import { TypeConverter } from '../utils/TypeConverter.js'
+
+// ==================== Type definitions ====================
+
+export interface MongoDBExporterOptions extends ExporterOptions {
+  /** Whether to use strict mode (validationLevel: 'strict' vs 'moderate'). */
+  strict: boolean
+}
+
+export interface MongoDBValidationSchema {
+  $jsonSchema: Record<string, unknown>
+}
+
+export interface MongoDBCreateCommand {
+  collectionName: string
+  options: {
+    validator: MongoDBValidationSchema
+    validationLevel: 'strict' | 'moderate'
+    validationAction: 'error' | 'warn'
+  }
+}
+
+// ==================== MongoDBExporter ====================
+
+export class MongoDBExporter extends BaseExporter<MongoDBExporterOptions> {
+  constructor(options: Partial<MongoDBExporterOptions> = {}) {
+    super({ strict: false, ...options })
+  }
+
+  /**
+   * Convert a JSON Schema to a MongoDB $jsonSchema validation schema.
+   */
+  export(jsonSchema: unknown): MongoDBValidationSchema {
+    if (!jsonSchema || typeof jsonSchema !== 'object') {
+      throw new Error('[schema-dsl] Invalid JSON Schema')
+    }
+    const mongoSchema = this._convertSchema(jsonSchema as JSONSchema)
+    return { $jsonSchema: mongoSchema }
+  }
+
+  /**
+   * Generate a db.createCollection() command object.
+   */
+  generateCreateCommand(collectionName: string, jsonSchema: JSONSchema): MongoDBCreateCommand {
+    const validationSchema = this.export(jsonSchema)
+    return {
+      collectionName,
+      options: {
+        validator: validationSchema,
+        validationLevel: this.options.strict ? 'strict' : 'moderate',
+        validationAction: 'error',
+      },
+    }
+  }
+
+  /**
+   * Generate an executable MongoDB command string.
+   */
+  generateCommand(collectionName: string, jsonSchema: JSONSchema): string {
+    const command = this.generateCreateCommand(collectionName, jsonSchema)
+    return `db.createCollection("${command.collectionName}", ${JSON.stringify(command.options, null, 2)})`
+  }
+
+  /**
+   * Static quick-export shorthand.
+   */
+  static export(jsonSchema: JSONSchema): MongoDBValidationSchema {
+    return new MongoDBExporter().export(jsonSchema)
+  }
+
+  // ==================== Private methods ====================
+
+  private _convertSchema(schema: JSONSchema): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+
+    if (schema.type) {
+      result['bsonType'] = TypeConverter.toMongoDBType(schema.type as string | string[])
+    } else if (schema.anyOf ?? schema.oneOf) {
+      const variants = (schema.anyOf ?? schema.oneOf) as JSONSchema[]
+      const bsonTypes = [...new Set(variants.map(v => v.type ? TypeConverter.toMongoDBType(v.type as string) : null).filter(Boolean))]
+      result['bsonType'] = bsonTypes.length === 1 ? bsonTypes[0] : bsonTypes
+    }
+
+    if (schema.properties) {
+      result['properties'] = {}
+      for (const [key, value] of Object.entries(schema.properties)) {
+        ;(result['properties'] as Record<string, unknown>)[key] = this._convertSchema(value)
+      }
+    }
+
+    if (schema.required && Array.isArray(schema.required)) {
+      result['required'] = schema.required
+    }
+
+    if (schema.items) {
+      result['items'] = this._convertSchema(schema.items as JSONSchema)
+    }
+
+    // String constraints
+    if (schema.minLength !== undefined) result['minLength'] = schema.minLength
+    if (schema.maxLength !== undefined) result['maxLength'] = schema.maxLength
+    if (schema.pattern) result['pattern'] = schema.pattern
+
+    // Numeric constraints
+    if (schema.minimum !== undefined) result['minimum'] = schema.minimum
+    if (schema.maximum !== undefined) result['maximum'] = schema.maximum
+
+    // Array constraints
+    if (schema.minItems !== undefined) result['minItems'] = schema.minItems
+    if (schema.maxItems !== undefined) result['maxItems'] = schema.maxItems
+
+    // Enum
+    if (schema.enum) result['enum'] = schema.enum
+
+    // Description
+    if (schema.description) result['description'] = schema.description
+
+    return result
+  }
+}