@bquery/bquery 1.6.0 → 1.7.0

package/src/store/types.ts

@@ -52,14 +52,72 @@ export type StoreSubscriber<S> = (state: S) => void;
  */
 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>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  A extends Record<string, (...args: any[]) => any>,
+  A extends StoreActionRecord,
 > = S &
   G &
   A & {
@@ -79,6 +137,27 @@ export type Store<
     $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;
   };
 
 /**
@@ -90,3 +169,79 @@ export type StorePlugin<S = unknown> = (context: {
   // 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

@@ -1,53 +1,53 @@
-/**
- * Store watch helpers.
- */
-
-import type { Store } from './types';
-import { deepEqual } from './utils';
-
-export type WatchStoreOptions<T> = {
-  /** Call the callback immediately with the current value. */
-  immediate?: boolean;
-  /** Use deep comparison when determining changes. */
-  deep?: boolean;
-  /** Custom equality check for selected values. */
-  equals?: (a: T, b: T) => boolean;
-};
-
-/**
- * Watch a selected slice of store state.
- *
- * @param store - The store instance
- * @param selector - Function to select the watched value
- * @param callback - Called when the selected value changes
- * @param options - Watch options
- * @returns Unsubscribe function
- */
-export const watchStore = <
-  S extends Record<string, unknown>,
-  G extends Record<string, 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>,
-  selector: (state: S) => T,
-  callback: (value: T, previous: T | undefined) => void,
-  options: WatchStoreOptions<T> = {}
-): (() => void) => {
-  const equals = options.equals ?? (options.deep ? deepEqual : Object.is);
-  let previous = selector(store.$state);
-
-  if (options.immediate) {
-    callback(previous, undefined);
-  }
-
-  return store.$subscribe((state) => {
-    const current = selector(state);
-    if (!equals(current, previous)) {
-      const prev = previous;
-      previous = current;
-      callback(current, prev);
-    }
-  });
-};
+/**
+ * Store watch helpers.
+ */
+
+import type { Store } from './types';
+import { deepEqual } from './utils';
+
+export type WatchStoreOptions<T> = {
+  /** Call the callback immediately with the current value. */
+  immediate?: boolean;
+  /** Use deep comparison when determining changes. */
+  deep?: boolean;
+  /** Custom equality check for selected values. */
+  equals?: (a: T, b: T) => boolean;
+};
+
+/**
+ * Watch a selected slice of store state.
+ *
+ * @param store - The store instance
+ * @param selector - Function to select the watched value
+ * @param callback - Called when the selected value changes
+ * @param options - Watch options
+ * @returns Unsubscribe function
+ */
+export const watchStore = <
+  S extends Record<string, unknown>,
+  G extends Record<string, 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>,
+  selector: (state: S) => T,
+  callback: (value: T, previous: T | undefined) => void,
+  options: WatchStoreOptions<T> = {}
+): (() => void) => {
+  const equals = options.equals ?? (options.deep ? deepEqual : Object.is);
+  let previous = selector(store.$state);
+
+  if (options.immediate) {
+    callback(previous, undefined);
+  }
+
+  return store.$subscribe((state) => {
+    const current = selector(state);
+    if (!equals(current, previous)) {
+      const prev = previous;
+      previous = current;
+      callback(current, prev);
+    }
+  });
+};

package/src/storybook/index.ts

@@ -25,7 +25,8 @@ const isWhitespace = (value: string): boolean => {
 /**
  * Detects interpolation boundaries embedded into joined template string fragments.
  */
-const isInterpolationBoundaryMarker = (value: string): boolean => value === INTERPOLATION_BOUNDARY_MARKER;
+const isInterpolationBoundaryMarker = (value: string): boolean =>
+  value === INTERPOLATION_BOUNDARY_MARKER;
 
 const isAttributeSeparator = (value: string): boolean => {
   return isWhitespace(value) || isInterpolationBoundaryMarker(value);

package/src/testing/index.ts

@@ -0,0 +1,42 @@
+/**
+ * bQuery.js Testing Utilities
+ *
+ * Helpers for mounting components, controlling signals, mocking the router,
+ * dispatching events, and asserting async conditions in tests.
+ *
+ * @module bquery/testing
+ *
+ * @example
+ * ```ts
+ * import {
+ *   renderComponent,
+ *   flushEffects,
+ *   mockSignal,
+ *   mockRouter,
+ *   fireEvent,
+ *   waitFor,
+ * } from '@bquery/bquery/testing';
+ * ```
+ */
+
+// Runtime API
+export {
+  renderComponent,
+  flushEffects,
+  mockSignal,
+  mockRouter,
+  fireEvent,
+  waitFor,
+} from './testing';
+
+// Types
+export type {
+  FireEventOptions,
+  MockRouter,
+  MockRouterOptions,
+  MockSignal,
+  RenderComponentOptions,
+  RenderResult,
+  TestRoute,
+  WaitForOptions,
+} from './types';