@bquery/bquery 1.5.0 → 1.7.0

package/src/store/types.ts

@@ -1,94 +1,247 @@
-/**
- * Store types for bQuery's state module.
- * @module bquery/store
- */
-
-/**
- * Store state factory function.
- */
-export type StateFactory<S> = () => S;
-
-/**
- * Getter definition - derives computed values from state.
- */
-export type Getters<S, G> = {
-  [K in keyof G]: (state: S, getters: G) => G[K];
-};
-
-/**
- * Action definition - methods that can modify state.
- * The `this` context includes state, getters, and other actions.
- */
-export type Actions<S, G, A> = {
-  [K in keyof A]: A[K] extends (...args: infer P) => infer R
-    ? (this: S & G & A, ...args: P) => R
-    : never;
-};
-
-/**
- * Store definition for createStore.
- */
-export type StoreDefinition<
-  S extends Record<string, unknown> = Record<string, unknown>,
-  G extends Record<string, unknown> = Record<string, unknown>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  A extends Record<string, (...args: any[]) => any> = Record<string, never>,
-> = {
-  /** Unique store identifier for devtools */
-  id: string;
-  /** State factory function */
-  state: StateFactory<S>;
-  /** Computed getters */
-  getters?: Getters<S, G>;
-  /** Action methods */
-  actions?: Actions<S, G, A>;
-};
-
-/**
- * Store subscriber callback.
- */
-export type StoreSubscriber<S> = (state: S) => void;
-
-/**
- * Patch payload for store updates.
- */
-export type StorePatch<S> = Partial<S> | ((state: S) => void);
-
-/**
- * The returned store instance with state, getters, and actions merged.
- */
-export type Store<
-  S extends Record<string, unknown>,
-  G extends Record<string, unknown>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  A extends Record<string, (...args: any[]) => any>,
-> = S &
-  G &
-  A & {
-    /** Store identifier */
-    $id: string;
-    /** Reset state to initial values */
-    $reset: () => void;
-    /** Subscribe to state changes */
-    $subscribe: (callback: StoreSubscriber<S>) => () => void;
-    /** Patch multiple state properties at once (shallow) */
-    $patch: (partial: StorePatch<S>) => void;
-    /**
-     * Patch with deep reactivity support.
-     * Unlike $patch, this method deep-clones nested objects before mutation,
-     * ensuring that all changes trigger reactive updates.
-     */
-    $patchDeep: (partial: StorePatch<S>) => void;
-    /** Get raw state object (non-reactive snapshot) */
-    $state: S;
-  };
-
-/**
- * Plugin that can extend store functionality.
- */
-export type StorePlugin<S = unknown> = (context: {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  store: Store<any, any, any>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  options: StoreDefinition<any, any, any>;
-}) => Partial<S> | void;
+/**
+ * Store types for bQuery's state module.
+ * @module bquery/store
+ */
+
+/**
+ * Store state factory function.
+ */
+export type StateFactory<S> = () => S;
+
+/**
+ * Getter definition - derives computed values from state.
+ */
+export type Getters<S, G> = {
+  [K in keyof G]: (state: S, getters: G) => G[K];
+};
+
+/**
+ * Action definition - methods that can modify state.
+ * The `this` context includes state, getters, and other actions.
+ */
+export type Actions<S, G, A> = {
+  [K in keyof A]: A[K];
+} & ThisType<S & G & A>;
+
+/**
+ * Store definition for createStore.
+ */
+export type StoreDefinition<
+  S extends Record<string, unknown> = Record<string, unknown>,
+  G extends Record<string, unknown> = Record<string, unknown>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  A extends Record<string, (...args: any[]) => any> = Record<string, never>,
+> = {
+  /** Unique store identifier for devtools */
+  id: string;
+  /** State factory function */
+  state: StateFactory<S>;
+  /** Computed getters */
+  getters?: Getters<S, G>;
+  /** Action methods */
+  actions?: Actions<S, G, A>;
+};
+
+/**
+ * Store subscriber callback.
+ */
+export type StoreSubscriber<S> = (state: S) => void;
+
+/**
+ * Patch payload for store updates.
+ */
+export type StorePatch<S> = Partial<S> | ((state: S) => void);
+
+/**
+ * Action function record used by store definitions and lifecycle hooks.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type StoreActionRecord = Record<string, (...args: any[]) => any>;
+
+type ActionName<A extends StoreActionRecord> = keyof A & string;
+type ActionArgs<A extends StoreActionRecord, K extends ActionName<A>> = Parameters<A[K]>;
+type ActionResult<A extends StoreActionRecord, K extends ActionName<A>> = Awaited<ReturnType<A[K]>>;
+
+/**
+ * Context provided to `$onAction` callbacks.
+ *
+ * @example
+ * ```ts
+ * store.$onAction(({ name, args, after, onError }) => {
+ *   console.log(`Action "${name}" called with`, args);
+ *   after((result) => console.log(`Returned:`, result));
+ *   onError((err) => console.error(`Failed:`, err));
+ * });
+ * ```
+ *
+ * Hook registration is synchronous: call `after()` and `onError()` before the
+ * callback returns. Promise-returning listeners may still observe errors, but
+ * any hooks registered after an `await` will not affect the current action.
+ */
+export type ActionContext<
+  S extends Record<string, unknown>,
+  G extends Record<string, unknown>,
+  A extends StoreActionRecord,
+  K extends ActionName<A> = ActionName<A>,
+> = {
+  /** The name of the action being called */
+  name: K;
+  /** The store instance */
+  store: Store<S, G, A>;
+  /** The arguments passed to the action */
+  args: ActionArgs<A, K>;
+  /**
+   * Register a callback to run after the action completes successfully.
+   * For async actions, runs after the returned promise resolves.
+   */
+  after: (callback: (result: ActionResult<A, K>) => void) => void;
+  /**
+   * Register a callback to run if the action throws or the returned
+   * promise rejects.
+   */
+  onError: (callback: (error: unknown) => void) => void;
+};
+
+/**
+ * Callback for `$onAction`.
+ */
+export type OnActionCallback<
+  S extends Record<string, unknown>,
+  G extends Record<string, unknown>,
+  A extends StoreActionRecord,
+> = <K extends ActionName<A>>(context: ActionContext<S, G, A, K>) => void;
+
+/**
+ * The returned store instance with state, getters, and actions merged.
+ */
+export type Store<
+  S extends Record<string, unknown>,
+  G extends Record<string, unknown>,
+  A extends StoreActionRecord,
+> = S &
+  G &
+  A & {
+    /** Store identifier */
+    $id: string;
+    /** Reset state to initial values */
+    $reset: () => void;
+    /** Subscribe to state changes */
+    $subscribe: (callback: StoreSubscriber<S>) => () => void;
+    /** Patch multiple state properties at once (shallow) */
+    $patch: (partial: StorePatch<S>) => void;
+    /**
+     * Patch with deep reactivity support.
+     * Unlike $patch, this method deep-clones nested objects before mutation,
+     * ensuring that all changes trigger reactive updates.
+     */
+    $patchDeep: (partial: StorePatch<S>) => void;
+    /** Get raw state object (non-reactive snapshot) */
+    $state: S;
+    /**
+     * Hook into action calls. The callback receives an {@link ActionContext}
+     * with `after` and `onError` hooks for the full action lifecycle.
+     *
+     * @param callback - Invoked before each action execution
+     * @returns A function to remove the hook
+     *
+     * @example
+     * ```ts
+     * const unsub = store.$onAction(({ name, args, after, onError }) => {
+     *   const start = Date.now();
+     *   after(() => console.log(`${name} took ${Date.now() - start}ms`));
+     *   onError((e) => console.error(`${name} failed`, e));
+     * });
+     * ```
+     *
+     * Register hooks synchronously before the callback returns. Async listeners
+     * that await before calling `after()` or `onError()` cannot affect the
+     * current action invocation.
+     */
+    $onAction: (callback: OnActionCallback<S, G, A>) => () => void;
+  };
+
+/**
+ * Plugin that can extend store functionality.
+ */
+export type StorePlugin<S = unknown> = (context: {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  store: Store<any, any, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  options: StoreDefinition<any, any, any>;
+}) => Partial<S> | void;
+
+/**
+ * Serializer interface for persisted stores.
+ *
+ * @example
+ * ```ts
+ * const dateSerializer: StoreSerializer = {
+ *   serialize: (state) => JSON.stringify(state, (_, v) =>
+ *     v instanceof Date ? v.toISOString() : v),
+ *   deserialize: (raw) => JSON.parse(raw),
+ * };
+ * ```
+ */
+export type StoreSerializer = {
+  /** Convert state to a string for storage */
+  serialize: (state: unknown) => string;
+  /** Convert a stored string back to state */
+  deserialize: (raw: string) => unknown;
+};
+
+/**
+ * Storage backend interface for persisted stores.
+ * Compatible with `localStorage`, `sessionStorage`, or any custom adapter.
+ *
+ * @example
+ * ```ts
+ * createPersistedStore(definition, {
+ *   storage: sessionStorage,
+ * });
+ * ```
+ */
+export type StorageBackend = {
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+};
+
+/**
+ * Options for `createPersistedStore`.
+ *
+ * @example
+ * ```ts
+ * createPersistedStore(definition, {
+ *   key: 'my-store',
+ *   storage: sessionStorage,
+ *   serializer: { serialize: JSON.stringify, deserialize: JSON.parse },
+ *   version: 2,
+ *   migrate: (persisted, version) => {
+ *     if (version < 2) return { ...persisted, newField: 'default' };
+ *     return persisted;
+ *   },
+ * });
+ * ```
+ */
+export type PersistedStoreOptions = {
+  /** Custom storage key. Defaults to `"bquery-store-${id}"`. */
+  key?: string;
+  /** Storage backend. Defaults to `localStorage`. */
+  storage?: StorageBackend;
+  /** Custom serializer/deserializer. Defaults to JSON. */
+  serializer?: StoreSerializer;
+  /**
+   * Schema version number. When this changes and `migrate` is provided,
+   * the migration function is called with the old state and version.
+   */
+  version?: number;
+  /**
+   * Migration function called when the persisted version differs from
+   * the current `version`. Receives the deserialized state and the old
+   * version number. Must return the migrated state object.
+   */
+  migrate?: (
+    persistedState: Record<string, unknown>,
+    oldVersion: number
+  ) => Record<string, unknown>;
+};

package/src/store/utils.ts

@@ -1,141 +1,135 @@
-/**
- * Internal utilities for the store module.
- * @internal
- */
-
-/**
- * Check if a value is a plain object (not array, null, Date, etc.).
- * @internal
- */
-export const isPlainObject = (value: unknown): value is Record<string, unknown> => {
-  return (
-    value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype
-  );
-};
-
-/**
- * Deep clones an object. Used for deep reactivity support.
- * @internal
- */
-export const deepClone = <T>(obj: T): T => {
-  if (obj === null || typeof obj !== 'object') {
-    return obj;
-  }
-
-  if (Array.isArray(obj)) {
-    return obj.map(deepClone) as T;
-  }
-
-  if (obj instanceof Date) {
-    return new Date(obj.getTime()) as T;
-  }
-
-  if (obj instanceof Map) {
-    return new Map(Array.from(obj.entries()).map(([k, v]) => [k, deepClone(v)])) as T;
-  }
-
-  if (obj instanceof Set) {
-    return new Set(Array.from(obj).map(deepClone)) as T;
-  }
-
-  const cloned = {} as T;
-  for (const key of Object.keys(obj)) {
-    (cloned as Record<string, unknown>)[key] = deepClone((obj as Record<string, unknown>)[key]);
-  }
-  return cloned;
-};
-
-/**
- * Compares two values for deep equality.
- * @internal
- */
-export const deepEqual = (a: unknown, b: unknown): boolean => {
-  if (a === b) return true;
-  if (a === null || b === null) return false;
-  if (typeof a !== 'object' || typeof b !== 'object') return false;
-
-  if (a instanceof Date && b instanceof Date) {
-    return a.getTime() === b.getTime();
-  }
-
-  if (a instanceof Map && b instanceof Map) {
-    if (a.size !== b.size) return false;
-    for (const [key, value] of a.entries()) {
-      if (!b.has(key) || !deepEqual(value, b.get(key))) return false;
-    }
-    return true;
-  }
-
-  if (a instanceof Set && b instanceof Set) {
-    if (a.size !== b.size) return false;
-    for (const value of a.values()) {
-      let found = false;
-      for (const candidate of b.values()) {
-        if (deepEqual(value, candidate)) {
-          found = true;
-          break;
-        }
-      }
-      if (!found) return false;
-    }
-    return true;
-  }
-
-  if (Array.isArray(a) && Array.isArray(b)) {
-    if (a.length !== b.length) return false;
-    return a.every((item, i) => deepEqual(item, b[i]));
-  }
-
-  if (Array.isArray(a) !== Array.isArray(b)) return false;
-
-  const keysA = Object.keys(a as object);
-  const keysB = Object.keys(b as object);
-
-  if (keysA.length !== keysB.length) return false;
-
-  return keysA.every((key) =>
-    deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])
-  );
-};
-
-/**
- * Detects if nested objects were mutated but the reference stayed the same.
- * Returns the keys where nested mutations were detected.
- * @internal
- */
-export const detectNestedMutations = <S extends Record<string, unknown>>(
-  before: S,
-  after: S,
-  signalValues: Map<keyof S, unknown>
-): Array<keyof S> => {
-  const mutatedKeys: Array<keyof S> = [];
-
-  for (const key of Object.keys(after) as Array<keyof S>) {
-    const beforeValue = before[key];
-    const afterValue = after[key];
-    const signalValue = signalValues.get(key);
-
-    // Check if it's the same reference but content changed
-    if (
-      signalValue === afterValue &&
-      isPlainObject(beforeValue) &&
-      isPlainObject(afterValue) &&
-      !deepEqual(beforeValue, afterValue)
-    ) {
-      mutatedKeys.push(key);
-    }
-  }
-
-  return mutatedKeys;
-};
-
-/** @internal Flag to enable/disable development warnings */
-export const isDev = (() => {
-  try {
-    const globalProcess = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process;
-    // Default to dev mode unless explicitly set to production
-    return !(typeof globalProcess !== 'undefined' && globalProcess.env?.NODE_ENV === 'production');
-  } catch {
-    return true;
-  }
-})();
+/**
+ * Internal utilities for the store module.
+ * @internal
+ */
+
+import { detectDevEnvironment } from '../core/env';
+
+/**
+ * Check if a value is a plain object (not array, null, Date, etc.).
+ * @internal
+ */
+export const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  return (
+    value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype
+  );
+};
+
+/**
+ * Deep clones an object. Used for deep reactivity support.
+ * @internal
+ */
+export const deepClone = <T>(obj: T): T => {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(deepClone) as T;
+  }
+
+  if (obj instanceof Date) {
+    return new Date(obj.getTime()) as T;
+  }
+
+  if (obj instanceof Map) {
+    return new Map(Array.from(obj.entries()).map(([k, v]) => [k, deepClone(v)])) as T;
+  }
+
+  if (obj instanceof Set) {
+    return new Set(Array.from(obj).map(deepClone)) as T;
+  }
+
+  const cloned = {} as T;
+  for (const key of Object.keys(obj)) {
+    (cloned as Record<string, unknown>)[key] = deepClone((obj as Record<string, unknown>)[key]);
+  }
+  return cloned;
+};
+
+/**
+ * Compares two values for deep equality.
+ * @internal
+ */
+export const deepEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== 'object' || typeof b !== 'object') return false;
+
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
+  }
+
+  if (a instanceof Map && b instanceof Map) {
+    if (a.size !== b.size) return false;
+    for (const [key, value] of a.entries()) {
+      if (!b.has(key) || !deepEqual(value, b.get(key))) return false;
+    }
+    return true;
+  }
+
+  if (a instanceof Set && b instanceof Set) {
+    if (a.size !== b.size) return false;
+    for (const value of a.values()) {
+      let found = false;
+      for (const candidate of b.values()) {
+        if (deepEqual(value, candidate)) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) return false;
+    }
+    return true;
+  }
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((item, i) => deepEqual(item, b[i]));
+  }
+
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+
+  const keysA = Object.keys(a as object);
+  const keysB = Object.keys(b as object);
+
+  if (keysA.length !== keysB.length) return false;
+
+  return keysA.every((key) =>
+    deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])
+  );
+};
+
+/**
+ * Detects if nested objects were mutated but the reference stayed the same.
+ * Returns the keys where nested mutations were detected.
+ * @internal
+ */
+export const detectNestedMutations = <S extends Record<string, unknown>>(
+  before: S,
+  after: S,
+  signalValues: Map<keyof S, unknown>
+): Array<keyof S> => {
+  const mutatedKeys: Array<keyof S> = [];
+
+  for (const key of Object.keys(after) as Array<keyof S>) {
+    const beforeValue = before[key];
+    const afterValue = after[key];
+    const signalValue = signalValues.get(key);
+
+    // Check if it's the same reference but content changed
+    if (
+      signalValue === afterValue &&
+      isPlainObject(beforeValue) &&
+      isPlainObject(afterValue) &&
+      !deepEqual(beforeValue, afterValue)
+    ) {
+      mutatedKeys.push(key);
+    }
+  }
+
+  return mutatedKeys;
+};
+
+/** @internal Returns whether development warnings should be enabled */
+export const isDev = (): boolean => detectDevEnvironment();

package/src/store/watch.ts

@@ -26,7 +26,8 @@ export type WatchStoreOptions<T> = {
 export const watchStore = <
   S extends Record<string, unknown>,
   G extends Record<string, unknown>,
-  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>,
   T,
 >(
   store: Store<S, G, A>,