fix: bound validator cache lifecycle

Author: rockyshi1993

changelogs/unreleased.md

@@ -1,3 +1,5 @@
 # Unreleased
 
-- No unreleased changes.
+## 2026-06-10
+
+- **[Fixed]** Bound Validator/AJV compiled schema lifecycle: repeated DSL definitions and DslBuilder materialization now reuse stable schema cache keys, cache eviction and `clearCache()` release AJV internal schema refs, `_removeAdditional` uses a bounded internal compile cache, locale flatten cache is bounded and revision-aware, and official plugin uninstall paths clean custom formats, types, keywords, global plugin state, and Validator caches.

docs/en/api-reference.md

@@ -950,6 +950,7 @@ Unified type registry. It is the public entry for custom type extension. If you
 - `TypeRegistry.register(name, def)`
 - `TypeRegistry.registerDynamic(name, factory)`
 - `TypeRegistry.unregister(name)`
+- `DslBuilder.unregisterType(name)` - removes one custom type from both the Builder-side custom type table and `TypeRegistry`.
 - `TypeRegistry.has(typeName)`
 - `TypeRegistry.getInternalKeys()`
 - `TypeRegistry.toJsonSchema(schema)`

docs/en/plugin-type-registration.md

@@ -23,11 +23,13 @@ DslBuilder.registerType('orderCode', {
 });
 ```
 
+Use `DslBuilder.unregisterType('orderCode')` when a plugin or test needs to remove one Builder-side custom type. Use `DslBuilder.clearCustomTypes()` only when you intentionally want to clear all custom types, such as after isolated tests.
+
 Plug-in extensions can be used in conjunction with [plugin-system.md](./plugin-system.md).
 
 ---
 
 ## Corresponding sample file
 
 **Example entry**: [plugin-type-registration.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/plugin-type-registration.ts)
-**Note**: Covers both entrances `TypeRegistry.register()` and `DslBuilder.registerType()`, as well as the real validation and cleanup process after registration.
+**Note**: Covers `TypeRegistry.register()`, `DslBuilder.registerType()`, and cleanup with `DslBuilder.unregisterType()` / `DslBuilder.clearCustomTypes()`.

docs/en/union-types.md

@@ -184,6 +184,10 @@ Check if the type is registered.
 
 Get all registered custom types.
 
+#### `DslBuilder.unregisterType(name)`
+
+Remove one custom type registered through `DslBuilder.registerType()` / `TypeRegistry`.
+
 #### `DslBuilder.clearCustomTypes()`
 
 Clear all custom types (mainly for testing).

docs/zh/api-reference.md

@@ -892,6 +892,7 @@ const schema = new JSONSchemaCore()
 - `TypeRegistry.register(name, def)`
 - `TypeRegistry.registerDynamic(name, factory)`
 - `TypeRegistry.unregister(name)`
+- `DslBuilder.unregisterType(name)` — 同时从 Builder 侧自定义类型表和 `TypeRegistry` 移除一个自定义类型
 - `TypeRegistry.has(typeName)`
 - `TypeRegistry.getInternalKeys()`
 - `TypeRegistry.toJsonSchema(schema)`

docs/zh/plugin-type-registration.md

@@ -23,12 +23,14 @@ DslBuilder.registerType('orderCode', {
 });
 ```
 
+当插件或测试只需要移除一个 Builder 侧自定义类型时，使用 `DslBuilder.unregisterType('orderCode')`；只有确实要清空全部自定义类型（例如隔离测试收尾）时，才使用 `DslBuilder.clearCustomTypes()`。
+
 插件化扩展可结合 [plugin-system.md](./plugin-system.md) 使用。
 
 ---
 
 ## 对应示例文件
 
 **示例入口**: [plugin-type-registration.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/plugin-type-registration.ts)  
-**说明**: 同时覆盖 `TypeRegistry.register()` 和 `DslBuilder.registerType()` 两条入口，以及注册后的真实验证与清理流程。
+**说明**: 覆盖 `TypeRegistry.register()`、`DslBuilder.registerType()`，以及通过 `DslBuilder.unregisterType()` / `DslBuilder.clearCustomTypes()` 清理注册状态的路径。
 

docs/zh/union-types.md

@@ -185,6 +185,10 @@ install(schemaDsl, options, context) {
 
 获取所有已注册的自定义类型。
 
+#### `DslBuilder.unregisterType(name)`
+
+移除一个通过 `DslBuilder.registerType()` / `TypeRegistry` 注册的自定义类型。
+
 #### `DslBuilder.clearCustomTypes()`
 
 清除所有自定义类型（主要用于测试）。

src/core/DslBuilder.ts

@@ -116,6 +116,15 @@ export class DslBuilder implements IDslBuilder {
     }
   }
 
+  /** Unregister a custom type from both DslBuilder and TypeRegistry. */
+  static unregisterType(name: string): void {
+    if (!name || typeof name !== 'string') {
+      throw new Error('[schema-dsl] Type name must be a non-empty string')
+    }
+    TypeRegistry.unregister(name)
+    DslBuilder._customTypes.delete(name)
+  }
+
   /** Check whether a type is registered (built-in or custom). */
   static hasType(type: string): boolean {
     return TypeRegistry.has(type)

src/core/Locale.ts

@@ -19,6 +19,11 @@ export const DEFAULT_LOCALE = 'en-US'
 export class Locale {
   private static _currentLocale: string = DEFAULT_LOCALE
   private static _customMessages: Record<string, LocaleMessage> = {}
+  private static _revision = 0
+
+  static get revision(): number {
+    return this._revision
+  }
 
   /** v1 compat: expose custom messages */
   static get customMessages(): Record<string, LocaleMessage> {
@@ -59,6 +64,7 @@ export class Locale {
 
   static setMessages(messages: Record<string, LocaleMessage>): void {
     this._customMessages = { ...this._customMessages, ...messages }
+    this._revision++
   }
 
   static addLocale(locale: string, messages: Record<string, LocaleMessage>): void {
@@ -67,6 +73,7 @@ export class Locale {
     for (const [k, v] of Object.entries(messages)) {
       this._customMessages[`${locale}:${k}`] = v
     }
+    this._revision++
   }
 
   static getAvailableLocales(): string[] {
@@ -142,6 +149,7 @@ export class Locale {
   static reset(): void {
     this._currentLocale = DEFAULT_LOCALE
     this._customMessages = {}
+    this._revision++
   }
 
   // ─── Private Helpers ──────────────────────────────────────────────────────