@bquery/bquery 1.6.0 → 1.8.1

package/src/ssr/serialize.ts

@@ -0,0 +1,296 @@
+/**
+ * Store state serialization for SSR.
+ *
+ * Provides utilities to serialize store state into a `<script>` tag
+ * for client-side hydration, and to deserialize state on the client.
+ *
+ * @module bquery/ssr
+ */
+
+import { getStore, listStores } from '../store/index';
+import { isPrototypePollutionKey } from '../core/utils/object';
+import type { DeserializedStoreState, SerializeOptions } from './types';
+
+const isStoreStateObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const sanitizeHydrationState = (value: Record<string, unknown>): Record<string, unknown> => {
+  const sanitized: Record<string, unknown> = {};
+  for (const [key, entryValue] of Object.entries(value)) {
+    if (isPrototypePollutionKey(key)) continue;
+    sanitized[key] = entryValue;
+  }
+  return sanitized;
+};
+
+/**
+ * Result of store state serialization.
+ */
+export type SerializeResult = {
+  /** JSON string of the state map */
+  stateJson: string;
+  /** Complete `<script>` tag ready to embed in HTML */
+  scriptTag: string;
+};
+
+/**
+ * Escapes a string for safe embedding in a `<script>` tag.
+ * Prevents XSS via `</script>` injection and HTML entities.
+ *
+ * @internal
+ */
+const escapeForScript = (str: string): string => {
+  return str
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/\//g, '\\u002f')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+};
+
+/**
+ * Escapes a string for safe embedding in an HTML attribute value.
+ * @internal
+ */
+const escapeForHtmlAttribute = (str: string): string => {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+};
+
+/**
+ * Serializes the state of registered stores into a JSON string and
+ * a `<script>` tag suitable for embedding in server-rendered HTML.
+ *
+ * The serialized state can be picked up on the client using
+ * `deserializeStoreState()` to restore stores to their server-side values.
+ *
+ * @param options - Serialization options
+ * @returns Object with JSON string and ready-to-use script tag
+ *
+ * @example
+ * ```ts
+ * import { serializeStoreState } from '@bquery/bquery/ssr';
+ * import { createStore } from '@bquery/bquery/store';
+ *
+ * const store = createStore({
+ *   id: 'counter',
+ *   state: () => ({ count: 42 }),
+ * });
+ *
+ * const { scriptTag } = serializeStoreState();
+ * // '<script id="__BQUERY_STORE_STATE__">window.__BQUERY_INITIAL_STATE__={"counter":{"count":42}}</script>'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Serialize only specific stores
+ * const { scriptTag } = serializeStoreState({ storeIds: ['counter'] });
+ * ```
+ */
+export const serializeStoreState = (options: SerializeOptions = {}): SerializeResult => {
+  const {
+    scriptId = '__BQUERY_STORE_STATE__',
+    globalKey = '__BQUERY_INITIAL_STATE__',
+    storeIds,
+    serialize = JSON.stringify,
+  } = options;
+
+  if (isPrototypePollutionKey(globalKey)) {
+    throw new Error(
+      `serializeStoreState: invalid globalKey "${globalKey}" - prototype-pollution keys are not allowed.`
+    );
+  }
+
+  if (isPrototypePollutionKey(scriptId)) {
+    throw new Error(
+      `serializeStoreState: invalid scriptId "${scriptId}" - prototype-pollution keys are not allowed.`
+    );
+  }
+
+  const ids = storeIds ?? listStores();
+  const stateMap = Object.create(null) as Record<string, Record<string, unknown>>;
+
+  for (const id of ids) {
+    if (isPrototypePollutionKey(id)) {
+      continue;
+    }
+
+    const store = getStore<{ $state: Record<string, unknown> }>(id);
+    if (store) {
+      stateMap[id] = sanitizeHydrationState(store.$state);
+    }
+  }
+
+  const stateJson = serialize(stateMap);
+  if (typeof stateJson !== 'string') {
+    throw new Error('serializeStoreState: custom serialize function must return a string.');
+  }
+
+  if (serialize !== JSON.stringify) {
+    let parsedStateJson: unknown;
+    try {
+      parsedStateJson = JSON.parse(stateJson);
+    } catch {
+      throw new Error('serializeStoreState: custom serialize function returned invalid JSON.');
+    }
+
+    if (!isStoreStateObject(parsedStateJson)) {
+      throw new Error(
+        'serializeStoreState: custom serialize function must return a JSON object string.'
+      );
+    }
+  }
+
+  const escapedJson = escapeForScript(stateJson);
+  const escapedGlobalKey = escapeForScript(JSON.stringify(globalKey));
+  const escapedScriptId = escapeForHtmlAttribute(scriptId);
+  const scriptTag = `<script id="${escapedScriptId}">window[${escapedGlobalKey}]=${escapedJson}</script>`;
+
+  return { stateJson, scriptTag };
+};
+
+/**
+ * Deserializes store state from the global variable set by the SSR script tag.
+ *
+ * Call this on the client before creating stores to pre-populate them with
+ * server-rendered state. After deserialization, the script tag and global
+ * variable are cleaned up automatically.
+ *
+ * @param globalKey - The global variable name where state was serialized
+ * @param scriptId - The ID of the SSR script tag to remove after hydration
+ * @returns The deserialized state map, or an empty object if not found
+ *
+ * @example
+ * ```ts
+ * import { deserializeStoreState } from '@bquery/bquery/ssr';
+ *
+ * // Call before creating stores
+ * const state = deserializeStoreState();
+ * // state = { counter: { count: 42 } }
+ * ```
+ */
+export const deserializeStoreState = (
+  globalKey = '__BQUERY_INITIAL_STATE__',
+  scriptId = '__BQUERY_STORE_STATE__'
+): DeserializedStoreState => {
+  if (isPrototypePollutionKey(globalKey)) {
+    throw new Error(
+      `deserializeStoreState: invalid globalKey "${globalKey}" - prototype-pollution keys are not allowed.`
+    );
+  }
+
+  if (isPrototypePollutionKey(scriptId)) {
+    throw new Error(
+      `deserializeStoreState: invalid scriptId "${scriptId}" - prototype-pollution keys are not allowed.`
+    );
+  }
+
+  if (typeof window === 'undefined') {
+    return {};
+  }
+
+  const state = (window as unknown as Record<string, unknown>)[globalKey];
+  if (!state) {
+    return {};
+  }
+
+  // Clean up global variable
+  try {
+    delete (window as unknown as Record<string, unknown>)[globalKey];
+  } catch {
+    // In strict mode on some environments, delete may fail
+    (window as unknown as Record<string, unknown>)[globalKey] = undefined;
+  }
+
+  // Clean up script tag
+  if (typeof document !== 'undefined' && typeof document.getElementById === 'function') {
+    const scriptEl = document.getElementById(scriptId);
+    if (scriptEl) {
+      scriptEl.remove();
+    }
+  }
+
+  if (!isStoreStateObject(state)) {
+    return {};
+  }
+
+  for (const value of Object.values(state)) {
+    if (!isStoreStateObject(value)) {
+      return {};
+    }
+  }
+
+  const sanitizedStateMap = Object.create(null) as DeserializedStoreState;
+
+  for (const [storeId, storeState] of Object.entries(state)) {
+    if (isPrototypePollutionKey(storeId) || !isStoreStateObject(storeState)) {
+      continue;
+    }
+
+    sanitizedStateMap[storeId] = sanitizeHydrationState(storeState);
+  }
+
+  return sanitizedStateMap;
+};
+
+/**
+ * Hydrates a store with pre-serialized state from SSR.
+ *
+ * If the store exists and has a `$patch` method, this applies the
+ * deserialized state as a patch. Otherwise, the state is ignored.
+ *
+ * @param storeId - The store ID to hydrate
+ * @param state - The plain state object to apply
+ *
+ * @example
+ * ```ts
+ * import { hydrateStore, deserializeStoreState } from '@bquery/bquery/ssr';
+ * import { createStore } from '@bquery/bquery/store';
+ *
+ * // 1. Deserialize state from SSR script tag
+ * const ssrState = deserializeStoreState();
+ *
+ * // 2. Create store (gets initial values from factory)
+ * const store = createStore({
+ *   id: 'counter',
+ *   state: () => ({ count: 0 }),
+ * });
+ *
+ * // 3. Apply SSR state
+ * if (ssrState.counter) {
+ *   hydrateStore('counter', ssrState.counter);
+ * }
+ * // store.count is now 42 (from SSR)
+ * ```
+ */
+export const hydrateStore = (storeId: string, state: Record<string, unknown>): void => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const store = getStore<{ $patch?: (partial: any) => void }>(storeId);
+  if (store && typeof store.$patch === 'function') {
+    store.$patch(sanitizeHydrationState(state));
+  }
+};
+
+/**
+ * Hydrates all stores at once from a deserialized state map.
+ *
+ * Convenience wrapper that calls `hydrateStore` for each entry in the state map.
+ *
+ * @param stateMap - Map of store IDs to their state objects
+ *
+ * @example
+ * ```ts
+ * import { hydrateStores, deserializeStoreState } from '@bquery/bquery/ssr';
+ *
+ * const ssrState = deserializeStoreState();
+ * hydrateStores(ssrState);
+ * ```
+ */
+export const hydrateStores = (stateMap: DeserializedStoreState): void => {
+  for (const [storeId, state] of Object.entries(stateMap)) {
+    hydrateStore(storeId, state);
+  }
+};

package/src/ssr/types.ts

@@ -0,0 +1,81 @@
+import type { HydrateMountOptions } from './hydrate';
+
+/**
+ * Public types for the SSR / Pre-rendering module.
+ */
+
+/**
+ * Options for server-side rendering a template to an HTML string.
+ */
+export type RenderOptions = {
+  /**
+   * Prefix for directive attributes.
+   * @default 'bq'
+   */
+  prefix?: string;
+
+  /**
+   * Whether to strip directive attributes from the output HTML.
+   * When `true`, attributes like `bq-text`, `bq-if`, etc. are removed
+   * from the rendered output for cleaner HTML.
+   * @default false
+   */
+  stripDirectives?: boolean;
+
+  /**
+   * Whether to include a serialized store state `<script>` tag in the output.
+   * When `true`, all registered store states are serialized and appended.
+   * You can also pass an array of store IDs to serialize only specific stores.
+   * @default false
+   */
+  includeStoreState?: boolean | string[];
+};
+
+/**
+ * Result of a `renderToString` call.
+ */
+export type SSRResult = {
+  /** The rendered HTML string */
+  html: string;
+
+  /**
+   * Serialized store state string, typically the `<script>` tag payload
+   * produced when `includeStoreState` is enabled.
+   */
+  storeState?: string;
+};
+
+/** @deprecated Use `HydrateMountOptions` instead. */
+export type HydrationOptions = HydrateMountOptions;
+
+/**
+ * Options for serializing store state.
+ */
+export type SerializeOptions = {
+  /**
+   * The ID attribute for the generated `<script>` tag.
+   * @default '__BQUERY_STORE_STATE__'
+   */
+  scriptId?: string;
+
+  /**
+   * The global variable name where state will be assigned.
+   * @default '__BQUERY_INITIAL_STATE__'
+   */
+  globalKey?: string;
+
+  /**
+   * Store IDs to serialize. If omitted, all registered stores are serialized.
+   */
+  storeIds?: string[];
+
+  /**
+   * Custom serializer function. Defaults to `JSON.stringify`.
+   */
+  serialize?: (data: unknown) => string;
+};
+
+/**
+ * Deserialized store state map: store ID → plain state object.
+ */
+export type DeserializedStoreState = Record<string, Record<string, unknown>>;

package/src/store/create-store.ts

@@ -2,6 +2,7 @@
  * Store creation logic.
  */
 
+import { isPromise } from '../core/utils/type-guards';
 import {
   batch,
   computed,
@@ -13,7 +14,14 @@ import {
 import { notifyDevtoolsStateChange, registerDevtoolsStore } from './devtools';
 import { applyPlugins } from './plugins';
 import { getStore, hasStore, registerStore } from './registry';
-import type { Getters, Store, StoreDefinition, StoreSubscriber } from './types';
+import type {
+  ActionContext,
+  Getters,
+  OnActionCallback,
+  Store,
+  StoreDefinition,
+  StoreSubscriber,
+} from './types';
 import { deepClone, detectNestedMutations, isDev } from './utils';
 
 /**
@@ -53,6 +61,63 @@ export const createStore = <
   // Subscribers for $subscribe
   const subscribers: Array<StoreSubscriber<S>> = [];
 
+  // Action lifecycle hooks for $onAction
+  const actionListeners: Array<OnActionCallback<S, G, A>> = [];
+
+  const reportOnActionError = (
+    phase: 'listener' | 'after' | 'onError',
+    actionName: string,
+    error: unknown
+  ): void => {
+    if (!isDev() || typeof console === 'undefined' || typeof console.error !== 'function') return;
+    console.error(
+      `[bQuery store "${id}"] Error in $onAction ${phase} for action "${actionName}"`,
+      error
+    );
+  };
+
+  const warnedAsyncOnActionListeners = new WeakSet<OnActionCallback<S, G, A>>();
+
+  const warnAsyncOnActionListener = (
+    listener: OnActionCallback<S, G, A>,
+    actionName: string
+  ): void => {
+    if (!isDev() || typeof console === 'undefined' || typeof console.warn !== 'function') return;
+    if (warnedAsyncOnActionListeners.has(listener)) return;
+    warnedAsyncOnActionListeners.add(listener);
+    console.warn(
+      `[bQuery store "${id}"] Async $onAction listener detected for action "${actionName}". If it awaits, register after()/onError() before the first await; late registrations will not affect the current action.`
+    );
+  };
+
+  /**
+   * Executes an action observer callback without allowing observer failures to
+   * affect the action result. Handles both synchronous exceptions and async
+   * rejections, routing all failures through the standard $onAction logger.
+   *
+   * @internal
+   */
+  const runOnActionCallback = (
+    phase: 'listener' | 'after' | 'onError',
+    actionName: string,
+    callback: () => unknown,
+    listener?: OnActionCallback<S, G, A>
+  ): void => {
+    try {
+      const result = callback();
+      if (isPromise(result)) {
+        if (phase === 'listener' && listener) {
+          warnAsyncOnActionListener(listener, actionName);
+        }
+        void result.catch((error) => {
+          reportOnActionError(phase, actionName, error);
+        });
+      }
+    } catch (error) {
+      reportOnActionError(phase, actionName, error);
+    }
+  };
+
   /**
    * Gets the current state.
    *
@@ -172,12 +237,13 @@ export const createStore = <
     });
   }
 
-  // Bind actions to the store context
+  // Bind actions to the store context, with $onAction lifecycle support
   for (const key of Object.keys(actions) as Array<keyof A>) {
     const actionFn = actions[key];
+    const actionName = key as keyof A & string;
 
-    // Wrap action to enable 'this' binding
-    (store as Record<string, unknown>)[key as string] = function (...args: unknown[]) {
+    // Wrap action to enable 'this' binding and $onAction hooks
+    (store as Record<string, unknown>)[actionName] = function (...args: unknown[]) {
       // Create a context that allows 'this.property' access
       const context = new Proxy(store, {
         get: (target, prop) => {
@@ -198,7 +264,67 @@ export const createStore = <
         },
       });
 
-      return actionFn.apply(context, args);
+      // Run $onAction hooks if any listeners are registered
+      if (actionListeners.length === 0) {
+        return actionFn.apply(context, args);
+      }
+
+      const afterHooks: Array<(result: unknown) => void> = [];
+      const errorHooks: Array<(error: unknown) => void> = [];
+      const listenerSnapshot = [...actionListeners];
+
+      const listenerContext = {
+        name: actionName,
+        store,
+        args: args as Parameters<A[typeof actionName]>,
+        after: (callback: (result: Awaited<ReturnType<A[typeof actionName]>>) => void) => {
+          afterHooks.push((result) =>
+            callback(result as Awaited<ReturnType<A[typeof actionName]>>)
+          );
+        },
+        onError: (callback: (error: unknown) => void) => {
+          errorHooks.push(callback);
+        },
+      } satisfies ActionContext<S, G, A, typeof actionName>;
+
+      // Notify all action listeners (before phase)
+      for (const listener of listenerSnapshot) {
+        runOnActionCallback('listener', actionName, () => listener(listenerContext), listener);
+      }
+
+      let result: unknown;
+      try {
+        result = actionFn.apply(context, args);
+      } catch (error) {
+        for (const hook of errorHooks) {
+          runOnActionCallback('onError', actionName, () => hook(error));
+        }
+        throw error;
+      }
+
+      // Handle async actions (promises)
+      if (isPromise(result)) {
+        return result.then(
+          (resolved) => {
+            for (const hook of afterHooks) {
+              runOnActionCallback('after', actionName, () => hook(resolved));
+            }
+            return resolved;
+          },
+          (error) => {
+            for (const hook of errorHooks) {
+              runOnActionCallback('onError', actionName, () => hook(error));
+            }
+            throw error;
+          }
+        );
+      }
+
+      // Sync action — run after hooks immediately
+      for (const hook of afterHooks) {
+        runOnActionCallback('after', actionName, () => hook(result));
+      }
+      return result;
     };
   }
 
@@ -233,13 +359,25 @@ export const createStore = <
       writable: false,
       enumerable: false,
     },
+    $onAction: {
+      value: (callback: OnActionCallback<S, G, A>) => {
+        actionListeners.push(callback);
+        return () => {
+          const index = actionListeners.indexOf(callback);
+          if (index > -1) actionListeners.splice(index, 1);
+        };
+      },
+      writable: false,
+      enumerable: false,
+    },
     $patch: {
       value: (partial: Partial<S> | ((state: S) => void)) => {
         batch(() => {
           if (typeof partial === 'function') {
             // Capture state before mutation for nested mutation detection
-            const stateBefore = isDev ? deepClone(getCurrentState()) : null;
-            const signalValuesBefore = isDev
+            const devMode = isDev();
+            const stateBefore = devMode ? deepClone(getCurrentState()) : null;
+            const signalValuesBefore = devMode
               ? new Map(Array.from(stateSignals.entries()).map(([k, s]) => [k, s.value]))
               : null;
 
@@ -248,7 +386,7 @@ export const createStore = <
             partial(state);
 
             // Detect nested mutations in development mode
-            if (isDev && stateBefore && signalValuesBefore) {
+            if (devMode && stateBefore && signalValuesBefore) {
               const mutatedKeys = detectNestedMutations(stateBefore, state, signalValuesBefore);
               if (mutatedKeys.length > 0) {
                 console.warn(

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

@@ -3,13 +3,18 @@
  */
 
 export type {
+  ActionContext,
   Actions,
   Getters,
+  OnActionCallback,
+  PersistedStoreOptions,
   StateFactory,
+  StorageBackend,
   Store,
   StoreDefinition,
   StorePatch,
   StorePlugin,
+  StoreSerializer,
   StoreSubscriber,
 } from './types';