@lacqjs/nuxt-dict 0.0.2

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

@@ -0,0 +1,79 @@
+export class MemoryCache {
+  cache;
+  maxSize;
+  /** 毫秒级 TTL，0 表示永不过期 */
+  ttl;
+  constructor(maxSize = 200, ttl = 0) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.maxSize = maxSize;
+    this.ttl = ttl;
+  }
+  /** 读取缓存项，命中后移至末尾（LRU），TTL 过期则清除 */
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return void 0;
+    if (this.ttl > 0 && Date.now() - entry.timestamp > this.ttl) {
+      this.cache.delete(key);
+      return void 0;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry;
+  }
+  /** 写入缓存项，超过 maxSize 时淘汰最旧条目 */
+  set(key, entry) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else {
+      this.sweep();
+      if (this.cache.size >= this.maxSize) {
+        const firstKey = this.cache.keys().next().value;
+        if (firstKey !== void 0) {
+          this.cache.delete(firstKey);
+        }
+      }
+    }
+    this.cache.set(key, entry);
+  }
+  has(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    if (this.ttl > 0 && Date.now() - entry.timestamp > this.ttl) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+  delete(key) {
+    this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  /** 按 key 前缀删除缓存项。用于按仓库名清除内存缓存（key 格式: `{storeName}:...`） */
+  deleteByPrefix(prefix) {
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+  get size() {
+    this.sweep();
+    return this.cache.size;
+  }
+  keys() {
+    this.sweep();
+    return Array.from(this.cache.keys());
+  }
+  /** 清除所有已过期的缓存项 */
+  sweep() {
+    if (this.ttl <= 0) return;
+    const now = Date.now();
+    for (const [key, entry] of this.cache) {
+      if (now - entry.timestamp > this.ttl) {
+        this.cache.delete(key);
+      }
+    }
+  }
+}

package/dist/runtime/core/cache/version-check.d.ts

@@ -0,0 +1,26 @@
+import type { DictAdapter } from '../../types/index.js';
+/**
+ * 版本检查器，使用 localStorage 存储版本号（替代 IndexedDB meta store）。
+ * localStorage 同步读写、无需异步初始化，比 IndexedDB 更简单可靠。
+ *
+ * 逻辑：
+ * 1. 调用远程版本接口 → 失败则抛出，不操作 localStorage，不清理字典
+ * 2. 成功则比对 → 版本一致不操作 → 不一致时写入 localStorage、标记 changed
+ */
+export declare class VersionCheck {
+    private adapter;
+    private storageKey;
+    constructor(adapter: DictAdapter, storageKey: string);
+    /**
+     * 执行版本比对。
+     * @returns changed 为 true 时调用方应执行 invalidateAll 清空全部缓存
+     */
+    check(storeName: string): Promise<{
+        changed: boolean;
+        version: string;
+    }>;
+    /** 从 localStorage 读取版本号，不可用时返回 null */
+    private getStoredVersion;
+    /** 将版本号写入 localStorage */
+    private setStoredVersion;
+}

package/dist/runtime/core/cache/version-check.js

@@ -0,0 +1,38 @@
+export class VersionCheck {
+  adapter;
+  storageKey;
+  constructor(adapter, storageKey) {
+    this.adapter = adapter;
+    this.storageKey = typeof storageKey === "string" ? storageKey : "__NUXT_DICT_VERSION__";
+  }
+  /**
+   * 执行版本比对。
+   * @returns changed 为 true 时调用方应执行 invalidateAll 清空全部缓存
+   */
+  async check(storeName) {
+    const storedVersion = this.getStoredVersion();
+    const remoteVersion = await this.adapter.fetchVersion(storeName);
+    const changed = storedVersion !== remoteVersion;
+    if (changed) {
+      this.setStoredVersion(remoteVersion);
+    }
+    return { changed, version: remoteVersion };
+  }
+  /** 从 localStorage 读取版本号，不可用时返回 null */
+  getStoredVersion() {
+    if (typeof localStorage === "undefined") return null;
+    try {
+      return localStorage.getItem(this.storageKey);
+    } catch {
+      return null;
+    }
+  }
+  /** 将版本号写入 localStorage */
+  setStoredVersion(version) {
+    if (typeof localStorage === "undefined") return;
+    try {
+      localStorage.setItem(this.storageKey, version);
+    } catch {
+    }
+  }
+}

package/dist/runtime/core/dict-manager.d.ts

@@ -0,0 +1,74 @@
+import { IndexedDBCache } from './cache/indexeddb-cache.js';
+import type { DictAdapter, DictEntry } from '../types/index.js';
+export interface DictManagerOptions {
+    /** 仓库名 → DictAdapter 映射表。至少包含默认仓库 'dicts' 的 adapter */
+    adapters: Map<string, DictAdapter>;
+    indexedDB: IndexedDBCache;
+    memoryMax: number;
+    ttl: number;
+    /** localStorage 中存储版本号的 key */
+    versionStorageKey: string;
+}
+/**
+ * 字典管理器 —— 核心调度层。
+ *
+ * 缓存策略：内存缓存 → IndexedDB 持久缓存 → 网络请求
+ * 请求去重：对同一 key 的并发请求合并为单次网络调用（pendingRequests）
+ */
+export declare class DictManager {
+    private memoryCache;
+    private indexedDB;
+    private adapters;
+    /** 每个仓库独立的版本检查器 */
+    private versionChecks;
+    /** 正在进行的字典请求，用于去重 */
+    private pendingRequests;
+    /** 已完成版本检查的仓库集合 */
+    private checkedStores;
+    /** 正在进行的版本检查请求，用于去重 */
+    private pendingVersionChecks;
+    locale: import("vue").ShallowRef<string, string>;
+    constructor(options: DictManagerOptions);
+    /** 构建带存储库命名空间和语言后缀的缓存键 */
+    private buildKey;
+    /** 根据 storeName 获取对应的 adapter。找不到时回退到默认仓库 'dicts' 的 adapter */
+    private getAdapter;
+    /** 切换语言，清空内存缓存和待处理请求 */
+    setLocale(locale: string): void;
+    getLocale(): string;
+    /**
+     * 惰性版本检查：首次访问该仓库时检查版本变更，按需清理缓存。
+     * 并发调用去重 —— 同一仓库的多个 getDict 共享单次版本检查。
+     */
+    private ensureVersionChecked;
+    /**
+     * 获取字典数据。
+     * 优先级：内存缓存 → 合并中的请求 → IndexedDB → 网络请求
+     */
+    getDict(type: string, storeName?: string): Promise<DictEntry>;
+    /** 执行实际的数据获取与缓存写入 */
+    private fetchAndCache;
+    /**
+     * 强制刷新指定字典：跳过缓存，直接从网络获取最新数据。
+     * 适用于用户手动刷新、数据变更通知等场景。
+     */
+    refresh(type: string, storeName?: string): Promise<DictEntry>;
+    /** 翻译 code → label，未命中时回退原样 */
+    translate(type: string, code: string | number, storeName?: string): string;
+    /** 树形字典中查找 code 的完整层级路径 */
+    translatePath(type: string, code: string | number, separator?: string, storeName?: string): string;
+    /** DFS 在树形字典中查找目标编码的路径 */
+    private findPathInTree;
+    /**
+     * code 比对 —— 统一转字符串比较。
+     * 避免字典配置中数字/字符串编码不一致导致的匹配失败。
+     */
+    private codeMatch;
+    /** 初始化：版本检查已改为惰性执行，在首次访问仓库时触发 */
+    initialize(): Promise<void>;
+    /**
+     * 失效缓存数据。
+     * @param storeName 指定要失效的存储库，不传则清空所有存储库及内存缓存
+     */
+    invalidateAll(storeName?: string): Promise<void>;
+}

package/dist/runtime/core/dict-manager.js

@@ -0,0 +1,217 @@
+import { shallowRef } from "vue";
+import { MemoryCache } from "./cache/memory-cache.js";
+import { DEFAULT_STORE_NAME } from "./cache/indexeddb-cache.js";
+import { VersionCheck } from "./cache/version-check.js";
+export class DictManager {
+  memoryCache;
+  indexedDB;
+  adapters;
+  /** 每个仓库独立的版本检查器 */
+  versionChecks;
+  /** 正在进行的字典请求，用于去重 */
+  pendingRequests;
+  /** 已完成版本检查的仓库集合 */
+  checkedStores = /* @__PURE__ */ new Set();
+  /** 正在进行的版本检查请求，用于去重 */
+  pendingVersionChecks = /* @__PURE__ */ new Map();
+  locale = shallowRef("zh-CN");
+  constructor(options) {
+    this.memoryCache = new MemoryCache(options.memoryMax, options.ttl);
+    this.indexedDB = options.indexedDB;
+    this.adapters = options.adapters;
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.versionChecks = /* @__PURE__ */ new Map();
+    for (const [storeName, adapter] of options.adapters) {
+      const storageKey = storeName === DEFAULT_STORE_NAME ? options.versionStorageKey : `${options.versionStorageKey}__${storeName}`;
+      this.versionChecks.set(storeName, new VersionCheck(adapter, storageKey));
+    }
+  }
+  /** 构建带存储库命名空间和语言后缀的缓存键 */
+  buildKey(dictType, storeName) {
+    return `${storeName}:${dictType}_${this.locale.value}`;
+  }
+  /** 根据 storeName 获取对应的 adapter。找不到时回退到默认仓库 'dicts' 的 adapter */
+  getAdapter(storeName) {
+    return this.adapters.get(storeName) ?? this.adapters.get(DEFAULT_STORE_NAME);
+  }
+  /** 切换语言，清空内存缓存和待处理请求 */
+  setLocale(locale) {
+    if (this.locale.value !== locale) {
+      this.locale.value = locale;
+      this.memoryCache.clear();
+      this.pendingRequests.clear();
+    }
+  }
+  getLocale() {
+    return this.locale.value;
+  }
+  /**
+   * 惰性版本检查：首次访问该仓库时检查版本变更，按需清理缓存。
+   * 并发调用去重 —— 同一仓库的多个 getDict 共享单次版本检查。
+   */
+  async ensureVersionChecked(storeName) {
+    if (this.checkedStores.has(storeName)) return;
+    const pending = this.pendingVersionChecks.get(storeName);
+    if (pending) {
+      await pending;
+      return;
+    }
+    const promise = this.versionChecks.get(storeName) ? (async () => {
+      const vc = this.versionChecks.get(storeName);
+      try {
+        if (typeof localStorage !== "undefined") {
+          const { changed } = await vc.check(storeName);
+          if (changed) {
+            await this.invalidateAll(storeName);
+          }
+        }
+      } catch {
+      }
+    })() : Promise.resolve();
+    this.pendingVersionChecks.set(storeName, promise);
+    this.checkedStores.add(storeName);
+    try {
+      await promise;
+    } finally {
+      this.pendingVersionChecks.delete(storeName);
+    }
+  }
+  /**
+   * 获取字典数据。
+   * 优先级：内存缓存 → 合并中的请求 → IndexedDB → 网络请求
+   */
+  async getDict(type, storeName = DEFAULT_STORE_NAME) {
+    await this.ensureVersionChecked(storeName);
+    const key = this.buildKey(type, storeName);
+    const memoryEntry = this.memoryCache.get(key);
+    if (memoryEntry) {
+      return memoryEntry.data;
+    }
+    const pending = this.pendingRequests.get(key);
+    if (pending) {
+      return pending;
+    }
+    const promise = this.fetchAndCache(type, storeName, key);
+    this.pendingRequests.set(key, promise);
+    try {
+      return await promise;
+    } finally {
+      this.pendingRequests.delete(key);
+    }
+  }
+  /** 执行实际的数据获取与缓存写入 */
+  async fetchAndCache(type, storeName, key) {
+    const idbEntry = await this.indexedDB.get(storeName, type, this.locale.value);
+    if (idbEntry) {
+      this.memoryCache.set(key, {
+        data: idbEntry.data,
+        timestamp: Date.now(),
+        version: idbEntry.version
+      });
+      return idbEntry.data;
+    }
+    const adapter = this.getAdapter(storeName);
+    const response = await adapter.fetchDict(storeName, {
+      types: [type],
+      locale: this.locale.value
+    });
+    const entry = response.data[type];
+    if (!entry) {
+      throw new Error(`Dictionary type "${type}" not found in response`);
+    }
+    const cacheEntry = {
+      data: entry,
+      timestamp: Date.now(),
+      version: response.version
+    };
+    this.memoryCache.set(key, cacheEntry);
+    try {
+      await this.indexedDB.set(storeName, type, this.locale.value, cacheEntry);
+    } catch {
+    }
+    return entry;
+  }
+  /**
+   * 强制刷新指定字典：跳过缓存，直接从网络获取最新数据。
+   * 适用于用户手动刷新、数据变更通知等场景。
+   */
+  async refresh(type, storeName = DEFAULT_STORE_NAME) {
+    const key = this.buildKey(type, storeName);
+    this.memoryCache.delete(key);
+    this.pendingRequests.delete(key);
+    const adapter = this.getAdapter(storeName);
+    const response = await adapter.fetchDict(storeName, {
+      types: [type],
+      locale: this.locale.value
+    });
+    const entry = response.data[type];
+    if (!entry) {
+      throw new Error(`Dictionary type "${type}" not found in response`);
+    }
+    const cacheEntry = {
+      data: entry,
+      timestamp: Date.now(),
+      version: response.version
+    };
+    this.memoryCache.set(key, cacheEntry);
+    try {
+      await this.indexedDB.set(storeName, type, this.locale.value, cacheEntry);
+    } catch {
+    }
+    return entry;
+  }
+  /** 翻译 code → label，未命中时回退原样 */
+  translate(type, code, storeName = DEFAULT_STORE_NAME) {
+    const key = this.buildKey(type, storeName);
+    const entry = this.memoryCache.get(key);
+    if (!entry) return String(code);
+    const item = entry.data.items.find((i) => this.codeMatch(i.code, code));
+    return item?.label ?? String(code);
+  }
+  /** 树形字典中查找 code 的完整层级路径 */
+  translatePath(type, code, separator = " / ", storeName = DEFAULT_STORE_NAME) {
+    const key = this.buildKey(type, storeName);
+    const entry = this.memoryCache.get(key);
+    if (!entry || !entry.data.tree) return String(code);
+    const path = this.findPathInTree(entry.data.tree, code);
+    return path.length > 0 ? path.join(separator) : String(code);
+  }
+  /** DFS 在树形字典中查找目标编码的路径 */
+  findPathInTree(nodes, targetCode) {
+    for (const node of nodes) {
+      if (this.codeMatch(node.code, targetCode)) {
+        return [node.label];
+      }
+      if (node.children && node.children.length > 0) {
+        const childPath = this.findPathInTree(node.children, targetCode);
+        if (childPath.length > 0) {
+          return [node.label, ...childPath];
+        }
+      }
+    }
+    return [];
+  }
+  /**
+   * code 比对 —— 统一转字符串比较。
+   * 避免字典配置中数字/字符串编码不一致导致的匹配失败。
+   */
+  codeMatch(a, b) {
+    return String(a) === String(b);
+  }
+  /** 初始化：版本检查已改为惰性执行，在首次访问仓库时触发 */
+  async initialize() {
+  }
+  /**
+   * 失效缓存数据。
+   * @param storeName 指定要失效的存储库，不传则清空所有存储库及内存缓存
+   */
+  async invalidateAll(storeName) {
+    if (storeName) {
+      this.memoryCache.deleteByPrefix(`${storeName}:`);
+    } else {
+      this.memoryCache.clear();
+    }
+    this.pendingRequests.clear();
+    await this.indexedDB.clear(storeName);
+  }
+}

package/dist/runtime/options.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedModuleOptions } from './types/index.js';
+/** 模块默认配置。module.ts 和 runtime 端共享同一份，避免重复定义。 */
+export declare const defaultOptions: ResolvedModuleOptions;

package/dist/runtime/options.js

@@ -0,0 +1,33 @@
+export const defaultOptions = {
+  enable: true,
+  logLevel: 3,
+  api: {
+    baseURL: "/api",
+    dictEndpoint: "/dict/list",
+    versionEndpoint: "/dict/version"
+  },
+  cache: {
+    memoryMax: 200,
+    ttl: 0,
+    indexedDB: {
+      enabled: true,
+      dbName: "nuxt-dict"
+    }
+  },
+  locale: {
+    default: "zh-CN",
+    source: "cookie",
+    cookieKey: "i18n_redirected",
+    queryKey: "lang",
+    headerKey: "accept-language",
+    paramKey: "lang",
+    apiHeaderKey: "X-Locale"
+  },
+  stores: {},
+  ssr: {
+    prefetch: []
+  },
+  version: {
+    storageKey: "__NUXT_DICT_VERSION__"
+  }
+};

package/dist/runtime/plugins/dict.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/plugins/dict.js

@@ -0,0 +1,130 @@
+import { watch } from "vue";
+import { defineNuxtPlugin, useRequestEvent, useCookie, useRoute } from "#imports";
+import { DictManager } from "../core/dict-manager.js";
+import { IndexedDBCache, DEFAULT_STORE_NAME } from "../core/cache/indexeddb-cache.js";
+import { createDefaultAdapter } from "../core/adapter.js";
+import { createDictTranslator } from "../utils/dict-translator.js";
+import { createLogger } from "../utils/logger.js";
+import { defaultOptions } from "../options.js";
+function resolveServerLocale(options) {
+  const event = useRequestEvent();
+  if (!event) return options.locale.default;
+  if (options.locale.source === "cookie") {
+    const langCookie = useCookie(options.locale.cookieKey);
+    return langCookie.value || options.locale.default;
+  }
+  if (options.locale.source === "header") {
+    const lang = event.headers.get(options.locale.headerKey);
+    return lang ? lang.split(",")[0]?.split(";")[0]?.trim() ?? options.locale.default : options.locale.default;
+  }
+  if (options.locale.source === "query") {
+    const url = event.node.req.url || "";
+    const searchIndex = url.indexOf("?");
+    if (searchIndex === -1) return options.locale.default;
+    const params = new URLSearchParams(url.slice(searchIndex));
+    return params.get(options.locale.queryKey) || options.locale.default;
+  }
+  return options.locale.default;
+}
+function isAbsoluteURL(url) {
+  return /^https?:\/\//iu.test(url);
+}
+function resolveBaseURL(baseURL) {
+  if (isAbsoluteURL(baseURL)) {
+    return baseURL;
+  }
+  if (import.meta.client) {
+    return baseURL;
+  }
+  const event = useRequestEvent();
+  if (!event) return baseURL;
+  const protocol = event.headers.get("x-forwarded-proto") || "http";
+  const host = event.headers.get("host");
+  return host ? `${protocol}://${host}` : baseURL;
+}
+function resolveClientLocale(options) {
+  if (options.locale.source === "cookie") {
+    const langCookie = useCookie(options.locale.cookieKey);
+    return langCookie.value || options.locale.default;
+  }
+  if (options.locale.source === "query") {
+    const route = useRoute();
+    return route.query[options.locale.queryKey] || options.locale.default;
+  }
+  return options.locale.default;
+}
+async function initClientCache(manager, indexedDB, logger) {
+  try {
+    await indexedDB.init();
+    await manager.initialize();
+  } catch (e) {
+    logger.warn("IndexedDB init failed:", e);
+  }
+}
+async function executePrefetch(manager, types, logger) {
+  try {
+    await Promise.all(types.map((type) => manager.getDict(type)));
+  } catch (e) {
+    logger.warn("SSR prefetch failed:", e);
+  }
+}
+function createAdapters(options, logger) {
+  const adapters = /* @__PURE__ */ new Map();
+  const defaultAdapter = options.api.adapter ?? createDefaultAdapter({
+    baseURL: resolveBaseURL(options.api.baseURL),
+    dictEndpoint: options.api.dictEndpoint,
+    versionEndpoint: options.api.versionEndpoint,
+    paramKey: options.locale.paramKey,
+    apiHeaderKey: options.locale.apiHeaderKey
+  });
+  adapters.set(DEFAULT_STORE_NAME, defaultAdapter);
+  logger.debug(`Dict adapter created for default store '${DEFAULT_STORE_NAME}': ${options.api.baseURL}${options.api.dictEndpoint}`);
+  for (const [storeName, storeApi] of Object.entries(options.stores)) {
+    const adapter = storeApi.adapter ?? createDefaultAdapter({
+      baseURL: resolveBaseURL(storeApi.baseURL ?? options.api.baseURL),
+      dictEndpoint: storeApi.dictEndpoint ?? options.api.dictEndpoint,
+      versionEndpoint: storeApi.versionEndpoint ?? options.api.versionEndpoint,
+      paramKey: options.locale.paramKey,
+      apiHeaderKey: options.locale.apiHeaderKey
+    });
+    adapters.set(storeName, adapter);
+    const desc = storeApi.adapter ? "custom adapter" : `${storeApi.baseURL ?? options.api.baseURL}${storeApi.dictEndpoint ?? options.api.dictEndpoint}`;
+    logger.debug(`Dict adapter created for store '${storeName}': ${desc}`);
+  }
+  return adapters;
+}
+const dictPlugin = defineNuxtPlugin(async (nuxtApp) => {
+  const options = nuxtApp.$config?.public?.dict ?? defaultOptions;
+  if (!options.enable) return;
+  const logger = createLogger("nuxt-dict", { level: options.logLevel });
+  const adapters = createAdapters(options, logger);
+  const indexedDB = new IndexedDBCache(options.cache.indexedDB.dbName);
+  const manager = new DictManager({
+    adapters,
+    indexedDB,
+    memoryMax: options.cache.memoryMax,
+    ttl: options.cache.ttl,
+    versionStorageKey: options.version.storageKey
+  });
+  const locale = import.meta.server ? resolveServerLocale(options) : resolveClientLocale(options);
+  manager.setLocale(locale);
+  if (import.meta.client && options.locale.source === "cookie") {
+    const langCookie = useCookie(options.locale.cookieKey);
+    watch(langCookie, (newLocale) => {
+      if (newLocale && newLocale !== manager.getLocale()) {
+        logger.debug(`Cookie locale changed to '${newLocale}'`);
+        manager.setLocale(newLocale);
+      }
+    });
+  }
+  if (import.meta.client && options.cache.indexedDB.enabled) {
+    await initClientCache(manager, indexedDB, logger);
+  }
+  if (import.meta.server && options.ssr.prefetch.length > 0) {
+    await executePrefetch(manager, options.ssr.prefetch, logger);
+  }
+  const translator = createDictTranslator(manager);
+  nuxtApp.provide("dict", translator);
+  nuxtApp.provide("dictManager", manager);
+});
+export default dictPlugin;