@bquery/bquery 1.6.0 → 1.7.0

package/src/store/define-store.ts

@@ -1,49 +1,49 @@
-/**
- * Store factory helpers.
- */
-
-import { createStore } from './create-store';
-import { getStore, hasStore } from './registry';
-import type { Store, StoreDefinition } from './types';
-
-/**
- * Creates a store factory that returns the store instance.
- *
- * The store is lazily created on first call and cached in the global store
- * registry. Subsequent calls return the same instance. After calling
- * `destroyStore(id)`, the next factory call will create a fresh store.
- *
- * @param id - Store identifier
- * @param definition - Store definition without id
- * @returns A function that returns the store instance
- *
- * @example
- * ```ts
- * const useCounter = defineStore('counter', {
- *   state: () => ({ count: 0 }),
- *   actions: { increment() { this.count++; } },
- * });
- *
- * const counter = useCounter();
- * counter.increment();
- * ```
- */
-export const defineStore = <
-  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>,
->(
-  id: string,
-  definition: Omit<StoreDefinition<S, G, A>, 'id'>
-): (() => Store<S, G, A>) => {
-  // Check registry first to avoid noisy warnings from createStore()
-  // when the factory is called multiple times (intended usage pattern).
-  // createStore() only called when store doesn't exist or was destroyed.
-  return () => {
-    if (hasStore(id)) {
-      return getStore(id) as Store<S, G, A>;
-    }
-    return createStore({ id, ...definition });
-  };
-};
+/**
+ * Store factory helpers.
+ */
+
+import { createStore } from './create-store';
+import { getStore, hasStore } from './registry';
+import type { Store, StoreDefinition } from './types';
+
+/**
+ * Creates a store factory that returns the store instance.
+ *
+ * The store is lazily created on first call and cached in the global store
+ * registry. Subsequent calls return the same instance. After calling
+ * `destroyStore(id)`, the next factory call will create a fresh store.
+ *
+ * @param id - Store identifier
+ * @param definition - Store definition without id
+ * @returns A function that returns the store instance
+ *
+ * @example
+ * ```ts
+ * const useCounter = defineStore('counter', {
+ *   state: () => ({ count: 0 }),
+ *   actions: { increment() { this.count++; } },
+ * });
+ *
+ * const counter = useCounter();
+ * counter.increment();
+ * ```
+ */
+export const defineStore = <
+  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>,
+>(
+  id: string,
+  definition: Omit<StoreDefinition<S, G, A>, 'id'>
+): (() => Store<S, G, A>) => {
+  // Check registry first to avoid noisy warnings from createStore()
+  // when the factory is called multiple times (intended usage pattern).
+  // createStore() only called when store doesn't exist or was destroyed.
+  return () => {
+    if (hasStore(id)) {
+      return getStore(id) as Store<S, G, A>;
+    }
+    return createStore({ id, ...definition });
+  };
+};

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

@@ -1,74 +1,74 @@
-/**
- * Mapping helpers for store state and actions.
- */
-
-/**
- * Maps store state properties to a reactive object for use in components.
- *
- * @param store - The store instance
- * @param keys - State keys to map
- * @returns Object with mapped properties
- */
-export const mapState = <S extends Record<string, unknown>, K extends keyof S>(
-  store: S,
-  keys: K[]
-): Pick<S, K> => {
-  const mapped = {} as Pick<S, K>;
-
-  for (const key of keys) {
-    Object.defineProperty(mapped, key, {
-      get: () => store[key],
-      enumerable: true,
-    });
-  }
-
-  return mapped;
-};
-
-/**
- * Maps store getters to a reactive object for use in components.
- *
- * @param store - The store instance
- * @param keys - Getter keys to map
- * @returns Object with mapped getters
- */
-export const mapGetters = <G extends Record<string, unknown>, K extends keyof G>(
-  store: G,
-  keys: K[]
-): Pick<G, K> => {
-  const mapped = {} as Pick<G, K>;
-
-  for (const key of keys) {
-    Object.defineProperty(mapped, key, {
-      get: () => store[key],
-      enumerable: true,
-    });
-  }
-
-  return mapped;
-};
-
-/**
- * Maps store actions to an object for easier destructuring.
- *
- * @param store - The store instance
- * @param keys - Action keys to map
- * @returns Object with mapped actions
- */
-export const mapActions = <
-  // 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,
-  keys: K[]
-): Pick<A, K> => {
-  const mapped = {} as Pick<A, K>;
-
-  for (const key of keys) {
-    (mapped as Record<string, unknown>)[key as string] = (...args: unknown[]) =>
-      (store[key] as (...args: unknown[]) => unknown)(...args);
-  }
-
-  return mapped;
-};
+/**
+ * Mapping helpers for store state and actions.
+ */
+
+/**
+ * Maps store state properties to a reactive object for use in components.
+ *
+ * @param store - The store instance
+ * @param keys - State keys to map
+ * @returns Object with mapped properties
+ */
+export const mapState = <S extends Record<string, unknown>, K extends keyof S>(
+  store: S,
+  keys: K[]
+): Pick<S, K> => {
+  const mapped = {} as Pick<S, K>;
+
+  for (const key of keys) {
+    Object.defineProperty(mapped, key, {
+      get: () => store[key],
+      enumerable: true,
+    });
+  }
+
+  return mapped;
+};
+
+/**
+ * Maps store getters to a reactive object for use in components.
+ *
+ * @param store - The store instance
+ * @param keys - Getter keys to map
+ * @returns Object with mapped getters
+ */
+export const mapGetters = <G extends Record<string, unknown>, K extends keyof G>(
+  store: G,
+  keys: K[]
+): Pick<G, K> => {
+  const mapped = {} as Pick<G, K>;
+
+  for (const key of keys) {
+    Object.defineProperty(mapped, key, {
+      get: () => store[key],
+      enumerable: true,
+    });
+  }
+
+  return mapped;
+};
+
+/**
+ * Maps store actions to an object for easier destructuring.
+ *
+ * @param store - The store instance
+ * @param keys - Action keys to map
+ * @returns Object with mapped actions
+ */
+export const mapActions = <
+  // 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,
+  keys: K[]
+): Pick<A, K> => {
+  const mapped = {} as Pick<A, K>;
+
+  for (const key of keys) {
+    (mapped as Record<string, unknown>)[key as string] = (...args: unknown[]) =>
+      (store[key] as (...args: unknown[]) => unknown)(...args);
+  }
+
+  return mapped;
+};

package/src/store/persisted.ts

@@ -2,15 +2,96 @@
  * Store persistence helpers.
  */
 
+import { isPrototypePollutionKey } from '../core/utils/object';
 import { createStore } from './create-store';
-import type { Store, StoreDefinition } from './types';
+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;
+};
 
 /**
- * Creates a store with automatic persistence to localStorage.
+ * 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 storageKey - Optional custom storage key
+ * @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>,
@@ -19,9 +100,40 @@ export const createPersistedStore = <
   A extends Record<string, (...args: any[]) => any> = Record<string, never>,
 >(
   definition: StoreDefinition<S, G, A>,
-  storageKey?: string
+  options?: PersistedStoreOptions | string
 ): Store<S, G, A> => {
-  const key = storageKey ?? `bquery-store-${definition.id}`;
+  // 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;
 
@@ -30,31 +142,106 @@ export const createPersistedStore = <
     state: () => {
       const defaultState = originalStateFactory();
 
-      if (typeof window !== 'undefined') {
-        try {
-          const saved = localStorage.getItem(key);
-          if (saved) {
-            return { ...defaultState, ...JSON.parse(saved) } as S;
+      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;
           }
-        } catch {
-          // Ignore parse errors
         }
-      }
 
-      return defaultState;
+        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 (typeof window !== 'undefined') {
-      try {
-        localStorage.setItem(key, JSON.stringify(state));
-      } catch {
-        // Ignore quota errors
+    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
     }
   });