schema-dsl 1.2.5 → 2.0.1

package/docs/validator.md

@@ -0,0 +1,39 @@
+# Validator 类概述
+
+`Validator` 是对 AJV 的封装，提供编译缓存、错误格式化、自定义关键字和批量验证能力。
+
+```javascript
+const { Validator, dsl } = require('schema-dsl');
+const validator = new Validator();
+const schema = dsl({ email: 'email!' });
+console.log(validator.validate(schema, { email: 'test@example.com' }));
+```
+
+## 缓存配置
+
+`Validator` 构造器支持两种缓存写法：
+
+```javascript
+new Validator({ cache: true });   // 使用默认缓存配置
+new Validator({ cache: false });  // 关闭缓存
+
+new Validator({
+  cache: {
+	enabled: true,
+	maxSize: 500,
+	ttl: 60 * 60 * 1000
+  }
+});
+```
+
+> 如果你希望直接传入 DSL 对象（例如 `validate({ email: 'email!' }, data)`），请使用顶层便捷函数 `validate()` / `validateAsync()`；`Validator` 实例方法仍建议接收标准 JSON Schema 或 `dsl({...})` 的转换结果。
+
+相关方法：`compile()`、`validate()`、`validateAsync()`、`validateBatch()`、`addKeyword()`、`addFormat()`。
+
+---
+
+## 对应示例文件
+
+**示例入口**: [validator.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/validator.ts)  
+**说明**: 覆盖 `new Validator()` 的常见配置、单次验证、编译缓存命中和 `validateBatch()` 复用路径。
+

package/package.json

@@ -1,73 +1,131 @@
-{
-  "name": "schema-dsl",
-  "version": "1.2.5",
-  "description": "简洁强大的JSON Schema验证库 - DSL语法 + String扩展 + 便捷validate",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "exports": {
-    ".": {
-      "require": "./index.js",
-      "import": "./index.mjs",
-      "types": "./index.d.ts"
-    }
-  },
-  "scripts": {
-    "test": "mocha test/unit/**/*.test.js",
-    "test:integration": "mocha test/integration/**/*.test.js",
-    "test:all": "mocha test/**/*.test.js",
-    "coverage": "nyc npm test",
-    "lint": "eslint lib/**/*.js",
-    "example": "node examples/dsl-style.js"
-  },
-  "keywords": [
-    "schema",
-    "validation",
-    "validator",
-    "dsl",
-    "json-schema",
-    "data-validation",
-    "form-validation",
-    "mongodb",
-    "mysql",
-    "postgresql",
-    "database-schema",
-    "i18n",
-    "internationalization",
-    "typescript",
-    "express",
-    "koa",
-    "fastify",
-    "rest-api",
-    "input-validation"
-  ],
-  "author": "rocky <rockyshi1993@gmail.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/vextjs/schema-dsl.git"
-  },
-  "bugs": {
-    "url": "https://github.com/vextjs/schema-dsl/issues"
-  },
-  "homepage": "https://github.com/vextjs/schema-dsl#readme",
-  "engines": {
-    "node": ">=12.0.0"
-  },
-  "dependencies": {
-    "ajv": "^8.17.1",
-    "ajv-formats": "^2.1.1"
-  },
-  "devDependencies": {
-    "benchmark": "^2.1.4",
-    "chai": "^4.5.0",
-    "eslint": "^8.57.1",
-    "express": "^5.2.1",
-    "joi": "^18.0.2",
-    "mocha": "^10.8.2",
-    "monsqlize": "^1.0.1",
-    "nyc": "^15.1.0",
-    "sinon": "^17.0.1",
-    "yup": "^1.7.1",
-    "zod": "^4.2.1"
-  }
-}
+{
+  "name": "schema-dsl",
+  "version": "2.0.1",
+  "description": "A concise and powerful JSON Schema validation library - DSL syntax + String extensions + convenient validate API",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./plugins/custom-format": {
+      "import": {
+        "types": "./dist/plugins/custom-format.d.ts",
+        "default": "./dist/plugins/custom-format.js"
+      },
+      "require": {
+        "types": "./dist/plugins/custom-format.d.cts",
+        "default": "./dist/plugins/custom-format.cjs"
+      }
+    },
+    "./plugins/custom-validator": {
+      "import": {
+        "types": "./dist/plugins/custom-validator.d.ts",
+        "default": "./dist/plugins/custom-validator.js"
+      },
+      "require": {
+        "types": "./dist/plugins/custom-validator.d.cts",
+        "default": "./dist/plugins/custom-validator.cjs"
+      }
+    },
+    "./plugins/custom-type-example": {
+      "import": {
+        "types": "./dist/plugins/custom-type-example.d.ts",
+        "default": "./dist/plugins/custom-type-example.js"
+      },
+      "require": {
+        "types": "./dist/plugins/custom-type-example.d.cts",
+        "default": "./dist/plugins/custom-type-example.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "examples:typecheck": "tsc -p tsconfig.examples.json --noEmit",
+    "examples:build": "tsc -p tsconfig.examples.json",
+    "lint": "eslint src/**/*.ts",
+    "test:version": "node -e \"const p=require('./package.json');const {VERSION}=require('./dist/index.cjs');if(p.version!==VERSION)throw new Error('Version mismatch: '+p.version+' vs '+VERSION);console.log('Version OK:',p.version)\"",
+    "bench": "node test/benchmarks/library-comparison.js",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test"
+  },
+  "keywords": [
+    "schema",
+    "validation",
+    "validator",
+    "dsl",
+    "json-schema",
+    "data-validation",
+    "form-validation",
+    "mongodb",
+    "mysql",
+    "postgresql",
+    "database-schema",
+    "i18n",
+    "internationalization",
+    "typescript",
+    "express",
+    "koa",
+    "fastify",
+    "rest-api",
+    "input-validation"
+  ],
+  "author": "rocky <rockyshi1993@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vextjs/schema-dsl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vextjs/schema-dsl/issues"
+  },
+  "homepage": "https://github.com/vextjs/schema-dsl#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.18.0",
+    "ajv-formats": "^2.1.1",
+    "cache-hub": "^1.0.0",
+    "json5": "^2.2.3",
+    "safe-regex": "^2.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.0.0",
+    "fastest-validator": "^1.19.1",
+    "joi": "^18.1.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0",
+    "yup": "^1.7.1",
+    "zod": "^4.3.6"
+  },
+  "type": "module",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.cjs",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.cts",
+    "plugins",
+    "src",
+    "docs",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}

package/plugins/custom-format.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+const mod = require('../dist/plugins/custom-format.cjs');
+const plugin = mod.default ?? mod.customFormatPlugin ?? mod;
+
+module.exports = plugin;
+module.exports.default = plugin;
+

package/plugins/custom-type-example.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+const mod = require('../dist/plugins/custom-type-example.cjs');
+const plugin = mod.default ?? mod.customTypeExamplePlugin ?? mod;
+
+module.exports = plugin;
+module.exports.default = plugin;
+

package/plugins/custom-validator.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+const mod = require('../dist/plugins/custom-validator.cjs');
+const plugin = mod.default ?? mod.customValidatorPlugin ?? mod;
+
+module.exports = plugin;
+module.exports.default = plugin;
+

package/src/adapters/DslAdapter.ts

@@ -0,0 +1,111 @@
+
+/**
+ * DslAdapter — DSL parsing adapter (thin wrapper layer).
+ *
+ * v2 changes:
+ *   - All parsing logic delegated to DslParser (replaces v1 DslAdapter._parseType duplication)
+ *   - Fixes DA-01/DA-02/DA-03 (handled uniformly by the DslParser pipeline)
+ *   - parseObject delegates to DslParser.parseObject (replaces JSONSchemaCore)
+ *   - BC-2 fix: parseObject() returns ObjectDslBuilder (supports chain .strict()/.requireAll())
+ *   - BC-4 fix: typeMap getter exposes all registered types; registerType() convenience entry point
+ */
+
+import type { JSONSchema } from '../types/schema.js'
+import type { DslDefinition } from '../types/dsl.js'
+import { DslParser } from '../parser/DslParser.js'
+import { TypeRegistry } from '../parser/TypeRegistry.js'
+import { ObjectDslBuilder } from '../core/ObjectDslBuilder.js'
+
+type DslMarker = Record<string, unknown>
+
+export const DslAdapter = {
+  /**
+   * Parse a DSL string into a JSON Schema.
+   * Equivalent to v1 DslAdapter.parseString(), but delegates to the unified DslParser.
+   */
+  parseString(dslString: string): JSONSchema {
+    if (!dslString || typeof dslString !== 'string') {
+      throw new Error('[schema-dsl] DslAdapter.parseString: DSL must be a string')
+    }
+    return DslParser.parseString(dslString)
+  },
+
+  /**
+   * parse() — alias for parseString() (backwards compat with v1).
+   */
+  parse(dslString: string): JSONSchema {
+    if (!dslString || typeof dslString !== 'string') {
+      throw new Error('[schema-dsl] DslAdapter.parse: DSL must be a string')
+    }
+    const schema = DslParser.parseString(dslString)
+    // v1 compat: always set _required (false if not set)
+    if ((schema as Record<string, unknown>)['_required'] === undefined) {
+      (schema as Record<string, unknown>)['_required'] = false
+    }
+    return schema
+  },
+
+  /**
+   * Parse an object-form DSL definition → ObjectDslBuilder (BC-2 fix).
+   * v1: parseObject() returned a chainable builder (.strict()/.requireAll()).
+   * v2 fix: returns ObjectDslBuilder wrapping the compiled JSONSchema.
+   */
+  parseObject(dslObj: DslDefinition): ObjectDslBuilder {
+    const schema = DslParser.parseObject(dslObj)
+    return new ObjectDslBuilder(schema)
+  },
+
+  /**
+   * Create a Match marker (v1 compat). The actual JSON Schema is built per target field in parseObject.
+   */
+  match(field: string, map: Record<string, unknown>): DslMarker {
+    return { _isMatch: true, field, map }
+  },
+
+  /**
+   * Create an If marker (v1 compat). The actual JSON Schema is built per target field in parseObject.
+   */
+  if(condition: string, thenSchema: unknown, elseSchema?: unknown): DslMarker {
+    return { _isIf: true, condition, then: thenSchema, else: elseSchema }
+  },
+
+  /**
+   * toCore() — v1 compat: returns { schema } wrapper
+   */
+  toCore(dslInput: string | DslDefinition): { schema: JSONSchema } {
+    let schema: JSONSchema
+    if (typeof dslInput === 'string') {
+      schema = this.parse(dslInput)
+    } else {
+      schema = DslParser.parseObject(dslInput)
+    }
+    return { schema }
+  },
+
+  /**
+   * typeMap getter — v1 compat: DslAdapter.typeMap exposes all registered types (BC-4 fix).
+   * Assigning typeMap[name] = schema is equivalent to calling TypeRegistry.register(name, schema).
+   */
+  get typeMap(): Record<string, JSONSchema> {
+    const map: Record<string, JSONSchema> = {}
+    for (const [name, def] of TypeRegistry.entries()) {
+      map[name] = def.baseSchema as JSONSchema
+    }
+    return new Proxy(map, {
+      set(_target: Record<string, JSONSchema>, key: string, value: JSONSchema) {
+        TypeRegistry.register(key, { baseSchema: value })
+        return true
+      },
+    })
+  },
+
+  /**
+   * registerType() — v1 compat: register a custom type into TypeRegistry (BC-4 fix).
+   */
+  registerType(name: string, schema: JSONSchema): void {
+    TypeRegistry.register(name, { baseSchema: schema })
+  },
+}
+
+export type DslAdapterType = typeof DslAdapter
+

package/src/adapters/index.ts

@@ -0,0 +1 @@
+export * from './DslAdapter.js'

package/src/config/constants.ts

@@ -0,0 +1,83 @@
+/**
+ * Global constants.
+ * Fixes:
+ *   CF-01 IPv4 regex too permissive → replaced with RFC-compliant standard regex
+ *   CF-02 IPv6 regex did not support compressed notation → replaced with full RFC 5952 compatible regex
+ */
+
+// ========== Validation config ==========
+export const VALIDATION = {
+  MAX_RECURSION_DEPTH: 100,
+  MAX_ARRAY_SIZE: 100_000,
+  MAX_STRING_LENGTH: 1_000_000,
+  MAX_OBJECT_KEYS: 10_000,
+  DEFAULT_TIMEOUT: 5_000,
+  REGEX_TIMEOUT: 100,
+  CUSTOM_VALIDATOR_TIMEOUT: 1_000,
+} as const
+
+// ========== Cache config ==========
+export const CACHE = {
+  ENABLED: true,
+  SCHEMA_CACHE: {
+    MAX_SIZE: 5_000,
+    TTL: 3_600_000,   // 1 hour
+    STRATEGY: 'LRU',
+  },
+  STATS_ENABLED: true,
+} as const
+
+// ========== Format validation regex ==========
+
+/**
+ * CF-01 fix: RFC-compliant IPv4 regex.
+ * Each octet 0-255, four groups, full-string match.
+ * Rejects invalid addresses such as 999.999.999.999.
+ */
+const IPV4_OCTET = '(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)'
+export const PATTERN_IPV4 = new RegExp(`^(?:${IPV4_OCTET}\\.){3}${IPV4_OCTET}$`)
+
+/**
+ * CF-02 fix: Full IPv6 regex (RFC 5952 compatible).
+ * Covers:
+ *   - Fully-expanded: 8 groups of hex
+ *   - :: compressed: prefix / suffix / standalone :: variants
+ * No nested quantifiers (avoids ReDoS).
+ */
+const HEX4 = '[0-9a-fA-F]{1,4}'
+const IPV6_FULL = `(?:${HEX4}:){7}${HEX4}`
+const IPV6_COMPRESS = [
+  `(?:${HEX4}:){1,7}:`,                         // n:...:
+  `(?:${HEX4}:){1,6}:${HEX4}`,                  // n:...:n
+  `(?:${HEX4}:){1,5}(?::${HEX4}){1,2}`,
+  `(?:${HEX4}:){1,4}(?::${HEX4}){1,3}`,
+  `(?:${HEX4}:){1,3}(?::${HEX4}){1,4}`,
+  `(?:${HEX4}:){1,2}(?::${HEX4}){1,5}`,
+  `${HEX4}:(?::${HEX4}){1,6}`,
+  `:(?::${HEX4}){1,7}`,                          // ::n...
+  `::`,                                           // standalone :: (all-zeros)
+].join('|')
+export const PATTERN_IPV6 = new RegExp(`^(?:${IPV6_FULL}|${IPV6_COMPRESS})$`)
+
+export const FORMATS = {
+  BUILT_IN: [
+    'email', 'url', 'uri', 'uuid', 'ipv4', 'ipv6',
+    'hostname', 'date', 'date-time', 'time', 'regex', 'json',
+  ] as const,
+  PATTERNS: {
+    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+    uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    ipv4: PATTERN_IPV4,
+    ipv6: PATTERN_IPV6,
+    hostname: /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i,
+    dateTime: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z?$/,
+    date: /^\d{4}-\d{2}-\d{2}$/,
+    time: /^\d{2}:\d{2}:\d{2}$/,
+  },
+} as const
+
+// ========== Plugin config ==========
+export const PLUGINS = {
+  MAX_PLUGINS: 50,
+  NAMING_CONVENTION: /^schema-dsl-plugin-/,
+} as const

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from './constants.js'
+export * from './patterns.js'

package/src/config/patterns.ts

@@ -0,0 +1,77 @@
+/**
+ * Built-in regex validation patterns (migrated from v1 lib/config/patterns/ to a single TypeScript file)
+ */
+
+export interface PatternConfig {
+  pattern: RegExp
+  min?: number
+  max?: number
+  key: string
+}
+
+const phone: Record<string, PatternConfig> = {
+  cn: { pattern: /^1[3-9]\d{9}$/, min: 11, max: 11, key: 'pattern.phone.cn' },
+  us: { pattern: /^\d{10}$/, min: 10, max: 10, key: 'pattern.phone.us' },
+  uk: { pattern: /^(\+44\s?)?0?\d{10}$/, min: 10, max: 15, key: 'pattern.phone.uk' },
+  hk: { pattern: /^[5-9]\d{7}$/, min: 8, max: 8, key: 'pattern.phone.hk' },
+  tw: { pattern: /^09\d{8}$/, min: 10, max: 10, key: 'pattern.phone.tw' },
+  international: { pattern: /^\+[1-9]\d{1,14}$/, min: 8, max: 15, key: 'pattern.phone.international' },
+}
+
+const idCard: Record<string, PatternConfig> = {
+  cn: {
+    pattern: /^[1-9]\d{5}(18|19|20)\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\d{3}[0-9Xx]$/,
+    min: 18, max: 18, key: 'pattern.idCard.cn',
+  },
+}
+
+const creditCard: Record<string, PatternConfig> = {
+  visa:       { pattern: /^4[0-9]{12}(?:[0-9]{3})?$/, key: 'pattern.creditCard.visa' },
+  mastercard: { pattern: /^5[1-5][0-9]{14}$/, key: 'pattern.creditCard.mastercard' },
+  amex:       { pattern: /^3[47][0-9]{13}$/, key: 'pattern.creditCard.amex' },
+  discover:   { pattern: /^6(?:011|5[0-9]{2})[0-9]{12}$/, key: 'pattern.creditCard.discover' },
+  jcb:        { pattern: /^(?:2131|1800|35\d{3})\d{11}$/, key: 'pattern.creditCard.jcb' },
+  unionpay:   { pattern: /^62[0-9]{14,17}$/, key: 'pattern.creditCard.unionpay' },
+}
+
+const licensePlate: Record<string, PatternConfig> = {
+  cn: {
+    pattern: /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-HJ-NP-Z0-9]{4}[A-HJ-NP-Z0-9挂学警港澳]$/,
+    key: 'pattern.licensePlate.cn',
+  },
+}
+
+const postalCode: Record<string, PatternConfig> = {
+  cn: { pattern: /^[1-9]\d{5}$/, key: 'pattern.postalCode.cn' },
+  us: { pattern: /^\d{5}(-\d{4})?$/, key: 'pattern.postalCode.us' },
+}
+
+const passport: Record<string, PatternConfig> = {
+  cn: {
+    pattern: /(^[EeKkGgDdHhMQqSs][0-9]{8}$)|(^(([Ee][a-fA-F])|([DdSPp][Ee])|([Kk][Jj])|([Mm][Aa])|(1[45]))[0-9]{7}$)/,
+    key: 'pattern.passport.cn',
+  },
+}
+
+const common: Record<string, PatternConfig> = {
+  domain: {
+    pattern: /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/i,
+    key: 'pattern.domain', min: 3, max: 253,
+  },
+  ip: {
+    // Composite IPv4 + IPv6 pattern (same as v1)
+    pattern:
+      /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$|^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$/,
+    key: 'pattern.ip',
+  },
+  base64: {
+    pattern: /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/,
+    key: 'pattern.base64',
+  },
+  jwt: {
+    pattern: /^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$/,
+    key: 'pattern.jwt',
+  },
+}
+
+export const PATTERNS = { phone, idCard, creditCard, licensePlate, postalCode, passport, common }