@bquery/bquery 1.7.0 → 1.8.1

package/src/store/types.ts

@@ -1,247 +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];
-} & 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>;
-};
+/**
+ * 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>;
+};