schema-dsl 1.2.4 → 2.0.0

package/package.json

@@ -1,23 +1,65 @@
 {
   "name": "schema-dsl",
-  "version": "1.2.4",
-  "description": "简洁强大的JSON Schema验证库 - DSL语法 + String扩展 + 便捷validate",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "version": "2.0.0",
+  "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": {
     ".": {
-      "require": "./index.js",
-      "import": "./index.mjs",
-      "types": "./index.d.ts"
+      "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": {
-    "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"
+    "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",
@@ -51,23 +93,39 @@
   },
   "homepage": "https://github.com/vextjs/schema-dsl#readme",
   "engines": {
-    "node": ">=12.0.0"
+    "node": ">=18.0.0"
   },
   "dependencies": {
-    "ajv": "^8.17.1",
-    "ajv-formats": "^2.1.1"
+    "ajv": "^8.18.0",
+    "ajv-formats": "^2.1.1",
+    "cache-hub": "^1.0.0",
+    "json5": "^2.2.3",
+    "safe-regex": "^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",
+    "@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.2.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 }

package/src/core/CacheManager.ts

@@ -0,0 +1,159 @@
+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 readonly _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) this._maxSize = opts.maxSize
+    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
+  }
+}