Troubleshooting

Troubleshoot common @ilokesto/store behavior by checking the Store contract, state replacement rules, and adapter wiring.

My UI is not updating

Most UI issues come from one of three causes:

1. The UI is reading store.getState() once and never subscribing.
2. The update returned the same root reference, so Object.is bailed out.
3. A framework adapter did not connect the Store notification to the framework render lifecycle.

Check the basic read, write, and subscribe flow in Core Concepts, then review framework cleanup and render wiring in Framework Usage.

My subscriber is not firing

A subscriber fires only after a successful state replacement. It does not fire when Object.is(prevState, nextState) is true.

store.setState((prev) => prev);
// subscriber does not fire.

If you mutated an object and passed the same reference back, create a new root value instead. Advanced Semantics covers the bailout and notification rules.

My subscriber fires too often

Store does not track which field a subscriber cares about. A subscriber runs after every successful root state replacement.

If a consumer only cares about one field, compare the previous selected value in your own layer and skip work when it has not changed. Keep that as adapter or application logic, not as a Store feature.

Patterns for wrapping Store behavior belong in Patterns and Building on Store.

My React value is stale

A stale React value usually means the component captured a Store value without subscribing through React state or an external-store bridge.

Read the value during render from framework state that is updated by a Store subscription. Do not expect a one-time const value = store.getState() outside render to stay current in the UI.

For framework-level wiring, see Framework Usage. For the raw subscription method, see API Reference.

How do I clean up in Vue, Svelte, or Angular?

store.subscribe(listener) returns an unsubscribe function. Call that function when the framework scope is destroyed.

The exact lifecycle hook belongs to the framework layer, not the Store package. The Store contract is only that calling the returned function removes that listener reference.

Framework Usage covers framework examples. API Reference covers the raw subscription API.

I changed a nested object, but nothing happened

Direct mutation does not notify subscribers.

store.getState().profile.name = "Ada";
// No setState call, no notification.

Use an immutable update and return a new root state value.

store.setState((prev) => ({
  ...prev,
  profile: {
    ...prev.profile,
    name: "Ada",
  },
}));

Nested mutation and Readonly<T> behavior are covered in Advanced Semantics.

Does Store replace Redux, Zustand, Pinia, or NgRx?

No. @ilokesto/store is a small state primitive. It stores one value, replaces that value, and notifies subscribers.

It does not provide reducer dispatch, a selector system, devtools, effects, modules, actions, or ready-made framework bindings. You can build higher-level patterns on top of it when that is useful.

Core Concepts covers the package boundary. Building on Store covers wrapper guidance.

Does Store manage server cache or data fetching?

No. Store does not manage server cache, request status, refetching, invalidation, retries, or persistence.

You can store any value you choose, including data that came from a server, but server-cache behavior must come from your application or another library.

Core Concepts covers what Store is and is not.

How do I debug an adapter?

Debug the adapter around the raw Store contract.

1. Confirm the adapter subscribes once for each live consumer scope.
2. Confirm it calls the unsubscribe function when that scope is destroyed.
3. Confirm the listener reads store.getState() after notification.
4. Confirm framework state is updated with a new value or signal that causes the UI to render.
5. Confirm the Store update returns a new root state reference when a change should publish.

The authoritative Store rules are in API Reference and Advanced Semantics. Adapter boundaries are covered in Building on Store.