Tiny, typed reducer state management for Preact

# State — integration reference

createStore and createAction with TypeScript-first action matching, Preact context providers, optional middleware, and a signals bridge — without a React runtime.

Package: @kamod-ch/state

## Choose an approach

Use named actions and reducers when changes need a clear explanation. Model the events in your flow first, then decide which components read state and which dispatch actions.

### A local open or closed control

Keep simple presentation state local to the component.

A reducer store is useful when events and shared ownership add clarity, not for every boolean.

### A shared domain workflow

Model named actions and derive the next state in a pure reducer.

Store domain facts; derive display labels and totals where possible instead of saving duplicates.

### A reactive view of store data

Select the smallest useful value with the package's Preact integration.

If a signals bridge is needed, keep one authoritative writer rather than two synchronized stores.

## Installation

Install @kamod-ch/state with Preact as a peer dependency when using the Preact context entry points.

```bash
pnpm add @kamod-ch/state preact
```

## Starting example

```tsx
import { createAction, createStore } from "@kamod-ch/state";

const increment = createAction("counter/increment");

const store = createStore({
  reducer: (state = { count: 0 }, action) =>
    increment.match(action) ? { count: state.count + 1 } : state,
});

store.dispatch(increment());
```

### Name the event

A named event describes an intention, not a particular button. Multiple controls can dispatch it without teaching the reducer about their markup. Keep naming consistent as the feature grows.

```tsx
const increment = createAction("counter/increment");
```

### Return a new value only for a handled event

The matcher selects the branch. Returning the existing state for unrelated actions protects the current value; returning a new object for the matching action makes the transition explicit. Avoid mutation or network work inside the reducer.

```tsx
increment.match(action) ? { count: state.count + 1 } : state
```

### Dispatch through the store boundary

A dispatch changes the model. A Preact view also needs a subscription, normally through the package's context and selector hooks. Reading a snapshot once does not turn an arbitrary component into a subscriber.

```tsx
store.dispatch(increment());
```

## Define the state and event contract together

An explicit state type makes the model readable as soon as a second view needs it. A factory gives each test or server request its own store. Decide where the app owns that instance before wiring a provider around its consumers.

File: src/state/counter.ts

```tsx
import { createAction, createStore } from "@kamod-ch/state";

export const increment = createAction("counter/increment");
type CounterState = { count: number };
type CounterAction = ReturnType<typeof increment>;

export function createCounterStore() {
  return createStore<CounterState, CounterAction>({
    reducer: (state = { count: 0 }, action) =>
      increment.match(action) ? { count: state.count + 1 } : state,
  });
}
```

Create two stores and confirm that dispatching to one does not change the other. When adding asynchronous work, represent pending, success and failure deliberately and keep the effect outside the reducer. Consult the package reference for context, selectors and middleware signatures.

## Ownership and environment

Put the store at the boundary of the workflow it represents. A page-local flow can use a page-local owner, while an app-wide session model may need a longer lifetime. For SSR and tests, factories make ownership explicit. Keep reducers deterministic so the same state and event produce the same result without depending on the clock or network.

Model asynchronous outcomes as deliberate transitions. A submit action can lead to pending, followed by success or failure; the component then renders those states. Keep the request itself outside the reducer and decide how stale results are handled if the user starts another operation or leaves the screen before it completes.

A useful state model explains both what happened and what the user sees next. Pair loading, success and failure transitions with visible feedback and deliberate focus behavior.

## Troubleshooting

### Dispatch happens but the view does not update

Verify that the view subscribes through the appropriate context or selector API. Also check that the matching reducer branch returns a new value instead of mutating existing state.

### An unrelated action resets the screen

Inspect the reducer's fallback branch. Return the current state for actions it does not handle rather than recreating the initial state.

### State leaks between tests or requests

Look for a shared module-level store. Create an instance for each independent owner and verify that updates in one instance cannot affect the other.

## Resources

- [Documentation](https://kamod-ch.github.io/kamod-state/)
- [Source](https://github.com/kamod-ch/kamod-state)
- [npm](https://www.npmjs.com/package/@kamod-ch/state)