pinia-plugin-uni-persist-next 1.0.1

package/README.md

@@ -0,0 +1,117 @@
+# pinia-plugin-uni-persist
+
+专为 **UniApp** 打造的 Pinia 持久化插件。
+
+> A Pinia persistence plugin specifically designed for UniApp.
+
+## ✨ 特性
+
+- ⚡ **UniApp 专用**：基于 `uni.setStorage` 和 `uni.getStorageSync` 开发。
+- 🚀 **性能优化**：
+  - **写入**：默认异步 (`async`)，避免大数据量写入阻塞主线程导致页面卡顿。
+  - **读取**：初始化时同步 (`sync`)，确保页面渲染前数据已就绪。
+- 🛡️ **安全可靠**：自动处理 `BigInt`、`Date` 和循环引用 (`Circular References`)。
+- 📦 **TypeScript**：提供完整的类型定义。
+
+## 📦 安装
+
+使用 pnpm (推荐):
+
+```bash
+pnpm add pinia-plugin-uni-persist
+```
+
+或者 npm/yarn:
+
+```bash
+npm install pinia-plugin-uni-persist
+# yarn add pinia-plugin-uni-persist
+```
+
+## 🚀 快速上手
+
+### 1. 注册插件 (main.ts)
+
+```typescript
+import { createSSRApp } from "vue";
+import { createPinia } from "pinia";
+import { createUniPersistPlugin } from "pinia-plugin-uni-persist"; // 引入插件
+import App from "./App.vue";
+
+export function createApp() {
+  const app = createSSRApp(App);
+  const pinia = createPinia();
+
+  // 注册插件
+  pinia.use(
+    createUniPersistPlugin({
+      keyPrefix: "app_storage_", // 可选：配置统一的 key 前缀
+    })
+  );
+
+  app.use(pinia);
+  return { app };
+}
+```
+
+### 2. 在 Store 中使用
+
+在定义 store 时，添加 `persist` 配置即可。
+
+#### 组合式 (Setup Store) - 推荐
+
+```typescript
+import { defineStore } from "pinia";
+import { ref } from "vue";
+
+export const useUserStore = defineStore(
+  "user",
+  () => {
+    const token = ref("");
+    const userInfo = ref({ name: "UniApp", age: 18 });
+
+    return { token, userInfo };
+  },
+  {
+    persist: {
+      enabled: true, // 开启持久化
+      strategies: [
+        {
+          key: "user_key", // 自定义存储 key
+          paths: ["token"], // 指定只持久化 token
+        },
+      ],
+    },
+  }
+);
+```
+
+## ⚙️ 配置说明
+
+| 选项         | 类型      | 默认值                 | 说明                         |
+| ------------ | --------- | ---------------------- | ---------------------------- |
+| `enabled`    | `boolean` | `false`                | 是否开启当前 store 的持久化  |
+| `async`      | `boolean` | `true`                 | 是否异步存储 (推荐保持 true) |
+| `strategies` | `Array`   | `[{ key: store.$id }]` | 存储策略数组                 |
+
+### Strategy 详情
+
+- **key**: 存储到本地缓存的键名。
+- **paths**: 需要持久化的 state 属性名数组（如 `['count', 'token']`）。如果不传，则持久化整个 store。
+- **async**: 覆盖全局的异步设置。
+
+## 🛠 工具函数
+
+```typescript
+import { clearStore, clearAll } from "pinia-plugin-uni-persist";
+
+// 清除特定 key
+clearStore("app_storage_user_key");
+
+// 清除全部缓存
+clearAll();
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,35 @@
+import { PiniaPluginContext } from 'pinia';
+
+interface PersistStrategy {
+    /** 存储 key，默认为 store.$id */
+    key?: string;
+    /** 只持久化指定的 state 路径 */
+    paths?: string[];
+    /** 强制异步存储（优先级高于全局 async） */
+    async?: boolean;
+}
+interface PersistOptions {
+    enabled?: boolean;
+    /** 多个存储策略 */
+    strategies?: PersistStrategy[];
+    /** 全局默认异步（推荐 true，避免主线程卡顿） */
+    async?: boolean;
+    /** 恢复前钩子（可用于数据迁移） */
+    beforeRestore?: (ctx: PiniaPluginContext) => void;
+    /** 恢复后钩子 */
+    afterRestore?: (ctx: PiniaPluginContext) => void;
+}
+interface PluginOptions {
+    /** 存储 key 统一前缀，如 'hsbc_' */
+    keyPrefix?: string;
+}
+declare module 'pinia' {
+    interface DefineStoreOptionsBase<S extends StateTree, Store> {
+        persist?: PersistOptions;
+    }
+}
+declare const createUniPersistPlugin: (pluginOptions?: PluginOptions) => (ctx: PiniaPluginContext) => void;
+declare const clearStore: (key: string) => void;
+declare const clearAll: () => void;
+
+export { type PersistOptions, type PersistStrategy, type PluginOptions, clearAll, clearStore, createUniPersistPlugin };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { PiniaPluginContext } from 'pinia';
+
+interface PersistStrategy {
+    /** 存储 key，默认为 store.$id */
+    key?: string;
+    /** 只持久化指定的 state 路径 */
+    paths?: string[];
+    /** 强制异步存储（优先级高于全局 async） */
+    async?: boolean;
+}
+interface PersistOptions {
+    enabled?: boolean;
+    /** 多个存储策略 */
+    strategies?: PersistStrategy[];
+    /** 全局默认异步（推荐 true，避免主线程卡顿） */
+    async?: boolean;
+    /** 恢复前钩子（可用于数据迁移） */
+    beforeRestore?: (ctx: PiniaPluginContext) => void;
+    /** 恢复后钩子 */
+    afterRestore?: (ctx: PiniaPluginContext) => void;
+}
+interface PluginOptions {
+    /** 存储 key 统一前缀，如 'hsbc_' */
+    keyPrefix?: string;
+}
+declare module 'pinia' {
+    interface DefineStoreOptionsBase<S extends StateTree, Store> {
+        persist?: PersistOptions;
+    }
+}
+declare const createUniPersistPlugin: (pluginOptions?: PluginOptions) => (ctx: PiniaPluginContext) => void;
+declare const clearStore: (key: string) => void;
+declare const clearAll: () => void;
+
+export { type PersistOptions, type PersistStrategy, type PluginOptions, clearAll, clearStore, createUniPersistPlugin };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var P=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var _=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var m=(n,t)=>{for(var r in t)P(n,r,{get:t[r],enumerable:!0})},E=(n,t,r,e)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of _(t))!k.call(n,a)&&a!==r&&P(n,a,{get:()=>t[a],enumerable:!(e=b(t,a))||e.enumerable});return n};var w=n=>E(P({},"__esModule",{value:!0}),n);var B={};m(B,{clearAll:()=>D,clearStore:()=>R,createUniPersistPlugin:()=>j});module.exports=w(B);var A=n=>{if(typeof TextEncoder!="undefined")return new TextEncoder().encode(n).length;let t=0;for(let r=0;r<n.length;r++){let e=n.charCodeAt(r);t+=e<=127?1:e<=2047?2:e<=65535?3:4}return t},C=n=>{let t=new WeakSet;return JSON.stringify(n,(r,e)=>{if(e===void 0)return null;if(typeof e=="bigint")return e.toString();if(e instanceof Date)return{__date__:e.toISOString()};if(typeof e=="object"&&e!==null){if(t.has(e))return"[Circular]";t.add(e)}return e})},O=n=>{if(!n)return null;try{let t=typeof n=="string"?JSON.parse(n):n;return t&&typeof t=="object"&&Object.keys(t).forEach(r=>{let e=t[r];e&&e.__date__&&typeof e.__date__=="string"&&(t[r]=new Date(e.__date__))}),t}catch(t){return console.error("[Pinia Persist] Parse failed:",t),null}},T=(n,t)=>{if(!t||t.length===0)return{...n};let r={};return t.forEach(e=>{e in n&&(r[e]=n[e])}),r},j=n=>{let t=(n==null?void 0:n.keyPrefix)||"";return r=>{var S,h,p,x;let{store:e,options:a}=r,o=a.persist;if(!(o!=null&&o.enabled))return;let l=(S=o.strategies)!=null&&S.length?o.strategies:[{key:e.$id}],y=(h=o.async)!=null?h:!0,u=f=>`${t}${f}`;if((p=o.beforeRestore)==null||p.call(o,r),l.forEach(f=>{let c=u(f.key||e.$id);try{let i=uni.getStorageSync(c),s=O(i);s!==null&&e.$patch(s)}catch(i){console.error(`[Pinia Persist] Load failed: ${c}`,i),uni.removeStorageSync(c)}}),(x=o.afterRestore)==null||x.call(o,r),e.$subscribe((f,c)=>{l.forEach(i=>{let s=u(i.key||e.$id),$=T(c,i.paths),d=C($);if(A(d)>3670016&&console.warn(`[Pinia Persist] Data too large (${s}): > 3.5MB`),y&&i.async!==!1||i.async===!0)uni.setStorage({key:s,data:d,fail:g=>{console.error(`[Pinia Persist] Async save failed (${s}):`,g)}});else try{uni.setStorageSync(s,d)}catch(g){console.error(`[Pinia Persist] Sync save failed (${s}):`,g)}})},{detached:!0,deep:!0,flush:y?"post":"sync"}),typeof e.$reset=="function"){let f=e.$reset;Object.defineProperty(e,"$reset",{value:function(){f.call(this),l.forEach(c=>{try{uni.removeStorageSync(u(c.key||e.$id))}catch{}})},writable:!0,configurable:!0})}console.log(`[Pinia Persist] ${e.$id} \u5DF2\u542F\u7528\u6301\u4E45\u5316 (${y?"\u5F02\u6B65":"\u540C\u6B65"}, \u524D\u7F00: "${t}")`)}},R=n=>uni.removeStorageSync(n),D=()=>uni.clearStorageSync();0&&(module.exports={clearAll,clearStore,createUniPersistPlugin});

package/dist/index.mjs

@@ -0,0 +1 @@
+var $=n=>{if(typeof TextEncoder!="undefined")return new TextEncoder().encode(n).length;let t=0;for(let r=0;r<n.length;r++){let e=n.charCodeAt(r);t+=e<=127?1:e<=2047?2:e<=65535?3:4}return t},b=n=>{let t=new WeakSet;return JSON.stringify(n,(r,e)=>{if(e===void 0)return null;if(typeof e=="bigint")return e.toString();if(e instanceof Date)return{__date__:e.toISOString()};if(typeof e=="object"&&e!==null){if(t.has(e))return"[Circular]";t.add(e)}return e})},_=n=>{if(!n)return null;try{let t=typeof n=="string"?JSON.parse(n):n;return t&&typeof t=="object"&&Object.keys(t).forEach(r=>{let e=t[r];e&&e.__date__&&typeof e.__date__=="string"&&(t[r]=new Date(e.__date__))}),t}catch(t){return console.error("[Pinia Persist] Parse failed:",t),null}},k=(n,t)=>{if(!t||t.length===0)return{...n};let r={};return t.forEach(e=>{e in n&&(r[e]=n[e])}),r},E=n=>{let t=(n==null?void 0:n.keyPrefix)||"";return r=>{var g,P,S,h;let{store:e,options:p}=r,o=p.persist;if(!(o!=null&&o.enabled))return;let f=(g=o.strategies)!=null&&g.length?o.strategies:[{key:e.$id}],l=(P=o.async)!=null?P:!0,y=c=>`${t}${c}`;if((S=o.beforeRestore)==null||S.call(o,r),f.forEach(c=>{let a=y(c.key||e.$id);try{let i=uni.getStorageSync(a),s=_(i);s!==null&&e.$patch(s)}catch(i){console.error(`[Pinia Persist] Load failed: ${a}`,i),uni.removeStorageSync(a)}}),(h=o.afterRestore)==null||h.call(o,r),e.$subscribe((c,a)=>{f.forEach(i=>{let s=y(i.key||e.$id),x=k(a,i.paths),u=b(x);if($(u)>3670016&&console.warn(`[Pinia Persist] Data too large (${s}): > 3.5MB`),l&&i.async!==!1||i.async===!0)uni.setStorage({key:s,data:u,fail:d=>{console.error(`[Pinia Persist] Async save failed (${s}):`,d)}});else try{uni.setStorageSync(s,u)}catch(d){console.error(`[Pinia Persist] Sync save failed (${s}):`,d)}})},{detached:!0,deep:!0,flush:l?"post":"sync"}),typeof e.$reset=="function"){let c=e.$reset;Object.defineProperty(e,"$reset",{value:function(){c.call(this),f.forEach(a=>{try{uni.removeStorageSync(y(a.key||e.$id))}catch{}})},writable:!0,configurable:!0})}console.log(`[Pinia Persist] ${e.$id} \u5DF2\u542F\u7528\u6301\u4E45\u5316 (${l?"\u5F02\u6B65":"\u540C\u6B65"}, \u524D\u7F00: "${t}")`)}},w=n=>uni.removeStorageSync(n),A=()=>uni.clearStorageSync();export{A as clearAll,w as clearStore,E as createUniPersistPlugin};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pinia-plugin-uni-persist-next",
+  "version": "1.0.1",
+  "description": "专为 UniApp 设计的 Pinia 持久化插件，支持异步/同步策略。",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "uniapp",
+    "pinia",
+    "storage",
+    "persist",
+    "plugin"
+  ],
+  "author": "1401009231@qq.com",
+  "license": "ISC",
+  "peerDependencies": {
+    "pinia": ">=3.0.4",
+    "typescript": ">=5.9.3"
+  },
+  "devDependencies": {
+    "@dcloudio/types": "^3.4.28",
+    "@types/node": "^25.0.1",
+    "pinia": "^3.0.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup"
+  }
+}