nanoeffects 0.4.0 → 0.6.0

package/dist/plugin-CCYlC0XS.d.ts

@@ -0,0 +1,207 @@
+import { B as EventMap, N as WithContext, V as Keys, b as Context, d as Effects, h as Bus, l as BoundForm } from "./action-creator-c292nK7v.js";
+import { n as NoClash } from "./context-plugin-1pYmSQEG.js";
+//#region src/utils/delay.d.ts
+/**
+ * Resolves after `ms`, or rejects early if `ctx.signal` aborts. `ms` can be a
+ * function that returns the number of ms, called once when the delay starts:
+ * handy for a random pause (jitter).
+ *
+ * @example
+ * ```ts
+ * await delay({}, 500);
+ *
+ * // 200 to 400 ms
+ * await delay({}, () => 200 + Math.random() * 200);
+ *
+ * // inside a task: stops waiting when the task is aborted
+ * bus.on("retry", async (_, ctx) => {
+ *   await delay(ctx, 1000);
+ *   await load();
+ * });
+ * ```
+ */
+declare const delay: (ctx: {
+  signal?: AbortSignal | undefined;
+}, ms: number | (() => number)) => Promise<void>;
+//#endregion
+//#region src/effects/run.d.ts
+/** Context passed into `race` / `all` effect starters. */
+type EffectContext = {
+  signal: AbortSignal;
+  abort: (reason?: unknown) => void;
+};
+type Starter<T> = (ctx: EffectContext) => T | PromiseLike<T>;
+//#endregion
+//#region src/effects/all.d.ts
+/**
+ * Runs all starters; waits for every result. On failure or parent abort, cancels the rest.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const { user, posts } = await all(ctx, {
+ *     user: ({ signal }) => fetchUser(id, { signal }),
+ *     posts: ({ signal }) => fetchPosts(id, { signal }),
+ *   });
+ *
+ *   // arrays work too: const [user, posts] = await all(ctx, [getUser, getPosts]);
+ * });
+ * ```
+ */
+declare function all<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+declare function all<const T extends readonly Starter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+//#endregion
+//#region src/effects/allSettled.d.ts
+/**
+ * Runs all starters and waits for every one to settle, whether it succeeds or
+ * fails: nothing is cancelled when a starter fails. The result has, for each
+ * starter, `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`.
+ * Only an abort of `ctx` rejects it, with the abort reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const { user, posts } = await allSettled(ctx, {
+ *     user: ({ signal }) => fetchUser(id, { signal }),
+ *     posts: ({ signal }) => fetchPosts(id, { signal }),
+ *   });
+ *
+ *   if (user.status === "fulfilled") render(user.value);
+ * });
+ * ```
+ */
+declare function allSettled<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+declare function allSettled<const T extends readonly Starter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+//#endregion
+//#region src/effects/race.d.ts
+type RaceStarter<T> = Starter<T>;
+/**
+ * Runs all starters; first to settle wins, losers are cancelled via `ctx.abort`.
+ * The result holds only the winner's value, under its key or index.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const result = await race(ctx, {
+ *     data: ({ signal }) => fetchData(id, { signal }),
+ *     timeout: ({ signal }) => delay({ signal }, 5000),
+ *   });
+ *
+ *   if ("timeout" in result) throw new Error("timed out");
+ *   render(result.data);
+ * });
+ * ```
+ */
+declare function race<T extends Record<string, RaceStarter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+declare function race<const T extends readonly RaceStarter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+//#endregion
+//#region src/effects/take.d.ts
+type TakeOptions<P> = {
+  /**
+   * Wait for the first payload this accepts; others are skipped. A type guard
+   * (`(payload): payload is T`) narrows the type of the result to `T`.
+   */
+  predicate?: (payload: P) => boolean;
+  /** Stop waiting when this aborts, e.g. the signal of a `race` starter. */
+  signal?: AbortSignal | undefined;
+};
+/**
+ * Waits for the next `event` on the bus and resolves with its payload. It sees
+ * only events emitted after the call, takes only one, and unsubscribes when it
+ * is done. If `ctx` (or `options.signal`) aborts first, it unsubscribes and
+ * rejects with the abort reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("login", async (user, ctx) => {
+ *   const reason = await take(ctx, "logout");
+ *   cleanup(user, reason);
+ * });
+ *
+ * // wait for a matching event, but not longer than 5 s
+ * const done = await timeout(ctx, 5000, ({ signal }) =>
+ *   take(ctx, "saved", { signal, predicate: (id) => id === draftId }),
+ * );
+ *
+ * // a type guard narrows the result: `failed` is `{ ok: false }`
+ * const failed = await take(ctx, "result", {
+ *   predicate: (result): result is { ok: false } => !result.ok,
+ * });
+ * ```
+ */
+declare function take<E extends EventMap, K extends Keys<E>, T extends E[K]>(ctx: Context<E>, event: K, options: TakeOptions<E[K]> & {
+  predicate: (payload: E[K]) => payload is T;
+}): Promise<T>;
+declare function take<E extends EventMap, K extends Keys<E>>(ctx: Context<E>, event: K, options?: TakeOptions<E[K]>): Promise<E[K]>;
+//#endregion
+//#region src/effects/plugin.d.ts
+/** The effects that `effectsPlugin` can put on `ctx`. */
+type Supported = {
+  race: typeof race;
+  all: typeof all;
+  allSettled: typeof allSettled;
+  take: typeof take;
+  delay: typeof delay;
+};
+type Results = Record<string, Starter<unknown>>;
+type List = readonly Starter<unknown>[];
+/** Each supported effect without its leading `ctx` argument. `take` knows the events of the bus. */
+type Bound<E extends EventMap> = {
+  race: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+  };
+  all: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+  };
+  allSettled: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+  };
+  take: <K extends Keys<E>>(event: K, options?: TakeOptions<E[K]>) => Promise<E[K]>;
+  delay: (ms: number | (() => number)) => Promise<void>;
+};
+/** Any function whose first parameter takes `{ signal }` can go on the context, not only the built-in ones. */
+type Helpers = Effects;
+/**
+ * The effects as a handler sees them: the built-in ones keep their hand-written
+ * types, any other loses its first parameter, or has the type `Effect<F>` says.
+ */
+type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H]: K extends keyof Bound<E> ? H[K] extends Supported[K] ? Bound<E>[K] : BoundForm<H[K]> : BoundForm<H[K]>; };
+/**
+ * Puts the effects you pass on the context of every task of the bus, bound to
+ * that task, so a handler can write `({ race })` instead of `race(ctx, …)`.
+ * The key is the name of the effect: `race`, `all`, `allSettled`, `take`,
+ * `delay`. Returns the same bus, typed with the new fields.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
+ *
+ * const bus = createBus().use(effectsPlugin({ race, delay }));
+ *
+ * bus.on("load", async (id, { race, delay }) => {
+ *   const result = await race({
+ *     data: ({ signal }) => fetchData(id, { signal }),
+ *     timeout: () => delay(5000),
+ *   });
+ * });
+ * ```
+ */
+declare const effectsPlugin: <H extends Helpers>(helpers: H) => <E extends EventMap>(bus: Bus<E> & NoClash<BoundOf<H, E>, E>) => Bus<E & WithContext<BoundOf<H, E>>>;
+//#endregion
+export { RaceStarter as a, all as c, delay as d, take as i, EffectContext as l, effectsPlugin as n, race as o, TakeOptions as r, allSettled as s, BoundOf as t, Starter as u };

package/dist/policies.d.ts

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

package/dist/react.js

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

package/dist/redux.d.ts

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

package/dist/redux.js

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

package/dist/scope-key-B7l7mUS5.js

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

package/dist/scope.d.ts

@@ -0,0 +1,58 @@
+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-c292nK7v.js";
+import { n as Scoped } from "./types-mLaAx-EZ.js";
+//#region src/scope/effect.d.ts
+/**
+ * Marks a function whose first parameter is `{ signal }` as an effect, so that
+ * as a value of a scope it is bound to the task: `ctx.first(items)`
+ * calls `first(ctx, items)`. The type is the function without that parameter,
+ * generics included, which `effects` cannot do: no annotation is needed, and
+ * JavaScript editors show the exact hint.
+ *
+ * Only `scopePlugin` binds it; the function itself is returned unchanged.
+ * Call it where the function is declared, not inline in the scope: TypeScript
+ * does not infer the fields of a scope from a generic call written there.
+ *
+ * @example
+ * ```ts
+ * const first = effect(<T>(ctx: { signal: AbortSignal }, items: T[]) => items[0]);
+ *
+ * const getUser = createCommand(
+ *   "user/get",
+ *   (id: string, { first }) => first([id]), // first: <T>(items: T[]) => T
+ *   { first },
+ * );
+ * ```
+ */
+export declare const effect: <A extends unknown[], R>(fn: (ctx: Signaled, ...args: A) => R) => ((...args: A) => R);
+//#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
+ * 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.
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { createCommand } 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
+ * });
+ * bus.emit(getUser("1"), { http: fakeHttp }); // this call only
+ * ```
+ */
+export declare const scopePlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus<E>;
+//#endregion
+export type { Effect, Effects, EmitScope, Scope, Scoped, Signaled };

package/dist/scope.js

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

package/dist/trace.d.ts

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

package/dist/types-mLaAx-EZ.d.ts

@@ -0,0 +1,15 @@
+import { B as EventMap, d as Effects, o as Scope, s as WithFields } from "./action-creator-c292nK7v.js";
+import { t as BoundOf } from "./plugin-CCYlC0XS.js";
+//#region src/scope/types.d.ts
+type BoundEffects<E extends EventMap, S extends Scope> = S extends {
+  effects: infer H extends Effects;
+} ? BoundOf<H, E> : unknown;
+/** The fields a scope gives a task: its values as they are and its `effects` bound; `unknown` for an empty scope. */
+type FieldsOfScope<E extends EventMap, S extends Scope> = [keyof S] extends [never] ? unknown : Omit<S, "effects"> & BoundEffects<E, S>;
+/**
+ * The event map `E` with the fields of a scope on top of its context fields.
+ * A field the scope sets replaces the one of the bus in the type too.
+ */
+type Scoped<E extends EventMap, S extends Scope> = WithFields<E, FieldsOfScope<E, S>>;
+//#endregion
+export { Scoped as n, FieldsOfScope as t };

package/docs/README.md

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

package/docs/actions.md

@@ -109,7 +109,7 @@ The registry lives in `nanoeffects/actions`, so a bus without one carries none o
 
 **When.** You want one mount / one unmount for that domain. Skip modules while a few top-level `bus.on` calls are enough.
 
-`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, and `commands`.
+`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, `commands`, and `createModule`: the same as `createModule` below, with the context fields of the bus typed (see [TypeScript](typescript.md)).
 
 ```js
 import { createBus } from "nanoeffects";
@@ -152,3 +152,27 @@ app.dispose(); // unmounts every module
   - `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.
+
+## Give a command, an action or a module its own fields
+
+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
+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());
+
+// the third argument — fields of this command only
+const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
+  api,
+});
+
+// a test replaces them for one call
+const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
+bus.emit(getUser("1"), { api: fakeApi });
+```
+
+The handler gets the fields typed. Without `scopePlugin` the scope is ignored. The full picture, with jobs, actions, modules and which value wins, is in [scopes](scope.md).

package/docs/context.md

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