nanoeffects 0.7.0 → 0.8.0

package/docs/stores.md

@@ -17,7 +17,7 @@ If you do not have a store yet, use `createBus` from the [Guide](guide.md).
   - [React: sharing a value across components](#react-sharing-a-value-across-components)
   - [Callbacks on every change](#callbacks-on-every-change)
   - [Stop watching a store](#stop-watching-a-store)
-  - [Give the store to every handler](#give-the-store-to-every-handler)
+  - [Change the store from any handler](#change-the-store-from-any-handler)
 
 ## Wire Redux Toolkit to a bus
 
@@ -28,23 +28,40 @@ Redux’s `dispatch` → reducers updates **state**. It does not give you first-
 Skip this section if you are not already on Redux. The recipe as a file, type-checked with the project: [`examples/redux.ts`](../examples/redux.ts).
 
 ```js
-import { configureStore, createAction } from "@reduxjs/toolkit";
+// bus.js
 import { createBus } from "nanoeffects";
-import { latest } from "nanoeffects/policies";
-import { createEffectsMiddleware } from "nanoeffects/redux";
 
-const userRequested = createAction("user/requested"); // RTK
-const userLoaded = createAction("user/loaded");
+export const bus = createBus(); // the bus of your app; it can exist before the store
+```
+
+```js
+// user.js
+import { createAction } from "@reduxjs/toolkit";
 
-const bus = createBus(); // the bus of your app; it can exist before the store
+export const userRequested = createAction("user/requested"); // RTK
+export const userLoaded = createAction("user/loaded");
+```
+
+```js
+// store.js
+import { configureStore } from "@reduxjs/toolkit";
+import { createEffectsMiddleware } from "nanoeffects/redux";
+import { bus } from "./bus";
 
 // createEffectsMiddleware — actions reach the bus after reducers; tasks get ctx.store
 const effects = createEffectsMiddleware(bus);
 
-const store = configureStore({
+export const store = configureStore({
   reducer,
   middleware: (getDefault) => getDefault().concat(effects),
 });
+```
+
+```js
+// user-handlers.js
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { userLoaded, userRequested } from "./user";
 
 // latest — a newer run aborts the older one
 bus.on(
@@ -95,28 +112,44 @@ const effects = createEffectsMiddleware(bus);
 Zustand, MobX, Jotai, Valtio, Nanostores and Pinia have no adapter. Redux is different: use the middleware from the first section, it sends actions to the bus. A plain store works with the bus in two directions, and both are shown for each store below:
 
 - **The store triggers an event.** The store tells you about a change with a callback. You pass that callback `bus.emitter(action)`, and the change becomes an event that starts a handler.
-- **The event changes the store.** The handler reports its result as an event. A listener of the bus writes it into the store.
+- **The event changes the store.** The handler reports its result as an event. A listener of the bus gets the store from `ctx` and changes it with a mutation.
 
 The example is a search box. The store holds two fields: `query`, which the user types, and `results`, which a request fills. A change of `query` starts a debounced search; the search ends with an event that writes `results`.
 
 Writing `(query) => bus.emit(queryChanged(query))` for every subscription repeats the bus and the action. `emitterPlugin` adds `bus.emitter(action)`: it returns that callback for you. The action stays a plain `createAction`, so `bus.emit(queryChanged("nano"))` and `bus.on(queryChanged, …)` work as before.
 
-The bus is the same for every store below. Create it once; each subsection imports it.
+The bus gets the store as context: `contextPlugin({ store })` puts it on every task as `ctx.store` ([Context fields](context.md)). A handler then changes the store with its mutations and never reaches for the store by name. Only `store.js` is different for each store below. It exports a `store` with the same three members:
+
+- `setQuery(query)` and `setResults(items)` are the mutations. The user's input calls the first, the handler calls the second.
+- `onQueryChanged(callback)` tells you about a change of `query`, and returns the function that stops it.
+
+The bus, the events, the handlers and the link from the store to the bus are the same for every store, each in a file of its own: the bus knows no events, and the events know no bus.
 
 ```js
-// search-bus.js
-import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { debounce, latest } from "nanoeffects/policies";
+// bus.js
+import { contextPlugin, createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+import { store } from "./store";
+
+export const bus = createBus()
+  .use(emitterPlugin()) // adds bus.emitter
+  .use(contextPlugin({ store })); // ctx.store on every task
+```
 
-export const bus = createBus().use(emitterPlugin()); // adds bus.emitter; returns the same bus
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
 // createAction — plain action creators; calling one only builds { type, payload }
 export const queryChanged = createAction("search/queryChanged");
 export const searchLoaded = createAction("search/loaded");
+```
 
-// bus.emitter: a callback (query) => bus.emit(queryChanged(query))
-export const emitQueryChanged = bus.emitter(queryChanged);
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 // debounce — wait 300 ms of quiet; latest — abort the search of the previous query
 bus.on(
@@ -130,141 +163,199 @@ bus.on(
     }),
   ),
 );
+
+// event → store: the store comes from ctx, and a mutation changes it
+bus.on(searchLoaded, (items, { store }) => {
+  store.setResults(items);
+});
+```
+
+```js
+// connect.js
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+import { store } from "./store";
+
+// store → event: bus.emitter turns the callback into an emit of queryChanged
+export const stopQuery = store.onQueryChanged(bus.emitter(queryChanged));
 ```
 
 Write `results` and never the field you watch: a handler that changed `query` would start itself again. Find your store below.
 
 ### Nanostores
 
-`listen` calls back with the new value. `subscribe` would also call at once, with the current value, so use `listen`.
+`action` makes a named mutation of an atom. `listen` calls back with the new value; `subscribe` would also call at once, with the current value, so use `listen`.
 
 ```js
-import { atom } from "nanostores";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+// store.js
+import { action, atom } from "nanostores";
 
 const $query = atom("");
 const $results = atom([]);
 
-// store → bus: listen calls back with the new query on every change
-const stopQuery = $query.listen(emitQueryChanged);
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  $results.set(items);
-});
+export const store = {
+  // action — a named mutation of an atom
+  setQuery: action($query, "setQuery", (target, query) => target.set(query)),
+  setResults: action($results, "setResults", (target, items) => target.set(items)),
+  // listen — calls back with the new query on every change
+  onQueryChanged: (callback) => $query.listen(callback),
+};
 ```
 
 ### MobX
 
-`reaction` watches an expression and calls back with its value. Change observables inside `runInAction`.
+`makeAutoObservable` turns the methods of a class into actions, which is where MobX wants changes to happen. `reaction` watches an expression and calls back with its value.
+
+<!-- docs-check: fork -->
 
 ```js
-import { observable, reaction, runInAction } from "mobx";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+// store.js
+import { makeAutoObservable, reaction } from "mobx";
 
-const search = observable({ query: "", results: [] });
+class SearchStore {
+  query = "";
+  results = [];
 
-// store → bus: reaction watches the expression and calls back with its value
-const stopQuery = reaction(() => search.query, emitQueryChanged);
+  constructor() {
+    makeAutoObservable(this); // the methods below become actions
+  }
 
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  runInAction(() => {
-    search.results = items;
-  });
-});
+  setQuery(query) {
+    this.query = query;
+  }
+
+  setResults(items) {
+    this.results = items;
+  }
+
+  // reaction — watches the expression and calls back with its value
+  onQueryChanged(callback) {
+    return reaction(() => this.query, callback);
+  }
+}
+
+export const store = new SearchStore();
 ```
 
 ### Valtio
 
-`subscribeKey` watches one field of a proxy state. Assign to the proxy to change it.
+`subscribeKey` watches one field of a proxy state. A mutation assigns to the proxy.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.js
 import { proxy } from "valtio";
 import { subscribeKey } from "valtio/utils";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
 
 const state = proxy({ query: "", results: [] });
 
-// store → bus: subscribeKey watches one field
-const stopQuery = subscribeKey(state, "query", emitQueryChanged);
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  state.results = items;
-});
+export const store = {
+  setQuery(query) {
+    state.query = query;
+  },
+  setResults(items) {
+    state.results = items;
+  },
+  // subscribeKey — watches one field
+  onQueryChanged: (callback) => subscribeKey(state, "query", callback),
+};
 ```
 
 ### Jotai
 
-`sub` gives no value, so read it yourself. Write with `store.set`.
+`sub` gives no value, so read it yourself. A write-only atom is the mutation, and `set` runs it.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.js
 import { atom, createStore } from "jotai";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
 
 const queryAtom = atom("");
 const resultsAtom = atom([]);
-const store = createStore();
-
-// store → bus: sub calls back without a value; store.get reads it
-const stopQuery = store.sub(queryAtom, () => emitQueryChanged(store.get(queryAtom)));
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  store.set(resultsAtom, items);
-});
+const jotai = createStore();
+
+// write-only atoms: the mutations
+const setQueryAtom = atom(null, (_get, set, query) => set(queryAtom, query));
+const setResultsAtom = atom(null, (_get, set, items) => set(resultsAtom, items));
+
+export const store = {
+  setQuery: (query) => jotai.set(setQueryAtom, query),
+  setResults: (items) => jotai.set(setResultsAtom, items),
+  // sub calls back without a value; get reads it
+  onQueryChanged: (callback) =>
+    jotai.sub(queryAtom, () => callback(jotai.get(queryAtom))),
+};
 ```
 
 ### Zustand
 
-With `subscribeWithSelector` the selector picks the field, and the callback is called only when it changes. Without a selector Zustand calls back on every `setState`, with the whole state.
+With `subscribeWithSelector` the selector picks the field, and the callback is called only when it changes. Without a selector Zustand calls back on every `setState`, with the whole state. The mutations are functions in the state.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.js
 import { create } from "zustand";
 import { subscribeWithSelector } from "zustand/middleware";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
 
-const useSearchStore = create(
-  subscribeWithSelector(() => ({ query: "", results: [] })),
+const useSearch = create(
+  subscribeWithSelector((set) => ({
+    query: "",
+    results: [],
+    // the mutations are part of the state
+    setQuery: (query) => set({ query }),
+    setResults: (items) => set({ results: items }),
+  })),
 );
 
-// store → bus: subscribe with a selector calls back with state.query only when it changes
-const stopQuery = useSearchStore.subscribe((state) => state.query, emitQueryChanged);
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  useSearchStore.setState({ results: items });
-});
+export const store = {
+  setQuery: (query) => useSearch.getState().setQuery(query),
+  setResults: (items) => useSearch.getState().setResults(items),
+  // a selector: called back with state.query only when it changes
+  onQueryChanged: (callback) => useSearch.subscribe((state) => state.query, callback),
+};
 ```
 
 ### Pinia
 
-Pinia (the store of Vue) keeps reactive objects, and its `$subscribe` reports every mutation of the store, not one field. Watch one getter with Vue's `watch` instead: it calls back with the new value. Assign to the store to change it.
+Pinia (the store of Vue) keeps reactive objects, and its `$subscribe` reports every mutation of the store, not one field. Watch one getter with Vue's `watch` instead: it calls back with the new value. The mutations are the actions of the store.
+
+<!-- docs-check: fork -->
 
 ```js
-import { watch } from "vue";
+// store.js
 import { defineStore } from "pinia";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+import { watch } from "vue";
 
-// defineStore — Pinia: the state of one store
+// defineStore — Pinia: the state and the actions of one store
 const useSearch = defineStore("search", {
   state: () => ({ query: "", results: [] }),
+  actions: {
+    setQuery(query) {
+      this.query = query;
+    },
+    setResults(items) {
+      this.results = items;
+    },
+  },
 });
 
 const search = useSearch(); // call it after the app has installed Pinia
 
-// store → bus: watch calls back with the new query when search.query changes
-const stopQuery = watch(() => search.query, emitQueryChanged);
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  search.results = items;
-});
+export const store = {
+  setQuery: (query) => search.setQuery(query),
+  setResults: (items) => search.setResults(items),
+  // watch — calls back with the new query when search.query changes
+  onQueryChanged: (callback) => watch(() => search.query, callback),
+};
 ```
 
 ### React: sharing a value across components
 
+<!-- docs-check: new -->
+
 A value of your UI (a query, a filter, a name) often has two jobs. Several components read it and re-render when it changes, and the bus must hear about each change to start a handler. The recipes below differ in where the value lives. Pick the first one unless a handler must read the value.
 
 | The value lives in | Use when |
@@ -277,20 +368,30 @@ A value of your UI (a query, a filter, a name) often has two jobs. Several compo
 
 Writing `useEffect(() => bus.emit(...), [value])` looks enough, but it emits on mount, emits twice on mount under StrictMode, and re-runs when the emit function is new on every render. `useEmitter` from `nanoeffects/react` avoids all three. It emits after a render commits with a changed value, never on mount, and compares with `Object.is`. You need React 18 or newer; no other entry of the package uses React.
 
-First the bus. `reactPlugin()` adds `bus.useEmitter`, and destructuring it gives a plain hook that you export:
+First the bus, the events and the handlers, each in its own file. `reactPlugin()` adds `bus.useEmitter`, and destructuring it gives a plain hook that you export from the bus file:
 
 ```js
-// react-search-bus.js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction } from "nanoeffects/actions";
-import { debounce, latest } from "nanoeffects/policies";
 import { reactPlugin } from "nanoeffects/react";
 
 export const bus = createBus().use(reactPlugin()); // the bus; reactPlugin adds bus.useEmitter
 export const { useEmitter } = bus; // a free hook: it does not read `this`
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
 export const queryChanged = createAction("query/changed");
 export const searchLoaded = createAction("search/loaded");
+```
+
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 // debounce — wait 300 ms of quiet; latest — a newer query aborts the older request
 bus.on(
@@ -310,7 +411,8 @@ Then the provider. It holds the state, calls `useEmitter` once, and listens for
 ```jsx
 // SearchProvider.jsx
 import { createContext, useContext, useEffect, useState } from "react";
-import { bus, queryChanged, searchLoaded, useEmitter } from "./react-search-bus";
+import { bus, useEmitter } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 const SearchContext = createContext(null);
 
@@ -367,6 +469,8 @@ Two limits to know:
 
 A context is not visible to a bus handler. When a handler needs the current value, keep the value outside React. About twelve lines of `useSyncExternalStore` do it, and `contextPlugin` hands it to every handler as `ctx.query`:
 
+<!-- docs-check: new -->
+
 ```jsx
 // value-store.js
 import { useSyncExternalStore } from "react";
@@ -396,19 +500,36 @@ export function createValue(initial) {
 export const useValue = (store) => useSyncExternalStore(store.subscribe, store.get);
 ```
 
-```jsx
-// search-value.jsx
-import { createBus, contextPlugin } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { createValue, useValue } from "./value-store";
+```js
+// query.js
+import { createValue } from "./value-store";
 
-const query = createValue("");
+export const query = createValue("");
+```
+
+```js
+// bus.js
+import { contextPlugin, createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+import { query } from "./query";
 
 // emitterPlugin adds bus.emitter; contextPlugin puts `query` on every task as ctx.query
-const bus = createBus().use(emitterPlugin()).use(contextPlugin({ query }));
+export const bus = createBus().use(emitterPlugin()).use(contextPlugin({ query }));
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
-const queryChanged = createAction("query/changed");
-const refreshed = createAction("search/refreshed");
+export const queryChanged = createAction("query/changed");
+export const refreshed = createAction("search/refreshed");
+```
+
+```js
+// search-handlers.js
+import { bus } from "./bus";
+import { query } from "./query";
+import { queryChanged, refreshed } from "./search";
 
 // store → bus: bus.emitter turns the action into a callback; one place, any number of setters
 const emitQueryChanged = bus.emitter(queryChanged);
@@ -419,6 +540,12 @@ bus.on(refreshed, async (_payload, ctx) => {
   const items = await api.search(ctx.query.get(), { signal: ctx.signal });
   console.log(items.length);
 });
+```
+
+```jsx
+// SearchBox.jsx
+import { query } from "./query";
+import { useValue } from "./value-store";
 
 // any number of components read and write the same value
 export function SearchBox() {
@@ -431,16 +558,31 @@ export function SearchBox() {
 
 With Nanostores, Jotai or Zustand the value already lives outside React and has a subscription. Connect it to the bus once, as in [Nanostores](#nanostores), and read it in components with the library's own hook:
 
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("query/changed");
+```
+
 ```jsx
-// search-atom.jsx
+// SearchBox.jsx
 import { atom } from "nanostores";
 import { useStore } from "@nanostores/react";
-import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
 const $query = atom("");
-const queryChanged = createAction("query/changed");
 
 // listen, not subscribe: listen skips the call with the current value at start
 $query.listen(bus.emitter(queryChanged));
@@ -455,16 +597,28 @@ export function SearchBox() {
 
 React may run a reducer more than once for one dispatch (twice in StrictMode), so a `bus.emit` inside it fires twice. Dispatch to the reducer first, then emit, from one helper. Or keep the state in a reducer and pass it to `useEmitter` like any other value.
 
-```jsx
-// search-reducer.jsx
-import { useReducer } from "react";
+<!-- docs-check: new -->
+
+```js
+// bus.js
 import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: created once
+```
+
+```js
+// search.js
 import { createAction } from "nanoeffects/actions";
 
-const bus = createBus(); // the bus: created once
+export const queryChanged = createAction("query/changed");
+export const queryCleared = createAction("query/cleared");
+```
 
-const queryChanged = createAction("query/changed");
-const queryCleared = createAction("query/cleared");
+```jsx
+// Search.jsx
+import { useReducer } from "react";
+import { bus } from "./bus";
+import { queryChanged, queryCleared } from "./search";
 
 function reducer(state, action) {
   if (queryChanged.match(action)) {
@@ -504,8 +658,8 @@ The stores above call back only when the value changed, so the emitter does not
 
 ### Stop watching a store
 
-Stop both directions with what the calls returned: `stopQuery` from the store and `stopResults` from `bus.on`. Call them yourself, or hand them over: `onAbort(ctx, stopQuery)` inside a task, or `m.signal.addEventListener("abort", stopQuery)` in a module.
+`connect.js` keeps the function that `onQueryChanged` returned (`stopQuery`). Call it yourself, or hand it over: `onAbort(ctx, stopQuery)` inside a task, or `m.signal.addEventListener("abort", stopQuery)` in a module. To stop the other direction, remove the listener of `searchLoaded` with `bus.off(searchLoaded, handler)`, or register it in a module, which removes it on unmount.
 
-### Give the store to every handler
+### Change the store from any handler
 
-Instead of a listener per store, give the store to all tasks with `createBus({ context: { store } })` ([Context fields](context.md)) and change it from any handler (`setState`, a MobX action, a Pinia store). The same rule holds: write the field you do not watch. For a MobX `flow`, `onAbort(ctx, () => promise.cancel())` cancels it with the task.
+A handler gets the store from `ctx.store` and calls a mutation, whatever it handles: not only the result of a search. The same rule holds: write the field you do not watch. For a MobX `flow`, `onAbort(ctx, () => promise.cancel())` cancels it with the task.