@lacqjs/nuxt-dict 0.0.2

package/dist/runtime/types/index.d.ts

@@ -0,0 +1,171 @@
+import type { ShallowRef, Ref, ComputedRef } from 'vue';
+/** 仓库名字面量联合类型，由 addTypeTemplate 根据 stores 配置动态生成 */
+import type { StoreKey } from '#build/types/nuxt-dict-store-names';
+export type { StoreKey };
+/** 字典项 */
+export interface DictItem {
+    code: string | number;
+    label: string;
+    [key: string]: unknown;
+}
+/** 树形字典节点，用于级联选择器 */
+export interface TreeNode extends DictItem {
+    children?: TreeNode[];
+}
+/** 单个字典类型的数据结构 */
+export interface DictEntry {
+    type: string;
+    items: DictItem[];
+    tree?: TreeNode[];
+}
+/** API 返回的字典响应格式 */
+export interface DictResponse {
+    version: string;
+    data: Record<string, DictEntry>;
+}
+/** IndexedDB 中存储的缓存条目 */
+export interface CacheEntry<T = DictEntry> {
+    data: T;
+    timestamp: number;
+    version: string;
+}
+/** 字典适配器接口，允许用户自定义数据源（REST / GraphQL / 本地文件等） */
+export interface DictAdapter {
+    fetchDict(storeName: string, options: {
+        types: string[];
+        locale: string;
+    }): Promise<DictResponse>;
+    fetchVersion(storeName: string): Promise<string>;
+}
+/** 语言来源类型 */
+export type LocaleSource = 'cookie' | 'header' | 'query';
+/** 单个仓库的 API 配置。未配置项从全局 `api` 继承。 */
+export interface StoreApiOptions {
+    /** API 基础地址，默认继承全局 `api.baseURL` */
+    baseURL?: string;
+    /** 字典列表接口路径，默认继承全局 `api.dictEndpoint` */
+    dictEndpoint?: string;
+    /** 版本号接口路径，默认继承全局 `api.versionEndpoint` */
+    versionEndpoint?: string;
+    /** 自定义字典适配器，不传则使用默认 REST 适配器（继承全局 api 配置） */
+    adapter?: DictAdapter;
+}
+/** 模块配置项（用户可传，字段均可选） */
+export interface ModuleOptions {
+    /** 是否启用字典模块，默认 `true` */
+    enable?: boolean;
+    /** 日志级别，0=静默, 1=错误, 2=警告, 3=信息, 4=调试, 5=详细，默认 `3` */
+    logLevel?: number;
+    api?: {
+        /** API 基础地址，支持绝对 URL（外部接口）或相对路径（本地接口），默认 `'/api'` */
+        baseURL?: string;
+        /** 字典列表接口路径，默认 `'/dict/list'` */
+        dictEndpoint?: string;
+        /** 版本号接口路径，默认 `'/dict/version'` */
+        versionEndpoint?: string;
+        /** 自定义字典适配器，不传则使用默认 REST 适配器 */
+        adapter?: DictAdapter;
+    };
+    cache?: {
+        /** 内存缓存最大条目数，默认 `200` */
+        memoryMax?: number;
+        /** 内存缓存 TTL（毫秒），`0` 表示永不过期，默认 `0` */
+        ttl?: number;
+        indexedDB?: {
+            /** 是否启用 IndexedDB 持久缓存，默认 `true` */
+            enabled?: boolean;
+            /** IndexedDB 数据库名称，默认 `'nuxt-dict'` */
+            dbName?: string;
+        };
+    };
+    locale?: {
+        /** 兜底语言，无法从指定来源检测到语言时使用，默认 `'zh-CN'` */
+        default?: string;
+        /** 语言检测来源，`'cookie'` / `'header'` / `'query'`，默认 `'cookie'` */
+        source?: LocaleSource;
+        /** `source` 为 `'cookie'` 时读取的 cookie 名称，默认 `'lang'` */
+        cookieKey?: string;
+        /** `source` 为 `'query'` 时读取的 URL 查询参数名，默认 `'lang'` */
+        queryKey?: string;
+        /** `source` 为 `'header'` 时读取的请求头名称，默认 `'accept-language'` */
+        headerKey?: string;
+        /** 发给字典 API 时，语言值的查询参数名，设为 `''` 则不传，默认 `'lang'` */
+        paramKey?: string;
+        /** 发给字典 API 时，语言值的请求头名，设为 `''` 则不传，默认 `'X-Locale'` */
+        apiHeaderKey?: string;
+    };
+    /** 仓库 API 配置映射。key 为仓库名，value 为该仓库的 API 端点配置。
+     * 未配置的字段从全局 `api` 继承。未在此列出的仓库使用全局 `api` 配置。
+     * @example { payment: { baseURL: 'https://pay-api.com' }, logistics: { dictEndpoint: '/logistics/list' } }
+     */
+    stores?: Record<string, StoreApiOptions>;
+    ssr?: {
+        /** 服务端预取的字典类型列表，加速首屏渲染 */
+        prefetch?: string[];
+    };
+    version?: {
+        /** localStorage 中存储版本号的 key，默认 `'__NUXT_DICT_VERSION__'` */
+        storageKey?: string;
+    };
+}
+/** 模块配置项（内部解析后，字段均必填） */
+export interface ResolvedModuleOptions {
+    enable: boolean;
+    logLevel: number;
+    api: {
+        baseURL: string;
+        dictEndpoint: string;
+        versionEndpoint: string;
+        adapter?: DictAdapter;
+    };
+    cache: {
+        memoryMax: number;
+        ttl: number;
+        indexedDB: {
+            enabled: boolean;
+            dbName: string;
+        };
+    };
+    locale: {
+        default: string;
+        source: LocaleSource;
+        cookieKey: string;
+        queryKey: string;
+        headerKey: string;
+        paramKey: string;
+        apiHeaderKey: string;
+    };
+    /** 仓库 API 配置映射（解析后） */
+    stores: Record<string, StoreApiOptions>;
+    ssr: {
+        prefetch: string[];
+    };
+    version: {
+        storageKey: string;
+    };
+}
+/** useDict 返回类型 */
+export interface UseDictReturn {
+    data: ShallowRef<DictItem[] | null>;
+    translate: (code: string | number) => string;
+    loading: Ref<boolean>;
+    error: Ref<string | null>;
+    refresh: () => Promise<void>;
+}
+/** useDictOptions 返回类型 */
+export interface UseDictOptionsReturn {
+    options: ComputedRef<{
+        label: string;
+        value: string | number;
+    }[]>;
+    loading: Ref<boolean>;
+    refresh: () => Promise<void>;
+}
+/** useDictTree 返回类型 */
+export interface UseDictTreeReturn {
+    tree: ShallowRef<TreeNode[] | null>;
+    translate: (code: string | number) => string;
+    findPath: (code: string | number) => string[];
+    loading: Ref<boolean>;
+    refresh: () => Promise<void>;
+}

package/dist/runtime/utils/dict-translator.d.ts

@@ -0,0 +1,34 @@
+import type { DictManager } from '../core/dict-manager.js';
+/**
+ * 创建字典翻译器，封装 translate / translatePath 方法。
+ * 作为 $dict 注入到 NuxtApp，供组件直接调用翻译。
+ * 使用包装层而非直接暴露 DictManager，以控制公开 API 范围。
+ *
+ * @example
+ * // 默认存储库 'dicts'
+ * $dict.translate('gender', code)
+ * $dict.translatePath('region', code)
+ *
+ * // 指定存储库，storeName 作为第一个参数
+ * $dict.translate('dicts2', 'gender', code)
+ * $dict.translatePath('dicts2', 'region', code)
+ * $dict.translatePath('dicts2', 'region', code, ' -> ')
+ *
+ * // 注意：默认存储库 + 自定义分隔符需显式传 storeName
+ * $dict.translatePath('dicts', 'region', code, ' -> ')
+ */
+export declare function createDictTranslator(manager: DictManager): {
+    /**
+     * 通过字典类型和编码获取翻译文本。
+     * 2 参：默认存储库；3 参：指定存储库（storeName 为第一个参数）
+     */
+    translate(storeOrType: string, codeOrType: string | number, code?: string | number): string;
+    /**
+     * 获取树形字典中某个编码的完整层级路径。
+     * 2 参：默认存储库 + 默认分隔符
+     * 3 参：指定存储库 + 默认分隔符（storeName 为第一个参数）
+     * 4 参：指定存储库 + 自定义分隔符
+     * 默认存储库 + 自定义分隔符需显式传 'dicts' 作为 storeName
+     */
+    translatePath(storeOrType: string, codeOrType: string | number, separatorOrCode?: string | number, separator?: string): string;
+};

package/dist/runtime/utils/dict-translator.js

@@ -0,0 +1,30 @@
+export function createDictTranslator(manager) {
+  return {
+    /**
+     * 通过字典类型和编码获取翻译文本。
+     * 2 参：默认存储库；3 参：指定存储库（storeName 为第一个参数）
+     */
+    translate(storeOrType, codeOrType, code) {
+      if (code !== void 0) {
+        return manager.translate(codeOrType, code, storeOrType);
+      }
+      return manager.translate(storeOrType, codeOrType);
+    },
+    /**
+     * 获取树形字典中某个编码的完整层级路径。
+     * 2 参：默认存储库 + 默认分隔符
+     * 3 参：指定存储库 + 默认分隔符（storeName 为第一个参数）
+     * 4 参：指定存储库 + 自定义分隔符
+     * 默认存储库 + 自定义分隔符需显式传 'dicts' 作为 storeName
+     */
+    translatePath(storeOrType, codeOrType, separatorOrCode, separator) {
+      if (separator !== void 0) {
+        return manager.translatePath(codeOrType, separatorOrCode, separator, storeOrType);
+      }
+      if (separatorOrCode !== void 0) {
+        return manager.translatePath(codeOrType, separatorOrCode, void 0, storeOrType);
+      }
+      return manager.translatePath(storeOrType, codeOrType);
+    }
+  };
+}

package/dist/runtime/utils/logger.d.ts

@@ -0,0 +1,10 @@
+import type { ConsolaInstance } from 'consola';
+/**
+ * 创建带标签的 consola logger（单例模式）。
+ * 同一 tag 多次调用返回同一个实例，确保日志配置一致。
+ * @param tag 日志标签（模块名）
+ * @param options.level 日志级别，支持数字或字符串
+ */
+export declare function createLogger(tag: string, options?: {
+    level?: number | string;
+}): ConsolaInstance;

package/dist/runtime/utils/logger.js

@@ -0,0 +1,33 @@
+import { consola } from "consola";
+const globalLoggers = /* @__PURE__ */ new Map();
+export function createLogger(tag, options = {}) {
+  if (globalLoggers.has(tag)) {
+    const cached = globalLoggers.get(tag);
+    if (options.level !== void 0) {
+      cached.level = resolveLogLevel(options.level);
+    }
+    return cached;
+  }
+  const logger = consola.create({}).withTag(tag);
+  if (options.level !== void 0) {
+    logger.level = resolveLogLevel(options.level);
+  }
+  globalLoggers.set(tag, logger);
+  return logger;
+}
+function resolveLogLevel(level) {
+  if (typeof level === "number") return level;
+  const map = {
+    silent: -999,
+    fatal: 0,
+    error: 0,
+    warn: 1,
+    log: 2,
+    info: 3,
+    success: 3,
+    debug: 4,
+    trace: 5,
+    verbose: 999
+  };
+  return map[level.toLowerCase()] ?? 3;
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { type ModuleOptions } from '../dist/runtime/types/index.js'
+
+export { default } from './module.mjs'

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@lacqjs/nuxt-dict",
+  "version": "0.0.2",
+  "description": "Nuxt 数据字典模块，提供扁平/树形字典翻译、多语言国际化、三级缓存与 SSR 预取。",
+  "keywords": [
+    "@lacqjs/nuxt-dict",
+    "nuxt",
+    "nuxt-dict",
+    "dict"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "miaozf",
+    "email": "miaozf@example.com"
+  },
+  "contributors": [],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.4.8",
+    "compare-versions": "^6.1.1",
+    "consola": "^3.4.2",
+    "defu": "^6.1.7"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.4",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.4.8",
+    "@types/node": "^25.9.2",
+    "changelogen": "^0.6.2",
+    "element-plus": "^2.14.1",
+    "nuxt": "^4.4.8",
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
+    "typescript": "~5.9.3",
+    "vant": "^4.9.24",
+    "vue-tsc": "^3.3.4",
+    "ws": "^8.21.0"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.0.0",
+    "pnpm": ">=10.22.0",
+    "yarn": ">=1.22.22"
+  },
+  "scripts": {
+    "cleanup": "pnpx nuxt cleanup || npx nuxt cleanup",
+    "clean:install": "pnpm run cleanup && pnpm run docs:cleanup && pnpm run playground:cleanup && pnpm install",
+    "dev": "pnpm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "docs:dev": "nuxi dev docs",
+    "docs:build": "nuxi build docs",
+    "docs:cleanup": "pnpx rimraf docs/.nuxt docs/.output docs/dist docs/node_modules",
+    "playground:cleanup": "pnpx rimraf playground/.nuxt playground/.output playground/dist playground/node_modules",
+    "release": "pnpm lint && pnpm typecheck && pnpm prepack && changelogen --release && pnpm publish && git push --follow-tags",
+    "release:major": "pnpm lint && pnpm typecheck && pnpm prepack && changelogen --release --major && pnpm publish && git push --follow-tags",
+    "release:e2e": "pnpm lint && pnpm e2e && pnpm typecheck && pnpm prepack && changelogen --release && pnpm publish && git push --follow-tags",
+    "release:e2e:major": "pnpm lint && pnpm e2e && pnpm typecheck && pnpm prepack && changelogen --release --major && pnpm publish && git push --follow-tags",
+    "lint": "oxlint . && oxlint docs --no-error-on-unmatched-pattern",
+    "lint:fix": "oxlint --fix . && oxlint --fix docs --no-error-on-unmatched-pattern",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "e2e": "cd playground && pnpm e2e",
+    "typecheck": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  }
+}