echo-state

One state model for in-memory data, persistence, and synchronization across windows.

State differs not only in what it stores, but in how long it should live and where it must remain consistent.

State inside a React component may exist for only a few seconds. Other state must survive a page reload or remain synchronized across browser tabs. Many projects handle these cases separately with component state, LocalStorage, IndexedDB, and additional synchronization code. The same business state then acquires several unrelated ways to initialize, read, and update it.

echo-state is a lightweight state library I extracted from repeatedly solving this problem. A single Echo instance describes the state, while its actual lifecycle can use temporary storage, LocalStorage, or IndexedDB.

State Should Have an Explicit Lifecycle

Temporary interface state does not need to be written to disk. User preferences should survive a refresh. Larger or structured data may belong in IndexedDB. When several windows operate on the same state, changes also need to propagate between them.

echo-state makes these decisions part of the state configuration instead of scattering them across component effects. Components use the same Hooks API regardless of storage mode, so persistence can change without redesigning the business-facing access pattern.

import { Echo } from "echo-state";

const user_store = new Echo({
  name: "",
  is_logged_in: false,
});

const state = user_store.use();
user_store.set({ name: "Wangenius" });

Subscribe Only to What Matters

A component usually depends on only part of a store. echo-state supports selector-based subscriptions so unrelated changes do not need to trigger a render.

const user_name = user_store.use((state) => state.name);

Persistent state can use ready() to wait until initialization is complete, preventing the application from reading an incorrect default before storage has loaded. Cross-window synchronization keeps multiple tabs current without requiring each product to implement its own communication layer.

A Building Block Extracted from Product Work

While building desktop tools, document workspaces, and agent products, I repeatedly encountered settings, sessions, editing state, and local data with different lifetimes. echo-state extracts the stable and reusable part of that work into an independent library: a small API, complete TypeScript definitions, and no external runtime dependencies.

It is not a framework intended to control an entire application architecture. It is a bounded state primitive: create state, update it, subscribe to the part that matters, and decide explicitly how it should persist and synchronize.