API Reference

The @ilokesto/store package exports one public class: Store<T>.

import { Store } from "@ilokesto/store";

The public Store<T> API includes construction, state reads and writes, middleware registration, and subscriptions.

Import path and export

Store<T>

Store<T> is the only exported symbol from @ilokesto/store.

const store = new Store({ count: 0 });

Constructor

new Store<T>(initialState: T)

Creates a store with an initial state value. The store keeps that value as both the initial state and current state until an update succeeds.

const store = new Store({ count: 0 });

Methods

getState()

getState(): Readonly<T>

Returns the current state reference as Readonly<T>.

Readonly<T> is a TypeScript type only. Store does not freeze, clone, or proxy the state value at runtime.

getInitialState()

getInitialState(): Readonly<T>

Returns the constructor value reference as Readonly<T>.

Use it when you need to compare against the original value or reset to it yourself.

setState(nextState)

setState(nextState: T | ((prevState: T) => T)): void

Replaces the current state with a value or with the result of an updater function.

store.setState({ count: 1 });

store.setState((prev) => ({
  ...prev,
  count: prev.count + 1,
}));

The resolved next value replaces the whole state. Store does not merge objects.

If the runtime value passed to setState is a function, Store treats it as an updater. This means a function root state value cannot be set directly through setState.

pushMiddleware(middleware)

pushMiddleware(
  middleware: (nextState: T | ((prevState: T) => T), next: (value: T | ((prevState: T) => T)) => void) => void,
): void

Appends middleware to the middleware array used by setState.

Middleware receives the pending state action and a next function. It must call next(nextState) to continue the update.

Because setState builds the runner with reduceRight, earlier middleware entries wrap later entries.

unshiftMiddleware(middleware)

unshiftMiddleware(
  middleware: (nextState: T | ((prevState: T) => T), next: (value: T | ((prevState: T) => T)) => void) => void,
): void

Prepends middleware to the middleware array used by setState.

Prepended middleware becomes an earlier middleware entry and wraps later entries in the chain.

subscribe(listener)

subscribe(listener: () => void): () => void

Registers a listener and returns an unsubscribe callback that removes the same listener reference.

const unsubscribe = store.subscribe(() => {
  console.log(store.getState());
});

unsubscribe();

Listeners run synchronously after a successful state replacement.

Guarantees

• @ilokesto/store exports Store<T> from the package root.
• getState() and getInitialState() return the current and initial state references typed as Readonly<T>.
• setState replaces the whole state value. It does not merge objects.
• Updater functions are called with the previous state.
• Object.is controls equality bailouts. When it returns true, state is not replaced and listeners are not notified.
• Successful replacements notify listeners synchronously in the same call flow.
• Notification uses a snapshot of the listener set, so unsubscribe calls during notification do not mutate the active iteration array.
• Duplicate listener function references are stored once because listeners are kept in a Set.
• Middleware registered with pushMiddleware or unshiftMiddleware participates in the setState chain and must call next for the update to continue.

Non-guarantees

• State is not frozen, cloned, proxied, or deeply immutable at runtime.
• Store does not shallow merge object updates.
• Store does not provide selectors, reducers, action dispatching, persistence, data fetching, devtools, or framework hooks.
• Store does not batch, schedule, or defer notifications.
• Store does not track which state properties a listener reads.

Related pages

• Core Concepts explains the state and subscription model.
• Advanced Semantics covers detailed behavior rules.
• Building on Store explains how to build adapters and libraries on this contract.