nanoeffects 0.3.0 → 0.5.0

package/dist/notrace/redux.d.ts

@@ -1,4 +1,4 @@
-import { k as EventMap, o as Bus, s as BusOptions } from "./action-Bdfp-Wvd.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/notrace/redux.js

@@ -1 +1 @@
-import{c as e}from"./context-yAWj0BFZ.js";import{t}from"./bus-Dx0l9X6h.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/observable.d.ts

@@ -1,4 +1,4 @@
-import { A as Keys, k as EventMap, o as Bus } from "./action-Bdfp-Wvd.js";
+import { _ as Bus, o as EventMap, s as Keys } from "./action-creator-DOWcbXpy.js";
 //#region src/observable.d.ts
 declare global {
   interface SymbolConstructor {

package/dist/policies.d.ts

@@ -1,4 +1,4 @@
-import { N as Task, k as EventMap } from "./action-Bdfp-Wvd.js";
+import { o as EventMap, u as Task } from "./action-creator-DOWcbXpy.js";
 //#region src/policies/keyed.d.ts
 /** Options shared by every policy that can keep its state per key. */
 type KeyOption<P> = {

package/dist/policies.js

@@ -1 +1 @@
-import{t as e}from"./onAbort-BgMfspK4.js";import{a as t,i as n,o as r,t as i}from"./context-DlA80GOA.js";import{n as a,r as o,t as s}from"./delay-CIHnOh_L.js";import{n as c,t as l}from"./promise-CSLpzwSR.js";const u=()=>{},d=(e,t)=>{let n=/* @__PURE__ */ new Map;return(r,i)=>{let a=e(r),o=n.get(a);if(!o){let e=t(()=>{n.get(a)===e&&n.delete(a)});o=e,n.set(a,e)}return o(r,i)}},f=(e,t)=>e?d(e,t):t(u),p=(e,t={})=>f(t.key,t=>m(`latest`,(t,n,r)=>(r(),e(t,n)),t)),m=(t,a,o=u)=>{let s=null;return(l,u)=>{if(s?.abort(),u.signal.aborted)return;let{ctx:d,unlink:f}=n(u);s=d;let p=i(d,t),m=!1,h=()=>{d.signal.aborted||(m=!0,r(d,t,`start`))};e(d,()=>p(m?`cancel`:`drop`));let g=()=>{f(),s===d&&(s=null,o())},_=e=>{if(!d.signal.aborted)return p(m?`done`:`drop`),e};try{let e=a(l,d,h);return c(e)?Promise.resolve(e).then(_,e=>{if(!d.signal.aborted)throw p(`error`,e),e}).finally(g):(g(),_(e))}catch(e){if(g(),d.signal.aborted)return;throw p(`error`,e),e}}},h=(e,t,n={})=>f(n.key,r=>_(e,t,n,r)),g=(e,n,i,s)=>{let c=s!==u,l=null,d=null;return(u,f)=>{if(f.signal.aborted)return;let p=Date.now(),m=l===null||p-l>=e||p-l<0;return l=p,d!==null&&a(d),d=c?o(s,e):null,i&&m?Promise.resolve(t(f,`debounce`,()=>n(u,f))):(r(f,`debounce`,`drop`),Promise.resolve(void 0))}},_=(n,r,i,a)=>{let o=i.leading??!1,c=i.trailing??!0;if(!c)return g(n,r,o,a);let l=!1,u=0,d=m(`debounce`,([t,i],a,o)=>{let d=u;return e(a,()=>{u===d&&(l=!1)}),s(a,n).then(()=>{if(l=!1,c&&!i)return o(),r(t,a)})},a);return(e,n)=>{if(n.signal.aborted)return;let i=o&&!l;l=!0,u++;let a=d([e,i],n);return i?Promise.resolve(t(n,`debounce`,()=>r(e,n))):a}},v=(n,i={})=>f(i.key,i=>{let a=null;return(o,s)=>{if(s.signal.aborted)return;if(a){r(s,`leading`,`drop`);return}let c={};a=c;let u=()=>{d(),a===c&&(a=null,i())},d=e(s,u);try{return l(t(s,`leading`,()=>n(o,s)),u)}catch(e){throw u(),e}}}),y=(e,t={})=>f(t.key,n=>b(e,t,n)),b=(n,i,a)=>{let o=i.concurrency??1,s=i.limit??1/0,c=[],l=0,d=()=>{for(;l<o;){let e=c.shift();if(!e)return;e.start()}};return(f,p)=>new Promise((m,h)=>{if(p.signal.aborted){m(void 0);return}let g=u,_=()=>{g(),r(p,`queue`,`drop`),m(void 0)},v=()=>{if(g(),p.signal.aborted){_();return}l++;let r=!0,i=()=>{r&&(r=!1,l--,d(),l===0&&c.length===0&&a())},o=e(p,()=>{i(),m(void 0)}),s;try{s=Promise.resolve(t(p,`queue`,()=>n(f,p)))}catch(e){s=Promise.reject(e)}let u=()=>{o(),i()};s.then(e=>{u(),m(p.signal.aborted?void 0:e)},e=>{u(),p.signal.aborted?m(void 0):h(e)})};if(l<o){v();return}if(c.length>=s){if(i.overflow!==`drop-old`||s<=0){_();return}c.shift()?.drop()}let y={start:v,drop:_};c.push(y),g=e(p,()=>{let e=c.indexOf(y);e>=0&&c.splice(e,1),_()})})},x=(e,t,n={})=>f(n.key,r=>S(e,t,n,r)),S=(e,n,i,s)=>{let c=i.leading??!0,l=i.trailing??!0,d=s!==u,f=null,p=0,m=null,h=null,g=null,_=!1,v=t=>f===null||t-f>=e||t-f<0||t-p>=e,y=e=>r(e,`throttle`,`drop`),b=()=>{let e=g;g=null,e&&(y(e.ctx),e.resolve())},x=(e,t)=>(b(),new Promise((n,r)=>{g={payload:e,ctx:t,resolve:n,reject:r}})),S=(e,r,i)=>{b(),p=i,_=!0;try{return t(r,`throttle`,()=>n(e,r))}finally{_=!1}},C=()=>{d&&(h=o(w,e))},w=()=>{if(h=null,!d||m!==null||g)return;let t=Date.now(),n=Math.max(e-(t-(f??-1/0)),e-(t-p));n<=0?s():h=o(w,n)},T=e=>{m=null;let t=g;if(l&&t&&!t.ctx.signal.aborted){g=null;try{t.resolve(S(t.payload,t.ctx,e))}catch(e){t.reject(e)}}else b();w()},E=()=>{let t=Date.now();v(t)?T(t):m=o(E,Math.min(e-(t-(f??t)),e-(t-p)))},D=()=>{h!==null&&(a(h),h=null)},O=(e,t)=>{if(!l)y(t);else return x(e,t)},k=(e,t,n,r)=>{if(!r)y(t);else if(p=n,C(),!c)y(t);else return S(e,t,n)},A=(t,n,r,i)=>i&&m!==null?(a(m),m=o(E,e),S(t,n,r)):m===null&&(m=o(E,e),i&&(p=r,c))?S(t,n,r):O(t,n);return(e,t)=>{if(t.signal.aborted)return;let n=Date.now(),r=!_&&v(n);return f=n,D(),l?A(e,t,n,r):k(e,t,n,r)}};export{h as debounce,p as latest,v as leading,y as queue,x as throttle};
+import{t as e}from"./onAbort-BgMfspK4.js";import{a as t,i as n,o as r,t as i}from"./context-CK0ZomWt.js";import{n as a,r as o,t as s}from"./delay-CIHnOh_L.js";import{n as c,t as l}from"./promise-CSLpzwSR.js";const u=()=>{},d=(e,t)=>{let n=/* @__PURE__ */ new Map;return(r,i)=>{let a=e(r),o=n.get(a);if(!o){let e=t(()=>{n.get(a)===e&&n.delete(a)});o=e,n.set(a,e)}return o(r,i)}},f=(e,t)=>e?d(e,t):t(u),p=(e,t={})=>f(t.key,t=>m(`latest`,(t,n,r)=>(r(),e(t,n)),t)),m=(t,a,o=u)=>{let s=null;return(l,u)=>{if(s?.abort(),u.signal.aborted)return;let{ctx:d,unlink:f}=n(u);s=d;let p=i(d,t),m=!1,h=()=>{d.signal.aborted||(m=!0,r(d,t,`start`))};e(d,()=>p(m?`cancel`:`drop`));let g=()=>{f(),s===d&&(s=null,o())},_=e=>{if(!d.signal.aborted)return p(m?`done`:`drop`),e};try{let e=a(l,d,h);return c(e)?Promise.resolve(e).then(_,e=>{if(!d.signal.aborted)throw p(`error`,e),e}).finally(g):(g(),_(e))}catch(e){if(g(),d.signal.aborted)return;throw p(`error`,e),e}}},h=(e,t,n={})=>f(n.key,r=>_(e,t,n,r)),g=(e,n,i,s)=>{let c=s!==u,l=null,d=null;return(u,f)=>{if(f.signal.aborted)return;let p=Date.now(),m=l===null||p-l>=e||p-l<0;return l=p,d!==null&&a(d),d=c?o(s,e):null,i&&m?Promise.resolve(t(f,`debounce`,()=>n(u,f))):(r(f,`debounce`,`drop`),Promise.resolve(void 0))}},_=(n,r,i,a)=>{let o=i.leading??!1,c=i.trailing??!0;if(!c)return g(n,r,o,a);let l=!1,u=0,d=m(`debounce`,([t,i],a,o)=>{let d=u;return e(a,()=>{u===d&&(l=!1)}),s(a,n).then(()=>{if(l=!1,c&&!i)return o(),r(t,a)})},a);return(e,n)=>{if(n.signal.aborted)return;let i=o&&!l;l=!0,u++;let a=d([e,i],n);return i?Promise.resolve(t(n,`debounce`,()=>r(e,n))):a}},v=(n,i={})=>f(i.key,i=>{let a=null;return(o,s)=>{if(s.signal.aborted)return;if(a){r(s,`leading`,`drop`);return}let c={};a=c;let u=()=>{d(),a===c&&(a=null,i())},d=e(s,u);try{return l(t(s,`leading`,()=>n(o,s)),u)}catch(e){throw u(),e}}}),y=(e,t={})=>f(t.key,n=>b(e,t,n)),b=(n,i,a)=>{let o=i.concurrency??1,s=i.limit??1/0,c=[],l=0,d=()=>{for(;l<o;){let e=c.shift();if(!e)return;e.start()}};return(f,p)=>new Promise((m,h)=>{if(p.signal.aborted){m(void 0);return}let g=u,_=()=>{g(),r(p,`queue`,`drop`),m(void 0)},v=()=>{if(g(),p.signal.aborted){_();return}l++;let r=!0,i=()=>{r&&(r=!1,l--,d(),l===0&&c.length===0&&a())},o=e(p,()=>{i(),m(void 0)}),s;try{s=Promise.resolve(t(p,`queue`,()=>n(f,p)))}catch(e){s=Promise.reject(e)}let u=()=>{o(),i()};s.then(e=>{u(),m(p.signal.aborted?void 0:e)},e=>{u(),p.signal.aborted?m(void 0):h(e)})};if(l<o){v();return}if(c.length>=s){if(i.overflow!==`drop-old`||s<=0){_();return}c.shift()?.drop()}let y={start:v,drop:_};c.push(y),g=e(p,()=>{let e=c.indexOf(y);e>=0&&c.splice(e,1),_()})})},x=(e,t,n={})=>f(n.key,r=>S(e,t,n,r)),S=(e,n,i,s)=>{let c=i.leading??!0,l=i.trailing??!0,d=s!==u,f=null,p=0,m=null,h=null,g=null,_=!1,v=t=>f===null||t-f>=e||t-f<0||t-p>=e,y=e=>r(e,`throttle`,`drop`),b=()=>{let e=g;g=null,e&&(y(e.ctx),e.resolve())},x=(e,t)=>(b(),new Promise((n,r)=>{g={payload:e,ctx:t,resolve:n,reject:r}})),S=(e,r,i)=>{b(),p=i,_=!0;try{return t(r,`throttle`,()=>n(e,r))}finally{_=!1}},C=()=>{d&&(h=o(w,e))},w=()=>{if(h=null,!d||m!==null||g)return;let t=Date.now(),n=Math.max(e-(t-(f??-1/0)),e-(t-p));n<=0?s():h=o(w,n)},T=e=>{m=null;let t=g;if(l&&t&&!t.ctx.signal.aborted){g=null;try{t.resolve(S(t.payload,t.ctx,e))}catch(e){t.reject(e)}}else b();w()},E=()=>{let t=Date.now();v(t)?T(t):m=o(E,Math.min(e-(t-(f??t)),e-(t-p)))},D=()=>{h!==null&&(a(h),h=null)},O=(e,t)=>{if(!l)y(t);else return x(e,t)},k=(e,t,n,r)=>{if(!r)y(t);else if(p=n,C(),!c)y(t);else return S(e,t,n)},A=(t,n,r,i)=>i&&m!==null?(a(m),m=o(E,e),S(t,n,r)):m===null&&(m=o(E,e),i&&(p=r,c))?S(t,n,r):O(t,n);return(e,t)=>{if(t.signal.aborted)return;let n=Date.now(),r=!_&&v(n);return f=n,D(),l?A(e,t,n,r):k(e,t,n,r)}};export{h as debounce,p as latest,v as leading,y as queue,x as throttle};

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 { k as EventMap, o as Bus, s as BusOptions } from "./action-Bdfp-Wvd.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{t}from"./bus-CRnlwmQ4.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 { E as Tracer, F as TraceEvent, I as TraceLogger, P as Trace } from "./action-Bdfp-Wvd.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

@@ -1,15 +1,36 @@
 # Documentation
 
-Start with the [Guide](guide.md): from a bare bus to modules, one step at a time. The pages below are the reference.
+## Start here
 
-- [Guide](guide.md)
-- [Policies](policies.md): `latest`, `leading`, `debounce`, `throttle`, `queue`, `key`
-- [Effects and cancellation](effects.md): `retry`, `timeout`, `poll`, `take`, `all`, `allSettled`, `race`, `ctx.on`
+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.
+
+Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-checked and tested).
+
+## Jump by project need
+
+| Project shape | First page |
+| ------------- | ---------- |
+| Small app / widget (rare races) | [Guide § Create a bus](guide.md#1-create-a-bus) |
+| 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 / 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)
-- [Your own fields in the context](context.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)
-- [Tracing](tracing.md): loggers, Redux DevTools, sampling, the `notrace` build
-- [Redux, Zustand, MobX](stores.md)
-- [Observable: events as streams](observable.md): `createObserve` for RxJS and friends
-- [Hot reload and dev diagnostics](hmr.md): modules replaced by name, `devPlugin`
+- [Package entries](package.md) — which import holds what
+- [Tracing](tracing.md) — loggers, Redux DevTools, `notrace`
+- [Observable](observable.md) — events as TC39 Observables
+- [Hot reload and dev diagnostics](hmr.md)
 - [Semantics](semantics.md)

package/docs/actions.md

@@ -1,68 +1,141 @@
 # Actions, commands, jobs and modules
 
-## Actions, commands and jobs
+Use this page when **domain logic lives on the bus**, off the UI: the UI emits and listens; handlers and modules own the work.
 
-`nanoeffects/actions` has the pieces to describe what a bus does, apart from the code that does it.
+If you only need `on` / `emit` or policies, stay in the [Guide](guide.md) until you need a result from `emit` or a mountable domain.
 
-```ts
+Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
+
+## Return a value from `emit` with a command
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+
+const bus = createBus();
+
+// createCommand — emit runs the handler and returns its result
+const double = createCommand("math/double", (value) => value * 2);
+bus.emit(double(21)); // 42
+```
+
+## Describe events, commands, and jobs
+
+`nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
+
+```js
 import { createAction, createCommand, createJob } from "nanoeffects/actions";
 
-// an event with a payload, as in Redux Toolkit
-// the payload types come from the event map of the bus: type Events = { "user/loaded": User; "user/failed": Error }
+// createAction — event with a payload (like RTK createAction)
 const userLoaded = createAction("user/loaded");
 const loadFailed = createAction("user/failed");
 
-// a request for a result: emit it and get what its handler returns
-const getUser = createCommand("user/get", (id: string, { signal }) => fetchUser(id, { signal }));
+// createCommand with a handler — emit returns what the handler returns
+const getUser = createCommand("user/get", (id, { signal }) => {
+  return fetchUser(id, { signal });
+});
 
-// a contract without a handler: the code that sends mail is elsewhere
-const sendMail = createCommand<Mail, void>("mail/send");
+// createCommand without a handler — a contract; register the work elsewhere
+const sendMail = createCommand("mail/send");
 
-// a command whose outcome is sent on as actions: they are its properties, loadUser.success and loadUser.fail
+// createJob — command that also emits success / fail actions
 const loadUser = createJob("user/load", fetchUser, {
-  success: userLoaded, // an action creator that exists: used and returned as it is
-  fail: "user/failed", // a string: the job makes the action creator
+  success: userLoaded,
+  fail: "user/failed",
 });
 ```
 
-**Actions.** `createAction(type)` returns a creator, with no generics: it keeps the literal type, and the bus checks the payload against its event map (`bus.emit(userLoaded(5))` is an error when `"user/loaded"` is a `User`). Without an event map give the payload type, `createAction<User>("user/loaded")`. The creator: `userLoaded(user)` is `{ type, payload }`, `userLoaded.type` is the type, `userLoaded.match(action)` narrows an action. `createAction(type, prepare)` builds the payload from several arguments. A creator works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`.
+### 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")`.
+
+- `userLoaded(user)` → `{ type, payload }`
+- `userLoaded.type` — the type string
+- `userLoaded.match(action)` — narrows an action
+- `createAction(type, prepare)` — build the payload from several arguments
+- Works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`
 
-**Commands.** `bus.emit(command, payload)` tells the listeners of the command's type, then runs its handler as a task, with a context, and returns the result. The handler can be wrapped in a policy, `createCommand("search", latest(fn))`. Calling `command(payload)` runs its own handler without a bus. `command.match(action)` tells whether an action has the command's type and narrows it, as `match` of an action creator does.
+### Commands
 
-**Where handlers are registered.** The command may carry a handler. The bus gets the handlers bound to commands from a registry, `commandsPlugin`, and a handler bound there wins over the command's own. The registry belongs to one bus, as an effector scope does with `fork({ handlers })`, so each bus (each test) can have its own.
+Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(command(payload))` (or `bus.emit(command, payload)`) tells the listeners of the command’s type, then runs its handler as a task and returns the result.
 
-```ts
-import { commandsPlugin, bindHandler } from "nanoeffects/actions";
+- Wrap the handler in a policy: `createCommand("search", latest(fn))`.
+- `command.match(action)` narrows like an action creator’s `match`.
 
-const bus = createBus<Events>();
-const commands = bus.use(commandsPlugin([bindHandler(sendMail, smtpSend)])); // attached to the bus
+**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.
 
-const unbind = commands.handle(getUser, async () => fakeUser); // later, e.g. in a test
-unbind(); // the command's own handler is back; the latest binding wins
+```js
+import { createBus } from "nanoeffects";
+import {
+  bindHandler,
+  commandsPlugin,
+  createCommand,
+} from "nanoeffects/actions";
+
+const sendMail = createCommand("mail/send");
+const getUser = createCommand("user/get");
+
+const bus = createBus();
+
+// commandsPlugin — registry of handlers for this bus
+const commands = bus.use(
+  commandsPlugin([bindHandler(sendMail, smtpSend)]),
+);
+
+// later, e.g. in a test — latest binding wins
+const unbind = commands.handle(getUser, async () => fakeUser);
+unbind();
 ```
 
-A command with no handler anywhere throws `No handler for command "..."` from `emit`. The registry lives in `nanoeffects/actions`, so a bus without one carries none of this code; without it `emit(command, payload)` simply runs the command's own handler. `bus.use(commandsPlugin())` sets the registry as `bus.commands`, and a second one on the same bus replaces it. There is no `commands` option in `createBus`; a custom runner is assigned, `bus.commands = { run }`.
+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 }`.
+
+### 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.
+
+- 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`.
+- `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 "..."`.
+- Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
+
+## Mount domains with modules
+
+**Problem.** A domain needs several subscriptions and command bindings. With plain `bus.on` / `commands.handle` you must remember every unsubscribe.
 
-**Jobs.** `createJob(type, handler, { success, fail })` makes a command that sends its outcome on as actions, for when nobody waits for the result, and returns the command itself, with the two actions on it: `loadUser.success` and `loadUser.fail`. When the handler succeeds, `loadUser.success(result)` is emitted on the bus, and when it fails, `loadUser.fail(error)`.
+**When.** You want one mount / one unmount for that domain. Skip modules while a few top-level `bus.on` calls are enough.
 
-- `success` and `fail` are a string, from which the job makes an action creator with `createAction` (the payload is the result, or the error), or an action creator that exists already, which is used and returned as it is. A missing one is made with the type `<type>/success` or `<type>/fail`.
-- `bus.emit(command, payload)` returns a promise of the result. An error of the handler always counts as handled: it goes to `loadUser.fail` and the promise resolves with `undefined`. For a result that must reject, use a command.
-- The actions are emitted as the task that ran the job, also for a handler bound with `commands.handle`, and are not sent once the task is aborted. A missing handler is not an outcome: `emit` throws `No handler for command "..."`.
-- Calling `command(payload)` directly runs only the handler.
+`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)).
 
-## Modules
+```js
+import { createBus } from "nanoeffects";
+import {
+  createCommand,
+  createModule,
+  modulePlugin,
+} from "nanoeffects/actions";
 
-`bus.use(modulePlugin(modules))`, with `modulePlugin` from `nanoeffects/actions`, assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose` and `commands`, the registry of command handlers. A module is what a domain of the app needs: the commands it handles, the events it listens to, its sub-modules and its background tasks.
+const getUser = createCommand("user/get");
+const saveUser = createCommand("user/save", persistUser);
 
-```ts
-const userModule = createModule<Events>("user", (m) => {
-  m.handle(getUser, fetchUser); // a contract gets its handler here
-  m.use(saveUser, authModule); // a command that carries a handler, and a sub-module
-  m.on("login", (user, ctx) => ctx.emit("loaded", user));
-  m.spawn(async (_, ctx) => { /* background work, ends with the module */ });
+// createModule — one domain; unmount undoes everything below
+const userModule = createModule("user", (m) => {
+  m.handle(getUser, fetchUser);
+  m.use(saveUser, authModule);
+  m.on("login", (user, ctx) => {
+    ctx.emit("loaded", user);
+  });
+  m.spawn(async (_, ctx) => {
+    /* background work; ends when the module unmounts */
+  });
 });
 
-const bus = createBus<Events>();
+const bus = createBus();
+// modulePlugin — mount modules on the bus
 const app = bus.use(modulePlugin([userModule]));
 
 const unmount = app.mount(orderModule); // later, e.g. after a lazy import
@@ -70,9 +143,12 @@ app.commands.handle(getUser, fakeUser); // in a test
 app.dispose(); // unmounts every module
 ```
 
-- **Unmounting undoes everything** the module did: its subscriptions, its bound commands, its sub-modules and its background tasks, which are aborted.
-- **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one. That is what hot reload needs: see [hmr.md](hmr.md).
-- **The registry.** If `bus.use(commandsPlugin())` was called, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`, so the commands that modules bind are the ones the bus runs.
+- **Unmounting undoes everything** the module did: subscriptions, bound commands, sub-modules, and background tasks (aborted).
+- **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.
-- A module context is a task context plus `handle` (give a command a handler: for a contract, or to override), `use` (bring sub-modules and commands that carry a handler: `m.use(getUser, saveUser, subModule)`, in any order; the returned function undoes just that call) and `spawn` (a background task, aborted on unmount).
-- A command that carries a handler keeps answering after its module is unmounted: the handler is its own, and `use` only brings the command and tracks it in the registry. Use `handle` for a handler that should live only as long as the module.
+- 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.
+  - `spawn` — background task, aborted on unmount.
+- A command that carries a handler keeps answering after unmount (`use` only tracks registration). Use `handle` for a handler that must live only as long as the module.

package/docs/context.md

@@ -1,15 +1,56 @@
-# Your own fields in the context
+# Put your own fields on every task
 
-Add fields to the context of every task of a bus: a store, a client, a logger. Describe them in the event map with `WithContext`, and give the values in `createBus({ context })`:
+Optional: put a store, client, or logger on every task. Skip until many handlers need the same dependency.
+
+## Pass values at runtime
+
+```js
+import { createBus } from "nanoeffects";
+
+// createBus({ context }) — every task gets these fields
+const bus = createBus({ context: { store } });
+
+bus.on("save", (draft, { store }) => {
+  store.put(draft);
+});
+```
+
+That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, commands, modules, and child tasks of effects and policies.
+
+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)
+
+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
-type Events = { save: Draft } & WithContext<{ store: Store }>;
+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 }));
 
-const bus = createBus<Events>({ context: { store } });
 bus.on("save", (draft, { store }) => store.put(draft));
 ```
 
-The fields are in the context of handlers, `ctx.run`, listeners added with `ctx.on`, commands, modules and the child tasks of effects and policies, and the compiler checks them: a handler of a bus without `WithContext` has no `store`, and `context` must have the fields that the map names. Two buses can have different fields.
+- 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 }))`.
 
-- The fields of the library (`signal`, `emit`, `run`, ...) win when the names are the same.
-- `context` can also be a function, `(task) => fields`, called with `{ type, payload }` of each task, for fields that depend on the task.
+### 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 }>;
+
+const bus = createBus<Events>({ context: { store } });
+```