Kin Store

Design Principles

These four principles shaped every API decision in Kin Store. Understanding them makes the library predictable, and explains why things work the way they do.

Explicit over implicit

No hidden merges, no auto-propagating destroy, no magic dependency graphs. If something happens, you triggered it.

set replaces the entire state — there is no shallow merge happening behind the scenes. derive tracks only the stores you explicitly read with get(store). destroy must be called manually — nothing propagates to child stores automatically. The CANCELED sentinel, named reducers, and the two-tier mutation model all follow from this principle.

Opt-in complexity

createStore is the floor. withPlugins adds methods, reducers, middleware, and lifecycle hooks, only when you import it. derive adds reactive composition, only when you reach for it. You never pay for capability you haven't opted into.

Type safety by default

Every reducer argument, dispatch call, and plugin method is fully inferred, no any or unknown, no manual annotation at call sites. The type system is load-bearing, not decorative.

dispatch.addTodo("Buy groceries") knows that addTodo takes a string. A middleware that reads ctx.reducer.args gets the correct tuple type. A plugin that adds methods sees the accumulated store type including every plugin registered before it. Type errors are caught statically, at definition time or at the call site.

Two tiers of mutation

dispatch.* and set are both first-class ways to change state, neither is a fallback for the other. dispatch.* calls a named reducer through the middleware pipeline, so the change is traceable, loggable, and cancellable. set writes state directly, with no pipeline in between. Which one a team reaches for is an architectural choice, not a hierarchy, and Kin Store is deliberately built so any point on that spectrum is a first-class way to use the library:

  • Primitive composition — createStore + derive + plain functions, no withPlugins at all.
  • Methods only — withPlugins + methods that call set directly, no reducers or middleware.
  • Reducers + middleware — withPlugins + reducers dispatched through dispatch.*, with middleware doing the logging/undo/guard work.
  • Fat store — createStore plus colocated top-level logic functions that call set, no plugin system involved.

Within a withPlugins store, a method can also mix both in the same call: dispatch.* for the parts of a change that should be traceable, set for a direct write, matching what that specific change needs rather than a store-wide rule. If your team standardizes on one style — e.g. "every mutation goes through dispatch.*" — that's a convention to hold at the module boundary (export dispatch and your methods, not set, from your store module), not something Kin Store enforces for you.