@bquery/bquery 1.5.0 → 1.7.0

package/src/store/define-store.ts

@@ -31,7 +31,8 @@ import type { Store, StoreDefinition } from './types';
 export const defineStore = <
   S extends Record<string, unknown>,
   G extends Record<string, unknown> = Record<string, never>,
-  A extends Record<string, (...args: unknown[]) => unknown> = Record<string, never>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- actions may declare specific parameter types
+  A extends Record<string, (...args: any[]) => any> = Record<string, never>,
 >(
   id: string,
   definition: Omit<StoreDefinition<S, G, A>, 'id'>

package/src/store/index.ts

@@ -1,22 +1,27 @@
-/**
- * Store module exports.
- */
-
-export type {
-  Actions,
-  Getters,
-  StateFactory,
-  Store,
-  StoreDefinition,
-  StorePatch,
-  StorePlugin,
-  StoreSubscriber,
-} from './types';
-
-export { createStore } from './create-store';
-export { defineStore } from './define-store';
-export { mapActions, mapGetters, mapState } from './mapping';
-export { createPersistedStore } from './persisted';
-export { registerPlugin } from './plugins';
-export { destroyStore, getStore, listStores } from './registry';
-export { watchStore } from './watch';
+/**
+ * Store module exports.
+ */
+
+export type {
+  ActionContext,
+  Actions,
+  Getters,
+  OnActionCallback,
+  PersistedStoreOptions,
+  StateFactory,
+  StorageBackend,
+  Store,
+  StoreDefinition,
+  StorePatch,
+  StorePlugin,
+  StoreSerializer,
+  StoreSubscriber,
+} from './types';
+
+export { createStore } from './create-store';
+export { defineStore } from './define-store';
+export { mapActions, mapGetters, mapState } from './mapping';
+export { createPersistedStore } from './persisted';
+export { registerPlugin } from './plugins';
+export { destroyStore, getStore, listStores } from './registry';
+export { watchStore } from './watch';

package/src/store/mapping.ts

@@ -56,7 +56,8 @@ export const mapGetters = <G extends Record<string, unknown>, K extends keyof G>
  * @returns Object with mapped actions
  */
 export const mapActions = <
-  A extends Record<string, (...args: unknown[]) => unknown>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- actions may declare specific parameter types
+  A extends Record<string, (...args: any[]) => any>,
   K extends keyof A,
 >(
   store: A,

package/src/store/persisted.ts

@@ -1,61 +1,249 @@
-/**
- * Store persistence helpers.
- */
-
-import { createStore } from './create-store';
-import type { Store, StoreDefinition } from './types';
-
-/**
- * Creates a store with automatic persistence to localStorage.
- *
- * @param definition - Store definition
- * @param storageKey - Optional custom storage key
- * @returns The reactive store instance
- */
-export const createPersistedStore = <
-  S extends Record<string, unknown>,
-  G extends Record<string, unknown> = Record<string, never>,
-  A extends Record<string, (...args: unknown[]) => unknown> = Record<string, never>,
->(
-  definition: StoreDefinition<S, G, A>,
-  storageKey?: string
-): Store<S, G, A> => {
-  const key = storageKey ?? `bquery-store-${definition.id}`;
-
-  const originalStateFactory = definition.state;
-
-  const wrappedDefinition: StoreDefinition<S, G, A> = {
-    ...definition,
-    state: () => {
-      const defaultState = originalStateFactory();
-
-      if (typeof window !== 'undefined') {
-        try {
-          const saved = localStorage.getItem(key);
-          if (saved) {
-            return { ...defaultState, ...JSON.parse(saved) } as S;
-          }
-        } catch {
-          // Ignore parse errors
-        }
-      }
-
-      return defaultState;
-    },
-  };
-
-  const store = createStore(wrappedDefinition);
-
-  // Subscribe to save changes
-  store.$subscribe((state) => {
-    if (typeof window !== 'undefined') {
-      try {
-        localStorage.setItem(key, JSON.stringify(state));
-      } catch {
-        // Ignore quota errors
-      }
-    }
-  });
-
-  return store;
-};
+/**
+ * Store persistence helpers.
+ */
+
+import { isPrototypePollutionKey } from '../core/utils/object';
+import { createStore } from './create-store';
+import { isDev } from './utils';
+import type { PersistedStoreOptions, StorageBackend, Store, StoreDefinition } from './types';
+
+/** @internal Version key suffix */
+const VERSION_SUFFIX = '__version';
+
+/** @internal Default JSON serializer */
+const defaultSerializer = {
+  serialize: (state: unknown) => JSON.stringify(state),
+  deserialize: (raw: string) => JSON.parse(raw) as unknown,
+};
+
+/** @internal Check whether a value can be merged into store state. */
+const isPersistedStateObject = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || Object.getPrototypeOf(prototype) === null;
+};
+
+/**
+ * Applies persisted state onto the default state while ignoring dangerous
+ * prototype-pollution keys such as `__proto__`, `constructor`, and `prototype`.
+ *
+ * @internal
+ */
+const mergePersistedState = <S extends Record<string, unknown>>(
+  defaultState: S,
+  persisted: Record<string, unknown>
+): S => {
+  const merged = { ...defaultState };
+  for (const [key, value] of Object.entries(persisted)) {
+    if (isPrototypePollutionKey(key)) continue;
+    if (!Object.prototype.hasOwnProperty.call(defaultState, key)) continue;
+    merged[key as keyof S] = value as S[keyof S];
+  }
+  return merged;
+};
+
+/** @internal Resolve the default storage backend safely. */
+const getDefaultStorage = (): StorageBackend | undefined => {
+  try {
+    return globalThis.localStorage;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Creates a store with automatic persistence.
+ *
+ * Supports configurable storage backends, custom serializers, and schema
+ * versioning with migration functions. All options are optional and
+ * backward-compatible with the simple `(definition, storageKey?)` signature.
+ *
+ * @param definition - Store definition
+ * @param options - Persistence options or a plain string storage key for backward compatibility
+ * @returns The reactive store instance
+ *
+ * @example Basic usage (localStorage + JSON)
+ * ```ts
+ * const store = createPersistedStore({
+ *   id: 'settings',
+ *   state: () => ({ theme: 'dark' }),
+ * });
+ * ```
+ *
+ * @example With sessionStorage and custom key
+ * ```ts
+ * const store = createPersistedStore(
+ *   { id: 'session', state: () => ({ token: '' }) },
+ *   { key: 'my-session', storage: sessionStorage },
+ * );
+ * ```
+ *
+ * @example With versioning and migration
+ * ```ts
+ * const store = createPersistedStore(
+ *   { id: 'app', state: () => ({ name: '', theme: 'auto' }) },
+ *   {
+ *     version: 2,
+ *     migrate: (old, v) => {
+ *       if (v < 2) return { ...old, theme: 'auto' };
+ *       return old;
+ *     },
+ *   },
+ * );
+ * ```
+ */
+export const createPersistedStore = <
+  S extends Record<string, unknown>,
+  G extends Record<string, unknown> = Record<string, never>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- actions may declare specific parameter types
+  A extends Record<string, (...args: any[]) => any> = Record<string, never>,
+>(
+  definition: StoreDefinition<S, G, A>,
+  options?: PersistedStoreOptions | string
+): Store<S, G, A> => {
+  // Normalize options — a plain string is treated as the storage key for backward compatibility
+  const opts: PersistedStoreOptions =
+    typeof options === 'string' ? { key: options } : (options ?? {});
+
+  const key = opts.key ?? `bquery-store-${definition.id}`;
+  const storage = opts.storage ?? getDefaultStorage();
+  const serializer = opts.serializer ?? defaultSerializer;
+  const version = opts.version;
+  const migrate = opts.migrate;
+  const versionKey = key + VERSION_SUFFIX;
+  let shouldPersistInitialVersion = storage !== undefined && version !== undefined;
+  let pendingVersionWrite = false;
+  let canRetryPendingVersionAfterCreate = false;
+
+  const tryPersistVersion = (warningMessage?: string): boolean => {
+    if (!storage || version === undefined) return false;
+
+    try {
+      storage.setItem(versionKey, String(version));
+      return true;
+    } catch (error) {
+      if (
+        warningMessage &&
+        isDev() &&
+        typeof console !== 'undefined' &&
+        typeof console.warn === 'function'
+      ) {
+        console.warn(warningMessage, error);
+      }
+      return false;
+    }
+  };
+
+  const originalStateFactory = definition.state;
+
+  const wrappedDefinition: StoreDefinition<S, G, A> = {
+    ...definition,
+    state: () => {
+      const defaultState = originalStateFactory();
+
+      if (!storage) return defaultState;
+
+      try {
+        const saved = storage.getItem(key);
+        if (!saved) return defaultState;
+
+        const deserialized = serializer.deserialize(saved);
+        if (!isPersistedStateObject(deserialized)) {
+          return defaultState;
+        }
+
+        let persisted = deserialized;
+
+        // Handle versioning & migration
+        if (version !== undefined && migrate) {
+          const rawVersion = storage.getItem(versionKey);
+          const parsedVersion = rawVersion !== null ? Number(rawVersion) : 0;
+          const oldVersion = Number.isFinite(parsedVersion) ? parsedVersion : 0;
+
+          if (oldVersion !== version) {
+            shouldPersistInitialVersion = false;
+            pendingVersionWrite = true;
+            const migrated = migrate(persisted, oldVersion);
+            if (!isPersistedStateObject(migrated)) {
+              return defaultState;
+            }
+            persisted = migrated;
+
+            let migratedStatePersisted = false;
+            // Save the migrated state and version immediately when possible.
+            // If the state write fails, never advance the version key.
+            try {
+              storage.setItem(key, serializer.serialize(persisted));
+              migratedStatePersisted = true;
+              canRetryPendingVersionAfterCreate = true;
+            } catch (e) {
+              // Migration will re-run on next load, but state is still usable
+              if (
+                isDev() &&
+                typeof console !== 'undefined' &&
+                typeof console.warn === 'function'
+              ) {
+                console.warn(
+                  `[bQuery store "${definition.id}"] Failed to persist migrated state:`,
+                  e
+                );
+              }
+            }
+
+            if (
+              migratedStatePersisted &&
+              tryPersistVersion(
+                `[bQuery store "${definition.id}"] Failed to persist migrated version:`
+              )
+            ) {
+              pendingVersionWrite = false;
+            }
+          } else {
+            shouldPersistInitialVersion = false;
+          }
+        }
+
+        return mergePersistedState(defaultState, persisted);
+      } catch {
+        // Ignore parse errors
+        return defaultState;
+      }
+    },
+  };
+
+  const store = createStore(wrappedDefinition);
+
+  // Persist the version number on first creation
+  if (shouldPersistInitialVersion && storage) {
+    tryPersistVersion();
+  } else if (
+    pendingVersionWrite &&
+    canRetryPendingVersionAfterCreate &&
+    tryPersistVersion(
+      `[bQuery store "${definition.id}"] Failed to persist migrated version after store creation:`
+    )
+  ) {
+    pendingVersionWrite = false;
+  }
+
+  // Subscribe to save changes
+  store.$subscribe((state) => {
+    if (!storage) return;
+    try {
+      storage.setItem(key, serializer.serialize(state));
+      if (
+        pendingVersionWrite &&
+        tryPersistVersion(
+          `[bQuery store "${definition.id}"] Failed to persist migrated version after a successful state write:`
+        )
+      ) {
+        pendingVersionWrite = false;
+      }
+    } catch {
+      // Ignore quota errors
+    }
+  });
+
+  return store;
+};