nanoeffects 0.3.0 → 0.5.0

package/docs/stores.md

@@ -1,48 +1,511 @@
-# Redux, Zustand, MobX
+# Connect Redux, Zustand, MobX, or Pinia
 
-## Redux
+Use this page when you **already have a store** and want async work with cancellation and policies next to it. It is not a reason to pick Redux (or any store).
 
-`createEffectsMiddleware()` from `nanoeffects/redux` gives you a bus and the Redux middleware that feeds it: the effects of an app in one place, without sagas. Every action goes to the bus after the reducers have handled it, so a handler that reads the store sees the new state, and every task gets `ctx.store` (`dispatch` and `getState`).
+If you do not have a store yet, use `createBus` from the [Guide](guide.md).
 
-```ts
-type Events = { userRequested: string } & WithContext<{ store: ReduxStoreApi<RootState> }>;
+## On this page
+
+- [Wire Redux Toolkit to a bus](#wire-redux-toolkit-to-a-bus)
+- [Emit from a state manager](#emit-from-a-state-manager)
+  - [Nanostores](#nanostores)
+  - [MobX](#mobx)
+  - [Valtio](#valtio)
+  - [Jotai](#jotai)
+  - [Zustand](#zustand)
+  - [Pinia](#pinia)
+  - [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)
+
+## Wire Redux Toolkit to a bus
+
+Redux’s `dispatch` → reducers updates **state**. It does not give you first-class **tasks** (abort in-flight work, `latest` / `debounce` / `queue`, `retry` / `timeout`). People usually reach for thunks, RTK listener middleware, or sagas for that.
+
+`createEffectsMiddleware(bus)` does the same job: after the reducer runs, the action also hits the nanoeffects bus you pass to it. Keep RTK for state; use policies and effects for async.
+
+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";
+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");
+
+const bus = createBus(); // the bus of your app; it can exist before the store
 
-const effects = createEffectsMiddleware<Events>();
+// createEffectsMiddleware — actions reach the bus after reducers; tasks get ctx.store
+const effects = createEffectsMiddleware(bus);
 
 const store = configureStore({
   reducer,
-  middleware: (getDefault) => getDefault().concat(effects.middleware),
+  middleware: (getDefault) => getDefault().concat(effects),
 });
 
-effects.bus.on(userRequested, latest(async (id, { store, signal }) => {
-  store.dispatch(userLoaded(await fetchUser(id, { signal })));
-}));
+// latest — a newer run aborts the older one
+bus.on(
+  userRequested,
+  latest(async (id, { store, signal }) => {
+    const user = await fetchUser(id, { signal });
+    store.dispatch(userLoaded(user));
+  }),
+);
 ```
 
-It looks after what is easy to get wrong:
+String event names (`"user/requested"`) work the same. Use your usual RTK actions (`createSlice` / `createAction`). nanoeffects adds the middleware and policies; it does not replace RTK actions.
 
-- **A handler does not loop on its own action.** An action that a handler dispatches through `ctx.store` and that has the type the handler works on does not go back to the bus. The action is not marked or changed: the middleware remembers which task dispatched it. Other handlers of that type do not get it either. Longer cycles, `a` to `b` to `a`, are yours to avoid.
-- **A failing handler does not break `dispatch`.** Errors go to `onError` (default `console.error`), as in Redux Toolkit listeners. Reducers still throw to the caller.
-- **The store gets to the tasks by itself**, though the bus is made before the store: `ctx.store` appears when the middleware is added.
+### What the middleware guarantees
 
-Options are those of `createBus` (except `context`, which adds fields next to `store`) and `filter`, which keeps the actions it rejects away from the bus. Values that are not plain actions (thunks) go through untouched. Nothing here depends on Redux.
+- **No self-loop.** An action that a handler dispatches through `ctx.store` and that has the type the handler works on does not go back to the bus. Other handlers of that type do not get it either. Longer cycles (`a` → `b` → `a`) are yours to avoid.
+- **A failing handler does not break `dispatch`.** With `onError` on the bus, the bus isolates the handlers. Without it the error goes to `console.error`, as in RTK listeners. Reducers still throw to the caller.
+- **`store` reaches tasks when the middleware is installed**, even though the bus is created before `configureStore`.
 
-## Zustand, MobX and other stores
+The only option is `filter`, which keeps rejected actions away from the bus. Options of the bus (`onError`, `context`, `trace`) go to `createBus`. Use one bus for one store. Values that are not plain actions (thunks) go through untouched. Nothing here depends on the `redux` package at runtime.
 
-No adapter is needed: a store tells about its changes, and `bus.emit` is a call.
+### Type `ctx.store` (optional)
+
+Only if you want TypeScript to know `store` on handlers. **Skip this in JavaScript** — the middleware already puts `store` on the task at runtime. These lines do not connect the store across the app.
 
 ```ts
-// Zustand
-const stop = store.subscribe((state, previous) => {
-  if (state.user !== previous.user) bus.emit(userChanged, state.user);
+import { createBus, type WithContext } from "nanoeffects";
+import {
+  createEffectsMiddleware,
+  type ReduxStoreApi,
+} from "nanoeffects/redux";
+
+// RootState — your Redux state shape (for getState)
+type RootState = { user: string | null };
+
+// Events — event name → payload for this bus
+// WithContext — checker-only: handlers also have ctx.store
+type Events = {
+  "user/requested": string;
+} & WithContext<{ store: ReduxStoreApi<RootState> }>;
+
+const bus = createBus<Events>(); // the event map types ctx.store
+const effects = createEffectsMiddleware(bus);
+```
+
+## Emit from a state manager
+
+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 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.
+
+```js
+// search-bus.js
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { debounce, latest } from "nanoeffects/policies";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter; returns the same bus
+
+// 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);
+
+// debounce — wait 300 ms of quiet; latest — abort the search of the previous query
+bus.on(
+  queryChanged,
+  debounce(
+    300,
+    latest(async (query, ctx) => {
+      // api — your client; ctx.signal lets latest cancel the request itself
+      const items = await api.search(query, { signal: ctx.signal });
+      ctx.emit(searchLoaded(items)); // report the result as an event
+    }),
+  ),
+);
+```
+
+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`.
+
+```js
+import { atom } from "nanostores";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+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);
+});
+```
+
+### MobX
+
+`reaction` watches an expression and calls back with its value. Change observables inside `runInAction`.
+
+```js
+import { observable, reaction, runInAction } from "mobx";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+const search = observable({ query: "", results: [] });
+
+// store → bus: reaction watches the expression and calls back with its value
+const stopQuery = reaction(() => search.query, emitQueryChanged);
+
+// bus → store: bus.on returns the function that removes this listener
+const stopResults = bus.on(searchLoaded, (items) => {
+  runInAction(() => {
+    search.results = items;
+  });
+});
+```
+
+### Valtio
+
+`subscribeKey` watches one field of a proxy state. Assign to the proxy to change it.
+
+```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;
+});
+```
+
+### Jotai
+
+`sub` gives no value, so read it yourself. Write with `store.set`.
+
+```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);
+});
+```
+
+### 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.
+
+```js
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+const useSearchStore = create(
+  subscribeWithSelector(() => ({ query: "", results: [] })),
+);
+
+// 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 });
+});
+```
+
+### 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.
+
+```js
+import { watch } from "vue";
+import { defineStore } from "pinia";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+// defineStore — Pinia: the state of one store
+const useSearch = defineStore("search", {
+  state: () => ({ query: "", results: [] }),
 });
 
-// MobX
-const stop = reaction(() => store.user, (user) => bus.emit(userChanged, user));
+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;
+});
+```
+
+### React: sharing a value across components
+
+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 |
+| --- | --- |
+| A Context provider with `useState` | Only components read it. Plain React, one `useEmitter` call. |
+| A small store on `useSyncExternalStore` | A bus handler, a test or a timer must read it too. |
+| An atom of a store library | You already use Nanostores, Jotai and the like. |
 
-bus.on(userChanged, latest((user, { signal }) => sync(user, { signal })));
+#### Plain React: Context and `useEmitter`
+
+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:
+
+```js
+// react-search-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`
+
+export const queryChanged = createAction("query/changed");
+export const searchLoaded = createAction("search/loaded");
+
+// debounce — wait 300 ms of quiet; latest — a newer query aborts the older request
+bus.on(
+  queryChanged,
+  debounce(
+    300,
+    latest(async (query, ctx) => {
+      const items = await api.search(query, { signal: ctx.signal });
+      ctx.emit(searchLoaded(items)); // the result goes back to the bus as an event
+    }),
+  ),
+);
 ```
 
-Stop watching with what the store returned: `onAbort(ctx, stop)` inside a task, or `m.signal.addEventListener("abort", stop)` in a module.
+Then the provider. It holds the state, calls `useEmitter` once, and listens for the result. Every component below it only reads the context:
+
+```jsx
+// SearchProvider.jsx
+import { createContext, useContext, useEffect, useState } from "react";
+import { bus, queryChanged, searchLoaded, useEmitter } from "./react-search-bus";
+
+const SearchContext = createContext(null);
+
+export function SearchProvider({ children }) {
+  const [query, setQuery] = useState("");
+  const [items, setItems] = useState([]);
+
+  // React → bus: emits queryChanged(query) after every change of query, not on mount
+  useEmitter(queryChanged, query);
+
+  // bus → React: bus.on returns the unsubscribe function, which the effect returns
+  useEffect(() => bus.on(searchLoaded, setItems), []);
+
+  return (
+    <SearchContext.Provider value={{ query, setQuery, items }}>
+      {children}
+    </SearchContext.Provider>
+  );
+}
+
+export const useSearch = () => useContext(SearchContext);
+```
+
+```jsx
+// Search.jsx
+import { useSearch } from "./SearchProvider";
+
+// any number of components can read the same value
+export function SearchBox() {
+  const { query, setQuery } = useSearch();
+  return <input value={query} onChange={(event) => setQuery(event.target.value)} />;
+}
+
+export function Results() {
+  const { items } = useSearch();
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Two limits to know:
+
+- **All consumers re-render** on any change of the context value. Split it into two contexts (`query` and `items`) if that is slow.
+- **A new object counts as a change.** For a value that is rebuilt with the same content, pass a third argument that says when two values are the same: `useEmitter(profileChanged, profile, (previous, next) => previous.id === next.id)`.
+
+`useEmitter` emits after the render, not at the moment of `setQuery`. To emit on every call, even with the same value, call an emitter from the event handler (`bus.emitter(action)`, see [Zustand](#zustand)) instead.
+
+#### A value that a handler must read
+
+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`:
+
+```jsx
+// value-store.js
+import { useSyncExternalStore } from "react";
+
+export function createValue(initial) {
+  let value = initial;
+  const listeners = new Set();
+
+  return {
+    get: () => value,
+    set(next) {
+      if (Object.is(next, value)) {
+        return; // no change, no notification: this also stops loops
+      }
+      value = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+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";
+
+const query = createValue("");
+
+// emitterPlugin adds bus.emitter; contextPlugin puts `query` on every task as ctx.query
+const bus = createBus().use(emitterPlugin()).use(contextPlugin({ query }));
+
+const queryChanged = createAction("query/changed");
+const refreshed = createAction("search/refreshed");
+
+// store → bus: bus.emitter turns the action into a callback; one place, any number of setters
+const emitQueryChanged = bus.emitter(queryChanged);
+query.subscribe(() => emitQueryChanged(query.get()));
+
+// the handler reads the current value from ctx, whoever changed it
+bus.on(refreshed, async (_payload, ctx) => {
+  const items = await api.search(ctx.query.get(), { signal: ctx.signal });
+  console.log(items.length);
+});
+
+// any number of components read and write the same value
+export function SearchBox() {
+  const text = useValue(query);
+  return <input value={text} onChange={(event) => query.set(event.target.value)} />;
+}
+```
+
+#### A store library
+
+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:
+
+```jsx
+// search-atom.jsx
+import { atom } from "nanostores";
+import { useStore } from "@nanostores/react";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+
+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));
+
+export function SearchBox() {
+  const query = useStore($query); // the hook of Nanostores; it re-renders on every change
+  return <input value={query} onChange={(event) => $query.set(event.target.value)} />;
+}
+```
+
+#### Do not emit inside a `useReducer` reducer
+
+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";
+import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+
+const bus = createBus(); // the bus: created once
+
+const queryChanged = createAction("query/changed");
+const queryCleared = createAction("query/cleared");
+
+function reducer(state, action) {
+  if (queryChanged.match(action)) {
+    return action.payload;
+  }
+  if (queryCleared.match(action)) {
+    return "";
+  }
+  return state;
+}
+
+export function Search() {
+  const [query, dispatch] = useReducer(reducer, "");
+
+  // send: the reducer first, then the bus (bus.emit accepts an action)
+  function send(action) {
+    dispatch(action);
+    bus.emit(action);
+  }
+
+  return (
+    <div>
+      <input value={query} onChange={(event) => send(queryChanged(event.target.value))} />
+      <button type="button" onClick={() => send(queryCleared())}>
+        Clear
+      </button>
+    </div>
+  );
+}
+```
+
+A plain `dispatch` skips the bus, so call `send` everywhere.
+
+### Callbacks on every change
+
+The stores above call back only when the value changed, so the emitter does not compare values. For a store that calls back on every change, select a smaller value first, as Zustand does above.
+
+### 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.
+
+### Give the store to every handler
 
-The other way, give the store to the tasks, `createBus({ context: { store } })`, and change it from a handler: `setState` for Zustand, an action of the MobX store (it wraps `runInAction`). A handler that changes the value it was started by emits the event again, so watch the smallest part of the state. For a MobX `flow`, `onAbort(ctx, () => promise.cancel())` cancels it with the task.
+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.