schema-dsl 1.2.4 → 2.0.0

package/src/core/PluginManager.ts

@@ -0,0 +1,326 @@
+import { EventEmitter } from 'node:events'
+import type { Plugin, HookName, HookFn } from '../types/plugin.js'
+
+/**
+ * PluginManager — plugin registration and hook execution.
+ *
+ * Full v1 compatible API:
+ *   - hooks        : public hooks Map; supports any hook name
+ *   - EventEmitter compat: on / once / off / emit / removeListener / removeAllListeners
+ *   - unhook(name, fn): remove a specific hook handler
+ *   - runHook(name, ...args): pass arbitrary args, collect return values
+ *   - install(core, name?, opts?): supports named + options install for a single plugin
+ *   - install / uninstall pass through context
+ *   - has / get / list / clear / size / uninstall (alias)
+ */
+export class PluginManager extends EventEmitter {
+  readonly plugins: Map<string, Plugin> = new Map()
+
+  /**
+   * Public hooks Map (v1 compat: pluginManager.hooks.get('hookName')).
+   * Supports any string name, not limited to built-in HookName values.
+   */
+  readonly hooks: Map<string, Array<HookFn>> = new Map()
+
+  /** v1 compat context (passed to plugin install / uninstall). */
+  readonly context: { plugins: Map<string, Plugin>; hooks: Map<string, Array<HookFn>> } = {
+    plugins: this.plugins,
+    hooks: this.hooks,
+  }
+
+  /** Per-plugin hook references (used for automatic cleanup on unregister). */
+  private readonly _pluginHooks: Map<string, Map<string, Set<HookFn>>> = new Map()
+
+  private _installedCore: unknown = undefined
+
+  /** Built-in hook names (pre-initialized on construction). */
+  private static readonly BUILTIN_HOOKS: ReadonlyArray<HookName> = [
+    'beforeParse',
+    'afterParse',
+    'beforeCompile',
+    'afterCompile',
+    'beforeValidate',
+    'afterValidate',
+    'onError',
+  ]
+
+  /** Legacy v1 lifecycle hook names. */
+  private static readonly LEGACY_HOOKS: ReadonlyArray<string> = [
+    'onBeforeRegister',
+    'onAfterRegister',
+    'onBeforeValidate',
+    'onAfterValidate',
+    'onBeforeExport',
+    'onAfterExport',
+    'onBeforeCompile',
+    'onAfterCompile',
+    'onError',
+  ]
+
+  constructor() {
+    super()
+    this.setMaxListeners(0)
+    for (const name of [...PluginManager.BUILTIN_HOOKS, ...PluginManager.LEGACY_HOOKS]) {
+      this._ensureHook(name)
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────
+  // Core API
+  // ─────────────────────────────────────────────────────────────────────
+
+  /**
+   * Register a plugin.
+   */
+  register(plugin: Plugin): this {
+    if (!plugin || typeof plugin !== 'object') {
+      throw new Error('[schema-dsl] Plugin must be an object')
+    }
+    if (!plugin.name) {
+      throw new Error('[schema-dsl] Plugin must have a valid name')
+    }
+    if (!plugin.install) {
+      throw new Error(`[schema-dsl] Plugin must have an install function`)
+    }
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`[schema-dsl] Plugin "${plugin.name}" is already registered`)
+    }
+
+    this._runHookSync('onBeforeRegister', plugin)
+
+    this.plugins.set(plugin.name, plugin)
+
+    // Auto-register hooks declared by the plugin
+    if (plugin.hooks) {
+      for (const [hookName, fn] of Object.entries(plugin.hooks)) {
+        if (fn) {
+          this._addPluginHook(plugin.name, hookName, fn)
+        }
+      }
+    }
+
+    this._runHookSync('onAfterRegister', plugin)
+    this.emit('plugin:registered', plugin)
+    return this
+  }
+
+  /**
+   * Add a hook callback (supports any name, not limited to built-in HookName).
+   */
+  hook(name: string, fn: HookFn): this {
+    this._ensureHook(name)
+    this.hooks.get(name)!.push(fn)
+    return this
+  }
+
+  /**
+   * Remove a specific hook handler (v1 compat: unhook).
+   */
+  unhook(name: string, fn: HookFn): this {
+    const list = this.hooks.get(name)
+    if (list) {
+      const idx = list.indexOf(fn)
+      if (idx !== -1) list.splice(idx, 1)
+    }
+    return this
+  }
+
+  /**
+   * Run the specified hook.
+   * - Args are passed directly to each handler (v1 compat: runHook(name, arg1, arg2, ...)).
+   * - Returns an array of all handler return values.
+   * - If a handler throws, emits 'hook:error' and runs onError (does not interrupt remaining handlers).
+   */
+  async runHook(name: string, ...args: unknown[]): Promise<unknown[]> {
+    const list = this.hooks.get(name)
+    if (!list || list.length === 0) return []
+
+    const results: unknown[] = []
+    for (const fn of list) {
+      try {
+        const result = await fn(...args)
+        results.push(result)
+      } catch (error) {
+        const payload = { hookName: name, handler: fn, error }
+        this.emit('hook:error', payload)
+        this._runHookSync('onError', error, { hookName: name, handler: fn })
+      }
+    }
+    return results
+  }
+
+  /**
+   * Install plugins.
+   *
+   * Supports two call forms (v1 compat):
+   *   install(core)                       — install all registered plugins
+   *   install(core, pluginName, options?) — install the named plugin, merging plugin.options + options
+   */
+  install(core: unknown, pluginName?: string, extraOptions?: Record<string, unknown>): this {
+    this._installedCore = core
+
+    if (pluginName !== undefined) {
+      // Install the named plugin
+      const plugin = this.plugins.get(pluginName)
+      if (!plugin) {
+        throw new Error(`[schema-dsl] Plugin "${pluginName}" is not registered`)
+      }
+      this._installPlugin(core, plugin, extraOptions)
+    } else {
+      // Install all plugins
+      for (const plugin of this.plugins.values()) {
+        this._installPlugin(core, plugin, extraOptions)
+      }
+    }
+    return this
+  }
+
+  private _installPlugin(core: unknown, plugin: Plugin, extraOptions?: Record<string, unknown>): void {
+    const mergedOptions = { ...(plugin.options ?? {}), ...(extraOptions ?? {}) }
+    try {
+      plugin.install?.(core, mergedOptions, this.context)
+      this.emit('plugin:installed', plugin)
+    } catch (error) {
+      this.emit('plugin:error', { plugin, error })
+      const msg = error instanceof Error ? error.message : String(error)
+      throw new Error(`[schema-dsl] Failed to install plugin "${plugin.name}": ${msg}`)
+    }
+  }
+
+  /**
+   * Unregister a plugin (v2 primary method).
+   * - Automatically cleans up all hooks registered by this plugin.
+   * - Emits 'plugin:uninstalled' event.
+   */
+  unregister(name: string, coreInstance?: unknown): this {
+    const plugin = this.plugins.get(name)
+    if (!plugin) return this
+
+    const effectiveCore = coreInstance === undefined ? this._installedCore : coreInstance
+
+    if (typeof plugin.uninstall === 'function') {
+      try {
+        plugin.uninstall(effectiveCore, this.context)
+      } catch (error) {
+        this.emit('plugin:error', { plugin, error })
+        const msg = error instanceof Error ? error.message : String(error)
+        throw new Error(`[schema-dsl] Failed to uninstall plugin "${name}": ${msg}`)
+      }
+    }
+
+    // Clean up hooks registered by this plugin
+    const pluginHookMap = this._pluginHooks.get(name)
+    if (pluginHookMap) {
+      for (const [hookName, fns] of pluginHookMap) {
+        const list = this.hooks.get(hookName)
+        if (list) {
+          for (const fn of fns) {
+            const idx = list.indexOf(fn)
+            if (idx !== -1) list.splice(idx, 1)
+          }
+        }
+      }
+      this._pluginHooks.delete(name)
+    }
+
+    this.plugins.delete(name)
+
+    this.emit('plugin:uninstalled', plugin)
+    return this
+  }
+
+  // ─────────────────────────────────────────────────────────────────────
+  // v1 Compat API
+  // ─────────────────────────────────────────────────────────────────────
+
+  /** v1 compat: check whether a plugin is registered. */
+  has(name: string): boolean {
+    return this.plugins.has(name)
+  }
+
+  /** v1 compat: get a single plugin or the full plugins Map. */
+  get(name?: string): Plugin | Map<string, Plugin> | undefined {
+    if (name === undefined) return this.plugins
+    return this.plugins.get(name)
+  }
+
+  /** v1 compat: list all plugin metadata. */
+  list(): Array<{ name: string; version?: string; description?: string }> {
+    return Array.from(this.plugins.values()).map(p => ({
+      name: p.name,
+      ...(p.version !== undefined ? { version: p.version } : {}),
+      ...(p.description !== undefined ? { description: p.description } : {}),
+    }))
+  }
+
+  /** v1 compat: clear all plugins (including hook cleanup). */
+  clear(coreInstance?: unknown): this {
+    for (const name of Array.from(this.plugins.keys())) {
+      try {
+        this.unregister(name, coreInstance)
+      } catch {
+        // v1 behavior: clear() ignores individual plugin uninstall errors and continues
+      }
+    }
+    this.plugins.clear()
+    this._pluginHooks.clear()
+    // Clear all custom hooks (keep built-in pre-initialized entries but empty their handler arrays)
+    for (const [, list] of this.hooks) {
+      list.length = 0
+    }
+    this.emit('plugins:cleared')
+    return this
+  }
+
+  /** v1 compat: uninstall a plugin (alias for unregister). */
+  uninstall(name: string, coreInstance?: unknown): this {
+    return this.unregister(name, coreInstance)
+  }
+
+  get pluginCount(): number {
+    return this.plugins.size
+  }
+
+  /** v1 compat: plugin count (alias for pluginCount). */
+  get size(): number {
+    return this.plugins.size
+  }
+
+  // ─────────────────────────────────────────────────────────────────────
+  // Private Helpers
+  // ─────────────────────────────────────────────────────────────────────
+
+  private _ensureHook(name: string): void {
+    if (!this.hooks.has(name)) {
+      this.hooks.set(name, [])
+    }
+  }
+
+  private _addPluginHook(pluginName: string, hookName: string, fn: HookFn): void {
+    this._ensureHook(hookName)
+    this.hooks.get(hookName)!.push(fn)
+
+    // Record the mapping (for cleanup on unregister)
+    if (!this._pluginHooks.has(pluginName)) {
+      this._pluginHooks.set(pluginName, new Map())
+    }
+    const pluginMap = this._pluginHooks.get(pluginName)!
+    if (!pluginMap.has(hookName)) {
+      pluginMap.set(hookName, new Set())
+    }
+    pluginMap.get(hookName)!.add(fn)
+  }
+
+  private _runHookSync(name: string, ...args: unknown[]): void {
+    const list = this.hooks.get(name)
+    if (!list || list.length === 0) return
+
+    for (const handler of list) {
+      try {
+        handler(...args)
+      } catch (error) {
+        this.emit('hook:error', { hookName: name, handler, error })
+      }
+    }
+  }
+}

package/src/core/StringExtensions.ts

@@ -0,0 +1,140 @@
+/**
+ * StringExtensions — opt-in String.prototype chainable DSL extensions.
+ *
+ * v2 fixes:
+ *   S-01/S-02: array-driven symmetric install/uninstall (v1 uninstall was missing `format` and
+ *              `phoneNumber`). All method names are now maintained in the EXTENSION_METHODS
+ *              array so both operations are guaranteed to be in sync.
+ *
+ * @example
+ * import { installStringExtensions } from 'schema-dsl'
+ * installStringExtensions(dsl)
+ * // Then you can use:
+ * 'email!'.label('Email address').messages({ format: 'Invalid format' })
+ * 'string:3-32!'.username('medium')
+ */
+
+import type { DslBuilder } from './DslBuilder.js'
+
+// S-01/S-02 fix: all extension method names are managed here so install/uninstall stay symmetric
+const EXTENSION_METHODS = [
+  'pattern',
+  'label',
+  'messages',
+  'error',
+  'description',
+  'format',
+  'custom',
+  'default',
+  'toSchema',
+  'toJsonSchema',
+  'username',
+  'password',
+  'phone',
+  'phoneNumber',
+  'idCard',
+  'creditCard',
+  'licensePlate',
+  'postalCode',
+  'passport',
+  'slug',
+  'domain',
+  'ip',
+  'base64',
+  'jwt',
+  'dateGreater',
+  'dateLess',
+  'after',
+  'before',
+  'dateFormat',
+  'min',
+  'max',
+  'alphanum',
+  'lowercase',
+  'uppercase',
+  'json',
+  'precision',
+  'multiple',
+  'port',
+  'requireAll',
+  'strict',
+  'noSparse',
+  'includesRequired',
+  'required',
+  'optional',
+  'enum',
+  '_dslExtensionsInstalled',
+] as const
+
+type DslFn = (dslStr: string) => DslBuilder
+
+// Track which dslFunction the extensions were installed with
+let _installedDslFn: DslFn | null = null
+
+/**
+ * Install String.prototype extensions.
+ * @param dslFunction - dsl() function (converts a string to a DslBuilder instance)
+ */
+export function installStringExtensions(dslFunction: DslFn): void {
+  // Idempotent: skip only if installed with the same dslFunction reference
+  if (_installedDslFn === dslFunction) return
+  // If installed with a different function, uninstall first then reinstall
+  if (_installedDslFn !== null) {
+    uninstallStringExtensions()
+  }
+
+  const proto = String.prototype as unknown as Record<string, unknown>
+
+  function extend(name: string, fn: (...args: unknown[]) => unknown): void {
+    proto[name] = fn
+  }
+
+  // Proxy all listed methods transparently to the DslBuilder instance
+  const delegatedMethods: string[] = [
+    'pattern', 'label', 'messages', 'error', 'description', 'format', 'custom',
+    'default', 'username', 'password', 'phone', 'phoneNumber', 'idCard', 'creditCard',
+    'licensePlate', 'postalCode', 'passport', 'slug', 'domain', 'ip', 'base64', 'jwt',
+    'dateGreater', 'dateLess', 'after', 'before', 'dateFormat',
+    'min', 'max', 'alphanum', 'lowercase', 'uppercase', 'json',
+    'precision', 'multiple', 'port', 'requireAll', 'strict',
+    'noSparse', 'includesRequired', 'required', 'optional',
+  ]
+
+  for (const method of delegatedMethods) {
+    extend(method, function (this: string, ...args: unknown[]): DslBuilder {
+      const builder = dslFunction(String(this))
+      return (builder as unknown as Record<string, (...args: unknown[]) => DslBuilder>)[method](...args)
+    })
+  }
+
+  // enum method accepts rest parameters
+  extend('enum', function (this: string, ...values: unknown[]): DslBuilder {
+    return dslFunction(String(this)).enum(...values)
+  })
+
+  // toSchema / toJsonSchema return JSONSchema (not DslBuilder)
+  extend('toSchema', function (this: string) {
+    return dslFunction(String(this)).toSchema()
+  })
+  extend('toJsonSchema', function (this: string) {
+    return dslFunction(String(this)).toJsonSchema()
+  })
+
+  // Installation marker (v1 BC)
+  proto['_dslExtensionsInstalled'] = true
+  _installedDslFn = dslFunction
+}
+
+/**
+ * Uninstall String.prototype extensions (useful for tests or clean-up).
+ * S-01/S-02 fix: uses EXTENSION_METHODS array to guarantee perfect symmetry with install.
+ */
+export function uninstallStringExtensions(): void {
+  if (!(String.prototype as unknown as Record<string, unknown>)['_dslExtensionsInstalled']) return
+
+  const proto = String.prototype as unknown as Record<string, unknown>
+  for (const method of EXTENSION_METHODS) {
+    delete proto[method]
+  }
+  _installedDslFn = null
+}

package/src/core/TemplateEngine.ts

@@ -0,0 +1,44 @@
+/**
+ * Unified template engine.
+ *
+ * Merges the two rendering implementations from v1 — MessageTemplate.render() and
+ * ErrorFormatter._interpolate() — into a single pipeline.
+ * Fixes the CORE-03 template injection vulnerability (single-pass replacement so that
+ * substituted values are never expanded a second time).
+ *
+ * Supports two placeholder formats:
+ *   {{#key}}  ← all v1 locale files use this format (must remain compatible)
+ *   {key}     ← recommended format for v2 message templates
+ */
+
+/**
+ * Render a template string by replacing placeholders with corresponding values from params.
+ *
+ * @param template - Template string, e.g. "{{#label}} must be at least {{#min}} characters"
+ * @param params   - Substitution parameter object
+ * @returns          Rendered string; placeholders with no matching key are kept as-is (aids debugging)
+ *
+ * @example
+ * renderTemplate('{{#label}} is required', { label: 'Email' })
+ * // → 'Email is required'
+ *
+ * renderTemplate('{field} must be {min}~{max}', { field: 'age', min: 18, max: 65 })
+ * // → 'age must be 18~65'
+ */
+export function renderTemplate(template: string, params: Record<string, unknown>): string {
+  // Single-pass replace — prevents substituted values from being expanded again (CORE-03 fix)
+  // Regex matches both formats: {{#key}} and {key}
+  return template.replace(/\{\{#([^}]+)\}\}|\{([^}]+)\}/g, (match, k1: string | undefined, k2: string | undefined) => {
+    const key = k1 ?? k2
+    if (key !== undefined && key in params) {
+      const val = params[key]
+      if (val === null) return 'null'
+      if (val === undefined) return match
+      if (Array.isArray(val)) return val.join(', ')
+      if (val instanceof RegExp) return val.toString()
+      if (val instanceof Date) return val.toISOString()
+      return String(val)
+    }
+    return match // No matching key — keep placeholder as-is
+  })
+}