[jaaamesey]

What

Any store can now take an action set instead of a setter, for apps that want every change to go through named, typed, testable functions. Its actions are then the only way to write.

export const counterActionSet = defineActions({
  add(s: Counter, n: number) {
    s.count += n
  },
})

const [counter, counterActions] = useNewStore({ count: 0 }, counterActionSet)
counterActions.add(1)

• Same APIs, one rule: useNewStore, createContextStore, createNarrowedStoreContext and useNarrowedStore each also accept an action set (or an action context). New exports are defineActions, withContext, createTestStore and four types.
• Narrowing is declared with the actions. A set narrows to other sets (narrow((s, id: string) => s.todos.find(…), todoActionSet)), to any depth, recursive data included, so each part of the state only gets its own actions.
• Context from above: a set declares what it needs (a page's size, an undo checkpoint) as its methods' this, and the level that narrows to it provides it from the parent's draft, in the same update.
• Pairing value and actions: NarrowList (actions={appActions.todo}), useNarrowedStore(app, (a) => a.todo(id), appActions) and narrowed contexts all hand out a level's value and actions together. Identity is memoized in React, with no caches outside it.
• Testing: called directly, a set's actions are pure functions (state in, next state out, whether they mutate or replace); createTestStore runs several in a row.
• Also: NarrowList can memoize items with neither a setter nor a level, and the published build is now compiled with the React Compiler.

Docs: docs/actions.md. Example: examples/todomvc-actions.

Compatibility

Additive: the 0.2 exports keep their behaviour, and the existing test files are unchanged and pass. Bumps the version to 0.3.0. Needs TypeScript 5.5 or later (5.4 has a NoInfer bug); the README says so.

Also in this PR

• Path-only writes (the change from Compose narrowed updates as one mutate recipe down the path (O(path), not O(store)) #3, cherry-picked): a write through narrowed setters is one mutate recipe on the root draft, so it costs the length of the path, not the size of the store (291 ms → 0.2 ms at 150k items). Bound actions now write the same way. A custom setter passed as a Provider's setStore must forward both arguments to a store's setter.
• JSON patches: onPatches on useNewStore, owning Providers and createTestStore gets Mutative's patches and inverse patches for each committed update (once per update, in order, not twice in Strict Mode), with exact paths from the root. applyPatches(rootSetterOrActions, patches) writes them back and reports them as applied, for undo and sync. Patches are plain data, so any copy of Mutative can apply them.
• The library source was reorganized for readability (no behaviour change).

Testing

• 252 tests, run with and without the React Compiler: types, nesting, recursion, contexts, many stores from one definition, the testing patterns in src/testing.test.tsx, and a regression test for a render loop fixed in this PR.
• A real app: zerodollarpdf's editor store (~40 actions, item gestures through a level with context, NarrowLists) ported to action sets in a scratch clone. Its own Playwright suite against the production build: 124 passed, 3 failed, identical to the unported code (the same 3 fail there, and none involve editing).
• Patches: paths through narrowed setters, { get, swap } Maps, actions on levels and replacing actions, swaps and no-ops, undo through applyPatches, Strict Mode, batching, Providers, and patches applied by plain Mutative after a JSON round trip.
• The packed library typechecks in a consumer project on TypeScript 5.5 through 5.9.
• The build compiles every component and hook with the React Compiler, with no bailouts; the packed dist imports cleanly.
• An action through a level costs the same as the equivalent setter update (about 0.6 ms at 10,000 items, dominated by the lookup).
• examples/todomvc-actions checked in the browser.
• New CI workflow: typecheck, tests, build, and the examples' typecheck.

🤖 Generated with Claude Code

[unadlib]

Great work on the 0.3.0 release and the Mutative JSON Patch integration! 👏

One small suggestion: could you update the lockfile to mutative@2.0.1 (and optionally bump the dependency range to ^2.0.1)? The current package-lock.json still resolves 2.0.0.

Mutative 2.0.1 fixes an array deletion edge case where deleting a no-longer-existing index could unexpectedly grow the array, along with related sparse-array patch handling. Given the new onPatches / applyPatches APIs, it's worth picking up that fix.

Release: https://github.com/unadlib/mutative/releases/tag/v2.0.1
Fix: unadlib/mutative#213

Thanks for building on Mutative!

[jaaamesey]

@unadlib On it! Maybe I need to start taking this project a bit more seriously now that you've got your eyes on it 😅