batteries

Small utilities for building zustand stores out of composable slices.

The idea: keep state in small, self-contained slices that live next to the component that owns them. When that state needs to move further up the tree (so a parent can read or coordinate it), you compose the slices into a larger store instead of rewriting them — the slice keeps working standalone or packed.

Every slice is built on the immer middleware, so set mutations are written directly (state.count++).

Install

npm install @andykarasek02/batts zustand immer react

zustand, immer, and react are peer dependencies.

Concepts

createSlice(ValuesClass)(methods)

Define a slice. State defaults live on a class; methods are a normal zustand (set, get) creator.

import { batteries } from '@andykarasek02/batts';

class CounterValues {
  count = 0;
}

export const counterSlice = batteries.createSlice(CounterValues)((set, get) => ({
  increment: () => set((state) => void state.count++),
  add: (n: number) => set((state) => void (state.count += n)),
  double: () => set({ count: get().count * 2 }),
}));

createSlice returns:

| Property | What it is | | --- | --- | | counterSlice.use | A ready-to-use shared store/hook for this slice on its own. | | counterSlice.create(initial?) | A fresh store seeded with initial over the class defaults — one per call. | | counterSlice.with(initial) | A new slice pre-seeded with initial, for packing (see below). | | counterSlice._slice | The raw slice creator used when composing into a larger store. |

Every slice automatically gets a reset() method that restores the values the store started with (defaults plus any seeded overrides).

// Use it standalone — e.g. local component state
const { count, increment } = counterSlice.use();

counterSlice.use.getState().add(5);
counterSlice.use.getState().reset(); // back to count: 0

Seeding different initial values

The class supplies defaults; create / with seed different initial values over them — no constructor needed. Pass any subset of the class's fields.

// A fresh store per use — e.g. one store per component, pre-filled from props:
const store = counterSlice.create({ count: 10 });
store.getState().count; // 10

// reset() goes back to the seeded value, not the class default:
store.getState().add(5);
store.getState().reset();
store.getState().count; // 10

// Seed a slice *inside a pack* with `with` (chainable):
const packed = batteries.packStore({
  counter: counterSlice.with({ count: 7 }),
  user: userSlice.with({ name: 'ada' }),
});
packed.getState().slices.counter.count; // 7

counterSlice.use remains the shared, zero-config singleton; create/with never touch it.

packStore(sliceMap)

Combine several slices into one store. Each slice lives under slices.<key> and can still only update itself — the wiring scopes each slice's set/get to its own corner of the store.

const store = batteries.packStore({
  counter: counterSlice,
  user: userSlice,
});

store.getState().slices.counter.increment();
store.getState().slices.user.rename('ada');

store.getState().slices.counter.count; // 1
store.getState().slices.user.name;     // 'ada'

packStore(sliceMap, ParentValuesClass)(parentMethods) — with a parent

Pass a second argument (a parent values class) and packStore returns a function that takes the parent's methods. The parent sits alongside the slices and can read and write across all of them. Parent values come from a class; parent methods get the full combined store via set/get.

class ParentValues {
  label = 'parent';
}

const store = batteries.packStore(
  { counter: counterSlice },
  ParentValues,
)((set, get) => ({
  summary: () => `${get().label} = ${get().slices.counter.count}`,
  bumpCounter: () =>
    set((state) => {
      state.slices.counter.count += 1;
    }),
}));

store.getState().bumpCounter();
store.getState().slices.counter.increment(); // children still control themselves
store.getState().summary(); // "parent = 2"

The parent form stays curried (two calls) because the parent methods' input type is the whole combined store — which includes the methods' own return type. Splitting the call lets TypeScript resolve the store type before inferring your methods. batteries.packParentStore(sliceMap, ParentValues)(methods) is kept as an explicit alias for the exact same thing.

packTuple([sliceA, sliceB] as const) — positional slices

Compose an ordered list of slices instead of a keyed map. Slices live under numeric indices, and — unlike a map — you can include the same slice more than once. Pass the list as const so each position keeps its own type.

const store = batteries.packTuple([counterSlice, userSlice] as const);

store.getState().slices[0].increment(); // typed as the counter slice
store.getState().slices[1].rename('ada'); // typed as the user slice

// Two independent instances of the same slice:
const pair = batteries.packTuple([counterSlice, counterSlice] as const);
pair.getState().slices[0].add(10);
pair.getState().slices[1].count; // still 0

Prototype — static only. The number and order of slices are fixed at pack time. Runtime add/remove (true dynamic collections) needs scoping by a stable id rather than by index; the select seam in scopeLens.ts is where that change lands.

packSlice(sliceMap) — a reusable, nestable pack

packSlice is the composite analog of createSlice: it packs a map of slices into a single reusable slice, returning the same { _slice, use } shape. So the result works standalone and drops into another pack as a slice — letting you nest a packed store inside a packed store.

const profile = batteries.packSlice({
  counter: counterSlice,
  user: userSlice,
});

// Standalone — it's a packed store on its own:
profile.use.getState().slices.counter.increment();

// …or nested inside a larger store:
const root = batteries.packStore({ profile, settings: settingsSlice });

root.getState().slices.profile.slices.counter.increment();
//                       ^ nested pack    ^ its child slice

Nesting is fully typed and composes to any depth (packSlice inside packSlice inside packStore). Scoping still holds: a deeply nested child can only ever write to itself, because each level writes to its own immer draft. A nested pack also slots into packTuple and the parent form of packStore, which can read and write nested children (get().slices.profile.slices.counter).

Each child keeps its own reset(). There's no group-level reset yet — a reset that cascades to every child would be a natural addition.

Typing

You rarely need to hand-write store types. Two helpers cover the common cases and work the same whether or not the store has a parent:

import { batteries, type StoreState, type SliceState } from '@andykarasek02/batts';

const useStore = batteries.packStore({ counter: counterSlice });

type Store = StoreState<typeof useStore>;        // { slices: { counter: ... } }
type Counter = SliceState<typeof counterSlice>;  // { count, increment, ..., reset }

StoreState<T> extracts the state from any store/hook (plain or parent), so downstream code doesn't care which pack* produced it.

Why

Co-locate state with the component that owns it as a slice. If a sibling or parent later needs that state, pack the slices upward instead of lifting and rewriting the state by hand. The same slice definition powers both the standalone (.use) and composed (packStore / packParentStore) cases.

Development

npm test          # run the test suite once (vitest)
npm run test:watch
npm run typecheck # tsc --noEmit