@aihu/store

function _resetStoreRegistry(): void

function createPersistPlugin(config: PersistPluginConfig = {}): StorePlugin

Build a persistence plugin.

function defineStore( id: string, setupOrConfig: | (() => Record<string, unknown>) | OptionsStoreConfig<StateTree, GettersTree<StateTree>, ActionsTree>, options?: StoreCustomOptions, ): UseStore<AnyStore>

function hydrateStores(snapshot: Record<string, StateTree>): void

Pre-seed store state from a server snapshot.

function registerStorePlugin(plugin: StorePlugin): Dispose

Register a plugin globally.

function serializeStores(): Record<string, StateTree>

Snapshot every instantiated store in the ACTIVE registry (per-request on the server) as `{ storeId: { stateKey: value } }`.

const persistPlugin: StorePlugin

Ready-made persistence plugin with default config (localStorage, `aihu:`).

interface ActionContext<S> {
  /** The store instance the action belongs to. */
  store: S
  /** The action's key on the store. */
  name: string
  /** The arguments the action was called with. */
  args: unknown[]
  /**
   * Register a hook that runs after the action returns (or, for an
   * async action, after the returned promise resolves).
   */
  after(cb: (result: unknown) => void): void
  /**
   * Register a hook that runs when the action throws (or the returned
   * promise rejects). The error is always re-thrown to the caller.
   */
  onError(cb: (error: unknown) => void): void
}

Context handed to every `$onAction` subscriber at the moment an action is invoked (before the action body runs).

interface OptionsStoreConfig<
  S extends StateTree,
  G extends GettersTree<S>,
  A extends ActionsTree,
> {
  state: () => S
  getters?: G
  actions?: A & ThisType<OptionsStore<S, G, A>>
}

Options-style store definition.

interface PersistPluginConfig {
  /** Storage backend; defaults to `window.localStorage` (client only). */
  storage?: StorageLike
  /** Key prefix, defaults to `"aihu:"`. Full key: `${prefix}${key ?? id}`. */
  prefix?: string
}

interface PersistStoreOptions {
  key?: string
}

Per-store opt-in shape: `{ persist: true }` or `{ persist: { key } }`.

interface StorageLike {
  getItem(key: string): string | null
  setItem(key: string, value: string): void
}

Minimal storage contract (satisfied by `window.localStorage`).

interface StoreBase<St extends StateTree = StateTree> {
  /** The store's unique id (registry key + serialization key). */
  readonly $id: string
  /**
   * Apply several state writes as one batch. Object form writes the given
   * state keys; function form receives the store and may call any setters —
   * either way subscribers are notified once.
   */
  $patch(patch: Partial<St> | ((store: this) => void)): void
  /**
   * Reset state back to the `state()` factory's initial values.
   * Options-style stores only: a setup store has no canonical initial-state
   * factory to re-run (its initial values are arbitrary expressions inside
   * the setup closure), so `$reset()` throws for setup-style stores.
   */
  $reset(): void
  /**
   * Subscribe to state changes. `cb` receives a fresh snapshot of the
   * store's state after each change (batched writes notify once).
   * Returns a dispose function.
   */
  $subscribe(cb: (state: St) => void): Dispose
  /** Hook before/after/onError around every action call. Returns dispose. */
  $onAction(cb: ActionSubscriber<this>): Dispose
  /**
   * Tear the store down: dispose subscriptions and store-owned computeds,
   * then remove the instance from the registry (the next `useStore()`
   * call re-instantiates fresh).
   */
  $dispose(): void
}

The ` -prefixed instance surface every store carries, regardless of definition style.

interface StorePluginContext {
  /** The just-built store instance (after hydration adoption). */
  store: AnyStore
  /** The store id. */
  id: string
  /** The per-store custom options bag (`defineStore`'s third argument). */
  options: StoreCustomOptions | undefined
}

Context handed to every registered plugin at store instantiation.

type ActionsTree = Record<string, (...args: never[]) => unknown>

type ActionSubscriber<S> = (context: ActionContext<S>) => void

type AnyStore = StoreBase & Record<string, unknown>

Widest store instance type — used by the registry, plugins, and SSR.

type GetterReads<S extends StateTree, G extends GettersTree<S>> = {
  readonly [K in keyof G]: G[K] extends (state: StateReads<S>) => infer R ? Read<R> : never
}

Each getter lowers onto the instance as a computed read function.

type GettersTree<S extends StateTree> = Record<string, (state: StateReads<S>) => unknown>

Getters receive the read-side state view and return a derived value.

type OptionsStore<
  S extends StateTree,
  G extends GettersTree<S>,
  A extends ActionsTree,
> = StateReads<S> & StateWrites<S> & GetterReads<S, G> & A & StoreBase<S>

Full instance type of an options-style store.

type SetupSnapshot<SS> = {
  [K in SetupStateKeys<SS>]: SS[K] extends Read<infer T> ? T : never
}

The serializable snapshot shape of a setup-style store.

type SetupStateKeys<SS> = {
  [K in keyof SS & string]: SS[K] extends Read<unknown>
    ? `set${Capitalize<K>}` extends keyof SS
      ? K
      : never
    : never
}[keyof SS & string]

State detection for setup-style stores — mirrored at runtime in `store.ts` (`collectSetupShape`): a key `k` is a state entry when the setup returns a zero-arg read function under `k` AND a setter under `set${Capitalize<k>}`.

type SetupStore<SS extends Record<string, unknown>> = SS & StoreBase<SetupSnapshot<SS>>

Full instance type of a setup-style store.

type StateReads<S extends StateTree> = { readonly [K in keyof S]: Read<S[K]> }

Read-side view of an options-style store's state.

type StateTree = Record<string, unknown>

A plain-object state tree: what a store serializes to / hydrates from.

type StateWrites<S extends StateTree> = {
  readonly [K in keyof S & string as `set${Capitalize<K>}`]: Write<S[K]>
}

Write-side view: each state key `k` lowers to a `setK` writer.

type StoreCustomOptions = Record<string, unknown>

Per-store options bag consumed by plugins (e.g.

type StorePlugin = (context: StorePluginContext) => Record<string, unknown> | undefined

A store plugin.

type UseStore<T> = (() => T) & { readonly $id: string }

What `defineStore` returns: a lazy accessor for the store instance.