nanoeffects 0.7.0 → 0.9.0

package/dist/react.d.ts

@@ -1,4 +1,5 @@
-import { B as EventMap, T as EventKey, h as Bus, r as FreeActionCreator, t as ActionCreator } from "./action-creator-Bd4TBZgl.js";
+import { B as EventMap, T as EventKey, W as Task, h as Bus, r as FreeActionCreator, t as ActionCreator } from "./action-creator-BrZF6hXc.js";
+import { t as PolicyFunction } from "./with-policy-CqUS-VWW.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. */
@@ -47,4 +48,35 @@ type ReactApi<E extends EventMap> = {
  */
 export declare const reactPlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus<E> & ReactApi<E>;
 //#endregion
+//#region src/react/use-policy.d.ts
+/**
+ * A policy (`debounce`, `throttle`, `latest`, ...) as one stable function for a
+ * component. A policy made in the body of a component is made again on every
+ * render and loses its timer; made once, it keeps the callback of the first
+ * render. This hook keeps the policy across renders and calls the `callback` of
+ * the latest render, so an inline callback sees fresh props and state.
+ *
+ * `make` gets a task that runs the callback and returns the policy built around
+ * it. It runs once, and again when an item of `deps` changes: list there what
+ * `make` reads, such as the wait time. The pending calls of the old function are
+ * cancelled then, and when the component unmounts. Needs `react` 18 or newer.
+ *
+ * @example
+ * ```tsx
+ * import { debounce } from "nanoeffects/policies";
+ * import { usePolicy } from "nanoeffects/react";
+ *
+ * const Search = ({ wait }: { wait: number }) => {
+ *   const [results, setResults] = useState([]);
+ *   const onChange = usePolicy(
+ *     async (query: string) => setResults(await search(query)), // latest render's callback
+ *     (task) => debounce(wait, task), // the policy, made once per wait
+ *     [wait],
+ *   );
+ *   return <input onChange={(event) => onChange(event.target.value)} />;
+ * };
+ * ```
+ */
+export declare const usePolicy: <P, R, S = R>(callback: Task<P, EventMap, R>, make: (task: Task<P, EventMap, R>) => Task<P, EventMap, S>, deps?: readonly unknown[]) => PolicyFunction<P, S>;
+//#endregion
 export type { ReactApi };

package/dist/react.js

@@ -1 +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};
+import{t as e}from"./with-policy-DBV9dh2F.js";import{useEffect as t,useMemo as n,useRef as r}from"react";const i=()=>e=>{function n(n,i,a){let o=r(i),s=r({event:n,equals:a});t(()=>{s.current={event:n,equals:a}}),t(()=>{let{event:t,equals:n}=s.current,r=n??Object.is,a=o.current;if(r(a,i))return;o.current=i;let c=typeof t==`function`?t(i):{type:t,payload:i};e.emit(c)},[i])}return Object.assign(e,{useEmitter:n})},a=(i,a,o=[])=>{let s=r(i);t(()=>{s.current=i});let c=n(()=>e(a((e,t)=>s.current(e,t))),o);return t(()=>()=>c.cancel(),[c]),c};export{i as reactPlugin,a as usePolicy};

package/dist/redux.d.ts

@@ -1,4 +1,4 @@
-import { B as EventMap, h as Bus } from "./action-creator-Bd4TBZgl.js";
+import { B as EventMap, h as Bus } from "./action-creator-BrZF6hXc.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 = {

package/dist/scope.d.ts

@@ -1,5 +1,5 @@
-import { B as EventMap, a as EmitScope, d as Effects, f as Signaled, h as Bus, o as Scope, u as Effect } from "./action-creator-Bd4TBZgl.js";
-import { n as Scoped } from "./types-BJ0fzV1p.js";
+import { B as EventMap, a as EmitScope, d as Effects, f as Signaled, h as Bus, o as Scope, u as Effect } from "./action-creator-BrZF6hXc.js";
+import { n as ScopeSlots, r as Scoped } from "./types-KavbvHix.js";
 //#region src/scope/effect.d.ts
 /**
  * Marks a function whose first parameter is `{ signal }` as an effect, so that
@@ -35,9 +35,8 @@ export declare function effect<A extends unknown[], R>(fn: (ctx: Signaled, ...ar
  * Fields of the library (`signal`, `emit`, `run`, …) are never replaced. Returns
  * the same bus.
  *
- * Use it after `effectsPlugin`, which assigns its effects over those of a scope
- * when it comes later, and before `modulePlugin`, which mounts its modules when
- * it is used. Without this plugin a scope is ignored.
+ * It works in any order with the other plugins. Without this plugin a scope is
+ * ignored.
  *
  * @example
  * ```ts
@@ -53,6 +52,6 @@ export declare function effect<A extends unknown[], R>(fn: (ctx: Signaled, ...ar
  * bus.emit(getUser("1"), { http: fakeHttp }); // this call only
  * ```
  */
-export declare const scopePlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus<E>;
+export declare const scopePlugin: () => <E extends EventMap>(bus: Bus<E> & ScopeSlots) => Bus<E> & ScopeSlots;
 //#endregion
 export type { Effect, Effects, EmitScope, Scope, Scoped, Signaled };

package/dist/scope.js

@@ -1 +1 @@
-import{t as e}from"./scope-key-B7l7mUS5.js";const t=/* @__PURE__ */ new WeakSet;function n(e){return t.add(e),e}const r=/* @__PURE__ */ new Set([`signal`,`abort`,`emit`,`on`,`off`,`run`,`type`,`payload`]),i=[],a=Symbol(`nanoeffects.scope.call`),o=Symbol(`nanoeffects.scope.module`),s=Symbol(`nanoeffects.scope.watched`),c=e=>e,l=e=>typeof e==`function`&&t.has(e),u=(e,t)=>(...n)=>Reflect.apply(t,null,[e,...n]),d=(e,t)=>{if(!t)return;for(let n in t)if(n!==`$effects`&&!r.has(n)){let r=t[n];e[n]=l(r)?u(e,r):r}let n=t.$effects;if(n)for(let t in n){let i=n[t];i&&!r.has(t)&&(e[t]=u(e,i))}},f=(e,t,n)=>{d(e,n);for(let n of t)d(e,n)},p=e=>typeof e==`object`&&!!e,m=e=>p(e),h=e=>(p(e)||typeof e==`function`)&&`type`in e,g=e=>h(e)?e.type:e,_=(e,t)=>p(e)&&h(e)?e.payload:t[0],v=t=>p(t)||typeof t==`function`?Reflect.get(t,e):void 0,y=(e,t)=>{let n=v(e),r=p(e)&&m(t[0])?t[0]:void 0;if(n&&r)return[n,r];let i=n??r;return i?[i]:void 0},b=()=>e=>{let t,n,r,l=e=>{let n=e.run;if(n[s])return;let r=(r,...i)=>{let s=t;t=void 0;try{return n((t,n)=>{let i=e[a];return i&&u(n,i,e[o]),r(t,n)},...i)}finally{t=s}};r[s]=!0,e.run=r},u=(e,t,n)=>{e[a]=t,n&&(e[o]=n),f(e,t,n),l(e)},d=e.addContext;e.addContext=e=>{d?.(e);let i=c(e);t&&i.type===n&&Object.is(i.payload,r)&&u(i,t,void 0)},e.applyScope=(e,t)=>{let n=c(e);u(n,n[a]??i,t)},e.fitScope=(t,n)=>typeof n==`function`?(r,i)=>(e.applyScope?.(i,t),Reflect.apply(n,null,[r,i])):n;let m=e.emit;return e.emit=(e,...i)=>{let a=y(e,i);if(!(a||t))return m(e,...i);let o=t,s=n,c=r;t=a,n=g(e),r=_(e,i);try{return p(e)?m(e):m(e,...i)}finally{t=o,n=s,r=c}},e};export{n as effect,b as scopePlugin};
+import{t as e}from"./scope-key-B7l7mUS5.js";const t=/* @__PURE__ */ new WeakSet;function n(e){return t.add(e),e}const r=/* @__PURE__ */ new Set([`signal`,`abort`,`emit`,`on`,`off`,`run`,`type`,`payload`]),i=[],a=Symbol(`nanoeffects.scope.call`),o=Symbol(`nanoeffects.scope.module`),s=Symbol(`nanoeffects.scope.watched`),c=e=>e,l=e=>typeof e==`function`&&t.has(e),u=(e,t)=>(...n)=>Reflect.apply(t,null,[e,...n]),d=(e,t)=>{if(!t)return;for(let n in t)if(n!==`$effects`&&!r.has(n)){let r=t[n];e[n]=l(r)?u(e,r):r}let n=t.$effects;if(n)for(let t in n){let i=n[t];i&&!r.has(t)&&(e[t]=u(e,i))}},f=(e,t,n)=>{d(e,n);for(let n of t)d(e,n)},p=e=>typeof e==`object`&&!!e,m=e=>p(e),h=e=>(p(e)||typeof e==`function`)&&`type`in e,g=e=>h(e)?e.type:e,_=(e,t)=>p(e)&&h(e)?e.payload:t[0],v=t=>p(t)||typeof t==`function`?Reflect.get(t,e):void 0,y=(e,t)=>{let n=v(e),r=p(e)&&m(t[0])?t[0]:void 0;if(n&&r)return[n,r];let i=n??r;return i?[i]:void 0},b=()=>e=>{let t,n,r,l=e=>{let n=e.run;if(n[s])return;let r=(r,...i)=>{let s=t;t=void 0;try{return n((t,n)=>{let i=e[a];return i&&u(n,i,e[o]),r(t,n)},...i)}finally{t=s}};r[s]=!0,e.run=r},u=(e,t,n)=>{e[a]=t,n&&(e[o]=n),f(e,t,n),l(e)},d=e.addContext;e.addContext=e=>{d?.(e);let i=c(e);t&&i.type===n&&Object.is(i.payload,r)&&u(i,t,void 0)},e.applyScope=(e,t)=>{let n=c(e);u(n,n[a]??i,t)},e.fitScope=(t,n)=>typeof n==`function`?(r,i)=>(e.applyScope?.(i,t),Reflect.apply(n,null,[r,i])):n;let p=e.emit;return e.emit=(e,...i)=>{let a=y(e,i);if(!(a||t))return p(e,...i);let o=t,s=n,c=r;t=a,n=g(e),r=_(e,i);try{return p(e,...i)}finally{t=o,n=s,r=c}},e};export{n as effect,b as scopePlugin};

package/dist/signal.d.ts

@@ -0,0 +1,51 @@
+import { B as EventMap, C as Emit, E as EventLike, a as EmitScope, c as WithScope, h as Bus, v as CommandCall } from "./action-creator-BrZF6hXc.js";
+//#region src/signal/plugin.d.ts
+/** What the second argument of `emit` takes besides the fields of a scope. */
+type SignalOption = {
+  /** Aborts the tasks that this `emit` starts, with its reason, when it aborts. */
+  signal?: AbortSignal;
+};
+/** `emit` of a bus with `signalPlugin`: the call forms take `{ signal }` as their second argument. */
+type SignalEmit<E extends EventMap> = Emit<E> & {
+  <P, R, F>(call: CommandCall<P, R> & WithScope<F>, options: SignalOption & EmitScope<E, F>): R;
+  <P, R>(call: CommandCall<P, R>, options: SignalOption & EmitScope<E>): R;
+  (event: EventLike<E>, options: SignalOption & EmitScope<E>): void;
+};
+/** A bus with `signalPlugin`: the same bus, with the `emit` that takes a signal. */
+type SignalBus<E extends EventMap> = Bus<E> & {
+  emit: SignalEmit<E>;
+};
+/**
+ * Lets `bus.emit(call, { signal })` tie the tasks that this emit starts to an
+ * outside `AbortSignal`: when it aborts, their `ctx.signal` aborts with the same
+ * reason, so a handler, `latest`, `retry` and `timeout` stop as for any abort. It
+ * is made for libraries that own the request and give you a signal, such as the
+ * `queryFn` of React Query. The tasks that count are those made while the call
+ * to `emit` runs (the command or job and the listeners of its type, and their
+ * `ctx.run` children); a separate `emit` that a handler makes later is not
+ * linked. `emit` returns what it returns without the plugin.
+ *
+ * For a command or a job the link ends when its promise settles; a handler
+ * that returns without a promise is finished with the call, so it is not
+ * linked after it. For an event the link stays until the signal aborts, so
+ * give each request its own signal.
+ *
+ * `{ signal }` can share the object with the fields of a scope (see
+ * `scopePlugin`); `signal` is never put on `ctx` by a scope. Without this
+ * plugin the signal is ignored. Returns the same bus, typed with the new `emit`.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { signalPlugin } from "nanoeffects/signal";
+ *
+ * const bus = createBus().use(signalPlugin()); // emit takes a signal now
+ *
+ * // React Query aborts `signal` when the component unmounts or the key changes
+ * const queryFn = ({ signal }: { signal: AbortSignal }) =>
+ *   bus.emit(getUser("1"), { signal });
+ * ```
+ */
+export declare const signalPlugin: () => <E extends EventMap>(bus: Bus<E>) => SignalBus<E>;
+//#endregion
+export type { SignalBus, SignalEmit, SignalOption };

package/dist/signal.js

@@ -0,0 +1 @@
+import{t as e}from"./onAbort-BgMfspK4.js";import{n as t}from"./promise-CSLpzwSR.js";import{n}from"./bus-CkTHUAvq.js";const r=e=>typeof e==`object`&&!!e,i=(e,t)=>{let n=t[0];if(!r(n)||!r(e)&&typeof e!=`function`)return;let i=Reflect.get(n,`signal`);return i instanceof AbortSignal?i:void 0},a=(r,i,a,o)=>{let s=e({signal:r},e=>{for(let{target:t}of i)t.abort(e)});return t(o)?o.then(s,s):n(a)&&s(),o},o=()=>e=>{let t,n,r=e.addContext;e.addContext=e=>{r?.(e),t?.push({target:e}),n?.aborted&&e.abort(n.reason)};let o=e.emit;return e.emit=(e,...r)=>{let s=i(e,r);if(!(s||t))return o(e,...r);let c=t,l=n,u=[];t=s?u:void 0,n=s;let d;try{d=o(e,...r)}finally{t=c,n=l}return s?a(s,u,e,d):d},e};export{o as signalPlugin};

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-import { G as Trace, K as TraceEvent, L as Tracer, q as TraceLogger } from "./action-creator-Bd4TBZgl.js";
+import { G as Trace, K as TraceEvent, L as Tracer, q as TraceLogger } from "./action-creator-BrZF6hXc.js";
 //#region src/trace/console.d.ts
 type ConsoleLoggerOptions = {
   /** Defaults to `globalThis.console`. */

package/dist/{types-BJ0fzV1p.d.ts → types-KavbvHix.d.ts}

@@ -1,6 +1,16 @@
-import { B as EventMap, d as Effects, o as Scope, s as WithFields } from "./action-creator-Bd4TBZgl.js";
-import { t as BoundOf } from "./plugin-DQNPBcxx.js";
+import { B as EventMap, d as Effects, o as Scope, s as WithFields } from "./action-creator-BrZF6hXc.js";
+import { t as BoundOf } from "./plugin-DkXCvsmB.js";
 //#region src/scope/types.d.ts
+/**
+ * The slots `scopePlugin` fills for `modulePlugin`. They are not on `Bus`: a bus
+ * has them in its type once the plugin returned it.
+ */
+interface ScopeSlots {
+  /** Puts the fields of a module's scope on the context of one of its tasks. Without it a module's scope is ignored. */
+  applyScope?: ((ctx: object, scope: Scope) => void) | undefined;
+  /** Wraps a handler so it runs with the fields of a module's scope. */
+  fitScope?: ((scope: Scope, fn: unknown) => unknown) | undefined;
+}
 type BoundEffects<E extends EventMap, S extends Scope> = S extends {
   $effects: infer H extends Effects;
 } ? BoundOf<H, E> : unknown;
@@ -12,4 +22,4 @@ type FieldsOfScope<E extends EventMap, S extends Scope> = [keyof S] extends [nev
  */
 type Scoped<E extends EventMap, S extends Scope> = WithFields<E, FieldsOfScope<E, S>>;
 //#endregion
-export { Scoped as n, FieldsOfScope as t };
+export { ScopeSlots as n, Scoped as r, FieldsOfScope as t };

package/dist/with-policy-CqUS-VWW.d.ts

@@ -0,0 +1,30 @@
+import { B as EventMap, H as PayloadOf, W as Task } from "./action-creator-BrZF6hXc.js";
+//#region src/policies/with-policy.d.ts
+/** What `withPolicy` returns: the task as a plain function that can be cancelled. */
+type PolicyFunction<P, R> = {
+  (...args: PayloadOf<P>): Promise<Awaited<R> | undefined>;
+  /** Aborts every call that has not finished. Calls made after it work as before. */
+  cancel: (reason?: unknown) => void;
+  /** Same as `cancel`; present where `Symbol.dispose` exists, for `using`. */
+  [Symbol.dispose]?: () => void;
+};
+/**
+ * Makes a policy (or any task) a plain function that needs no bus and no
+ * context. The returned function keeps the state of the policy between calls,
+ * so a debounced one waits across calls. `cancel()` aborts what is pending or
+ * running; calls after it work again. The callback keeps the `(payload, ctx)`
+ * shape; `ctx.signal`, `ctx.abort` and `ctx.run` work, `ctx.emit` and `ctx.on`
+ * do nothing because there is no bus.
+ *
+ * @example
+ * ```ts
+ * const onChange = withPolicy(debounce(300, (query: string) => search(query)));
+ *
+ * onChange("re");
+ * onChange("redux"); // only this one runs, 300 ms after it
+ * onChange.cancel(); // or nothing runs at all
+ * ```
+ */
+declare const withPolicy: <P, R>(task: Task<P, EventMap, R>) => PolicyFunction<P, R>;
+//#endregion
+export { withPolicy as n, PolicyFunction as t };

package/dist/with-policy-DBV9dh2F.js

@@ -0,0 +1 @@
+import{n as e}from"./context-COgyNlrC.js";const t=Reflect.get(Symbol,`dispose`),n=n=>{let r=new AbortController,i=async(...t)=>{let i=t[0],{ctx:a,unlink:o}=e({event:{type:`withPolicy`,payload:i},parent:{signal:r.signal}});try{return await n(i,a)}finally{o()}},a=e=>{r.abort(e),r=new AbortController},o=Object.assign(i,{cancel:a});return t&&Reflect.set(o,t,()=>a()),o};export{n as t};

package/docs/README.md

@@ -4,6 +4,8 @@
 
 The [Guide](guide.md) is the ladder: small bus → policies for async UI → effects when you need them → commands and modules for domain logic off the UI.
 
+Why the library exists, and when to pick it over Redux, Effector or RxJS (SDKs, shared libraries, Module Federation): [Why nanoeffects exists](motivation.md).
+
 Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-checked and tested).
 
 ## Jump by project need
@@ -16,6 +18,10 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 | Domain logic off the UI | [Actions, commands, modules](actions.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) |
+| Old responses overwrite new ones | [Cancel stale requests](cancel-stale-requests.md) |
+| Debounced input that must also cancel the old request | [Debounce and abort](debounce-and-abort.md) |
+| A second click sends a second request | [Prevent a double submit](prevent-double-submit.md) |
+| Using mitt, nanoevents or EventEmitter | [Coming from mitt](migrating-from-mitt.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) |
@@ -27,6 +33,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 - [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
+- [Use the bus from a class](oop.md) — `extendBus`, `@WithBus`, `@On`, and `dispose()` for the subscriptions of an instance
 - [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

package/docs/actions.md

@@ -8,14 +8,28 @@ Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
 
 ## Return a value from `emit` with a command
 
+The bus lives in one file and its events in another, so any module can import both without a cycle.
+
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 
-const bus = createBus();
+// createBus — one bus for the app
+export const bus = createBus();
+```
+
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
 
 // createCommand — emit runs the handler and returns its result
-const double = createCommand("math/double", (value) => value * 2);
+export const double = createCommand("math/double", (value) => value * 2);
+```
+
+```js
+import { bus } from "./bus";
+import { double } from "./math";
+
 bus.emit(double(21)); // 42
 ```
 
@@ -24,27 +38,30 @@ bus.emit(double(21)); // 42
 `nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
 
 ```js
+// user.js
 import { createAction, createCommand, createJob } from "nanoeffects/actions";
 
 // createAction — event with a payload (like RTK createAction)
-const userLoaded = createAction("user/loaded");
-const loadFailed = createAction("user/failed");
+export const userLoaded = createAction("user/loaded");
+export const loadFailed = createAction("user/failed");
 
 // createCommand with a handler — emit returns what the handler returns
-const getUser = createCommand("user/get", (id, { signal }) => {
+export const getUser = createCommand("user/get", (id, { signal }) => {
   return fetchUser(id, { signal });
 });
 
 // createCommand without a handler — a contract; register the work elsewhere
-const sendMail = createCommand("mail/send");
+export const sendMail = createCommand("mail/send");
 
 // createJob — command that also emits success / fail actions
-const loadUser = createJob("user/load", fetchUser, {
+export const loadUser = createJob("user/load", fetchUser, {
   success: userLoaded,
   fail: "user/failed",
 });
 ```
 
+These are the events of the user domain, in a file of their own (`user.js`). The bus is made in another file (`bus.js` below), and neither imports the other.
+
 ### Actions
 
 `createAction(type)` returns a creator. Without generics it keeps the literal type; the bus checks the payload against its event map. Without an event map, give the payload type: `createAction<User>("user/loaded")`.
@@ -65,22 +82,22 @@ Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(comm
 **Where handlers are registered.** The command may carry a handler. The bus can also take handlers from a registry (`commandsPlugin`). A handler bound there wins over the command’s own. Each bus (each test) has its own registry.
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import {
-  bindHandler,
-  commandsPlugin,
-  createCommand,
-} from "nanoeffects/actions";
+import { bindHandler, commandsPlugin } from "nanoeffects/actions";
+import { sendMail } from "./user";
 
-const sendMail = createCommand("mail/send");
-const getUser = createCommand("user/get");
-
-const bus = createBus();
+export const bus = createBus();
 
 // commandsPlugin — registry of handlers for this bus
-const commands = bus.use(
+export const commands = bus.use(
   commandsPlugin([bindHandler(sendMail, smtpSend)]),
 );
+```
+
+```js
+import { commands } from "./bus";
+import { getUser } from "./user";
 
 // later, e.g. in a test — latest binding wins
 const unbind = commands.handle(getUser, async () => fakeUser);
@@ -89,19 +106,88 @@ unbind();
 
 A command with no handler anywhere throws `No handler for command "..."` from `emit` (the call itself only builds the action).
 
-The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the command’s own handler. `bus.use(commandsPlugin())` sets `bus.commands`. A second plugin on the same bus replaces it. There is no `commands` option in `createBus`; assign a custom runner with `bus.commands = { run }`.
+The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the command’s own handler. `bus.use(commandsPlugin())` sets `bus.commands`. A second `commandsPlugin` binds its list in that registry and returns it. There is no `commands` option in `createBus`; assign a custom runner with `bus.commands = { run }`.
 
 ### Jobs
 
-`createJob(type, handler, { success, fail })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.success` and `loadUser.fail` on it.
+`createJob(type, handler, { pending, success, fail, cancel })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.pending`, `loadUser.success`, `loadUser.fail` and `loadUser.cancel` on it.
 
+- When the handler starts, emits `loadUser.pending(payload)`.
 - On success, emits `loadUser.success(result)`.
 - On failure, emits `loadUser.fail(error)`.
-- `success` / `fail` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/success` or `<type>/fail`.
+- When the task is aborted before the handler settles, emits `loadUser.cancel(reason)` instead of `success` or `fail`. After `pending`, exactly one of the three follows.
+- `pending` / `success` / `fail` / `cancel` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/pending`, `<type>/success`, `<type>/fail` or `<type>/cancel`.
 - `bus.emit(loadUser(id))` returns a promise of the result. Handler errors are always handled: they go to `fail` and the promise resolves with `undefined`. For a result that must reject, use a command.
-- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). Nothing is sent after abort.
-- A missing handler is not an outcome: `emit` throws `No handler for command "..."`.
+- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). `success` and `fail` are not sent after abort; `cancel` is, once the handler settles.
+- A missing handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent.
 - Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
+- The outcomes are events like any other: with `onUnhandled` set on the bus, it is called for a `pending` or a `cancel` that nobody listens to.
+
+## Show a loading state with a job
+
+**Problem.** A spinner needs a flag that is `true` while a request runs. Setting it by hand in the handler (`loading = true`, then `try` / `finally`) breaks when the task is aborted: `ctx.emit` does nothing after an abort, so a flag that is cleared through the bus stays `true`.
+
+**When.** The UI shows a loading state for a request, and the request can be aborted (a page is left, `ctx.abort()` is called). Skip it when nothing shows the state.
+
+A job sends one action when the handler starts and one when it ends, whatever way it ends. A store sets the flag on `pending` and clears it on `success`, `fail` and `cancel`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus the app shares
+export const bus = createBus();
+```
+
+```js
+// user.js
+import { createJob } from "nanoeffects/actions";
+
+// createJob — a command that also sends pending, success, fail and cancel
+export const loadUser = createJob("user/load", fetchUser);
+```
+
+```js
+// user-store.js
+import { bus } from "./bus";
+import { loadUser } from "./user";
+
+export const state = { loading: false, user: null };
+
+// pending — the handler starts: show the spinner
+bus.on(loadUser.pending, () => {
+  state.loading = true;
+});
+
+// success — the handler returned a user
+bus.on(loadUser.success, (user) => {
+  state.loading = false;
+  state.user = user;
+});
+
+// fail — the handler threw
+bus.on(loadUser.fail, () => {
+  state.loading = false;
+});
+
+// cancel — the task was aborted: the only way to clear the flag then
+bus.on(loadUser.cancel, () => {
+  state.loading = false;
+});
+```
+
+```js
+// page.js
+import { bus } from "./bus";
+import { loadUser } from "./user";
+
+// emit — runs the job; state.loading is true as soon as it returns
+bus.emit(loadUser("1"));
+```
+
+`cancel` is sent when the handler settles, not at the moment of the abort. A handler that stops on `ctx.signal` (as `fetch` does) settles at once. A handler that ignores the signal sends `cancel` when it finishes, and one that never finishes sends nothing.
+
+**Limit: policies.** A policy such as `latest`, `leading`, `throttle` or `queue` wraps the handler, inside the job. The job does not know what the policy decides, so `pending` is sent for every call. A call that the policy drops, and a run that `latest` replaces, then close with `success(undefined)`, not with `cancel`. A flag set by `pending` is exact for a job without a policy, and for an abort of the task or of its parent. With a policy, count the calls or use the result of `emit`.
 
 ## Mount domains with modules
 
@@ -112,18 +198,20 @@ The registry lives in `nanoeffects/actions`, so a bus without one carries none o
 `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";
-import {
-  createCommand,
-  createModule,
-  modulePlugin,
-} from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
+
+export const getUser = createCommand("user/get");
+export const saveUser = createCommand("user/save", persistUser);
+```
 
-const getUser = createCommand("user/get");
-const saveUser = createCommand("user/save", persistUser);
+```js
+// user-module.js
+import { createModule } from "nanoeffects/actions";
+import { getUser, saveUser } from "./user";
 
 // createModule — one domain; unmount undoes everything below
-const userModule = createModule("user", (m) => {
+export const userModule = createModule("user", (m) => {
   m.handle(getUser, fetchUser);
   m.use(saveUser, authModule);
   m.on("login", (user, ctx) => {
@@ -133,10 +221,22 @@ const userModule = createModule("user", (m) => {
     /* background work; ends when the module unmounts */
   });
 });
+```
 
-const bus = createBus();
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { userModule } from "./user-module";
+
+export const bus = createBus();
 // modulePlugin — mount modules on the bus
-const app = bus.use(modulePlugin([userModule]));
+export const app = bus.use(modulePlugin([userModule]));
+```
+
+```js
+import { app } from "./bus";
+import { getUser } from "./user";
 
 const unmount = app.mount(orderModule); // later, e.g. after a lazy import
 app.commands.handle(getUser, fakeUser); // in a test
@@ -147,6 +247,7 @@ app.dispose(); // unmounts every module
 - **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one (see [Hot reload](hmr.md)).
 - **Registry.** If `bus.use(commandsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`.
 - A disposed app cannot mount modules.
+- **The given modules are mounted on the first use** of the app or the bus (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`), so the plugins you use after `modulePlugin` still reach them. The `bus.on` calls made in between are held and made right after, so the listeners of a module stay ahead of them. See [using plugins in any order](plugins.md#use-them-in-any-order).
 - Module context = task context plus `handle`, `use`, and `spawn`:
   - `handle` — give a command a handler (contract, or override).
   - `use` — bring sub-modules and commands that carry a handler; the returned function undoes that call.
@@ -158,17 +259,29 @@ app.dispose(); // unmounts every module
 A command can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`$effects` binds functions to the task), as the last argument of `createCommand`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 import { scopePlugin } from "nanoeffects/scope";
 
 // scopePlugin — makes the scope of a command work on this bus
-const bus = createBus().use(scopePlugin());
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
 // the third argument — fields of this command only
-const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
-  api,
-});
+export const getUser = createCommand(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 // a test replaces them for one call
 const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };

package/docs/cancel-stale-requests.md

@@ -0,0 +1,111 @@
+# Cancel stale requests and fix race conditions
+
+Read this page if an older response can overwrite a newer one: a search box that shows the results of the previous query, a filter that flickers, a form that submits twice. It shows the cause, the fix with `latest`, and how to add a pause, a retry and a timeout. It needs only the bus from the [README](../README.md).
+
+## See the problem
+
+A user types `ab`, then `abc`. Two requests start. If the one for `ab` is slower, it finishes last and its results replace the right ones.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// Without a policy every "search" starts its own request, and the slowest one wins.
+bus.on("search", async (query) => {
+  const items = await api.search(query);
+  bus.emit("results", items);
+});
+```
+
+Checking a counter by hand (`if (id !== lastId) return`) hides the old result, but the old request still runs. Calling `controller.abort()` by hand works, but you must keep the controller somewhere and abort it before each new call.
+
+## Keep only the latest request
+
+Wrap the handler in `latest`. A new `"search"` aborts the task of the previous one, and an aborted task delivers no result.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer "search" aborts the older run
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    // signal: pass it on so the browser cancels the request, not only drops the result
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+
+bus.on("results", (items) => render(items));
+```
+
+What to replace: `api.search` is your own request function. It must accept `{ signal }` and give it to `fetch`. Without it, `latest` still ignores the old result, but the request keeps running.
+
+Result: `emit("search", "ab")` followed by `emit("search", "abc")` shows only the results for `abc`, and the request for `ab` is cancelled.
+
+## Wait for a pause in typing
+
+Add `debounce` outside `latest`. The search starts after 300 ms without a new keystroke.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer search aborts the request in flight
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce: run after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+```
+
+## Retry a failed request and limit its time
+
+Use `retry` and `timeout` around the request. The pause grows with each attempt.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { backoff, retry, timeout } from "nanoeffects/effects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// timeout: abort one attempt after 5 s
+const searchOnce = timeout(5000, (query, { signal }) => api.search(query, { signal }));
+
+// retry: up to 4 attempts, backoff makes the pause longer each time
+const searchWithRetry = retry(searchOnce, {
+  times: 4,
+  delay: backoff({ base: 200, max: 5000, jitter: true }),
+});
+
+// latest: a newer search aborts the whole retry chain
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await ctx.run(searchWithRetry, query); // ctx.run: a child task, aborted with this one
+    ctx.emit("results", items);
+  }),
+);
+```
+
+## Pick another policy for another race
+
+| Situation | Policy |
+| --------- | ------ |
+| Only the newest result matters (search, filter, tab switch) | `latest` |
+| A second click while the first call runs must be ignored (submit, pay) | `leading` |
+| Every call must run, one after another (save, upload) | `queue` |
+| Calls come in bursts and you want one at the end | `debounce` |
+| Calls come in bursts and you want one per period | `throttle` |
+| Each user or item has its own race | add `{ key }`, for example `latest(handler, { key })` |
+
+All policies and their options: [Policies](policies.md). The same step by step in a form: [Build a sign-up form in React](react.md).