@lacqjs/nuxt-dict 0.0.2

package/dist/module.d.mts

@@ -0,0 +1,13 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import * as __runtime_types from '../dist/runtime/types/index.js';
+import { ModuleOptions } from '../dist/runtime/types/index.js';
+export { ModuleOptions } from '../dist/runtime/types/index.js';
+
+/**
+ * Nuxt Dict 模块入口。
+ * 提供字典数据的统一管理、缓存、翻译和 SSR 预取能力。
+ * 用户通过 nuxt.config.ts 的 `dict` 配置项进行定制。
+ */
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, __runtime_types.ResolvedModuleOptions, true>;
+
+export { _default as default };

package/dist/module.d.ts

@@ -0,0 +1,13 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import * as __runtime_types from '../dist/runtime/types/index.js';
+import { ModuleOptions } from '../dist/runtime/types/index.js';
+export { ModuleOptions } from '../dist/runtime/types/index.js';
+
+/**
+ * Nuxt Dict 模块入口。
+ * 提供字典数据的统一管理、缓存、翻译和 SSR 预取能力。
+ * 用户通过 nuxt.config.ts 的 `dict` 配置项进行定制。
+ */
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, __runtime_types.ResolvedModuleOptions, true>;
+
+export { _default as default };

package/dist/module.json

@@ -0,0 +1,13 @@
+{
+  "name": "@lacqjs/nuxt-dict",
+  "version": "0.0.2",
+  "configKey": "dict",
+  "compatibility": {
+    "nuxt": "^4.4.8"
+  },
+  "moduleDependencies": {},
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,83 @@
+import { fileURLToPath } from 'url';
+import { defineNuxtModule, useLogger, createResolver, addPlugin, addImportsDir, addTypeTemplate } from '@nuxt/kit';
+import { defaultOptions } from '../dist/runtime/options.js';
+import { createLogger } from '../dist/runtime/utils/logger.js';
+
+const name = "@lacqjs/nuxt-dict";
+const version = "0.0.2";
+const devDependencies = {
+	nuxt: "^4.4.8"};
+const pkg = {
+	name: name,
+	version: version,
+	devDependencies: devDependencies};
+
+function registerTypeTemplates(resolver, stores) {
+  addTypeTemplate({
+    filename: "types/nuxt-dict.d.ts",
+    getContents: () => `
+import type { DictManager } from '${pkg.name}'
+
+declare module '#app' {
+  interface NuxtApp {
+    $dict: ReturnType<typeof import('${pkg.name}').createDictTranslator>
+    $dictManager: DictManager
+  }
+}
+
+export {}
+`
+  });
+  addTypeTemplate({
+    filename: "types/nuxt-dict-store-names.d.ts",
+    getContents: () => {
+      const storeNames = ["dicts", ...Object.keys(stores ?? {})];
+      const union = storeNames.map((s) => `'${s}'`).join(" | ");
+      return `export type StoreKey = ${union}
+`;
+    }
+  });
+}
+const module$1 = defineNuxtModule().with({
+  meta: {
+    name: pkg.name,
+    version: pkg.version,
+    configKey: "dict",
+    compatibility: {
+      nuxt: pkg.devDependencies.nuxt
+    },
+    moduleDependencies: {}
+  },
+  defaults: defaultOptions,
+  setup(_options, _nuxt) {
+    const logger = useLogger(pkg.name, { level: _options.logLevel });
+    logger.debug(`\u521D\u59CB\u5316\u6A21\u5757 ${pkg.name}`);
+    logger.debug(`${pkg.name} \u6A21\u5757\u9009\u9879:`, _options);
+    if (!_options.enable) {
+      logger.debug(`${pkg.name} \u6A21\u5757\u88AB\u7981\u7528\uFF0C\u8DF3\u8FC7\u8BBE\u7F6E\u3002`);
+      return;
+    }
+    const resolver = createResolver(import.meta.url);
+    const runtimeDir = fileURLToPath(new URL("./runtime", import.meta.url));
+    _nuxt.options.runtimeConfig.public.dict = _options;
+    _nuxt.options.build.transpile.push(resolver.resolve(runtimeDir));
+    addPlugin({ src: resolver.resolve(runtimeDir, "plugins", "dict.ts") });
+    addImportsDir(resolver.resolve(runtimeDir, "composables"));
+    registerTypeTemplates(resolver, _options.stores);
+    _nuxt.hook("prepare:types", ({ references }) => {
+      references.push({ types: pkg.name });
+    });
+  },
+  /** 模块首次安装到项目时触发 */
+  onInstall(_nuxt) {
+    const logger = createLogger(pkg.name);
+    logger.info(`\u9996\u6B21\u4E3A ${pkg.name} \u8FDB\u884C\u8BBE\u7F6E\uFF01`);
+  },
+  /** 模块版本升级时触发（使用 semver 比较，每版本只触发一次） */
+  onUpgrade(_nuxt, _options, _previousVersion) {
+    const logger = createLogger(pkg.name, { level: _options.logLevel });
+    logger.info(`\u5347\u7EA7 ${pkg.name} \u4ECE ${_previousVersion} \u5230 ${pkg.version}`);
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/composables/useDict.d.ts

@@ -0,0 +1,14 @@
+import type { UseDictReturn, StoreKey } from '../types/index.js';
+/**
+ * 使用指定类型的字典数据。
+ * 组件挂载时自动加载，卸载时自动清理引用。
+ * 返回翻译函数、加载状态和手动刷新方法。
+ *
+ * @example
+ * // 默认存储库 'dicts'
+ * const { data, translate } = useDict('gender')
+ * // 指定存储库 'dicts2'
+ * const { data, translate } = useDict('dicts2', 'gender')
+ */
+export declare function useDict(type: string): UseDictReturn;
+export declare function useDict(storeName: StoreKey, type: string): UseDictReturn;

package/dist/runtime/composables/useDict.js

@@ -0,0 +1,59 @@
+import { shallowRef, ref, watch, onMounted, onBeforeUnmount } from "vue";
+import { useNuxtApp } from "#imports";
+import { DEFAULT_STORE_NAME } from "../core/cache/indexeddb-cache.js";
+const activeInstances = /* @__PURE__ */ new Map();
+async function fetchDictData(manager, dictType, storeName, data, loading, error, mode = "load") {
+  loading.value = true;
+  error.value = null;
+  try {
+    const entry = await (mode === "refresh" ? manager.refresh(dictType, storeName) : manager.getDict(dictType, storeName));
+    data.value = entry.items;
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : String(e);
+  } finally {
+    loading.value = false;
+  }
+}
+function trackInstance(type, instanceId) {
+  if (!activeInstances.has(type)) {
+    activeInstances.set(type, /* @__PURE__ */ new Set());
+  }
+  activeInstances.get(type).add(instanceId);
+  onBeforeUnmount(() => {
+    const instances = activeInstances.get(type);
+    if (instances) {
+      instances.delete(instanceId);
+      if (instances.size === 0) {
+        activeInstances.delete(type);
+      }
+    }
+  });
+}
+export function useDict(storeOrType, maybeType) {
+  const nuxtApp = useNuxtApp();
+  const manager = nuxtApp.$dictManager;
+  const storeName = maybeType === void 0 ? DEFAULT_STORE_NAME : storeOrType;
+  const dictType = maybeType ?? storeOrType;
+  const data = shallowRef(null);
+  const loading = ref(false);
+  const error = ref(null);
+  const instanceId = Symbol(dictType);
+  const trackKey = `${storeName}:${dictType}`;
+  trackInstance(trackKey, instanceId);
+  function translate(code) {
+    return manager.translate(dictType, code, storeName);
+  }
+  async function refresh() {
+    await fetchDictData(manager, dictType, storeName, data, loading, error, "refresh");
+  }
+  onMounted(() => {
+    fetchDictData(manager, dictType, storeName, data, loading, error, "load");
+  });
+  watch(
+    () => manager.locale.value,
+    () => {
+      fetchDictData(manager, dictType, storeName, data, loading, error, "load");
+    }
+  );
+  return { data, translate, loading, error, refresh };
+}

package/dist/runtime/composables/useDictOptions.d.ts

@@ -0,0 +1,13 @@
+import type { UseDictOptionsReturn, StoreKey } from '../types/index.js';
+/**
+ * 以 { label, value } 格式使用字典数据，
+ * 直接适配 UI 库的 options 属性。
+ *
+ * @example
+ * // 默认存储库 'dicts'
+ * const { options } = useDictOptions('industry')
+ * // 指定存储库 'dicts2'
+ * const { options } = useDictOptions('dicts2', 'industry')
+ */
+export declare function useDictOptions(type: string): UseDictOptionsReturn;
+export declare function useDictOptions(storeName: StoreKey, type: string): UseDictOptionsReturn;

package/dist/runtime/composables/useDictOptions.js

@@ -0,0 +1,17 @@
+import { computed } from "vue";
+import { useDict } from "./useDict.js";
+export function useDictOptions(storeOrType, maybeType) {
+  const { data, loading, refresh } = maybeType === void 0 ? useDict(storeOrType) : useDict(storeOrType, maybeType);
+  const options = computed(() => {
+    if (!data.value) return [];
+    return data.value.map((item) => ({
+      label: item.label,
+      value: item.code
+    }));
+  });
+  return {
+    options,
+    loading,
+    refresh
+  };
+}

package/dist/runtime/composables/useDictTree.d.ts

@@ -0,0 +1,13 @@
+import type { UseDictTreeReturn, StoreKey } from '../types/index.js';
+/**
+ * 使用树形字典数据，支持翻译和路径查找。
+ * 组件挂载时自动加载，适用于区域选择器等级联场景。
+ *
+ * @example
+ * // 默认存储库 'dicts'
+ * const { tree, translate } = useDictTree('region')
+ * // 指定存储库 'dicts2'
+ * const { tree, translate } = useDictTree('dicts2', 'region')
+ */
+export declare function useDictTree(type: string): UseDictTreeReturn;
+export declare function useDictTree(storeName: StoreKey, type: string): UseDictTreeReturn;

package/dist/runtime/composables/useDictTree.js

@@ -0,0 +1,53 @@
+import { shallowRef, ref, watch, onMounted } from "vue";
+import { useNuxtApp } from "#imports";
+import { DEFAULT_STORE_NAME } from "../core/cache/indexeddb-cache.js";
+export function useDictTree(storeOrType, maybeType) {
+  const nuxtApp = useNuxtApp();
+  const manager = nuxtApp.$dictManager;
+  const storeName = maybeType === void 0 ? DEFAULT_STORE_NAME : storeOrType;
+  const dictType = maybeType ?? storeOrType;
+  const tree = shallowRef(null);
+  const loading = ref(false);
+  function translate(code) {
+    return manager.translate(dictType, code, storeName);
+  }
+  function findPath(code) {
+    if (!tree.value) return [];
+    return findPathInTree(tree.value, code);
+  }
+  async function load() {
+    loading.value = true;
+    try {
+      const entry = await manager.getDict(dictType, storeName);
+      tree.value = entry.tree ?? null;
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function refresh() {
+    loading.value = true;
+    try {
+      const entry = await manager.refresh(dictType, storeName);
+      tree.value = entry.tree ?? null;
+    } finally {
+      loading.value = false;
+    }
+  }
+  onMounted(load);
+  watch(() => manager.locale.value, load);
+  return { tree, translate, findPath, loading, refresh };
+}
+function findPathInTree(nodes, targetCode) {
+  for (const node of nodes) {
+    if (node.code === targetCode) {
+      return [node.label];
+    }
+    if (node.children && node.children.length > 0) {
+      const childPath = findPathInTree(node.children, targetCode);
+      if (childPath.length > 0) {
+        return [node.label, ...childPath];
+      }
+    }
+  }
+  return [];
+}

package/dist/runtime/composables/useLocale.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 获取/切换当前语言。
+ * 切换语言时会同步更新 cookie（客户端）并通知 DictManager 刷新缓存。
+ * locale 为 DictManager 上的响应式 ref，语言切换后所有 useDict / useDictTree 组件自动重取。
+ */
+export declare function useLocale(): {
+    locale: import("vue").ShallowRef<string, string>;
+    setLocale: (newLocale: string) => void;
+    locales: string[];
+};

package/dist/runtime/composables/useLocale.js

@@ -0,0 +1,20 @@
+import { useNuxtApp, useCookie, useRuntimeConfig } from "#imports";
+import { defaultOptions } from "../options.js";
+export function useLocale() {
+  const nuxtApp = useNuxtApp();
+  const manager = nuxtApp.$dictManager;
+  const options = useRuntimeConfig().public.dict ?? defaultOptions;
+  function setLocale(newLocale) {
+    manager.setLocale(newLocale);
+    if (import.meta.client) {
+      const langCookie = useCookie(options.locale.cookieKey, { maxAge: 60 * 60 * 24 * 365 });
+      langCookie.value = newLocale;
+    }
+  }
+  const locales = [];
+  return {
+    locale: manager.locale,
+    setLocale,
+    locales
+  };
+}

package/dist/runtime/core/adapter.d.ts

@@ -0,0 +1,17 @@
+import type { DictAdapter } from '../types/index.js';
+/** 创建默认适配器所需的配置参数 */
+export interface DefaultAdapterOptions {
+    baseURL: string;
+    dictEndpoint: string;
+    versionEndpoint: string;
+    /** 发送给 API 的语言参数名，设为空则不传，默认 'lang' */
+    paramKey: string;
+    /** 发送给 API 的语言请求头名，设为空则不传，默认 'X-Locale' */
+    apiHeaderKey: string;
+}
+/**
+ * 创建默认的 REST 字典适配器。
+ * 底层使用原生 fetch，兼容浏览器和 Node.js 18+（Nuxt 4 要求）。
+ * SSR 侧由 resolveBaseURL() 保证 baseURL 为绝对 origin，客户端相对路径由浏览器处理。
+ */
+export declare function createDefaultAdapter(options: DefaultAdapterOptions): DictAdapter;

package/dist/runtime/core/adapter.js

@@ -0,0 +1,50 @@
+function buildURL(baseURL, endpoint, params) {
+  const searchParams = new URLSearchParams(params);
+  const qs = searchParams.toString();
+  return qs ? `${baseURL}${endpoint}?${qs}` : `${baseURL}${endpoint}`;
+}
+async function fetchDictImpl(_storeName, config, types, locale) {
+  const params = { types: types.join(",") };
+  if (config.paramKey) {
+    params[config.paramKey] = locale;
+  }
+  const url = buildURL(config.baseURL, config.dictEndpoint, params);
+  const headers = { Accept: "application/json" };
+  if (config.apiHeaderKey) {
+    headers[config.apiHeaderKey] = locale;
+  }
+  try {
+    const response = await fetch(url, { method: "GET", headers });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return response.json();
+  } catch (e) {
+    throw new Error(`Failed to fetch dictionary: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+  }
+}
+async function fetchVersionImpl(_storeName, config) {
+  const url = buildURL(config.baseURL, config.versionEndpoint, {});
+  try {
+    const response = await fetch(url, { method: "GET", headers: { Accept: "application/json" } });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const data = await response.json();
+    if (!data.version) {
+      throw new Error("Version not found in response");
+    }
+    return data.version;
+  } catch (e) {
+    throw new Error(`Failed to fetch version: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+  }
+}
+export function createDefaultAdapter(options) {
+  const { baseURL, dictEndpoint, versionEndpoint, paramKey, apiHeaderKey } = options;
+  const dictConfig = { baseURL, dictEndpoint, paramKey, apiHeaderKey };
+  const versionConfig = { baseURL, versionEndpoint };
+  return {
+    fetchDict: (storeName, { types, locale }) => fetchDictImpl(storeName, dictConfig, types, locale),
+    fetchVersion: (storeName) => fetchVersionImpl(storeName, versionConfig)
+  };
+}

package/dist/runtime/core/cache/indexeddb-cache.d.ts

@@ -0,0 +1,48 @@
+import type { DictEntry, CacheEntry } from '../../types/index.js';
+/** 默认 IndexedDB 对象存储库名称 */
+export declare const DEFAULT_STORE_NAME = "dicts";
+/**
+ * IndexedDB 缓存实现，用于持久化字典数据。
+ * 支持客户端离线访问，减少重复网络请求。
+ * 版本号改用 localStorage 存储，不再使用 IndexedDB。
+ *
+ * 多对象存储库支持：
+ * - 默认存储库 `'dicts'` 在 init() 时创建
+ * - 额外存储库通过 ensureStore() 惰性创建
+ * - 使用串行升级队列处理并发多 store 创建，批量累积后一次升级完成
+ */
+export declare class IndexedDBCache {
+    private dbName;
+    private db;
+    private version;
+    /** 串行化升级队列，防止并发 ensureStore 导致多次版本升级 */
+    private upgradeQueue;
+    /** 累积待创建的 store 名，批量创建以减少升级次数 */
+    private pendingStores;
+    constructor(dbName: string);
+    /** 初始化 IndexedDB，创建默认对象存储库 */
+    init(): Promise<void>;
+    /**
+     * 惰性确保指定名称的对象存储库存在。
+     * 若当前 DB 中已有该 store 则立即返回；
+     * 否则将 store 名加入待建集合，通过串行队列触发一次版本升级批量创建。
+     */
+    private ensureStore;
+    /**
+     * 执行一次版本升级，批量创建所有累积的待建 object store。
+     * 内部注册 onversionchange 确保旧连接能被浏览器主动关闭，
+     * blocked 事件不视为错误——旧连接释放后 success 事件会自动触发。
+     */
+    private doUpgrade;
+    /** 生成存储键名：`{dictType}_{locale}` */
+    private getStoreKey;
+    /** 从指定存储库读取字典缓存 */
+    get(storeName: string, dictType: string, locale: string): Promise<CacheEntry<DictEntry> | null>;
+    /** 写入字典缓存条目到指定存储库 */
+    set(storeName: string, dictType: string, locale: string, entry: CacheEntry<DictEntry>): Promise<void>;
+    /**
+     * 清空字典缓存数据。
+     * @param storeName 指定要清空的存储库名，不传则清空全部存储库
+     */
+    clear(storeName?: string): Promise<void>;
+}

package/dist/runtime/core/cache/indexeddb-cache.js

@@ -0,0 +1,142 @@
+export const DEFAULT_STORE_NAME = "dicts";
+export class IndexedDBCache {
+  dbName;
+  db = null;
+  version = 1;
+  /** 串行化升级队列，防止并发 ensureStore 导致多次版本升级 */
+  upgradeQueue = Promise.resolve();
+  /** 累积待创建的 store 名，批量创建以减少升级次数 */
+  pendingStores = /* @__PURE__ */ new Set();
+  constructor(dbName) {
+    this.dbName = dbName;
+  }
+  /** 初始化 IndexedDB，创建默认对象存储库 */
+  init() {
+    if (this.db) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName);
+      request.addEventListener("upgradeneeded", () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(DEFAULT_STORE_NAME)) {
+          db.createObjectStore(DEFAULT_STORE_NAME);
+        }
+      });
+      request.addEventListener("success", () => {
+        this.db = request.result;
+        this.version = this.db.version;
+        resolve();
+      });
+      request.addEventListener("error", () => {
+        reject(new Error("Failed to open IndexedDB: " + (request.error?.message || "unknown error")));
+      });
+      request.addEventListener("blocked", () => {
+        reject(new Error("IndexedDB is blocked by another tab"));
+      });
+    });
+  }
+  /**
+   * 惰性确保指定名称的对象存储库存在。
+   * 若当前 DB 中已有该 store 则立即返回；
+   * 否则将 store 名加入待建集合，通过串行队列触发一次版本升级批量创建。
+   */
+  async ensureStore(storeName) {
+    await this.init();
+    if (this.db.objectStoreNames.contains(storeName)) return;
+    this.pendingStores.add(storeName);
+    this.upgradeQueue = this.upgradeQueue.then(() => this.doUpgrade());
+    return this.upgradeQueue;
+  }
+  /**
+   * 执行一次版本升级，批量创建所有累积的待建 object store。
+   * 内部注册 onversionchange 确保旧连接能被浏览器主动关闭，
+   * blocked 事件不视为错误——旧连接释放后 success 事件会自动触发。
+   */
+  async doUpgrade() {
+    if (this.pendingStores.size === 0) return;
+    const stores = new Set(this.pendingStores);
+    this.pendingStores.clear();
+    const toCreate = [...stores].filter((s) => !this.db.objectStoreNames.contains(s));
+    if (toCreate.length === 0) return;
+    this.db.onversionchange = () => {
+      this.db.close();
+    };
+    this.db.close();
+    this.version++;
+    await new Promise((resolve, reject) => {
+      const req = indexedDB.open(this.dbName, this.version);
+      req.addEventListener("upgradeneeded", () => {
+        const db = req.result;
+        for (const name of toCreate) {
+          if (!db.objectStoreNames.contains(name)) {
+            db.createObjectStore(name);
+          }
+        }
+      });
+      req.addEventListener("success", () => {
+        this.db = req.result;
+        resolve();
+      });
+      req.addEventListener("error", () => reject(req.error));
+      req.addEventListener("blocked", () => {
+      });
+    });
+  }
+  /** 生成存储键名：`{dictType}_{locale}` */
+  getStoreKey(dictType, locale) {
+    return `${dictType}_${locale}`;
+  }
+  /** 从指定存储库读取字典缓存 */
+  async get(storeName, dictType, locale) {
+    if (!this.db) return null;
+    await this.ensureStore(storeName);
+    if (!this.db) return null;
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeName, "readonly");
+      const store = tx.objectStore(storeName);
+      const request = store.get(this.getStoreKey(dictType, locale));
+      request.addEventListener("success", () => resolve(request.result ?? null));
+      request.addEventListener("error", () => reject(request.error));
+    });
+  }
+  /** 写入字典缓存条目到指定存储库 */
+  async set(storeName, dictType, locale, entry) {
+    if (!this.db) return;
+    await this.ensureStore(storeName);
+    if (!this.db) return;
+    return new Promise((resolve, reject) => {
+      const tx = this.db.transaction(storeName, "readwrite");
+      const store = tx.objectStore(storeName);
+      const request = store.put(entry, this.getStoreKey(dictType, locale));
+      request.addEventListener("success", () => resolve());
+      request.addEventListener("error", () => reject(request.error));
+    });
+  }
+  /**
+   * 清空字典缓存数据。
+   * @param storeName 指定要清空的存储库名，不传则清空全部存储库
+   */
+  async clear(storeName) {
+    if (!this.db) return;
+    if (storeName) {
+      if (!this.db.objectStoreNames.contains(storeName)) return;
+      await new Promise((resolve, reject) => {
+        const tx = this.db.transaction(storeName, "readwrite");
+        const store = tx.objectStore(storeName);
+        const request = store.clear();
+        request.addEventListener("success", () => resolve());
+        request.addEventListener("error", () => reject(request.error));
+      });
+      return;
+    }
+    const storeNames = Array.from(this.db.objectStoreNames);
+    for (const name of storeNames) {
+      await new Promise((resolve, reject) => {
+        const tx = this.db.transaction(name, "readwrite");
+        const store = tx.objectStore(name);
+        const request = store.clear();
+        request.addEventListener("success", () => resolve());
+        request.addEventListener("error", () => reject(request.error));
+      });
+    }
+  }
+}

package/dist/runtime/core/cache/memory-cache.d.ts

@@ -0,0 +1,25 @@
+import type { CacheEntry } from '../../types/index.js';
+/**
+ * 内存缓存，支持 LRU 淘汰和 TTL 过期。
+ * Map 保证插入顺序，借助 keys().next() 获取最久未使用项。
+ */
+export declare class MemoryCache<T = unknown> {
+    private cache;
+    private maxSize;
+    /** 毫秒级 TTL，0 表示永不过期 */
+    private ttl;
+    constructor(maxSize?: number, ttl?: number);
+    /** 读取缓存项，命中后移至末尾（LRU），TTL 过期则清除 */
+    get(key: string): CacheEntry<T> | undefined;
+    /** 写入缓存项，超过 maxSize 时淘汰最旧条目 */
+    set(key: string, entry: CacheEntry<T>): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+    clear(): void;
+    /** 按 key 前缀删除缓存项。用于按仓库名清除内存缓存（key 格式: `{storeName}:...`） */
+    deleteByPrefix(prefix: string): void;
+    get size(): number;
+    keys(): string[];
+    /** 清除所有已过期的缓存项 */
+    private sweep;
+}