Mental Model

@ilokesto/state only really makes sense once you stop thinking of it as “another React state library.” It is closer to a React binding for an external store that happens to feel small enough to use like local state.

The package is easiest to reason about if you keep four layers in your head: the store, the hook, the selector, and the writer.

Store + hook, not provider + context

Unlike provider-first libraries, @ilokesto/state starts with a store and then binds that store to React.

1. The store lives outside React and owns the real state.
2. The hook returned by create() is how components subscribe to that store.
3. The selector narrows what a component reads.
4. The writer still updates the full state or dispatches a reducer action.

Selectors narrow reads, not writes

Selectors are the main reason the API looks more scalable than a raw external store.

• They keep components subscribed to a narrow slice.
• They reduce noisy re-renders.
• They let the hook reuse a previous selected value when store snapshots are deeply equal.

But selectors do not give you a slice-local setter. The writer still updates the whole store state.

Data Flow

• Reads happen through useSyncExternalStore.
• Writes go through the store writer or reducer dispatch.
• Middleware sits at the store layer, not the React layer.
• SSR works because the server snapshot comes from store.getInitialState().

Why this shape is useful

This model gives you a useful middle ground:

• lighter than a provider-heavy architecture,
• more explicit than ad-hoc local state spread across components,
• still close enough to a real store that middleware and non-React integration remain possible.

If you want the exact API surface next, read create. If you want practical organization patterns, go to Patterns.