nanoeffects 0.4.0 → 0.5.0

package/dist/react.d.ts

@@ -0,0 +1,50 @@
+import { D as EventKey, _ as Bus, o as EventMap, r as FreeActionCreator, t as ActionCreator } from "./action-creator-DOWcbXpy.js";
+//#region src/react/plugin.d.ts
+/** What `reactPlugin` adds to the bus. */
+/** Tells whether two values are the same: `Object.is` unless the caller gives another. */
+type Equals<V> = (previous: V, next: V) => boolean;
+type ReactApi<E extends EventMap> = {
+  /**
+   * A React hook: after a render commits with a `value` that differs from the
+   * previous one (`Object.is`, or the `equals` you pass), emits `event` with it. It does not emit on mount,
+   * not twice under StrictMode, and not for an equal value. Changes before one
+   * commit emit once, with the last value. The method does not read `this`, so
+   * `export const { useEmitter } = bus` gives a free hook.
+   */
+  useEmitter: {
+    <K extends EventKey<E>>(event: K, value: E[K], equals?: Equals<E[K]>): void;
+    /** A creator without a payload type: the payload comes from the event map. */
+    <K extends EventKey<E>>(creator: FreeActionCreator<K>, value: E[K], equals?: Equals<E[K]>): void;
+    <P, T extends string>(creator: ActionCreator<P, T>, value: P, equals?: Equals<P>): void;
+  };
+};
+/**
+ * Adds `bus.useEmitter(event, value)`: a hook that tells the bus when a value of
+ * a component changes, without the traps of `useEffect(() => emit(value), [value])`
+ * (an emit on mount, two on mount under StrictMode, a new `emit` re-running it).
+ * Pass `equals` as the third argument for values that `Object.is` tells apart
+ * although they are the same, such as a new object with the same fields.
+ * Needs `react` 18 or newer. Returns the same bus.
+ *
+ * @example
+ * ```tsx
+ * import { createBus } from "nanoeffects";
+ * import { createAction } from "nanoeffects/actions";
+ * import { reactPlugin } from "nanoeffects/react";
+ *
+ * export const bus = createBus().use(reactPlugin());
+ * export const { useEmitter } = bus; // a free hook
+ *
+ * const nameChanged = createAction<string>("name/changed");
+ * bus.on(nameChanged, (name) => console.log(name));
+ *
+ * const Profile = () => {
+ *   const [name, setName] = useState("Adam");
+ *   useEmitter(nameChanged, name); // nameChanged("…") on every change of name
+ *   return <input value={name} onChange={(event) => setName(event.target.value)} />;
+ * };
+ * ```
+ */
+export declare const reactPlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus<E> & ReactApi<E>;
+//#endregion
+export type { ReactApi };

package/dist/react.js

@@ -0,0 +1 @@
+import{useEffect as e,useRef as t}from"react";const n=()=>n=>{function r(r,i,a){let o=t(i),s=t({event:r,equals:a});e(()=>{s.current={event:r,equals:a}}),e(()=>{let{event:e,equals:t}=s.current,r=t??Object.is,a=o.current;if(r(a,i))return;o.current=i;let c=typeof e==`function`?e(i):{type:e,payload:i};n.emit(c)},[i])}return Object.assign(n,{useEmitter:r})};export{n as reactPlugin};

package/dist/redux.d.ts

@@ -1,4 +1,4 @@
-import { _ as Bus, o as EventMap, v as BusOptions } from "./action-creator-D48fp13T.js";
+import { _ as Bus, o as EventMap } from "./action-creator-DOWcbXpy.js";
 //#region src/store/redux/middleware.d.ts
 /** What Redux passes through a middleware: an action is a plain object with a `type`. */
 type ReduxAction = {
@@ -8,6 +8,8 @@ type ReduxAction = {
 type NanoeffectsMiddlewareOptions = {
   /** Return `false` for the actions that the bus should not get. Default: all of them. */
   filter?: (action: ReduxAction) => boolean;
+  /** Receives an error that `emit` throws, so `dispatch` does not. Default: the error is thrown. */
+  onError?: (error: unknown, action: ReduxAction) => void;
 };
 //#endregion
 //#region src/store/redux/effects.d.ts
@@ -19,48 +21,44 @@ type ReduxStoreApi<State = unknown> = {
   }) => unknown;
   getState: () => State;
 };
-type EffectsMiddlewareOptions<E extends EventMap> = Omit<BusOptions<E>, "context"> & NanoeffectsMiddlewareOptions & {
-  /** More fields for the context of every task, next to `store`. */
-  context?: object;
-};
+type EffectsMiddlewareOptions = Pick<NanoeffectsMiddlewareOptions, "filter">;
 /**
- * Creates a bus and the Redux middleware that feeds it: the effects of an app
- * in one place, without sagas. Every task gets `ctx.store`, the `dispatch` and
- * `getState` of the store, as soon as the middleware is added to it. Type it
- * in the event map:
+ * Makes the Redux middleware that feeds a bus you already have: the actions of
+ * the store reach its handlers, and every task gets `ctx.store`, the `dispatch`
+ * and `getState` of the store, as soon as Redux has installed the middleware.
+ * Type it in the event map of the bus:
  *
  * ```ts
  * type Events = { userRequested: string } & WithContext<{ store: ReduxStoreApi<RootState> }>;
  * ```
  *
- * Two things are looked after for you:
+ * Use one bus for one store: a second store would replace the first in the
+ * contexts. Two things are looked after for you:
  *
  * - **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 (a handler of `a` that dispatches `a`). 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`,
- *   by default to `console.error`, as in Redux Toolkit listeners; reducers
- *   still throw to the caller.
+ * - **A failing handler does not break `dispatch`.** With `onError` on the bus
+ *   the bus isolates the handlers. Without it the error is written to
+ *   `console.error`, as in Redux Toolkit listeners. Reducers still throw to
+ *   the caller.
  *
  * @example
  * ```ts
- * const effects = createEffectsMiddleware<Events>();
+ * const bus = createBus<Events>();
  *
  * const store = configureStore({
  *   reducer,
- *   middleware: (getDefault) => getDefault().concat(effects.middleware),
+ *   middleware: (getDefault) => getDefault().concat(createEffectsMiddleware(bus)),
  * });
  *
- * effects.bus.on(userRequested, latest(async (id, { store, signal }) => {
+ * bus.on(userRequested, latest(async (id, { store, signal }) => {
  *   store.dispatch(userLoaded(await fetchUser(id, { signal })));
  * }));
  * ```
  */
-export declare const createEffectsMiddleware: <E extends EventMap = EventMap>(options?: EffectsMiddlewareOptions<E>) => {
-  bus: Bus<E>;
-  middleware: (storeApi: ReduxStoreApi) => (next: (action: unknown) => unknown) => (action: unknown) => unknown;
-};
+export declare const createEffectsMiddleware: <E extends EventMap>(bus: Bus<E>, options?: EffectsMiddlewareOptions) => (storeApi: ReduxStoreApi) => (next: (action: unknown) => unknown) => (action: unknown) => unknown;
 //#endregion
 export type { EffectsMiddlewareOptions, ReduxStoreApi };

package/dist/redux.js

@@ -1 +1 @@
-import{n as e}from"./onAbort-BgMfspK4.js";import{n as t}from"./bus-Cho463Sq.js";const n=e=>typeof e==`object`&&!!e&&`type`in e,r=(e,t={})=>{let r=e.emit;return()=>e=>i=>{let a=e(i);return n(i)&&(t.filter?.(i)??!0)&&r(i),a}},i=(n={})=>{let{filter:i,context:a,onError:o,...s}=n,c,l=/* @__PURE__ */ new WeakMap,u=e=>({...a,store:c&&{getState:c.getState,dispatch:t=>{typeof t==`object`&&t&&l.set(t,e.type);let n=t;return c?.dispatch(n)}}}),d=t({...s,onError:o??((t,{type:n})=>{e(`handler of "${n}" failed`,t)}),context:u}),f=r(d,{filter:e=>l.get(e)!==e.type&&(i?.(e)??!0)});return{bus:d,middleware:e=>(c=e,f())}};export{i as createEffectsMiddleware};
+const e=e=>typeof e==`object`&&!!e&&`type`in e,t=(t,n={})=>{let r=t.emit,i=e=>{try{r(e)}catch(t){if(!n.onError)throw t;n.onError(t,e)}};return()=>t=>r=>{let a=t(r);return e(r)&&(n.filter?.(r)??!0)&&i(r),a}},n=(e,n={})=>{let r,i=/* @__PURE__ */ new WeakMap,a=e.addContext;e.addContext=e=>{a?.(e);let t=r;if(!t)return;let{type:n}=e;Object.assign(e,{store:{getState:t.getState,dispatch:e=>{typeof e==`object`&&e&&i.set(e,n);let r=e;return t.dispatch(r)}}})};let o=t(e,{filter:e=>i.get(e)!==e.type&&(n.filter?.(e)??!0),onError:(e,{type:t})=>{globalThis.console?.error(`[nanoeffects] handler of "${t}" failed`,e)}});return e=>(r=e,o())};export{n as createEffectsMiddleware};

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-import { R as Tracer, d as Trace, f as TraceEvent, p as TraceLogger } from "./action-creator-D48fp13T.js";
+import { d as Trace, f as TraceEvent, p as TraceLogger, z as Tracer } from "./action-creator-DOWcbXpy.js";
 //#region src/trace/console.d.ts
 type ConsoleLoggerOptions = {
   /** Defaults to `globalThis.console`. */

package/docs/README.md

@@ -14,14 +14,20 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 | SPA with async UI | [Policies](policies.md), [Guide § latest](guide.md#3-abort-the-previous-run-with-latest) |
 | Unreliable network / long flows | [Effects](effects.md) — one helper per job, then the rest as reference |
 | Domain logic off the UI | [Actions, commands, modules](actions.md) |
-| Already on Redux / Zustand / MobX | [Stores](stores.md) |
+| Already on Redux / Zustand / MobX / Pinia | [Stores](stores.md) |
+| A React form with async checks | [Build a sign-up form in React](react.md) |
+| Moving from redux-saga | [Coming from redux-saga](migrating-from-saga.md) |
+| Using RxJS | [Use nanoeffects next to RxJS](migrating-from-rxjs.md) |
+| Moving from Effector | [Coming from Effector](migrating-from-effector.md) |
 
 ## Reference
 
 - [Policies](policies.md) — `latest`, `leading`, `debounce`, `throttle`, `queue`, `key`
 - [Effects and cancellation](effects.md) — `retry`, `timeout`, `poll`, `take`, `all`, …
 - [Actions, commands, jobs and modules](actions.md)
+- [Sign-up form in React](react.md) — one form: races, double submit, retry
 - [Context fields](context.md) — store or client on every task
+- [TypeScript in many files](typescript.md) — keep the types of the bus in commands and modules
 - [Errors and unheard events](errors.md)
 - [Package entries](package.md) — which import holds what
 - [Tracing](tracing.md) — loggers, Redux DevTools, `notrace`

package/docs/actions.md

@@ -109,7 +109,7 @@ The registry lives in `nanoeffects/actions`, so a bus without one carries none o
 
 **When.** You want one mount / one unmount for that domain. Skip modules while a few top-level `bus.on` calls are enough.
 
-`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, and `commands`.
+`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, `commands`, and `createModule`: the same as `createModule` below, with the context fields of the bus typed (see [TypeScript](typescript.md)).
 
 ```js
 import { createBus } from "nanoeffects";

package/docs/context.md

@@ -19,14 +19,36 @@ That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`
 
 Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may be a function `(task) => fields` when the value depends on the task.
 
+To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
+
 ## Type the fields (optional)
 
-`WithContext` on the event map only tells TypeScript that handlers of **this** bus have those fields. It does not wire anything at runtime and is not app-wide — another bus can have different fields or none.
+In TypeScript, `contextPlugin` puts the fields on every task of **this** bus and takes their types from the value you pass. The event map holds only events. It does not wire anything across the app — another bus can have different fields or none.
 
 ```ts
-import { createBus, type WithContext } from "nanoeffects";
+import { contextPlugin, createBus } from "nanoeffects";
 
 // Events — event name → payload
+type Events = { save: Draft };
+
+// contextPlugin — every task gets ctx.store; the type is the type of `store`
+const bus = createBus<Events>().use(contextPlugin({ store }));
+
+bus.on("save", (draft, { store }) => store.put(draft));
+```
+
+- A function `(task) => fields` makes the fields per task. It gets `{ type, payload }`.
+- Several `contextPlugin` calls, `effectsPlugin` and the `context` option of `createBus` all add their fields to the same context.
+- A name that the bus already has is a type error. The fields of the library (`signal`, `emit`, `run`, …) win at runtime, and a field that the context already has is not replaced.
+- The plugin returns the same bus, so keep the result of the chain: `const bus = createBus().use(contextPlugin({ store }))`.
+
+### Name the fields in the event map instead
+
+`createBus<Events>({ context: { store } })` also types the fields, but through the event map: `WithContext` is checker-only and says which fields the handlers of this bus have. Use it when you cannot call `use`, for example for the bus that `createEffectsMiddleware` makes.
+
+```ts
+import { createBus, type WithContext } from "nanoeffects";
+
 // WithContext — checker-only: handlers also have ctx.store
 type Events = { save: Draft } & WithContext<{ store: Store }>;
 

package/docs/effects.md

@@ -84,16 +84,93 @@ Each attempt or call of a wrapper gets its own child context. Abort of the calle
 - `fn` gets the call number from `0`.
 - An error from `fn` stops polling and rejects. An abort ends it normally and clears the timer.
 
-A pause can be a function wherever a time is given (backoff or jitter):
+A pause can be a function wherever a time is given. For retries with a cap and jitter, see [Back off between retries](#back-off-between-retries):
 
 ```js
-retry(ctx, load, { times: 5, delay: (attempt) => 2 ** attempt * 100 }); // 200, 400, 800, …
-poll(ctx, refresh, (call) => Math.min(1000 * 2 ** call, 60_000)); // slows to once a minute
-await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
+import { createBus } from "nanoeffects";
+import { delay, poll, retry } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("sync", async (_, ctx) => {
+  retry(ctx, load, { times: 5, delay: (attempt) => 2 ** attempt * 100 }); // 200, 400, 800, …
+  poll(ctx, refresh, (call) => Math.min(1000 * 2 ** call, 60_000)); // slows to once a minute
+  await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
+});
 ```
 
 All three are traced: the effect is a group (`retry`, `timeout`, `poll`) and each attempt or call is a `run` child.
 
+## Back off between retries
+
+Use this when a server or network fails under load. Retrying at once, or at the same fixed pause, sends every client back at the same moment and can keep the server down. Make the pause grow with each attempt, and add jitter so clients spread out.
+
+The shortest form is a `delay` function. It needs no import:
+
+```js
+import { retry } from "nanoeffects/effects";
+
+const loadWithRetry = retry(loadUser, {
+  times: 5,
+  delay: (attempt) => 2 ** attempt * 100, // 200, 400, 800, 1600 ms
+});
+```
+
+When you also want a cap and jitter, build the function with `backoff`:
+
+```js
+import { backoff, retry } from "nanoeffects/effects";
+
+const loadWithRetry = retry(loadUser, {
+  times: 5,
+  // backoff — pause 200, 400, 800, … ms, never over 5 s, a random part of it
+  delay: backoff({ base: 200, max: 5000, jitter: true }),
+});
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `base` | pause before the second attempt, in ms (default `100`) |
+| `factor` | each pause is this many times longer (default `2`) |
+| `max` | longest pause, in ms (default none) |
+| `jitter` | `true` picks a random pause from 0 up to the computed one (default `false`) |
+
+- With `jitter: true` a pause can be close to 0, so treat `base` as a scale, not a minimum.
+- `retry` counts attempts from 1. `poll` counts calls from 0, so with `poll` the first pause is `base / factor`.
+- The result is a plain function `(attempt) => ms`, so it also fits `delay(ctx, …)`.
+
+## Put selected effects on `ctx`
+
+If handlers call the same helpers often, put them on the task once. A handler then destructures them like `signal`, with no `ctx` argument. Only the effects you pass are imported, so the rest stay out of the bundle ([package entries](package.md)).
+
+```js
+import { createBus } from "nanoeffects";
+import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
+
+// effectsPlugin — add race, all and delay to the context of every task; returns the same bus
+const bus = createBus().use(effectsPlugin({ race, all, delay }));
+
+bus.on("load", async (id, { race, all, delay }) => {
+  // race — same as race(ctx, …)
+  const result = await race({
+    data: ({ signal }) => fetchData(id, { signal }),
+    timeout: () => delay(5000), // delay — same as delay(ctx, 5000)
+  });
+  if ("timeout" in result) throw new Error("timed out");
+
+  // all — same as all(ctx, …)
+  const { user, posts } = await all({
+    user: ({ signal }) => fetchUser(id, { signal }),
+    posts: ({ signal }) => fetchPosts(id, { signal }),
+  });
+});
+```
+
+- Supported: `race`, `all`, `allSettled`, `take`, `delay`. The key is the effect name.
+- `retry`, `timeout` and `poll` are not supported: bound to the task they would look like their handler wrappers.
+- Fields from `createBus({ context })` stay. TypeScript rejects an effect whose name is already a context field of the bus, including one added by an earlier `effectsPlugin`.
+- Free forms keep working: `race(ctx, …)`.
+
 ## Tie a promise to the task signal
 
 `delay(ctx, ms)` waits and rejects on abort (`ms` can be a function).
@@ -179,7 +256,7 @@ bus.on("login", async (user, ctx) => {
 ```
 
 - Sees only events emitted after the call, takes one, and unsubscribes.
-- `options.predicate` skips payloads it rejects.
+- `options.predicate` skips payloads it rejects. In TypeScript, a type guard (`(payload): payload is Admin`) narrows the type of the result.
 - `options.signal` stops the wait (how a `race` or `timeout` starter cancels it).
 - On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.
 

package/docs/guide.md

@@ -294,6 +294,8 @@ Modules also make [hot reload](hmr.md) work. Full API in [Actions](actions.md);
 Describe events once when you want `on` / `emit` checked. An event without data is `void`. Skip this while you are learning the bus.
 
 ```ts
+import { createBus } from "nanoeffects";
+
 // Events — event name → payload for this bus (checker only)
 type Events = {
   greet: string;

package/docs/migrating-from-effector.md

@@ -0,0 +1,293 @@
+# Coming from Effector
+
+Read this page if your project uses Effector and you want to know where nanoeffects fits. They overlap in one place: events that start effects. Effector also holds state; nanoeffects does not. It maps the names, shows one effect both ways, and lists what has no equivalent.
+
+## Split the work
+
+| Job | Use |
+| --- | --- |
+| Hold state (`createStore`, `combine`, `restore`) | Effector, or any store: [Stores](stores.md) |
+| Derive state from events (`.on`, `sample` into a store) | Effector, or any store |
+| Run a request when an event happens, cancel, retry, time out, trace | nanoeffects |
+
+nanoeffects has no store. `createStore` can be replaced by any store you like, for example Zustand: a store and its `set` do the job of `createStore` and `.on`. [Stores](stores.md) shows how each of Zustand, Redux, MobX, Jotai and others calls the bus. If you keep Effector, use nanoeffects only for the effects that `createEffect` runs with little control over overlapping calls.
+
+## Find the equivalent
+
+| Effector | nanoeffects |
+| -------- | ----------- |
+| `createEvent()` | an event name on the bus, or [`createAction`](actions.md) |
+| event call `loaded(user)` | `bus.emit("loaded", user)` |
+| `createEffect(handler)` | a handler: `bus.on(event, handler)` |
+| effect with `done` and `fail` | [`createJob`](actions.md): emits the success and fail actions |
+| `effect.pending` | not provided: keep a flag in your store, or read it from [Tracing](tracing.md) |
+| `sample({ clock, fn, target })` | `bus.on(clock, handler)` and `ctx.emit(target, …)` |
+| `sample({ source: $store, clock })` | read the store from a [context field](context.md) in the handler |
+| `sample({ filter })` | an `if` in the handler |
+| `debounce`, `throttle` from patronum | [`debounce`, `throttle`](policies.md) (same rules as lodash, checked in tests) |
+| take only the last effect call | [`latest`](policies.md) |
+| `attach` | a [context field](context.md): the handler reads it from `ctx` |
+| `fork()` and scope | one `createBus()` per scope |
+| `createStore`, `combine`, `restore` | any store, such as Zustand, Redux, MobX or Jotai: see [Stores](stores.md) |
+| `watch`, `createWatch` | `bus.on(event, handler)` |
+| `event.prepend(fn)` | a function that you write, `(event) => ({ key, value })`; the bus needs nothing |
+| `useStoreMap({ store, keys, fn })` | a selector of your store; with `useState` the component keeps the value |
+| `event.watch((e) => e.preventDefault())` | call `event.preventDefault()` in the `onSubmit` handler |
+
+## Rewrite an effect
+
+A search that runs on every query, and reacts to the result:
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+// Effector
+import { createEffect, createEvent, createStore, sample } from "effector";
+
+const queryChanged = createEvent();
+const searchFx = createEffect((query) => api.search(query));
+const $items = createStore([]).on(searchFx.doneData, (_, items) => items);
+
+sample({ clock: queryChanged, target: searchFx });
+```
+
+If the user types fast, several `searchFx` calls overlap, and the old ones are not cancelled. The same job in nanoeffects, with the old request cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer query aborts the request in flight
+const search = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("found", items);
+});
+
+bus.on("query-changed", debounce(300, search)); // debounce: run after 300 ms of quiet
+```
+
+The store (`$items`) is not here. Keep it in Effector and update it from the `found` event, or replace it with a store of your choice. The next example does that with Zustand.
+
+### Keep the state in Zustand
+
+Without Effector, something must hold `$items`. A Zustand store does it: `create` replaces `createStore`, and `setState` replaces `.on(searchFx.doneData, …)`. The handler writes the result to the store directly, so the `found` event is not needed. A component reads the store with a selector, as `useUnit($items)` did.
+
+```jsx
+// search-zustand.jsx
+import { create } from "zustand";
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+// create — Zustand: the store replaces $items
+const useSearchStore = create(() => ({ items: [] }));
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest — a newer query aborts the request in flight; debounce — wait 300 ms of quiet
+const search = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  useSearchStore.setState({ items }); // Zustand: replaces .on(searchFx.doneData, …)
+});
+
+bus.on("query-changed", debounce(300, search));
+
+export function Search() {
+  const items = useSearchStore((state) => state.items); // Zustand: a selector reads items
+
+  return (
+    <div>
+      <input onChange={(event) => bus.emit("query-changed", event.target.value)} />
+      <ul>
+        {items.map((item) => (
+          <li key={item.id}>{item.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+`bus.emit("query-changed", …)` in `onChange` does the work of calling the `queryChanged` event. To also start a task when the store changes, see [Zustand in Stores](stores.md#zustand).
+
+## Rewrite a form
+
+The form from the [Forms recipe of the Effector docs](https://effector.dev/en/recipes/react/forms/) has five parts: an event for a change of a field (`fieldUpdate`), a store for the values (`$form`), an event for the submit (`formSubmitted`), an effect that sends them (`sendFormFx`), and a `sample` that reads the store when the form is submitted. Four of them keep state or wire units together. Only the effect has a counterpart in nanoeffects.
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```jsx
+// Effector (adapted from the Effector docs)
+import { createEffect, createEvent, createStore, sample } from "effector";
+import { useStoreMap } from "effector-react";
+
+const formSubmitted = createEvent();
+const fieldUpdate = createEvent();
+
+const sendFormFx = createEffect((params) => {
+  console.log(params);
+});
+
+const $form = createStore({});
+$form.on(fieldUpdate, (form, { key, value }) => ({ ...form, [key]: value }));
+
+// sample: when the form is submitted, read $form and run the effect with it
+sample({ clock: formSubmitted, source: $form, target: sendFormFx });
+
+// prepend: turn a DOM event into the { key, value } that fieldUpdate takes
+const handleChange = fieldUpdate.prepend((event) => ({
+  key: event.target.name,
+  value: event.target.value,
+}));
+
+const Field = ({ name, type, label }) => {
+  const value = useStoreMap({
+    store: $form,
+    keys: [name],
+    fn: (values) => values[name] ?? "",
+  });
+
+  return (
+    <div>
+      {label} <input name={name} type={type} value={value} onChange={handleChange} />
+    </div>
+  );
+};
+
+const App = () => (
+  <form onSubmit={formSubmitted}>
+    <Field name="login" label="Login" />
+    <Field name="password" type="password" label="Password" />
+    <button type="submit">Submit!</button>
+  </form>
+);
+
+formSubmitted.watch((event) => {
+  event.preventDefault();
+});
+```
+
+The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus, in its own file:
+
+```js
+// form-bus.js
+import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: events and their handlers
+
+// bus.on — the job of sendFormFx: runs when the form is submitted
+bus.on("form/submitted", (values) => {
+  console.log(values);
+});
+```
+
+Then the form. `useState` does the work of `$form`, `fieldUpdate` and `prepend`; the event handler does the work of the `watch` that called `preventDefault`:
+
+```jsx
+// App.jsx
+import { useState } from "react";
+import { bus } from "./form-bus"; // the bus of the previous snippet
+
+function Field({ name, type, label, value, onChange }) {
+  return (
+    <div>
+      {label} <input name={name} type={type} value={value} onChange={onChange} />
+    </div>
+  );
+}
+
+export function App() {
+  const [form, setForm] = useState({}); // the values of the form, as $form held them
+
+  // one handler for every field, as handleChange was
+  function handleChange(event) {
+    const { name, value } = event.target;
+    setForm((current) => ({ ...current, [name]: value }));
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault(); // the page must not reload; no separate watcher is needed
+    bus.emit("form/submitted", form); // bus.emit — the values go in the event
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Field name="login" label="Login" value={form.login ?? ""} onChange={handleChange} />
+      <Field
+        name="password"
+        type="password"
+        label="Password"
+        value={form.password ?? ""}
+        onChange={handleChange}
+      />
+      <button type="submit">Submit!</button>
+    </form>
+  );
+}
+```
+
+`useStoreMap` re-renders only the field whose value changed. Here every field re-renders with the form, which is fine for a small form. If it matters, use the selector of your store (Zustand and Jotai have one).
+
+If the values live in a store outside React, give the store to the handlers with `createBus({ context: { store } })` ([Context fields](context.md)) and read it in the handler, as `sample` read `$form`.
+
+### Replace the log with a request
+
+`sendFormFx` only logs. A real sign-up sends a request, and then the double click and the network matter. `leading` drops a second submit while the first one runs, and `ctx.signal` lets the request be cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and their handlers
+
+// leading — a second submit is ignored while the request is running
+bus.on(
+  "form/submitted",
+  leading(async (values, ctx) => {
+    // api — your client; ctx.signal lets the request be cancelled
+    await api.signUp(values, { signal: ctx.signal });
+  }),
+);
+```
+
+Retrying a failed network request, and cancelling when the form closes, are in [Build a sign-up form in React](react.md).
+
+## Use both in one app
+
+Keep the Effector stores, and run the effects on the bus. A store calls the bus through `bus.emitter`, and the handler sends the result back as an event that the store listens to.
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+import { createEvent, createStore } from "effector";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+
+const queryChanged = createAction("query/changed"); // a plain action creator
+
+const found = createEvent(); // Effector: the result comes back as an event
+const $items = createStore([]).on(found, (_, items) => items);
+const $query = createStore("");
+
+// watch calls back on every change of the store; bus.emitter turns it into an emit
+$query.watch(bus.emitter(queryChanged));
+
+bus.on(
+  queryChanged,
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal });
+    found(items); // back to Effector
+  }),
+);
+```
+
+## What is different
+
+- **No state.** There is no `createStore`, `combine`, `restore`, `$store.map`. The bus holds listeners only. Take a store such as Zustand for state ([Stores](stores.md)).
+- **No `pending`.** A running task is visible through [Tracing](tracing.md), not through a store. A flag in your store set at the start and the end of the handler does the job.
+- **Cancellation is the default tool.** An Effector effect runs every call to the end. Here `latest` and `ctx.signal` stop what is no longer needed.
+- **Events are matched by name, not by identity.** An event is a string or a `createAction` creator, not a unit that you import and call. Two modules agree on the name.
+- **No graph.** `sample` and `forward` build a static graph. A bus subscribes handlers at runtime and the call order is the order of `on`.
+- **The event carries the data.** `sample({ source })` reads a store at the moment of the clock. Here the sender puts the values in the event (`bus.emit("form/submitted", form)`), or the handler reads a store from a [context field](context.md).
+- **Scopes are buses.** `fork()` becomes a `createBus()` per scope (a test, a request on the server).