@pubinfo/core 2.0.15 → 2.1.1

package/src/built-in/pinia-plugin/plugins/persistedstate/persistedstate.ts

@@ -0,0 +1,575 @@
+import type { PiniaPluginContext, StateTree } from 'pinia';
+import type {
+  CustomStorageEventDetail,
+  ExtendedPersistenceOptions,
+  NormalizedGlobalOptions,
+  PersistenceEntry,
+  Serializer,
+  StorageArea,
+  StorageBinding,
+  SyncedPersistedStateOptions,
+} from './types';
+import type { PiniaPersistReadHookPayload, PiniaPersistWriteHookPayload } from '@/core/interface';
+import { deepOmitUnsafe, deepPickUnsafe } from 'deep-pick-omit';
+import { destr } from 'destr';
+import { cloneDeep } from 'lodash-es';
+import { callHookSync } from '@/core/ctx';
+import { CUSTOM_EVENT, dispatchLocalMutation, resolveStorageArea, scheduleMicrotask } from './utils';
+
+export type {
+  PersistenceOptions,
+  Serializer,
+  StorageLike,
+  SyncedPersistedStateOptions,
+} from './types';
+
+/**
+ * 默认的序列化器，使用 JSON.stringify 和 destr
+ */
+const DEFAULT_SERIALIZER: Serializer = {
+  serialize: (data) => {
+    return JSON.stringify(data);
+  },
+  deserialize: (value) => {
+    return destr<StateTree>(value);
+  },
+};
+
+interface BindingHandlers {
+  hydrate: (binding: StorageBinding, options?: { runHooks?: boolean, skipPersist?: boolean }) => void
+  reset: (binding: StorageBinding) => void
+}
+
+interface BindingRegistry {
+  register: (binding: StorageBinding) => void
+  unregister: (binding: StorageBinding) => void
+  suppressNextLocalEvent: (fullKey?: string) => void
+  ensurePatchedFor: (entry: PersistenceEntry) => void
+}
+
+function createBindingRegistry(
+  _globalOptions: NormalizedGlobalOptions,
+  handlers: BindingHandlers,
+): BindingRegistry {
+  const keyBindingRegistry = new Map<string, StorageBinding[]>();
+  const suppressedLocalEvents = new Set<string>();
+  let listenersReady = false;
+  let localPatchApplied = false;
+
+  ensureListeners();
+
+  return {
+    register(binding) {
+      const { entry } = binding;
+      if (!entry.fullKey) {
+        return;
+      }
+      const list = keyBindingRegistry.get(entry.fullKey) ?? [];
+      list.push(binding);
+      keyBindingRegistry.set(entry.fullKey, list);
+    },
+    unregister(binding) {
+      const { entry } = binding;
+      if (!entry.fullKey) {
+        return;
+      }
+      const bindings = keyBindingRegistry.get(entry.fullKey);
+      if (!bindings) {
+        return;
+      }
+      const next = bindings.filter(item => item !== binding);
+      if (next.length) {
+        keyBindingRegistry.set(entry.fullKey, next);
+      }
+      else {
+        keyBindingRegistry.delete(entry.fullKey);
+      }
+    },
+    suppressNextLocalEvent(fullKey) {
+      if (!fullKey) {
+        return;
+      }
+      suppressedLocalEvents.add(fullKey);
+      scheduleMicrotask(() => {
+        suppressedLocalEvents.delete(fullKey);
+      });
+    },
+    ensurePatchedFor(entry) {
+      if (entry.storageArea === 'local') {
+        ensureStoragePatch();
+      }
+    },
+  };
+
+  function ensureListeners() {
+    if (listenersReady || typeof window === 'undefined') {
+      return;
+    }
+
+    window.addEventListener('storage', (event) => {
+      if (!event.key) {
+        if (event.storageArea === window.localStorage) {
+          handleStorageClear('local');
+        }
+        return;
+      }
+
+      const storageArea: StorageArea | undefined = event.storageArea === window.localStorage
+        ? 'local'
+        : event.storageArea === window.sessionStorage
+          ? 'session'
+          : undefined;
+
+      if (!storageArea) {
+        return;
+      }
+
+      handleStorageSignal({
+        key: event.key,
+        newValue: event.newValue,
+        oldValue: event.oldValue,
+        storageArea,
+      }, 'native');
+    });
+
+    window.addEventListener(CUSTOM_EVENT, (event) => {
+      const detail = (event as CustomEvent<CustomStorageEventDetail>).detail;
+      if (!detail) {
+        return;
+      }
+      handleStorageSignal(detail, 'local');
+    });
+
+    listenersReady = true;
+  }
+
+  function ensureStoragePatch() {
+    if (localPatchApplied || typeof window === 'undefined') {
+      return;
+    }
+
+    const StorageCtor = window.Storage;
+    if (!StorageCtor || !StorageCtor.prototype) {
+      return;
+    }
+
+    const prototype = StorageCtor.prototype;
+    const originalSetItem = prototype.setItem;
+    const originalRemoveItem = prototype.removeItem;
+    const originalClear = prototype.clear;
+
+    if (typeof originalSetItem !== 'function' || typeof originalRemoveItem !== 'function' || typeof originalClear !== 'function') {
+      return;
+    }
+
+    const dispatchFromInstance = (storage: Storage, detail: Omit<CustomStorageEventDetail, 'storageArea'> & { storageArea?: StorageArea }) => {
+      const storageArea = detail.storageArea ?? resolveStorageArea(storage);
+      if (!storageArea) {
+        return;
+      }
+      if (storageArea === 'local') {
+        dispatchLocalMutation({
+          key: detail.key,
+          newValue: detail.newValue,
+          oldValue: detail.oldValue,
+          storageArea,
+        });
+      }
+    };
+
+    prototype.setItem = function patchedSetItem(key: string, value: string) {
+      const storage = this as Storage;
+      const oldValue = storage.getItem(key);
+      originalSetItem.call(storage, key, value);
+      dispatchFromInstance(storage, { key, newValue: value, oldValue });
+    };
+
+    prototype.removeItem = function patchedRemoveItem(key: string) {
+      const storage = this as Storage;
+      const oldValue = storage.getItem(key);
+      originalRemoveItem.call(storage, key);
+      dispatchFromInstance(storage, { key, newValue: null, oldValue });
+    };
+
+    prototype.clear = function patchedClear() {
+      const storage = this as Storage;
+      const storageArea = resolveStorageArea(storage);
+      originalClear.call(storage);
+      if (storageArea === 'local') {
+        dispatchLocalMutation({
+          key: null,
+          newValue: null,
+          oldValue: null,
+          storageArea,
+        });
+      }
+    };
+
+    localPatchApplied = true;
+  }
+
+  function handleStorageClear(area: StorageArea) {
+    keyBindingRegistry.forEach((bindings) => {
+      bindings.forEach((binding) => {
+        if (binding.entry.storageArea === area) {
+          handlers.reset(binding);
+        }
+      });
+    });
+  }
+
+  function handleStorageSignal(detail: CustomStorageEventDetail, source: 'native' | 'local') {
+    if (!detail.key) {
+      if (detail.storageArea === 'local') {
+        handleStorageClear('local');
+      }
+      return;
+    }
+
+    if (detail.storageArea === 'local' && source === 'local' && shouldIgnoreLocalEvent(detail.key)) {
+      return;
+    }
+
+    const bindings = keyBindingRegistry.get(detail.key);
+    if (!bindings?.length) {
+      return;
+    }
+
+    bindings.forEach((binding) => {
+      if (detail.newValue === null) {
+        handlers.reset(binding);
+      }
+      else {
+        handlers.hydrate(binding, { runHooks: false, skipPersist: true });
+      }
+    });
+  }
+
+  function shouldIgnoreLocalEvent(fullKey: string) {
+    if (!suppressedLocalEvents.has(fullKey)) {
+      return false;
+    }
+    suppressedLocalEvents.delete(fullKey);
+    return true;
+  }
+}
+
+/**
+ * 解析存储区域类型
+ * @param storage - Storage 实例
+ * @returns 存储区域类型或 undefined
+ */
+/**
+ * 创建同步持久化状态插件
+ * 该插件支持跨标签页状态同步，并提供完整的持久化控制
+ * @param options - 插件配置选项
+ * @returns Pinia 插件函数
+ */
+export function createSyncedPersistedState(options: SyncedPersistedStateOptions = {}) {
+  // 在非浏览器环境中提前返回空操作插件（用于 SSR）
+  if (typeof window === 'undefined') {
+    return function noopPlugin() {
+      // SSR 环境下的空操作插件
+    };
+  }
+
+  const globalOptions = normalizeGlobalOptions(options);
+  const registry = createBindingRegistry(globalOptions, {
+    hydrate: (binding, hydrateOptions) => hydrateBinding(binding, hydrateOptions),
+    reset: resetBinding,
+  });
+
+  /**
+   * 同步持久化状态插件的实际实现
+   * @param context - Pinia 插件上下文
+   */
+  return function syncedPersistedStatePlugin(context: PiniaPluginContext) {
+    // 标准化持久化选项
+    const persistOptions = normalizeStorePersistOptions(context.options.persist, globalOptions.auto);
+    if (!persistOptions?.length) {
+      return;
+    }
+
+    // 解析所有持久化条目
+    const entries = persistOptions
+      .map((option) => {
+        return resolvePersistenceEntry(context, option, globalOptions);
+      })
+      .filter((entry): entry is PersistenceEntry => Boolean(entry));
+
+    if (!entries.length) {
+      return;
+    }
+
+    const storeBindings: StorageBinding[] = [];
+    // 保存初始状态快照，用于重置
+    const initialState = cloneDeep(context.store.$state);
+
+    // 为每个持久化条目创建绑定
+    entries.forEach((entry) => {
+      registry.ensurePatchedFor(entry);
+
+      const binding: StorageBinding = {
+        context,
+        entry,
+        skipPersist: 0,
+        stopSubscription: () => { },
+        initialState,
+      };
+
+      // 订阅 store 状态变化
+      binding.stopSubscription = context.store.$subscribe((_mutation, state) => {
+        if (binding.skipPersist > 0) {
+          // 跳过本次持久化（避免循环）
+          binding.skipPersist -= 1;
+          return;
+        }
+        persistState(
+          state,
+          entry,
+          context.store.$id,
+          binding.entry.fullKey ? () => registry.suppressNextLocalEvent(binding.entry.fullKey) : undefined,
+        );
+      }, { detached: true });
+
+      // 初始恢复状态
+      hydrateBinding(binding, { skipPersist: true });
+      registry.register(binding);
+      storeBindings.push(binding);
+    });
+
+    // 添加 $hydrate 方法，用于手动恢复状态
+    context.store.$hydrate = ({ runHooks = true } = {}) => {
+      storeBindings.forEach(binding => hydrateBinding(binding, { runHooks }));
+    };
+
+    // 添加 $persist 方法，用于手动持久化状态
+    context.store.$persist = () => {
+      storeBindings.forEach((binding) => {
+        persistState(
+          context.store.$state,
+          binding.entry,
+          context.store.$id,
+          binding.entry.fullKey ? () => registry.suppressNextLocalEvent(binding.entry.fullKey) : undefined,
+        );
+      });
+    };
+
+    // 增强 $dispose 方法，清理资源
+    const originalDispose = context.store.$dispose.bind(context.store);
+    context.store.$dispose = () => {
+      storeBindings.forEach((binding) => {
+        binding.stopSubscription();
+        registry.unregister(binding);
+      });
+      originalDispose();
+    };
+  };
+}
+
+/**
+ * 标准化全局配置选项
+ * @param options - 原始配置选项
+ * @returns 标准化后的配置
+ */
+function normalizeGlobalOptions(options: SyncedPersistedStateOptions): NormalizedGlobalOptions {
+  return {
+    key: options.key ?? (value => value),
+    serializer: options.serializer ?? DEFAULT_SERIALIZER,
+    storage: options.storage,
+    storageArea: options.storageArea ?? 'local',
+    debug: options.debug ?? false,
+    auto: options.auto ?? false,
+  };
+}
+
+/**
+ * 标准化 store 的持久化选项
+ * @param persist - 原始持久化配置
+ * @param auto - 是否自动持久化
+ * @returns 标准化后的选项数组
+ */
+function normalizeStorePersistOptions<State extends StateTree>(
+  persist: boolean | ExtendedPersistenceOptions<State> | ExtendedPersistenceOptions<State>[] | undefined,
+  auto: boolean,
+) {
+  if (Array.isArray(persist)) {
+    return persist;
+  }
+  if (persist === true) {
+    return [{}];
+  }
+  if (persist && typeof persist === 'object') {
+    return [persist];
+  }
+  if (auto) {
+    return [{}];
+  }
+  return undefined;
+}
+
+/**
+ * 解析持久化条目
+ * @param context - Pinia 插件上下文
+ * @param option - 持久化选项
+ * @param globalOptions - 全局配置
+ * @returns 持久化条目或 null
+ */
+function resolvePersistenceEntry(
+  context: PiniaPluginContext,
+  option: ExtendedPersistenceOptions,
+  globalOptions: NormalizedGlobalOptions,
+): PersistenceEntry | null {
+  const keyBuilder = globalOptions.key ?? ((value: string) => value);
+  const resolvedKey = keyBuilder(option.key ?? context.store.$id);
+  const storage = option.storage ?? globalOptions.storage;
+
+  if (!storage) {
+    if (globalOptions.debug) {
+      console.warn('[persistedstate] storage is not available for store', context.store.$id);
+    }
+    return null;
+  }
+
+  const serializer = option.serializer ?? globalOptions.serializer;
+  const storageArea = option.storageArea ?? globalOptions.storageArea;
+  const storageKey = resolvedKey;
+  const syncKey = storageArea === 'local' ? storageKey : undefined;
+
+  return {
+    key: storageKey,
+    storage,
+    serializer,
+    debug: option.debug ?? globalOptions.debug,
+    beforeHydrate: option.beforeHydrate,
+    afterHydrate: option.afterHydrate,
+    pick: option.pick,
+    omit: option.omit,
+    storageArea,
+    fullKey: syncKey,
+  };
+}
+
+/**
+ * 持久化状态到存储
+ * @param state - 状态对象
+ * @param entry - 持久化条目
+ */
+function persistState(
+  state: StateTree,
+  entry: PersistenceEntry,
+  storeId: string,
+  suppressEvent?: () => void,
+) {
+  try {
+    // 应用白名单过滤
+    const picked = entry.pick ? deepPickUnsafe(state, entry.pick as string[]) : state;
+    // 应用黑名单过滤
+    const omitted = entry.omit ? deepOmitUnsafe(picked, entry.omit as string[]) : picked;
+    // 序列化状态
+    const value = entry.serializer.serialize(omitted as StateTree);
+    const payload = callHookSync<PiniaPersistWriteHookPayload>('pinia:persist:write', {
+      storeId,
+      key: entry.key,
+      fullKey: entry.fullKey,
+      storageArea: entry.storageArea,
+      state: omitted as StateTree,
+      value,
+    });
+    const nextValue = payload?.value ?? value;
+
+    // 抑制由 Pinia store 状态变化引起的本地事件，避免循环更新
+    // 但允许其他方式（如手动修改 localStorage）触发的事件通过
+    suppressEvent?.();
+    entry.storage.setItem(entry.key, nextValue);
+  }
+  catch (error) {
+    if (entry.debug) {
+      console.error('[persistedstate] failed to persist store', error);
+    }
+  }
+}
+
+/**
+ * 从存储恢复状态到 store
+ */
+function hydrateBinding(
+  binding: StorageBinding,
+  options: { runHooks?: boolean, skipPersist?: boolean } = {},
+) {
+  const { entry, context } = binding;
+  const { runHooks = true, skipPersist = false } = options;
+
+  try {
+    // 执行恢复前钩子
+    if (runHooks) {
+      entry.beforeHydrate?.(context);
+    }
+
+    // 从存储中读取数据
+    const sourceKey = entry.key;
+    const value = entry.storage.getItem(entry.key);
+    if (value === null) {
+      return;
+    }
+
+    const readPayload = callHookSync<PiniaPersistReadHookPayload>('pinia:persist:read', {
+      storeId: context.store.$id,
+      key: entry.key,
+      fullKey: entry.fullKey,
+      storageArea: entry.storageArea,
+      sourceKey,
+      value,
+    });
+    const normalizedValue = readPayload?.value ?? value;
+
+    // 反序列化数据
+    const parsed = entry.serializer.deserialize(normalizedValue);
+    // 应用白名单过滤
+    const picked = entry.pick ? deepPickUnsafe(parsed, entry.pick as string[]) : parsed;
+    // 应用黑名单过滤
+    const omitted = entry.omit ? deepOmitUnsafe(picked, entry.omit as string[]) : picked;
+
+    // 标记跳过下一次持久化（避免循环）
+    if (skipPersist) {
+      binding.skipPersist += 1;
+    }
+    // 更新 store 状态
+    context.store.$patch(omitted);
+  }
+  catch (error) {
+    if (entry.debug) {
+      console.error('[persistedstate] failed to hydrate store', error);
+    }
+  }
+  finally {
+    // 执行恢复后钩子
+    if (runHooks) {
+      entry.afterHydrate?.(context);
+    }
+  }
+}
+
+/**
+ * 重置绑定到初始状态
+ * @param binding - 存储绑定
+ */
+function resetBinding(binding: StorageBinding) {
+  const snapshot = binding.initialState;
+  const { entry, context } = binding;
+  try {
+    // 应用白名单过滤
+    const picked = entry.pick ? deepPickUnsafe(snapshot, entry.pick as string[]) : snapshot;
+    // 应用黑名单过滤
+    const omitted = entry.omit ? deepOmitUnsafe(picked, entry.omit as string[]) : picked;
+    // 标记跳过下一次持久化
+    binding.skipPersist += 1;
+    // 使用深拷贝避免引用问题
+    context.store.$patch(cloneDeep(omitted));
+  }
+  catch (error) {
+    if (entry.debug) {
+      console.error('[persistedstate] failed to reset store', error);
+    }
+  }
+}