nanoeffects 0.27.0 → 0.29.0

package/dist/scope.d.ts

@@ -1,5 +1,5 @@
-import { H as EventMap, I as WithSignal, c as Scope, f as Effect, m as Signaled, p as Effects, s as EmitScope, v as Bus } from "./action-creator-D_c223C7.js";
-import { n as ScopeSlots, r as Scoped } from "./types-Bf-LX_tE.js";
+import { H as EventMap, I as WithSignal, c as Scope, f as Effect, m as Signaled, p as Effects, s as EmitScope, v as Bus } from "./action-creator-jeEqIKgK.js";
+import { n as ScopeSlots, r as Scoped } from "./types-D5xsR37j.js";
 //#region src/scope/effect.d.ts
 /**
  * Marks a function whose first parameter is `{ signal }` as an effect, so that
@@ -16,7 +16,7 @@ import { n as ScopeSlots, r as Scoped } from "./types-Bf-LX_tE.js";
  * ```ts
  * const first = effect(<T>(ctx: WithSignal, items: T[]) => items[0]);
  *
- * const getUser = createCommand(
+ * const getUser = createAction(
  *   "user/get",
  *   (id: string, { first }) => first([id]), // first: <T>(items: T[]) => T
  *   { first },
@@ -27,11 +27,11 @@ export declare function effect<A extends unknown[], R>(fn: (ctx: WithSignal, ...
 //#endregion
 //#region src/scope/plugin.d.ts
 /**
- * Switches scopes on for a bus: the scope given to a command, a job, an
- * action or a module (an object whose keys go on `ctx`, with `$effects` bound to
+ * Switches scopes on for a bus: the scope given to an action, a job
+ * or a module (an object whose keys go on `ctx`, with `$effects` bound to
  * the task), and the second argument of `emit`, put fields on
  * the context of the tasks they are for. A stronger layer replaces a field of
- * the same name: `emit`, then action / command / job, then module, then the bus.
+ * the same name: `emit`, then action / job, then module, then the bus.
  * Fields of the library (`signal`, `emit`, `run`, …) are never replaced. Returns
  * the same bus.
  *
@@ -41,13 +41,13 @@ export declare function effect<A extends unknown[], R>(fn: (ctx: WithSignal, ...
  * @example
  * ```ts
  * import { createBus } from "nanoeffects";
- * import { createCommand } from "nanoeffects/actions";
+ * import { createAction } from "nanoeffects/actions";
  * import { scopePlugin } from "nanoeffects/scope";
  *
  * const bus = createBus().use(scopePlugin()); // scopes work on this bus
  *
- * const getUser = createCommand("user/get", (id: string, { http }) => http.get(id), {
- *   http, // a field of this command only
+ * const getUser = createAction("user/get", (id: string, { http }) => http.get(id), {
+ *   http, // a field of this action only
  * });
  * bus.emit(getUser("1"), { http: fakeHttp }); // this call only
  * ```

package/dist/signal-field-key-CWT-3OXC.js

@@ -0,0 +1 @@
+const e=Symbol.for(`nanoeffects.signalField`);export{e as t};

package/dist/signal.d.ts

@@ -1,4 +1,26 @@
-import { H as EventMap, O as EventLike, T as Emit, s as EmitScope, u as WithScope, v as Bus, x as CommandCall } from "./action-creator-D_c223C7.js";
+import { A as HandledCall, C as Emit, E as EventLike, H as EventMap, s as EmitScope, u as WithScope, v as Bus } from "./action-creator-jeEqIKgK.js";
+import { n as FromSignal } from "./context-types-Bme1mzkn.js";
+//#region src/signal/from-signal.d.ts
+/**
+ * Marks a field of `contextPlugin` as a value that needs the signal of its task: a
+ * client, a database handle. `make` runs when the task first reads the field, with the
+ * `ctx.signal` of that task, and runs once for it. A child task (`ctx.run`) makes its
+ * own with its own signal. Without `contextPlugin` the marker means nothing.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus().use(
+ *   contextPlugin({
+ *     logger, // a plain field, the same for every task
+ *     http: fromSignal((signal) => axios.create({ signal })), // one client per task, aborted with it
+ *   }),
+ * );
+ *
+ * bus.on("user/open", (id, { http }) => http.get(`/users/${id}`));
+ * ```
+ */
+export declare const fromSignal: <T>(make: (signal: AbortSignal) => T) => FromSignal<T>;
+//#endregion
 //#region src/signal/plugin.d.ts
 /** What the second argument of `emit` takes besides the fields of a scope. */
 type SignalOption = {
@@ -7,8 +29,8 @@ type SignalOption = {
 };
 /** `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;
+  <P, R, F>(call: HandledCall<P, R> & WithScope<F>, options: SignalOption & EmitScope<E, F>): R;
+  <P, R>(call: HandledCall<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. */
@@ -16,16 +38,22 @@ type SignalBus<E extends EventMap> = Bus<E> & {
   emit: SignalEmit<E>;
 };
 /**
+ * Also lets `bus.on(event, handler, { signal })` and `bus.once` remove the
+ * listener when the signal aborts, as `addEventListener` does, so a component or
+ * a script that holds a signal keeps no `unbind`. A handler that already runs is
+ * not aborted; a signal that is aborted already adds no listener. `off(event, fn)`
+ * does not end the link: the returned function does.
+ *
  * 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
+ * to `emit` runs (the action 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
+ * For an action 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.
@@ -48,4 +76,4 @@ type SignalBus<E extends EventMap> = Bus<E> & {
  */
 export declare const signalPlugin: () => <E extends EventMap>(bus: Bus<E>) => SignalBus<E>;
 //#endregion
-export type { SignalBus, SignalEmit, SignalOption };
+export type { FromSignal, SignalBus, SignalEmit, SignalOption };

package/dist/signal.js

@@ -1 +1 @@
-import{u as e}from"./context-UcmrAIhP.js";import{n as t}from"./promise-CSLpzwSR.js";import{t as n}from"./bus-DQDHUN5e.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};
+import{t as e}from"./onAbort-BgMfspK4.js";import{n as t}from"./promise-CSLpzwSR.js";import{n}from"./bus-0uYn_kRj.js";import{t as r}from"./signal-field-key-CWT-3OXC.js";const i=e=>({[r]:e}),a=(t,n)=>(r,i,a)=>{let o=a?.signal;if(!o)return t(r,i,a);let s=t(r,n?(e,t)=>(c(),i(e,t)):i,a),c=e({signal:o},s);return()=>{c(),s()}},o=e=>typeof e==`object`&&!!e,s=(e,t)=>{let n=t[0];if(!o(n)||!o(e)&&typeof e!=`function`)return;let r=Reflect.get(n,`signal`);return r instanceof AbortSignal?r:void 0},c=(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},l=()=>e=>{let t,n,r=e.addContext;e.addContext=e=>{r?.(e),t?.push({target:e}),n?.aborted&&e.abort(n.reason)};let i=e.emit;e.emit=(e,...r)=>{let a=s(e,r);if(!(a||t))return i(e,...r);let o=t,l=n,u=[];t=a?u:void 0,n=a;let d;try{d=i(e,...r)}finally{t=o,n=l}return a?c(a,u,e,d):d};let o=e.on,l=e.once;return e.on=a(o,!1),e.once=a(l,!0),e};export{i as fromSignal,l as signalPlugin};

package/dist/svelte.d.ts

@@ -1,4 +1,4 @@
-import { D as EventKey, H as EventMap, a as FreeActionCreator, t as ActionCreator, v as Bus } from "./action-creator-D_c223C7.js";
+import { H as EventMap, T as EventKey, a as FreeActionCreator, t as ActionCreator, v as Bus } from "./action-creator-jeEqIKgK.js";
 import { t as StateOf } from "./state-of-C19H6BoV.js";
 import { Readable } from "svelte/store";
 //#region src/svelte/plugin.d.ts

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-import { B as Tracer, H as EventMap, J as Trace, K as Phase, V as EffectName, X as TraceLogger, Y as TraceEvent, v as Bus } from "./action-creator-D_c223C7.js";
+import { B as Tracer, H as EventMap, J as Trace, K as Phase, V as EffectName, X as TraceLogger, Y as TraceEvent, v as Bus } from "./action-creator-jeEqIKgK.js";
 //#region src/trace/console.d.ts
 type ConsoleLoggerOptions = {
   /** Defaults to `globalThis.console`. */
@@ -52,7 +52,7 @@ export declare const performanceLogger: (options?: PerformanceLoggerOptions) =>
 /**
  * Names and groups what the trace shows, on a bus that has a tracer:
  *
- * - `traceGroupId` in the scope of a command, a job or an action goes to every
+ * - `traceGroupId` in the scope of an action, a job or an action goes to every
  *   task that the call starts;
  * - `useEmitter` and `bus.emitter` emit from a root task named by their
  *   `traceId`, so a chain says which subscription began it;
@@ -80,12 +80,21 @@ export declare const tracePlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus
 //#endregion
 //#region src/trace/recorder.d.ts
 type Recorder<E = Record<string, unknown>> = TraceLogger<E> & {
-  /** Every event received so far, in order. */
+  /**
+   * The events received so far, oldest first. Without a `capacity` it is one
+   * live array; with one, each read is a new array that is a snapshot.
+   */
   readonly events: TraceEvent<E>[];
   clear: () => void;
 };
 /**
- * Trace logger that keeps events in memory; meant for tests.
+ * Trace logger that keeps events in memory. With no option it keeps all of
+ * them, for tests. With `capacity` it keeps the last events, to send when
+ * something goes wrong.
+ *
+ * `payload` and `error` are kept as they are, and can hold private data: cut
+ * what you send. An event has no time, and a `parentId` can name an event that
+ * was pushed out: read it as a root.
  *
  * @example
  * ```ts
@@ -95,9 +104,15 @@ type Recorder<E = Record<string, unknown>> = TraceLogger<E> & {
  * bus.emit("search", "re");
  * bus.emit("search", "redux");
  * recorder.events.map((e) => e.phase); // ["start", "cancel", "start", "done"]
+ *
+ * const lastEvents = createTraceRecorder<Events>({ capacity: 500 });
  * ```
  */
-export declare const createTraceRecorder: <E = Record<string, unknown>>() => Recorder<E>;
+export declare const createTraceRecorder: <E = Record<string, unknown>>(
+/** `capacity`: keep the last N events (a ring buffer); not a positive integer, or left out: keep all. */
+options?: {
+  capacity?: number;
+}) => Recorder<E>;
 //#endregion
 //#region src/trace/redux.d.ts
 type ReduxConnection = {

package/dist/trace.js

@@ -1 +1 @@
-import{a as e,c as t,d as n,n as r,o as i,r as a,s as o,u as s}from"./context-UcmrAIhP.js";import{n as c}from"./promise-CSLpzwSR.js";import{t as l}from"./origin-key-BbWN3gmN.js";import{t as u}from"./scope-key-B7l7mUS5.js";const d=(e={})=>{let t=e.console??globalThis.console,n=e.prefix??`[nanoeffects]`,r=/* @__PURE__ */ new Map;return({id:e,parentId:i,type:a,effect:o,phase:s,payload:c,error:l,traceGroupId:u})=>{r.has(e)||r.set(e,typeof i==`number`?(r.get(i)??0)+1:0);let d=`  `.repeat(r.get(e)??0);s!==`start`&&r.delete(e);let f=u===void 0?``:` [${u}]`,p=`${n}${f} ${d}${a} · ${o} ${s}`;s===`error`?t?.error(p,l):t?.debug(p,c)}},f=(e={})=>{let t=e.performance??globalThis.performance,n=/* @__PURE__ */ new Map;return({id:e,parentId:r,rootId:i,traceGroupId:a,type:o,effect:s,phase:c,error:l})=>{if(!t)return;if(c===`start`){n.set(e,t.now());return}let u=`${o} · ${s} (${c})`,d={id:e,parentId:r,...i!==void 0&&{rootId:i},...a!==void 0&&{traceGroupId:a},phase:c,...c===`error`&&{error:String(l)}},f=n.get(e);n.delete(e),typeof f==`number`?t.measure(u,{start:f,end:t.now(),detail:d}):t.mark(u,{detail:d})}};let p;const m=()=>p,h=(e,t)=>{let n=p;p=e;try{return t()}finally{p=n}},g=(e,t,n={})=>{let{trace:i}=e;if(!i){e.emit(t);return}let{traceId:a,traceGroupId:s}=n,{ctx:c,unlink:l}=r({event:{type:a??t.type,payload:t,...s===void 0?{}:{traceGroupId:s}},bus:{emit:e.emit,on:e.on,off:e.off,ctx:e.ctx,addContext:e.addContext},tracer:i});o(c,`run`,`start`);try{c.emit(t),o(c,`run`,`done`)}catch(e){throw o(c,`run`,`error`,e),e}finally{l()}},_=e=>typeof e==`string`?e:Reflect.get(Object(e),`type`),v=(e,t)=>typeof e==`object`?Reflect.get(Object(e),`payload`):t[0],y=()=>n=>{if(!(t&&n.trace))return n;let{trace:r}=n,o=(e,t)=>{let n=r.task({type:_(e),payload:v(e,t)},a());r.report(n,`emit`,`done`)},s=n.emit;n.emit=(e,...t)=>h(e,()=>(o(e,t),s(e,...t))),Reflect.set(n,l,(e,t)=>{g(n,e,t)});let c=/* @__PURE__ */ new WeakMap,u=(e,t,n)=>{let r=c.get(t)??/* @__PURE__ */ new Map,i=_(e);r.set(i,[...r.get(i)??[],n]),c.set(t,r)},d=(e,t)=>(c.get(t)?.get(_(e)))?.pop(),f=(t,n)=>(r,a)=>(e(a,n),i(a,`run`,()=>t(r,a))),p=(e,t)=>(n,r,i)=>{let a=Reflect.get(Object(i),`traceId`);if(typeof a!=`string`)return e(n,r);let o=t?(e,t)=>(d(n,r),f(r,a)(e,t)):f(r,a);u(n,r,o);let s=e(n,o);return()=>{s()}},m=n.off,y=(e,t)=>{t===void 0?m(e):m(e,d(e,t)??t)},b=n.on,x=n.once;return n.on=p(b,!1),n.once=p(x,!0),n.off=y,n},b=()=>{let e=[];return Object.assign(t=>{e.push(t)},{events:e,clear:()=>{e.length=0}})},x=()=>{},S=/* @__PURE__ */ new Set([`cancel`,`drop`,`error`]),C=()=>!1,w=()=>!0,T=e=>{if(typeof e==`function`)return e;if(Array.isArray(e)){let t=new Set(e);return({phase:e})=>t.has(e)}return e?w:C},E=(e={})=>{let t=e.extension??globalThis.__REDUX_DEVTOOLS_EXTENSION__;if(!t)return x;let{starts:n=!1,depth:r=0,maxAge:i}=e,a=T(e.policies),o=e.payload??`essential`,s=t.connect({name:e.name??`nanoeffects`,...i!==void 0&&{maxAge:i}}),c=/* @__PURE__ */ new Map,l=/* @__PURE__ */ new Map,u=()=>({running:Object.fromEntries(c)});s.init(u());let d=(e,t,n)=>n===0?a({effect:e,phase:t}):n<=r,f=(e,t)=>{e.phase===`start`?(l.set(e.id,t),d(e.effect,`start`,t)&&c.set(e.id,{type:e.type,effect:e.effect,...e.traceGroupId!==void 0&&{traceGroupId:e.traceGroupId}})):(l.delete(e.id),c.delete(e.id))},p=!1,m=!1,h=(e,t)=>{p||m||t!==0||e===`start`||(m=!0,globalThis.console?.warn(`[nanoeffects] reduxDevtools got a task but no emit event: add bus.use(tracePlugin()) to see the emits.`))},g=e=>{let{payload:t,...n}=e;return o===`all`||o===`essential`&&(e.effect===`emit`||S.has(e.phase))?{...n,payload:t}:n},_=(e,t)=>{s.send({...g(e),type:`${e.type}/${e.effect}/${e.phase}`,event:e.type,...e.phase===`error`&&{error:t instanceof Error?t.message:t}},u())};return({error:e,...t})=>{if(t.effect===`emit`){p=!0,s.send({...g(t),event:t.type},u());return}let r=(t.parentId===void 0?-1:l.get(t.parentId)??-1)+1;f(t,r),h(t.phase,r),(t.phase===`error`&&r===0||d(t.effect,t.phase,r))&&(t.phase!==`start`||n)&&_(t,e)}},D=e=>{let t=typeof e==`function`?[e]:[...e??[]];return t.length===0?null:e=>{for(let r of t)try{r(e)}catch(e){n(`trace logger failed`,e)}}},O=()=>{},k=e=>{if(typeof e.traceGroupId==`string`)return e.traceGroupId;let t=m();if(typeof t!=`object`&&typeof t!=`function`||t===null)return;let n=Reflect.get(t,u),r=typeof n==`object`&&n?Reflect.get(n,`traceGroupId`):void 0;return typeof r==`string`?r:void 0},A=(e,t={})=>{let n=D(e),{filter:r,sample:i=1}=t,a=0,o=e=>typeof i==`function`?i({type:e.type,payload:e.payload}):Math.random()<i,l={task:(e,t)=>({id:++a,root:t?.root??a,parent:t?.id,type:e.type,payload:e.payload,sampled:t?.sampled??o(e),group:k(e)??t?.group}),rename:(e,t)=>{e.type=t},report:(e,t,i,a)=>{if(!e.sampled)return;let o={id:e.id,type:e.type,effect:t,phase:i,payload:e.payload};typeof e.parent==`number`&&(o.parentId=e.parent),e.root!==e.id&&(o.rootId=e.root),e.group!==void 0&&(o.traceGroupId=e.group),i===`error`&&(o.error=a),(!r||r(o))&&n?.(o)},settler:(e,t)=>{if(!e.sampled)return O;let n=!1;return(r,i)=>{n||(n=!0,l.report(e,t,r,i))}},run:(e,t,n,r)=>{if(!e.sampled)return r();let i=l.settler(e,t);l.report(e,t,`start`),s({signal:n},()=>i(`cancel`));let a;try{a=r()}catch(e){throw i(`error`,e),e}return c(a)?Promise.resolve(a).then(e=>(i(`done`),e),e=>{throw i(`error`,e),e}):(i(`done`),a)}};return l};export{d as consoleLogger,b as createTraceRecorder,A as createTracer,f as performanceLogger,E as reduxDevtools,y as tracePlugin};
+import{n as e,t}from"./onAbort-BgMfspK4.js";import{a as n,c as r,n as i,o as a,r as o,s}from"./context-DtUnzC-1.js";import{n as c}from"./promise-CSLpzwSR.js";import{t as l}from"./origin-key-BbWN3gmN.js";import{t as u}from"./scope-key-B7l7mUS5.js";const d=(e={})=>{let t=e.console??globalThis.console,n=e.prefix??`[nanoeffects]`,r=/* @__PURE__ */ new Map;return({id:e,parentId:i,type:a,effect:o,phase:s,payload:c,error:l,traceGroupId:u})=>{r.has(e)||r.set(e,typeof i==`number`?(r.get(i)??0)+1:0);let d=`  `.repeat(r.get(e)??0);s!==`start`&&r.delete(e);let f=u===void 0?``:` [${u}]`,p=`${n}${f} ${d}${a} · ${o} ${s}`;s===`error`?t?.error(p,l):t?.debug(p,c)}},f=(e={})=>{let t=e.performance??globalThis.performance,n=/* @__PURE__ */ new Map;return({id:e,parentId:r,rootId:i,traceGroupId:a,type:o,effect:s,phase:c,error:l})=>{if(!t)return;if(c===`start`){n.set(e,t.now());return}let u=`${o} · ${s} (${c})`,d={id:e,parentId:r,...i!==void 0&&{rootId:i},...a!==void 0&&{traceGroupId:a},phase:c,...c===`error`&&{error:String(l)}},f=n.get(e);n.delete(e),typeof f==`number`?t.measure(u,{start:f,end:t.now(),detail:d}):t.mark(u,{detail:d})}};let p;const m=()=>p,h=(e,t)=>{let n=p;p=e;try{return t()}finally{p=n}},g=(e,t,n={})=>{let{trace:r}=e;if(!r){e.emit(t);return}let{traceId:a,traceGroupId:o}=n,{ctx:c,unlink:l}=i({event:{type:a??t.type,payload:t,...o===void 0?{}:{traceGroupId:o}},bus:{emit:e.emit,on:e.on,off:e.off,ctx:e.ctx,addContext:e.addContext},tracer:r});s(c,`run`,`start`);try{c.emit(t),s(c,`run`,`done`)}catch(e){throw s(c,`run`,`error`,e),e}finally{l()}},_=e=>typeof e==`string`?e:Reflect.get(Object(e),`type`),v=(e,t)=>typeof e==`object`?Reflect.get(Object(e),`payload`):t[0],y=()=>e=>{if(!(r&&e.trace))return e;let{trace:t}=e,i=(e,n)=>{let r=t.task({type:_(e),payload:v(e,n)},o());t.report(r,`emit`,`done`)},s=e.emit;e.emit=(e,...t)=>h(e,()=>(i(e,t),s(e,...t))),Reflect.set(e,l,(t,n)=>{g(e,t,n)});let c=/* @__PURE__ */ new WeakMap,u=(e,t,n)=>{let r=c.get(t)??/* @__PURE__ */ new Map,i=_(e);r.set(i,[...r.get(i)??[],n]),c.set(t,r)},d=(e,t)=>(c.get(t)?.get(_(e)))?.pop(),f=(e,t)=>(r,i)=>(n(i,t),a(i,`run`,()=>e(r,i))),p=(e,t)=>(n,r,i)=>{let a=Reflect.get(Object(i),`traceId`);if(typeof a!=`string`)return e(n,r,i);let o=t?(e,t)=>(d(n,r),f(r,a)(e,t)):f(r,a);u(n,r,o);let s=e(n,o,i);return()=>{s()}},m=e.off,y=(e,t)=>{t===void 0?m(e):m(e,d(e,t)??t)},b=e.on,x=e.once;return e.on=p(b,!1),e.once=p(x,!0),e.off=y,e},b=e=>{let t=e?.capacity??0,n=Number.isInteger(t)&&t>0?t:0,r=[],i=0,a=e=>{n===0?r.push(e):(r[i%n]=e,i+=1)},o=()=>{r.length=0,i=0},s=()=>{let e=Math.min(i,n),t=i>n?i%n:0,a=[];for(let i=0;i<e;i+=1){let e=r[(t+i)%n];e&&a.push(e)}return a},c=Object.assign(a,{clear:o,events:r});return n>0&&Object.defineProperty(c,"events",{get:s}),c},x=()=>{},S=/* @__PURE__ */ new Set([`cancel`,`drop`,`error`]),C=()=>!1,w=()=>!0,T=e=>{if(typeof e==`function`)return e;if(Array.isArray(e)){let t=new Set(e);return({phase:e})=>t.has(e)}return e?w:C},E=(e={})=>{let t=e.extension??globalThis.__REDUX_DEVTOOLS_EXTENSION__;if(!t)return x;let{starts:n=!1,depth:r=0,maxAge:i}=e,a=T(e.policies),o=e.payload??`essential`,s=t.connect({name:e.name??`nanoeffects`,...i!==void 0&&{maxAge:i}}),c=/* @__PURE__ */ new Map,l=/* @__PURE__ */ new Map,u=()=>({running:Object.fromEntries(c)});s.init(u());let d=(e,t,n)=>n===0?a({effect:e,phase:t}):n<=r,f=(e,t)=>{e.phase===`start`?(l.set(e.id,t),d(e.effect,`start`,t)&&c.set(e.id,{type:e.type,effect:e.effect,...e.traceGroupId!==void 0&&{traceGroupId:e.traceGroupId}})):(l.delete(e.id),c.delete(e.id))},p=!1,m=!1,h=(e,t)=>{p||m||t!==0||e===`start`||(m=!0,globalThis.console?.warn(`[nanoeffects] reduxDevtools got a task but no emit event: add bus.use(tracePlugin()) to see the emits.`))},g=e=>{let{payload:t,...n}=e;return o===`all`||o===`essential`&&(e.effect===`emit`||S.has(e.phase))?{...n,payload:t}:n},_=(e,t)=>{s.send({...g(e),type:`${e.type}/${e.effect}/${e.phase}`,event:e.type,...e.phase===`error`&&{error:t instanceof Error?t.message:t}},u())};return({error:e,...t})=>{if(t.effect===`emit`){p=!0,s.send({...g(t),event:t.type},u());return}let r=(t.parentId===void 0?-1:l.get(t.parentId)??-1)+1;f(t,r),h(t.phase,r),(t.phase===`error`&&r===0||d(t.effect,t.phase,r))&&(t.phase!==`start`||n)&&_(t,e)}},D=t=>{let n=typeof t==`function`?[t]:[...t??[]];return n.length===0?null:t=>{for(let r of n)try{r(t)}catch(t){e(`trace logger failed`,t)}}},O=()=>{},k=e=>{if(typeof e.traceGroupId==`string`)return e.traceGroupId;let t=m();if(typeof t!=`object`&&typeof t!=`function`||t===null)return;let n=Reflect.get(t,u),r=typeof n==`object`&&n?Reflect.get(n,`traceGroupId`):void 0;return typeof r==`string`?r:void 0},A=(e,n={})=>{let r=D(e),{filter:i,sample:a=1}=n,o=0,s=e=>typeof a==`function`?a({type:e.type,payload:e.payload}):Math.random()<a,l={task:(e,t)=>({id:++o,root:t?.root??o,parent:t?.id,type:e.type,payload:e.payload,sampled:t?.sampled??s(e),group:k(e)??t?.group}),rename:(e,t)=>{e.type=t},report:(e,t,n,a)=>{if(!e.sampled)return;let o={id:e.id,type:e.type,effect:t,phase:n,payload:e.payload};typeof e.parent==`number`&&(o.parentId=e.parent),e.root!==e.id&&(o.rootId=e.root),e.group!==void 0&&(o.traceGroupId=e.group),n===`error`&&(o.error=a),(!i||i(o))&&r?.(o)},settler:(e,t)=>{if(!e.sampled)return O;let n=!1;return(r,i)=>{n||(n=!0,l.report(e,t,r,i))}},run:(e,n,r,i)=>{if(!e.sampled)return i();let a=l.settler(e,n);l.report(e,n,`start`),t({signal:r},()=>a(`cancel`));let o;try{o=i()}catch(e){throw a(`error`,e),e}return c(o)?Promise.resolve(o).then(e=>(a(`done`),e),e=>{throw a(`error`,e),e}):(a(`done`),o)}};return l};export{d as consoleLogger,b as createTraceRecorder,A as createTracer,f as performanceLogger,E as reduxDevtools,y as tracePlugin};

package/dist/{types-Bf-LX_tE.d.ts → types-D5xsR37j.d.ts}

@@ -1,5 +1,5 @@
-import { H as EventMap, c as Scope, l as WithFields, p as Effects } from "./action-creator-D_c223C7.js";
-import { t as BoundOf } from "./plugin-vvkmIIz2.js";
+import { H as EventMap, c as Scope, l as WithFields, p as Effects } from "./action-creator-jeEqIKgK.js";
+import { t as BoundOf } from "./plugin-BaErevLy.js";
 //#region src/scope/types.d.ts
 /**
  * The slots `scopePlugin` fills for `modulePlugin`. They are not on `Bus`: a bus

package/dist/vue.d.ts

@@ -1,4 +1,4 @@
-import { D as EventKey, H as EventMap, a as FreeActionCreator, t as ActionCreator, v as Bus } from "./action-creator-D_c223C7.js";
+import { H as EventMap, T as EventKey, a as FreeActionCreator, t as ActionCreator, v as Bus } from "./action-creator-jeEqIKgK.js";
 import { t as OriginOptions } from "./origin-key-CxK0SkeG.js";
 import { t as StateOf } from "./state-of-C19H6BoV.js";
 import { ShallowRef, WatchSource, WatchStopHandle } from "vue";

package/dist/{with-policy-CPjx0sLm.d.ts → with-policy-BZVRBUOm.d.ts}

@@ -1,4 +1,4 @@
-import { G as PayloadOf, H as EventMap, q as Task } from "./action-creator-D_c223C7.js";
+import { G as PayloadOf, H as EventMap, q as Task } from "./action-creator-jeEqIKgK.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> = {

package/dist/{with-policy-D-SQRkPh.js → with-policy-C6BIiPIi.js}

@@ -1 +1 @@
-import{n as e}from"./context-UcmrAIhP.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};
+import{n as e}from"./context-DtUnzC-1.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

@@ -8,6 +8,18 @@ Why the library exists (logic and side effects outside React, Vue and Svelte com
 
 Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-checked and tested).
 
+## Start with three imports
+
+Most apps need only these. Everything else is optional; read it when you hit its need.
+
+| Import | Gives you |
+| ------ | --------- |
+| `nanoeffects` | `createBus`: `on`, `emit`, `ctx` |
+| `nanoeffects/policies` | `latest`, `debounce`, ... for races in async UI |
+| `nanoeffects/effects` | `retry`, `timeout`, `poll`, ... for an unreliable network |
+
+The other entries and plugins: [Package entries](package.md) and [Plugins](plugins.md#pick-a-plugin-by-task).
+
 ## Jump by project need
 
 | Project shape | First page |
@@ -19,6 +31,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 | Already on Redux / Zustand / MobX / Pinia | [Stores](stores.md) |
 | A Node server (Fastify) whose work must stop when the client leaves | [Stop work on a server](server.md) |
 | A React form with async checks | [Build a sign-up form in React](react.md) |
+| A site widget that listens only while open | [Build a chat widget](chat-widget.md) |
 | A Vue app | [Use nanoeffects in a Vue app](vue.md) |
 | A Svelte app | [Use nanoeffects in a Svelte app](svelte.md) |
 | Old responses overwrite new ones | [Cancel stale requests](cancel-stale-requests.md) |
@@ -39,7 +52,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 - [nanoeffects in a Svelte app](svelte.md) — `eventStore`
 - [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
+- [TypeScript in many files](typescript.md) — keep the types of the bus in actions and modules
 - [Errors and unheard events](errors.md)
 - [Package entries](package.md) — which import holds what
 - [Stability](stability.md) — which entries are stable, what is breaking, supported versions

package/docs/actions.md

@@ -10,6 +10,32 @@ A chat with two entities and three features, jobs under policies and effects, an
 
 A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
 
+## Pick the word: event, action, job, module
+
+Four names, one idea each. Take the first row that fits.
+
+| Word | What it is | Use it when |
+| ---- | ---------- | ----------- |
+| Event | A name and a payload; `createAction("x")` with no handler. | The UI or a handler tells that something happened. |
+| Action with a handler | The same, plus work: `createAction("x", handler)`. `emit` returns the result. | The caller needs a value back. |
+| Job | An action with a handler that also emits `pending`, `success`, `fail` and `cancel`. | The UI shows a loading state. |
+| Module | A group of listeners, handlers and tasks, mounted and unmounted with one call. | One domain must start and stop as a unit. |
+
+Start with events. Add a handler when you need a result, a job when you need a status, a module when you need a unit.
+
+## On this page
+
+- [Pick the word: event, action, job, module](#pick-the-word-event-action-job-module)
+- [Return a value from `emit` with a handler](#return-a-value-from-emit-with-a-handler)
+- [Describe events, handlers and jobs](#describe-events-handlers-and-jobs)
+  - [Actions](#actions)
+  - [Bind a handler later](#bind-a-handler-later)
+  - [Say what a bound handler returns](#say-what-a-bound-handler-returns)
+  - [Jobs](#jobs)
+- [Show a loading state with a job](#show-a-loading-state-with-a-job)
+- [Mount domains with modules](#mount-domains-with-modules)
+- [Give an action or a module its own fields](#give-an-action-or-a-module-its-own-fields)
+
 ## Return a value from `emit` with a handler
 
 Give `createAction` a handler, and `emit` runs it and returns its result. There is one creator for an event and for an action with work behind it; the handler is the only difference.
@@ -164,7 +190,7 @@ On a bus without an event map you can say it where you call: `const id = bus.emi
 - `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, give `createAction` the handler.
 - Outcome actions are emitted as the task that ran the job (also for a handler bound with `actions.handle`). `success` and `fail` are not sent after abort; `cancel` is, at the moment of the abort.
-- A job without a handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent. An action without a handler is an event and does not throw.
+- A job without a handler is not an outcome: `emit` throws `No handler for action "..."` and nothing is sent. An action without a handler is an event and does not throw.
 - 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.
 
@@ -326,7 +352,7 @@ If the `setup` of one module throws, the modules of that call that were already
 - **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(actionsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.actions` and `app.actions`.
 - A disposed app cannot mount modules.
-- **The given modules are mounted at the end of the block that made the app**, or at the first use of the app or the bus if that comes first (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`). Nothing needs to use the app: `bus.use(modulePlugin([a, b]))` is enough to start them. The plugins that you use after `modulePlugin` in the same block still reach them, because the modules wait until that block has finished. A plugin used after an `await` can come too late: use every plugin before the first `await`. 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).
+- **The given modules are mounted at the end of the block that made the app**, or at the first use of the app or the bus if that comes first (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `actions`). Nothing needs to use the app: `bus.use(modulePlugin([a, b]))` is enough to start them. The plugins that you use after `modulePlugin` in the same block still reach them, because the modules wait until that block has finished. A plugin used after an `await` can come too late: use every plugin before the first `await`. 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).
 - **To mount by hand instead**, pass no modules: `modulePlugin()` starts nothing, and `app.mount(...)` starts the modules when you want.
 - Module context = task context plus `handle`, `use`, and `spawn`:
   - `handle` — give an action a handler (one that has none, or an override).

package/docs/chat-example.md

@@ -14,6 +14,18 @@ npm run dev
 
 `npm run dev` starts the server and Vite together. Start it with `CHAOS=off npm run dev` to turn the failures off.
 
+## On this page
+
+- [Read how the server fails](#read-how-the-server-fails)
+- [See how the files are split](#see-how-the-files-are-split)
+- [Load a history that must not race](#load-a-history-that-must-not-race)
+- [Send a message that can fail](#send-a-message-that-can-fail)
+- [Search where one room is slow](#search-where-one-room-is-slow)
+- [Wait for a room before marking a result](#wait-for-a-room-before-marking-a-result)
+- [Poll for new messages](#poll-for-new-messages)
+- [Know where each value lives](#know-where-each-value-lives)
+- [Where to go next](#where-to-go-next)
+
 ## Read how the server fails
 
 The server keeps its data in memory. These rules are on purpose, and they are the same every run, so you can follow each section below by doing what the table says:
@@ -48,7 +60,7 @@ The code is in layers, and a file imports only from the layers below it. The com
 
 That rule is why `show-history` exists. Selecting a room must load its history, but `room` does not know `message` and `message` does not know `room`. The feature `show-history` is the one place that knows both: it listens to `rooms/selected` and starts the job `messages/loadHistory`. The same goes for a message that arrives: `receive-messages` emits `incoming/received`, an event that the `message` entity owns and listens to.
 
-A folder has its events (`room.ts`, which imports no bus), its work (`room-handlers.ts`), the state it keeps (`room-store.ts`) and a module (`room-module.ts`) that wires them. Another layer reaches an entity through its events and commands, never through its handlers or its store. Events and commands both live in the events file. An event (`createAction` with no handler) says that something happened, and any feature may listen: `rooms/selected` is heard by two. A command (`createAction` with a handler) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createAction`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
+A folder has its events (`room.ts`, which imports no bus), its work (`room-handlers.ts`), the state it keeps (`room-store.ts`) and a module (`room-module.ts`) that wires them. Another layer reaches an entity through its actions, never through its handlers or its store. All actions live in the events file. An action with no handler says that something happened, and any feature may listen: `rooms/selected` is heard by two. An action with a handler is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createAction`, so the action works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is an action with a handler that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
 
 The layers come from [Feature-Sliced Design](https://feature-sliced.design/), reduced to the three that an app of this size needs.
 
@@ -64,7 +76,7 @@ A job sends `pending` when its handler starts and exactly one of `success`, `fai
 // message.js
 import { createJob } from "nanoeffects/actions";
 
-// createJob — a command that also sends pending, success, fail and cancel
+// createJob — an action with a handler that also sends pending, success, fail and cancel
 export const loadHistory = createJob("messages/loadHistory");
 ```
 
@@ -195,7 +207,7 @@ export const goToResult = async (hit, ctx) => {
     ctx.emit("rooms/selected", hit.roomId);
     await loaded;
   }
-  // ctx.emit with a command — the message entity marks the message
+  // ctx.emit with an action that has a handler — the message entity marks the message
   ctx.emit(markMessage(hit.id));
 };
 ```
@@ -247,6 +259,6 @@ Each entity and each feature that has state keeps it in a [Zustand](https://zust
 
 ## Where to go next
 
-- The API of commands, jobs and modules: [Actions, jobs and modules](actions.md).
+- The API of actions, jobs and modules: [Actions, jobs and modules](actions.md).
 - Policies such as `latest` and `queue`: [Policies](policies.md). Effects such as `allSettled`, `take` and `poll`: [Effects](effects.md).
 - A smaller project with two domains: [Start with domains](starter.md#start-with-domains). Its two domains do not talk to each other, so it needs no layers.

package/docs/chat-widget.md

@@ -0,0 +1,135 @@
+# Build a chat widget that listens only while it is open
+
+Use this page when a site has a chat with a bot behind a launcher button, and the chat must cost nothing while it is closed. Closed means no subscriptions on the bus, no polling, no keyboard listener, and no request still running. Opening turns all of it on, and closing turns all of it off in one call.
+
+The code is in [`examples/chat-widget`](../examples/chat-widget): plain DOM and TypeScript, a fake bot in the browser, no server. Run it on [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat-widget), or on your machine:
+
+```bash
+cd examples/chat-widget
+npm install
+npm run dev
+```
+
+It is a level D example: the logic lives in one module, and the page only mounts and unmounts it. For an app with several features see [Build a chat with entities, features, modules and a small server](chat-example.md).
+
+## Know what happens on open and on close
+
+| Moment | What happens |
+| ------ | ------------ |
+| Open | The module is mounted: the bot handler is subscribed, the operator messages are polled, the `Escape` listener is added. The panel is drawn and listens to the bus. |
+| The user sends a text | The bot is asked, one text after another, with a time limit and a retry. |
+| `Escape` | The module emits `chat/closeRequested`; the launcher closes the chat. |
+| Close | The panel is removed and unsubscribed, the module is unmounted. A request in flight is aborted, the polling stops, the `Escape` listener goes away. |
+
+## Find the parts in the files
+
+| File | Job |
+| ---- | --- |
+| `src/bus.ts` | The bus, and `modulePlugin()` with no module: the launcher mounts the module itself. |
+| `src/chat.ts` | The events only: `messageSent`, `messageAdded`, `typingChanged`, `closeRequested`. |
+| `src/chat-handlers.ts` | `askBot` (`timeout` and `retry` inside) and `watchOperator` (`poll`): plain `async` functions that know nothing about the page. |
+| `src/chat-module.ts` | The list of what is alive while the chat is open. |
+| `src/panel.ts` | The view: shows the lines, sends the texts, returns one function that removes it. |
+| `src/main.ts` | The launcher: the only file that knows both the module and the panel; it listens for `closeRequested` only while the chat is open. |
+
+## Bind everything in one module
+
+A module is the list of what is alive while the chat is open. When it unmounts, the bus undoes every line of it.
+
+<!-- docs-check: skip - the other files of the example are in examples/chat-widget -->
+```js
+// chat-module.js
+import { createModule } from "nanoeffects/actions";
+import { queue } from "nanoeffects/policies";
+import { closeRequested, messageSent } from "./chat";
+import { askBot, watchOperator } from "./chat-handlers";
+
+// a task that stays pending until the module unmounts; its signal then aborts
+const untilAborted = (ctx) =>
+  new Promise((resolve) => {
+    ctx.signal.addEventListener("abort", resolve, { once: true });
+  });
+
+// a DOM listener that lives as long as the module: `signal` removes it when it aborts
+const listenToEscape = async (_, ctx) => {
+  const onKey = (event) => {
+    if (event.key === "Escape") {
+      ctx.emit(closeRequested());
+    }
+  };
+  document.addEventListener("keydown", onKey, { signal: ctx.signal });
+  await untilAborted(ctx);
+};
+
+export const chatModule = createModule("chat", (module) => {
+  // module.run — runs askBot as a child task of the module, so an unmount aborts it
+  const answer = (text) => module.run(askBot, text);
+  // on + queue — answer the texts one after another, in the order they were sent
+  module.on(messageSent, queue(answer));
+  // spawn — a background task that lives as long as the module
+  module.spawn(watchOperator);
+  module.spawn(listenToEscape);
+});
+```
+
+Three details that make the cleanup complete:
+
+- **`module.run`, not `askBot` directly.** A handler given to `module.on` runs as a child of whoever emitted the event (here the panel), so unmounting stops listening but does not abort a request that is already running. Running it with `module.run` makes it a child of the module.
+- **`queue`, not `latest`.** `queue` keeps the order when the user sends two texts fast. [`latest`](policies.md) would abort the first answer, which is wrong for a conversation.
+- **A DOM listener with `signal`.** `addEventListener` takes a `signal` option and removes the listener when it aborts. The task stays pending until then, because a task that has finished is not aborted again.
+
+## Open and close from the launcher
+
+`app.mount` returns the function that unmounts the module. `bus.on` returns the one that unsubscribes. The launcher puts them together with the one that removes the panel into a single `close`.
+
+<!-- docs-check: skip - the other files of the example are in examples/chat-widget -->
+```js
+// main.js
+import { app, bus } from "./bus";
+import { closeRequested } from "./chat";
+import { chatModule } from "./chat-module";
+import { renderPanel } from "./panel";
+
+const button = document.querySelector("#chat-launcher");
+let close = null; // set while the chat is open
+
+const open = () => {
+  const stopModule = app.mount(chatModule); // subscriptions, polling and Escape start
+  const stopPanel = renderPanel(document.body);
+  // the module emits closeRequested on Escape; nothing does while the chat is closed
+  const stopEscape = bus.on(closeRequested, () => close?.());
+  close = () => {
+    stopEscape();
+    stopPanel();
+    stopModule(); // everything the module started ends, a running request included
+    close = null;
+  };
+};
+
+button.addEventListener("click", () => {
+  if (close) {
+    close();
+  } else {
+    open();
+  }
+});
+```
+
+While the chat is closed the launcher holds no subscription at all: it only has the click listener of the button, which is a DOM listener, not a listener of the bus.
+
+## Check that closing cleans up
+
+1. Open the chat and send a text. The bot answers after about a second. Every third question fails, and the retry asks again.
+2. Send a text and close the chat before the answer arrives. No line appears, also when you open the chat again.
+3. Look at the box "Listeners on the bus": it shows `bus.get(event).length` for four events and updates when the chat opens or closes. Closed: every event shows `0`, and so does "all events". Open: each of the four has one listener, and "all events" is `4`. That is the proof that nothing is left subscribed.
+4. Wait 10 s with the chat closed. The operator is not polled: no line from the operator appears.
+5. Press `Escape` with the chat closed. Nothing happens. Open the chat and press it again: it closes.
+6. Open the chat again. The old lines are back, and the polling runs.
+
+`src/tests/chat-widget-example.test.ts` checks the same points without a browser.
+
+## Where to go next
+
+- Show an unread count on the launcher while the chat is closed: a second module that stays mounted and listens only to `chat/messageAdded`.
+- Replace the polling by a WebSocket in a spawned task: the abort closes it the same way (see [`examples/trades`](../examples/trades) for a socket under `retry` and `latest`).
+- Watch the whole thing in the [trace](tracing.md): the module, the bot task, the retries and the polling are tasks of one tree.

package/docs/context.md

@@ -21,7 +21,7 @@ Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may
 
 To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
 
-To give fields to **one** command, action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
+To give fields to **one** action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
 
 ## Type the fields (optional)
 
@@ -45,6 +45,38 @@ bus.on("save", (draft, { store }) => store.put(draft));
 - 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 }))`.
 
+## Build a field from the signal of each task
+
+Problem: an HTTP client or a database handle should stop when the task is aborted. Without help, every handler passes `ctx.signal` to it by hand, and one forgotten call leaves a request running.
+
+`fromSignal(make)` from `nanoeffects/signal` marks a field of `contextPlugin` as a value that is built from the signal of the task. It does not run `make` for the bus: it runs it for each task that reads the field, once, with the `ctx.signal` of that task.
+
+```js
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal } from "nanoeffects/signal";
+import axios from "axios";
+
+// contextPlugin — every task gets these fields
+// fromSignal — http is made from the signal of the task that reads ctx.http
+const bus = createBus().use(
+  contextPlugin({
+    logger: console, // a plain field: the same object for every task
+    http: fromSignal((signal) => axios.create({ signal })),
+  }),
+);
+
+bus.on("user/open", async (id, ctx) => {
+  const response = await ctx.http.get(`/users/${id}`); // aborts with the task
+  ctx.logger.log(response.data);
+});
+```
+
+- `make` runs at the first read, so a handler that never uses `ctx.http` pays nothing for it.
+- A task that `ctx.run` starts builds its own value from its own signal, so aborting the child stops only the child's requests.
+- The field is not copied by `{ ...ctx }` and `Object.keys(ctx)` does not list it. Read `ctx.http` first if you copy a context.
+- Without `contextPlugin` a `fromSignal` marker is only an object.
+
 ### 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.