vue-cacheable-dictionary 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# vue-cacheable-dictionary
+
+[中文 README](./README.zh-CN.md)
+
+A small cacheable dictionary loader for Vue 3. It keeps a reactive store, dedupes in-flight requests, and lets you query dictionaries by key from anywhere.
+
+## Install
+
+```bash
+pnpm add vue-cacheable-dictionary
+# or
+npm i vue-cacheable-dictionary
+```
+
+## Usage
+
+Create a single instance (usually in a composable/module), provide a `load` function, then query dicts on demand.
+
+```ts
+import { createDictionaryInstance, type DictItem } from 'vue-cacheable-dictionary'
+
+interface MyDictItem extends DictItem {
+  color?: string
+}
+
+const dict = createDictionaryInstance<MyDictItem>({
+  load: async (dicts) => {
+    const res = await fetch('/dict', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(dicts),
+    })
+    return res.json() as Promise<Record<string, MyDictItem[]>>
+  },
+})
+
+export const useDict = dict.getDictData
+```
+
+In components:
+
+```ts
+import { computed } from 'vue'
+import { useDict } from './useDict'
+
+const store = useDict(['type', 'status'])
+
+const statusLabel = computed(() => store.get('status')?.label(1) ?? '')
+```
+
+## What you get
+
+- `createDictionaryInstance(...)`: creates an instance that manages caching and request deduplication.
+- `DictArray`: an array-like wrapper with helpers like `pick`, `omit`, `label`, and `item`.
+- `DictItem` / `DictKey` types for typing your dictionaries.
+
+## Notes
+
+- Only string keys are sent to `load(...)`. Non-string keys (e.g. `Symbol`) are ignored for remote loading.
+- The store is reactive and backed by a `Map`, so it works naturally in Vue templates/computed.
+
+## Development
+
+```bash
+pnpm install
+pnpm play
+pnpm test
+pnpm build
+pnpm typecheck
+```
+
+## Contributing
+
+- File an issue for bugs/feature requests.
+- Send a PR with focused changes and a clear description.
+- Ensure `pnpm test` and `pnpm typecheck` pass before opening a PR.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,81 @@
+# vue-cacheable-dictionary
+
+[English README](./README.md)
+
+一个面向 Vue 3 的可缓存字典加载器：维护响应式字典仓库、去重并发请求，并支持按 key 随用随取。
+
+## 安装
+
+```bash
+pnpm add vue-cacheable-dictionary
+# 或
+npm i vue-cacheable-dictionary
+```
+
+## 使用
+
+通常在一个 composable/模块中创建单例，提供 `load` 方法，然后按需查询字典。
+
+```ts
+import { createDictionaryInstance, type DictItem } from 'vue-cacheable-dictionary'
+
+interface MyDictItem extends DictItem {
+  color?: string
+}
+
+const dict = createDictionaryInstance<MyDictItem>({
+  load: async (dicts) => {
+    const res = await fetch('/dict', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(dicts),
+    })
+    return res.json() as Promise<Record<string, MyDictItem[]>>
+  },
+})
+
+export const useDict = dict.getDictData
+```
+
+组件内使用：
+
+```ts
+import { computed } from 'vue'
+import { useDict } from './useDict'
+
+const store = useDict(['type', 'status'])
+
+const statusLabel = computed(() => store.get('status')?.label(1) ?? '')
+```
+
+## 你会得到什么
+
+- `createDictionaryInstance(...)`：创建实例，负责缓存与请求去重。
+- `DictArray`：类数组封装，提供 `pick` / `omit` / `label` / `item` 等便捷方法。
+- `DictItem` / `DictKey`：字典数据类型定义。
+
+## 说明
+
+- 只有字符串类型的 key 会传给 `load(...)`；非字符串 key（例如 `Symbol`）会被忽略，不会触发远程请求。
+- 字典仓库底层是 `Map` 且具备响应式能力，可直接用于模板与 computed。
+
+## 开发
+
+```bash
+pnpm install
+pnpm play
+pnpm test
+pnpm build
+pnpm typecheck
+```
+
+## 贡献
+
+- 通过 Issue 提交 bug/需求。
+- 提交 PR 时保持改动聚焦，并写清楚变更目的与影响范围。
+- 提交前确保 `pnpm test` 与 `pnpm typecheck` 通过。
+
+## 许可证
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+import * as vue0 from "vue";
+
+//#region src/dict.d.ts
+type DictKey = string | symbol;
+interface DictItem {
+  label: string;
+  value: any;
+}
+type DictItemValue = DictItem['value'];
+declare class DictArray<D extends DictItem = DictItem> extends Array<D> {
+  constructor(dicts: D[]);
+  /**
+   * Like `omit` in `lodash.js`
+   * @param values The values of dict items to omit.
+   * @returns DictArray
+   */
+  omit(values: DictKey[]): DictArray<D>;
+  /**
+   * Like `pick` in `lodash.js`
+   * @param values The values of dict items.
+   * @returns DictArray
+   */
+  pick(values: DictKey[]): DictArray<D>;
+  /**
+   * Get label by value.
+   * @param value The value of dict item.
+   * @returns The label of dict item.
+   */
+  label(value: DictItemValue): string;
+  /**
+   * Get dict item by value.
+   * @param value The value of dict item.
+   * @param defaultDict The default dict item.
+   * @returns The dict item.
+   */
+  item(value: DictItemValue, defaultDict?: D): D | undefined;
+  /**
+   * Convert to plain array.
+   * It will lost all methods of DictArray.
+   * @returns Plain array.
+   */
+  toPlainArray(): D[];
+}
+//#endregion
+//#region src/store.d.ts
+declare class DictionaryStore<D extends DictItem = DictItem> {
+  #private;
+  /**
+   * A readonly handler.
+   * For native invoke on two-direction data binding.
+   */
+  readonly store: vue0.ComputedRef<vue0.ShallowReactive<Map<DictKey, DictArray<D>>>>;
+  add(key: DictKey, dict: DictArray<D>): void;
+  addRaw(key: DictKey, dict: D[]): void;
+  addAll(data: Record<DictKey, DictArray<D>>): void;
+  delete(key: DictKey): void;
+  get(key: DictKey, defaultValue?: DictArray<D>): DictArray<D> | undefined;
+  size(): number;
+  keys(): DictKey[];
+}
+//#endregion
+//#region src/index.d.ts
+interface DictionaryOptions<D extends DictItem = DictItem> {
+  /**
+   * Load dictionary data.
+   * @param dicts The dicts to load. DictItem keys that are not of type string will be ignored.
+   * @returns A promise that resolves to a record of dicts.
+   */
+  load: (dicts: string[]) => Promise<Record<string, D[]>>;
+}
+interface DictionaryInstance<D extends DictItem = DictItem> {
+  /**
+   * Dictionary store.
+   * @readonly
+   */
+  readonly store: DictionaryStore;
+  /**
+   * Query queue for dict request.
+   * @readonly
+   */
+  readonly queue: Set<DictKey>;
+  /**
+   * Query dictionary data
+   *
+   * Read from cache first, fetch remotely if not present.
+   *
+   * @param dicts The dicts to query.
+   * @returns The dictionary store.
+   * @example
+   * const dict = useDict(['type', 'status']);
+   * const dict2 = useDict(['type', 'order_type']); // duplicate for test.
+   *
+   * dict1.get('order_type'); // ✅
+   * dict2.get('status'); // ✅
+   */
+  getDictData: (dicts?: DictKey[]) => DictionaryStore<D>;
+  /**
+   * Reload dictionary data.
+   *
+   * @param dicts The dicts to reload.
+   * @returns A promise that resolves to a record of dicts.
+   */
+  reloadDictData: (dicts: DictKey[]) => Promise<Record<string, D[]>>;
+}
+/**
+ * Create a dictionary instance.
+ * @param options The dictionary options.
+ * @returns The dictionary instance.
+ */
+declare function createDictionaryInstance<D extends DictItem = DictItem>(options: DictionaryOptions<D>): DictionaryInstance<D>;
+//#endregion
+export { DictArray, type DictItem, type DictKey, createDictionaryInstance };

package/dist/index.js

@@ -0,0 +1,141 @@
+import { difference } from "lodash-es";
+import { computed, shallowReactive } from "vue";
+
+//#region src/dict.ts
+var DictArray = class DictArray extends Array {
+	constructor(dicts) {
+		super();
+		for (let i = 0; i < dicts.length; i++) {
+			const dict = dicts[i];
+			this.push(dict);
+		}
+	}
+	/**
+	* Like `omit` in `lodash.js`
+	* @param values The values of dict items to omit.
+	* @returns DictArray
+	*/
+	omit(values) {
+		return new DictArray(this.filter((item) => !values.includes(item.value)));
+	}
+	/**
+	* Like `pick` in `lodash.js`
+	* @param values The values of dict items.
+	* @returns DictArray
+	*/
+	pick(values) {
+		return new DictArray(this.filter((item) => values.includes(item.value)));
+	}
+	/**
+	* Get label by value.
+	* @param value The value of dict item.
+	* @returns The label of dict item.
+	*/
+	label(value) {
+		return this.item(value)?.label ?? "";
+	}
+	/**
+	* Get dict item by value.
+	* @param value The value of dict item.
+	* @param defaultDict The default dict item.
+	* @returns The dict item.
+	*/
+	item(value, defaultDict) {
+		return this.find((item) => item.value === value) ?? defaultDict;
+	}
+	/**
+	* Convert to plain array.
+	* It will lost all methods of DictArray.
+	* @returns Plain array.
+	*/
+	toPlainArray() {
+		return Array.from(this);
+	}
+};
+
+//#endregion
+//#region src/store.ts
+var DictionaryStore = class {
+	#store = shallowReactive(/* @__PURE__ */ new Map());
+	/**
+	* A readonly handler.
+	* For native invoke on two-direction data binding.
+	*/
+	store = computed(() => this.#store);
+	add(key, dict) {
+		this.#store.set(key, dict);
+	}
+	addRaw(key, dict) {
+		this.#store.set(key, new DictArray(dict));
+	}
+	addAll(data) {
+		for (const key in data) if (Object.prototype.hasOwnProperty.call(data, key)) this.add(key, data[key]);
+	}
+	delete(key) {
+		this.#store.delete(key);
+	}
+	get(key, defaultValue) {
+		return this.#store.get(key) ?? defaultValue;
+	}
+	size() {
+		return this.#store.size;
+	}
+	keys() {
+		return Array.from(this.#store.keys());
+	}
+};
+
+//#endregion
+//#region src/index.ts
+/**
+* Create a dictionary instance.
+* @param options The dictionary options.
+* @returns The dictionary instance.
+*/
+function createDictionaryInstance(options) {
+	const store = new DictionaryStore();
+	/**
+	* Query queue for dict request.
+	* @readonly
+	*/
+	const fetchQueueSet = /* @__PURE__ */ new Set();
+	function getDictData(dicts) {
+		if (!Array.isArray(dicts) || dicts.length === 0) return store;
+		const diff = difference(dicts, [...store.keys(), ...fetchQueueSet]);
+		if (diff.length > 0) loadDictData(diff);
+		return store;
+	}
+	/**
+	* Load dictionary data.
+	* @param dicts The dicts to load.
+	* @returns A promise that resolves to a record of dicts.
+	*/
+	function loadDictData(dicts) {
+		dicts.forEach((dict) => fetchQueueSet.add(dict));
+		const requestDicts = dicts.filter((key) => typeof key === "string");
+		return options.load(requestDicts).then((response) => {
+			for (const key in response) if (Object.prototype.hasOwnProperty.call(response, key)) store.addRaw(key, response[key]);
+			return response;
+		}).finally(() => {
+			dicts.forEach((dict) => fetchQueueSet.delete(dict));
+		});
+	}
+	/**
+	* Reload dictionary data.
+	* @param dicts The dicts to reload.
+	* @returns A promise that resolves to a record of dicts.
+	*/
+	function reloadDictData(dicts) {
+		if (dicts && dicts.length > 0) return loadDictData(dicts).then();
+		return Promise.resolve({});
+	}
+	return {
+		store,
+		queue: fetchQueueSet,
+		getDictData,
+		reloadDictData
+	};
+}
+
+//#endregion
+export { DictArray, createDictionaryInstance };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "vue-cacheable-dictionary",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A cacheable dictionary library for Vue.",
+  "author": "Even Wan <me@tuanzi.ink>",
+  "license": "MIT",
+  "homepage": "https://github.com/tuanzisama/vue-cacheable-dictionary#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tuanzisama/vue-cacheable-dictionary.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tuanzisama/vue-cacheable-dictionary/issues"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^25.0.3",
+    "@vitejs/plugin-vue": "^6.0.3",
+    "@vitest/browser-playwright": "^4.0.16",
+    "bumpp": "^10.3.2",
+    "express": "^5.2.1",
+    "playwright": "^1.57.0",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16",
+    "vitest-browser-vue": "^2.0.1",
+    "vue": "^3.5.25",
+    "vue-tsc": "^3.1.8"
+  },
+  "dependencies": {
+    "lodash-es": "^4.17.22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "play": "vite",
+    "test": "vitest run",
+    "typecheck": "vue-tsc --noEmit",
+    "release": "bumpp && pnpm publish"
+  }
+}