nanoeffects 0.3.0 → 0.5.0

package/dist/effects.d.ts

@@ -1,4 +1,5 @@
-import { A as Keys, N as Task, k as EventMap, u as Context } from "./action-Bdfp-Wvd.js";
+import { F as WithContext, S as Context, _ as Bus, o as EventMap, s as Keys, u as Task } from "./action-creator-DOWcbXpy.js";
+import { n as NoClash } from "./context-plugin-B0sLWOxR.js";
 //#region src/utils/delay.d.ts
 /**
  * Resolves after `ms`, or rejects early if `ctx.signal` aborts. `ms` can be a
@@ -85,6 +86,38 @@ export declare function allSettled<const T extends readonly Starter<unknown>[]>(
   signal?: AbortSignal;
 }, effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
 //#endregion
+//#region src/effects/backoff.d.ts
+type BackoffOptions = {
+  /** Pause before the second attempt, in ms. Default 100. */
+  base?: number;
+  /** How many times each pause is longer than the one before. Default 2. */
+  factor?: number;
+  /** Longest pause, in ms. Default `Infinity`. */
+  max?: number;
+  /**
+   * Use a random pause from 0 up to the computed one ("full jitter"), so
+   * clients that failed together do not retry together. Default `false`.
+   */
+  jitter?: boolean;
+};
+/**
+ * Builds the `delay` of `retry`: the pause grows as `base * factor ** (attempt - 1)`
+ * and never passes `max`. `retry` counts attempts from 1; `poll` counts calls from
+ * 0, so there the first pause is `base / factor`.
+ *
+ * @example
+ * ```ts
+ * bus.on(
+ *   "load",
+ *   retry(loadUser, {
+ *     times: 5,
+ *     delay: backoff({ base: 200, max: 5000, jitter: true }), // 200, 400, 800, ... up to 5 s, randomised
+ *   }),
+ * );
+ * ```
+ */
+export declare const backoff: (options?: BackoffOptions) => (attempt: number) => number;
+//#endregion
 //#region src/effects/cancellable.d.ts
 type CancellableHandle<T> = {
   resolve: (value: T | PromiseLike<T>) => void;
@@ -118,6 +151,124 @@ export declare const cancellable: <T = void>(ctx: {
   signal: AbortSignal;
 }, executor: CancellableExecutor<T>) => Promise<T>;
 //#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);
+ * });
+ * ```
+ */
+export declare function race<T extends Record<string, RaceStarter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+export 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,
+ * });
+ * ```
+ */
+export 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>;
+export 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>;
+};
+type Helpers = Partial<Supported>;
+type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H & keyof Bound<E>]: Bound<E>[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),
+ *   });
+ * });
+ * ```
+ */
+export 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
 //#region src/effects/poll.d.ts
 type PollOptions = {
   /** Also call `fn` at once, not only after the first `ms`. Default `false`. */
@@ -160,32 +311,6 @@ export declare function poll(ctx: {
   signal: AbortSignal;
 }, fn: (tick: number) => unknown, ms: PollMs, options?: PollOptions): Promise<void>;
 //#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);
- * });
- * ```
- */
-export declare function race<T extends Record<string, RaceStarter<unknown>>>(ctx: {
-  signal?: AbortSignal;
-}, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
-export 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/retry.d.ts
 type RetryOptions = {
   /** Total number of attempts, the first one included. Default 3. */
@@ -226,34 +351,6 @@ export declare function retry<T>(ctx: {
   signal?: AbortSignal;
 }, fn: RetryFn<T>, options?: RetryOptions): Promise<T>;
 //#endregion
-//#region src/effects/take.d.ts
-type TakeOptions<P> = {
-  /** Wait for the first payload this accepts; others are skipped. */
-  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 }),
- * );
- * ```
- */
-export declare const take: <E extends EventMap, K extends Keys<E>>(ctx: Context<E>, event: K, options?: TakeOptions<E[K]>) => Promise<E[K]>;
-//#endregion
 //#region src/effects/timeout.d.ts
 /**
  * Runs a function; if it takes longer than `ms`, aborts its signal and rejects
@@ -281,4 +378,4 @@ export declare function timeout<T>(ctx: {
   signal?: AbortSignal;
 }, ms: number, starter: Starter<T>): Promise<T>;
 //#endregion
-export type { CancellableExecutor, CancellableHandle, EffectContext, PollOptions, RaceStarter, RetryOptions, TakeOptions };
+export type { BackoffOptions, CancellableExecutor, CancellableHandle, EffectContext, PollOptions, RaceStarter, RetryOptions, TakeOptions };

package/dist/effects.js

@@ -1 +1 @@
-import{n as e,t}from"./onAbort-BgMfspK4.js";import{a as n,i as r,o as i,t as a}from"./context-DlA80GOA.js";import{n as o,r as s,t as c}from"./delay-CIHnOh_L.js";const l=(e,n)=>n?.signal?new Promise((r,i)=>{let a=t(n,i);e.then(r,i).finally(a)}):e,u=async(e,n,o,s)=>{n?.signal?.throwIfAborted();let{ctx:c,unlink:u}=r(n??{}),d=a(c,e);i(c,e,`start`),t(c,()=>d(`cancel`));try{let e=await l(o(c),n);return d(`done`),s?.(!1),e}catch(e){throw d(`error`,e),s?.(!0),e}finally{u()}},d=async(e,t)=>{let{ctx:i,unlink:a}=r(e);try{return await n(i,`run`,()=>t(i))}finally{a()}},f=e=>e,p=(e,t)=>n=>e(t,f(n)),m=e=>Array.isArray(e)?Array(e.length):{},h=(e,t)=>{let i=Object.entries(t).map(([t,i])=>{let a=r(e),o={signal:a.ctx.signal,abort:a.ctx.abort},s=()=>i(o);return{key:t,task:new Promise(e=>e(n(a.ctx,`run`,s))).finally(a.unlink),cancel:a.ctx.abort}});return{tasks:i.map(({key:e,task:t})=>[e,t]),cancelAll:()=>{for(let e of i)e.cancel()}}},g=(e,t,n,r,i)=>{let a=()=>{};return u(e,t,async e=>{let t=h(e,n);return a=t.cancelAll,r(t.tasks)},e=>{(e||i===`end`)&&a()})};function _(e,t){return g(`all`,e,t,async e=>{let n=await Promise.all(e.map(([,e])=>e)),r=m(t);for(let[t,[i]]of e.entries())r[i]=n[t];return r},`failure`)}const v=e=>e.then(e=>({status:`fulfilled`,value:e}),e=>({status:`rejected`,reason:e}));function y(e,t){return g(`allSettled`,e,t,async e=>{let n=await Promise.all(e.map(([,e])=>v(e))),r=m(t);for(let[t,[i]]of e.entries())r[i]=n[t];return r},`failure`)}const b=(n,r)=>n.signal.aborted?Promise.reject(n.signal.reason):new Promise((i,a)=>{let o=[],s=`pending`,c=t=>{try{t()}catch(t){e(`cancel cleanup failed`,t)}},l=t(n,e=>{s=`cancelled`;for(let e of o.reverse())c(e);a(e)}),u=e=>(...t)=>{s===`pending`&&(s=`settled`,l(),o.length=0,e(...t))},d=e=>{s===`pending`?o.push(e):s===`cancelled`&&c(e)};try{r({resolve:u(i),reject:u(a),onCancel:d})}catch(e){u(a)(e)}}),x=(e,n,r,i)=>{if(e.signal.aborted)return Promise.resolve();let a=i.leading??!1,c=i.waitForFn??!1;return u(`poll`,e,e=>new Promise((i,l)=>{let u=0,f=null,p=()=>{f!==null&&(o(f),f=null)},m=e=>{try{f=s(h,typeof r==`function`?r(e):r)}catch(e){p(),l(e)}},h=()=>{f=null,c||m(u+1),g()},g=()=>{let t=u++;d(e,e=>n(e,t)).then(()=>{c&&!e.signal.aborted&&m(u)},e=>{p(),l(e)})};t(e,p),a?(g(),c||m(u)):m(0)})).catch(t=>{if(!e.signal.aborted)throw t})};function S(e,t,n,r={}){if(typeof e!=`object`){let r=t,i=n??{};return(t,n)=>x(n,p(r,t),e,i)}let i=t;return x(e,(e,t)=>i(t),n,r)}function C(e,t){let n=m(t);return Object.keys(t).length===0?Promise.resolve(n):g(`race`,e,t,async e=>{let[t,r]=await Promise.race(e.map(([e,t])=>t.then(t=>[e,t])));return n[t]=r,n},`end`)}const w=(e,t,n)=>typeof e==`function`?e(t,n):e,T=e=>({times:e.times??3,delay:e.delay??0,shouldRetry:e.shouldRetry??(()=>!0)}),E=(e,t,n)=>u(`retry`,e,async e=>{let{times:r,delay:i,shouldRetry:a}=T(n);for(let n=1;;n++)try{return await d(e,e=>t(e,n))}catch(t){if(e.signal.throwIfAborted(),n>=r||!a(t,n))throw t;let o=w(i,n,t);o>0&&await c(e,o)}});function D(e,t,n={}){if(typeof e==`function`){let n=e;return(e,r)=>E(r,p(n,e),t??{})}let r=t;return E(e,(e,t)=>r(t),n)}const O=(e,n,r={})=>u(`take`,e,i=>new Promise((a,o)=>{let{predicate:s}=r,c=[],l=()=>{for(let e of c)e()},u=e=>{l(),o(e)};c.push(e.on(n,e=>{(!s||s(e))&&(l(),a(e))})),c.push(t(i,u)),c.push(t({signal:r.signal},u))})),k=(e,t,i)=>u(`timeout`,e,async e=>{let a=r(e),c=s(()=>a.ctx.abort(new DOMException(`Timed out after ${t}ms`,`TimeoutError`)),t);try{return await l(Promise.resolve(n(a.ctx,`run`,()=>i(a.ctx))),a.ctx)}finally{o(c),a.unlink()}});function A(e,t,n){if(typeof e==`number`){let n=t;return(t,r)=>k(r,e,p(n,t))}let r=t,i=n;return k(e,r,e=>i({signal:e.signal,abort:e.abort}))}export{_ as all,y as allSettled,b as cancellable,c as delay,t as onAbort,S as poll,C as race,D as retry,O as take,A as timeout};
+import{n as e,t}from"./onAbort-BgMfspK4.js";import{a as n,i as r,o as i,t as a}from"./context-CK0ZomWt.js";import{n as o,r as s,t as c}from"./delay-CIHnOh_L.js";const l=(e,n)=>n?.signal?new Promise((r,i)=>{let a=t(n,i);e.then(r,i).finally(a)}):e,u=async(e,n,o,s)=>{n?.signal?.throwIfAborted();let{ctx:c,unlink:u}=r(n??{}),d=a(c,e);i(c,e,`start`),t(c,()=>d(`cancel`));try{let e=await l(o(c),n);return d(`done`),s?.(!1),e}catch(e){throw d(`error`,e),s?.(!0),e}finally{u()}},d=async(e,t)=>{let{ctx:i,unlink:a}=r(e);try{return await n(i,`run`,()=>t(i))}finally{a()}},f=e=>e,p=(e,t)=>n=>e(t,f(n)),m=e=>Array.isArray(e)?Array(e.length):{},h=(e,t)=>{let i=Object.entries(t).map(([t,i])=>{let a=r(e),o={signal:a.ctx.signal,abort:a.ctx.abort},s=()=>i(o);return{key:t,task:new Promise(e=>e(n(a.ctx,`run`,s))).finally(a.unlink),cancel:a.ctx.abort}});return{tasks:i.map(({key:e,task:t})=>[e,t]),cancelAll:()=>{for(let e of i)e.cancel()}}},g=(e,t,n,r,i)=>{let a=()=>{};return u(e,t,async e=>{let t=h(e,n);return a=t.cancelAll,r(t.tasks)},e=>{(e||i===`end`)&&a()})};function _(e,t){return g(`all`,e,t,async e=>{let n=await Promise.all(e.map(([,e])=>e)),r=m(t);for(let[t,[i]]of e.entries())r[i]=n[t];return r},`failure`)}const v=e=>e.then(e=>({status:`fulfilled`,value:e}),e=>({status:`rejected`,reason:e}));function y(e,t){return g(`allSettled`,e,t,async e=>{let n=await Promise.all(e.map(([,e])=>v(e))),r=m(t);for(let[t,[i]]of e.entries())r[i]=n[t];return r},`failure`)}const b=e=>e>0?e:0,x=(e={})=>{let t=b(e.base??100),n=e.factor??2,r=b(e.max??1/0),i=e.jitter??!1;return e=>{let a=b(Math.min(r,t*n**(e-1)));return i?Math.random()*a||0:a}},S=(n,r)=>n.signal.aborted?Promise.reject(n.signal.reason):new Promise((i,a)=>{let o=[],s=`pending`,c=t=>{try{t()}catch(t){e(`cancel cleanup failed`,t)}},l=t(n,e=>{s=`cancelled`;for(let e of o.reverse())c(e);a(e)}),u=e=>(...t)=>{s===`pending`&&(s=`settled`,l(),o.length=0,e(...t))},d=e=>{s===`pending`?o.push(e):s===`cancelled`&&c(e)};try{r({resolve:u(i),reject:u(a),onCancel:d})}catch(e){u(a)(e)}}),C=e=>t=>{let n=t.addContext,r=Object.entries(e);return t.addContext=e=>{n?.(e);for(let[t,n]of r)Object.assign(e,{[t]:(...t)=>n(e,...t)})},t},w=(e,n,r,i)=>{if(e.signal.aborted)return Promise.resolve();let a=i.leading??!1,c=i.waitForFn??!1;return u(`poll`,e,e=>new Promise((i,l)=>{let u=0,f=null,p=()=>{f!==null&&(o(f),f=null)},m=e=>{try{f=s(h,typeof r==`function`?r(e):r)}catch(e){p(),l(e)}},h=()=>{f=null,c||m(u+1),g()},g=()=>{let t=u++;d(e,e=>n(e,t)).then(()=>{c&&!e.signal.aborted&&m(u)},e=>{p(),l(e)})};t(e,p),a?(g(),c||m(u)):m(0)})).catch(t=>{if(!e.signal.aborted)throw t})};function T(e,t,n,r={}){if(typeof e!=`object`){let r=t,i=n??{};return(t,n)=>w(n,p(r,t),e,i)}let i=t;return w(e,(e,t)=>i(t),n,r)}function E(e,t){let n=m(t);return Object.keys(t).length===0?Promise.resolve(n):g(`race`,e,t,async e=>{let[t,r]=await Promise.race(e.map(([e,t])=>t.then(t=>[e,t])));return n[t]=r,n},`end`)}const D=(e,t,n)=>typeof e==`function`?e(t,n):e,O=e=>({times:e.times??3,delay:e.delay??0,shouldRetry:e.shouldRetry??(()=>!0)}),k=(e,t,n)=>u(`retry`,e,async e=>{let{times:r,delay:i,shouldRetry:a}=O(n);for(let n=1;;n++)try{return await d(e,e=>t(e,n))}catch(t){if(e.signal.throwIfAborted(),!(n<r)||!a(t,n))throw t;let o=D(i,n,t);o>0&&await c(e,o)}});function A(e,t,n={}){if(typeof e==`function`){let n=e;return(e,r)=>k(r,p(n,e),t??{})}let r=t;return k(e,(e,t)=>r(t),n)}function j(e,n,r={}){return u(`take`,e,i=>new Promise((a,o)=>{let{predicate:s}=r,c=[],l=()=>{for(let e of c)e()},u=e=>{l(),o(e)};c.push(e.on(n,e=>{(!s||s(e))&&(l(),a(e))})),c.push(t(i,u)),c.push(t({signal:r.signal},u))}))}const M=(e,t,i)=>u(`timeout`,e,async e=>{let a=r(e),c=s(()=>a.ctx.abort(new DOMException(`Timed out after ${t}ms`,`TimeoutError`)),t);try{return await l(Promise.resolve(n(a.ctx,`run`,()=>i(a.ctx))),a.ctx)}finally{o(c),a.unlink()}});function N(e,t,n){if(typeof e==`number`){let n=t;return(t,r)=>M(r,e,p(n,t))}let r=t,i=n;return M(e,r,e=>i({signal:e.signal,abort:e.abort}))}export{_ as all,y as allSettled,x as backoff,S as cancellable,c as delay,C as effectsPlugin,t as onAbort,T as poll,E as race,A as retry,j as take,N as timeout};

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-import { A as Keys, C as WithPayload, D as anyEventType, E as Tracer, F as TraceEvent, I as TraceLogger, L as UnsubscribeCallback, M as Phase, N as Task, O as EffectName, P as Trace, S as WithContext, T as createBus, _ as EventPayload, a as AnyEvent, b as Off, c as Command, d as ContextOf, f as ContextOption, g as EventLike, h as EventKey, i as Action, j as PayloadOf, k as EventMap, l as Commands, m as Emittable, o as Bus, p as Emit, s as BusOptions, u as Context, v as Handler, w as WithType, x as On, y as HandlerRef } from "./action-Bdfp-Wvd.js";
-export { type Action, type AnyEvent, type Bus, type BusOptions, type Command, type Commands, type Context, type ContextOf, type ContextOption, type EffectName, type Emit, type Emittable, type EventKey, type EventLike, type EventMap, type EventPayload, type Handler, type HandlerRef, type Keys, type Off, type On, type PayloadOf, type Phase, type Task, type Trace, type TraceEvent, type TraceLogger, type Tracer, type UnsubscribeCallback, type WithContext, type WithPayload, type WithType, anyEventType, createBus };
+import { A as EventsOf, B as anyEventType, C as ContextOf, D as EventKey, E as Emittable, F as WithContext, I as WithType, L as commandCall, M as HandlerRef, N as Off, O as EventLike, P as On, R as createBus, S as Context, T as Emit, _ as Bus, a as EffectName, b as CommandCall, c as PayloadOf, d as Trace, f as TraceEvent, g as AnyEvent, h as Action, i as WithPayload, j as Handler, k as EventPayload, l as Phase, m as UnsubscribeCallback, o as EventMap, p as TraceLogger, s as Keys, u as Task, v as BusOptions, w as ContextOption, x as Commands, y as Command, z as Tracer } from "./action-creator-DOWcbXpy.js";
+import { n as NoClash, r as contextPlugin, t as ContextTask } from "./context-plugin-B0sLWOxR.js";
+export { type Action, type AnyEvent, type Bus, type BusOptions, type Command, type CommandCall, type Commands, type Context, type ContextOf, type ContextOption, type ContextTask, type EffectName, type Emit, type Emittable, type EventKey, type EventLike, type EventMap, type EventPayload, type EventsOf, type Handler, type HandlerRef, type Keys, type NoClash, type Off, type On, type PayloadOf, type Phase, type Task, type Trace, type TraceEvent, type TraceLogger, type Tracer, type UnsubscribeCallback, type WithContext, type WithPayload, type WithType, anyEventType, commandCall, contextPlugin, createBus };

package/dist/index.js

@@ -1 +1 @@
-export{n as anyEventType,t as createBus}from"./bus-CRnlwmQ4.js";
+import{i as e,n as t,t as n}from"./bus-BAs9x7IQ.js";const r=e=>typeof e==`function`,i=e=>({type:Reflect.get(e,`type`),payload:Reflect.get(e,`payload`)}),a=e=>t=>{let n=t.addContext;return t.addContext=t=>{n?.(t);let a=r(e)?e(i(t)):e;for(let[e,n]of Object.entries(a))e in t||Reflect.set(t,e,n)},t};export{e as anyEventType,n as commandCall,a as contextPlugin,t as createBus};

package/dist/{module-I1ixyJzx.d.ts → module-DCJl-qfi.d.ts}

@@ -1,4 +1,4 @@
-import { L as UnsubscribeCallback, N as Task, c as Command, j as PayloadOf, k as EventMap, o as Bus, u as Context } from "./action-Bdfp-Wvd.js";
+import { S as Context, _ as Bus, c as PayloadOf, m as UnsubscribeCallback, o as EventMap, u as Task, y as Command } from "./action-creator-DOWcbXpy.js";
 //#region src/actions/command.d.ts
 /** What `createCommand` returns: a command that also tells whether an action is of its type. */
 type MadeCommand<P, R, T extends string> = Command<P, R> & {
@@ -13,17 +13,18 @@ type MadeCommand<P, R, T extends string> = Command<P, R> & {
   };
 };
 /**
- * Creates a command: a typed request for a result. `bus.emit(command, payload)`
- * runs its handler as a task, with a context, and returns what the handler
- * returns. Listeners of the command's type are told first, as for any event.
+ * Creates a command: a typed request for a result. Calling it builds
+ * `{ type, payload }` like `createAction`. `bus.emit(command(payload))` (or
+ * `bus.emit(command, payload)`) runs its handler as a task, with a context, and
+ * returns what the handler returns. Listeners of the command's type are told
+ * first, as for any event.
  *
  * The handler is optional. A command without one is only a contract, and the
  * bus gets its implementation from the `commands` registry (see
  * `commandsPlugin` and `bindHandler`). A handler bound there wins over the one
  * the command was created with, so a test can give a bus its own implementation.
  *
- * A handler can be wrapped in a policy, e.g. `latest(fn)`. Calling the command
- * directly, `command(payload)`, runs its own handler outside of any bus.
+ * A handler can be wrapped in a policy, e.g. `latest(fn)`.
  * `command.match(action)` tells whether an action has the type of the command,
  * as it does for an action creator.
  *
@@ -34,9 +35,9 @@ type MadeCommand<P, R, T extends string> = Command<P, R> & {
  * );
  * const sendMail = createCommand<Mail, void>("mail/send"); // implemented elsewhere
  *
+ * const bus = createBus<Events>();
  * bus.use(commandsPlugin([bindHandler(sendMail, smtpSend)]));
- * const bus = createBus({ commands });
- * const user = await bus.emit(getUser, "1");
+ * const user = await bus.emit(getUser("1"));
  *
  * commands.handle(getUser, async () => fakeUser); // in a test
  * ```
@@ -103,7 +104,10 @@ type ModuleContext<E extends EventMap = EventMap> = Context<E> & {
    * returned function undoes just this call, e.g. for what was added later from
    * a listener.
    */
-  use(...items: Array<Module<E> | Command<never, unknown>>): UnsubscribeCallback;
+  use(...items: Array<Module<E> | {
+    readonly type: string;
+    (payload: never): unknown;
+  }>): UnsubscribeCallback;
   /**
    * Starts a background task that lives as long as the module: it is aborted
    * on unmount, and an error of it is left unhandled, as in any handler.
@@ -145,6 +149,12 @@ type ModuleApi<E extends EventMap = EventMap> = {
   isMounted(module: Module<E>): boolean;
   /** Unmounts every module; a disposed app cannot mount modules. */
   dispose(): void;
+  /**
+   * `createModule` with the event map of this bus: the module sees the context
+   * fields of the bus without a type argument. It returns a plain module, not
+   * mounted, with no link to this bus.
+   */
+  createModule(name: string, setup: (m: ModuleContext<E>) => void): Module<E>;
 };
 /**
  * The plugin that assembles an app from modules: `bus.use(modulePlugin(modules))`
@@ -170,6 +180,11 @@ type ModuleApi<E extends EventMap = EventMap> = {
  * const unmount = app.mount(orderModule); // later, e.g. after a lazy import
  * unmount(); // or app.unmount(orderModule)
  *
+ * // a module made from the app has the context fields of the bus, typed
+ * const userModule = app.createModule("user", (m) => {
+ *   m.on("loaded", (user, { store }) => store.put(user));
+ * });
+ *
  * bus.emit(getUser, "1");
  * app.commands.handle(getUser, fakeUser); // in a test
  * app.dispose();

package/dist/notrace/{action-Bdfp-Wvd.d.ts → action-creator-DOWcbXpy.d.ts}

@@ -1,29 +1,3 @@
-//#region src/core/types.d.ts
-type PayloadOf<P> = undefined extends P ? [payload?: P] : [payload: P];
-type EventMap = Record<string, unknown>;
-type Keys<E> = keyof E & string;
-type Task<P, E extends EventMap, R = unknown> = (payload: P, ctx: Context<E>) => R;
-type EffectName = "every" | "latest" | "leading" | "debounce" | "throttle" | "run" | "all" | "race" | "retry" | "timeout" | "poll" | "take" | "queue" | "allSettled" | "command";
-type Phase = "start" | "done" | "error" | "cancel" | "drop";
-type TraceEvent<E = Record<string, unknown>> = { [K in Keys<E>]: {
-  id: number;
-  parent?: number;
-  type: K;
-  effect: EffectName;
-  phase: Phase;
-  payload: E[K];
-  error?: unknown;
-}; }[Keys<E>];
-/**
- * The contract of every trace logger: receives each task phase of a bus.
- * Adapters in `nanoeffects/trace` are factories that return one; pass it
- * through `createTracer` to `createBus({ trace })`.
- */
-type TraceLogger<E = Record<string, unknown>> = (event: TraceEvent<E>) => void;
-/** One logger or several; a throwing logger never breaks the task or the others. */
-type Trace<E = Record<string, unknown>> = TraceLogger<E> | readonly TraceLogger<E>[];
-type UnsubscribeCallback = () => void;
-//#endregion
 //#region src/core/store.d.ts
 declare const anyEventType = "*";
 //#endregion
@@ -68,21 +42,29 @@ type Action<E extends EventMap> = {
   type: EventKey<E>;
   payload: EventPayload<E>;
 };
-type WithPayload<E extends EventMap, K extends EventKey<E>> = undefined extends E[K] ? {
-  type: K;
-  payload?: E[K];
-} : {
-  type: K;
-  payload: E[K];
-};
 type EventLike<E extends EventMap> = { [K in EventKey<E>]: WithPayload<E, K>; }[Keys<E>];
 /**
- * A typed request for a result. `bus.emit(command, payload)` runs the handler
- * of the command as a task and returns what it returns. Made by
+ * Brands `{ type, payload }` from a command call so `emit` can run the command.
+ * Not enumerable on the object.
+ */
+declare const commandCall: unique symbol;
+/**
+ * What `command(payload)` returns: an action-shaped value that `emit` runs as
+ * that command. A plain `{ type, payload }` without this brand is notify-only.
+ */
+type CommandCall<P = unknown, R = unknown> = {
+  type: string;
+  payload: P;
+  readonly [commandCall]: Command<P, R>;
+};
+/**
+ * A typed request for a result. Calling it builds `{ type, payload }` like
+ * `createAction`; `bus.emit(command(payload))` (or `bus.emit(command, payload)`)
+ * runs the handler as a task and returns what it returns. Made by
  * `createCommand` in `nanoeffects/actions`.
  */
 type Command<P = never, R = unknown> = {
-  (payload: P, ctx?: never): R;
+  (payload: P): CommandCall<P, R>;
   readonly type: string;
   /** Wraps the handler that really runs, e.g. to route its outcome. */
   readonly wrap?: (run: (payload: never, ctx: never) => unknown) => (payload: never, ctx: never) => unknown;
@@ -96,11 +78,13 @@ interface Commands {
   run(command: Command, payload: unknown, ctx: unknown): unknown;
 }
 /** Anything `emit` takes as its first argument: an event type, an action or a command. */
-type Emittable<E extends EventMap> = EventKey<E> | Command | EventLike<E>;
+type Emittable<E extends EventMap> = EventKey<E> | Command | CommandCall | EventLike<E>;
 type Emit<E extends EventMap> = {
   <K extends EventKey<E>>(event: K, ...payload: PayloadOf<E[K]>): void;
-  <K extends EventKey<E>, R>(event: Handler<E, R, K>, ...payload: PayloadOf<E[K]>): R;
+  /** Before Handler: a command is callable too, and must return its result type. */
   <P, R>(command: Command<P, R>, ...payload: PayloadOf<P>): R;
+  <P, R>(call: CommandCall<P, R>): R;
+  <K extends EventKey<E>, R>(event: Handler<E, R, K>, ...payload: PayloadOf<E[K]>): R;
   (event: EventLike<E>): void;
 };
 type On<E extends EventMap> = {
@@ -119,6 +103,8 @@ type On<E extends EventMap> = {
   }, fn: Task<E[K], E>): UnsubscribeCallback;
 };
 type Off<E extends EventMap> = {
+  /** Removes every listener of every event (including `"*"`). */
+  (): void;
   (event: AnyEvent): void;
   (event: AnyEvent, fn: Task<EventPayload<E>, E>): void;
   <K extends EventKey<E>>(event: K): void;
@@ -171,8 +157,25 @@ type Context<E extends EventMap> = EventLike<E> & ContextOf<E> & {
   /** Child task: aborted with the parent; errors propagate to the parent. */
   run<P, R>(fn: Task<P, E, R>, ...args: PayloadOf<P>): Promise<Awaited<R>>;
 };
+/**
+ * The event map of a bus, with the context fields that plugins added. Use it to
+ * name the types of a bus in other files: `type AppEvents = EventsOf<typeof bus>`.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus<Events>().use(effectsPlugin({ race }));
+ * type AppEvents = EventsOf<typeof bus>;
+ * type AppContext = Context<AppEvents>; // has `race`
+ * ```
+ */
+type EventsOf<B> = B extends Bus<infer E extends EventMap> ? E : never;
 interface Bus<E extends EventMap> {
   on: On<E>;
+  /**
+   * Like `on`, but the handler runs at most once: it is removed before it is
+   * invoked, so a nested emit of the same event does not re-enter it.
+   */
+  once: On<E>;
   off: Off<E>;
   emit: Emit<E>;
   /**
@@ -182,10 +185,12 @@ interface Bus<E extends EventMap> {
    */
   use<R>(plugin: (bus: Bus<E>) => R): R;
   /** `BusOptions.context` and `.trace`, and `commands`, for what makes tasks of its own, like `modulePlugin`. */
-  readonly context?: ContextOption<E> | undefined;
+  readonly ctx?: ContextOption<E> | undefined;
   /** What runs the commands; `commandsPlugin` and `modulePlugin` set it. Without one a command runs its own handler. */
   commands?: Commands | undefined;
   readonly trace?: Tracer | undefined;
+  /** Called with every new task context to add fields to it, for what needs the task, like `effectsPlugin`. Chain to the previous one. */
+  addContext?: ((ctx: object) => void) | undefined;
 }
 type BusOptions<E extends EventMap> = {
   /** Tracing of every task phase; make it with `createTracer` from `nanoeffects/trace`. */
@@ -223,7 +228,40 @@ type BusOptions<E extends EventMap> = {
 };
 declare const createBus: <Events extends EventMap>(options?: BusOptions<Events>) => Bus<Events>;
 //#endregion
-//#region src/actions/action.d.ts
+//#region src/core/types.d.ts
+type PayloadOf<P> = undefined extends P ? [payload?: P] : [payload: P];
+type EventMap = Record<string, unknown>;
+type Keys<E> = keyof E & string;
+type Task<P, E extends EventMap, R = unknown> = (payload: P, ctx: Context<E>) => R;
+type EffectName = "every" | "latest" | "leading" | "debounce" | "throttle" | "run" | "all" | "race" | "retry" | "timeout" | "poll" | "take" | "queue" | "allSettled" | "command";
+type Phase = "start" | "done" | "error" | "cancel" | "drop";
+type TraceEvent<E = Record<string, unknown>> = { [K in Keys<E>]: {
+  id: number;
+  parent?: number;
+  type: K;
+  effect: EffectName;
+  phase: Phase;
+  payload: E[K];
+  error?: unknown;
+}; }[Keys<E>];
+/**
+ * The contract of every trace logger: receives each task phase of a bus.
+ * Adapters in `nanoeffects/trace` are factories that return one; pass it
+ * through `createTracer` to `createBus({ trace })`.
+ */
+type TraceLogger<E = Record<string, unknown>> = (event: TraceEvent<E>) => void;
+/** One logger or several; a throwing logger never breaks the task or the others. */
+type Trace<E = Record<string, unknown>> = TraceLogger<E> | readonly TraceLogger<E>[];
+type UnsubscribeCallback = () => void;
+//#endregion
+//#region src/core/action-creator.d.ts
+type WithPayload<E extends EventMap, K extends Keys<E>> = undefined extends E[K] ? {
+  type: K;
+  payload?: E[K];
+} : {
+  type: K;
+  payload: E[K];
+};
 type Absent<P> = [P] extends [void] ? undefined : P;
 type Made<P, T extends string> = WithPayload<{ [K in T]: Absent<P>; }, T>;
 declare const free: unique symbol;
@@ -267,37 +305,5 @@ interface ActionCreator<P = void, T extends string = string, A extends unknown[]
   }): action is Made<P, T>;
   toString(): T;
 }
-/**
- * Creates an action creator, as in Redux Toolkit.
- *
- * - `createAction("user/loaded")` needs no generics: the payload type comes
- *   from the event map of the bus that the action goes to, and the literal
- *   type of the action is kept.
- * - `createAction<User>("user/loaded")` gives the payload type, for a bus
- *   without an event map or to check the calls of the creator. The type of
- *   the action is then `string`; to keep the literal, give it as the second
- *   generic: `createAction<User, "user/loaded">("user/loaded")`.
- * - With `prepare` the arguments of the creator can differ from the payload,
- *   and both types are inferred.
- *
- * @example
- * ```ts
- * const added = createAction<number>("counter/added");
- * added(2); // { type: "counter/added", payload: 2 }
- * added.type; // "counter/added"
- * added.match(action); // true for actions of this type
- *
- * const renamed = createAction("user/renamed", (id: string, name: string) => ({
- *   payload: { id, name },
- * }));
- *
- * bus.emit(added(2));
- * bus.on(added, (n) => console.log(n));
- * ```
- */
-declare function createAction<P = Free, T extends string = string>(type: T): [P] extends [Free] ? FreeActionCreator<T> : ActionCreator<P, T>;
-declare function createAction<A extends unknown[], P, T extends string = string>(type: T, prepare: (...args: A) => {
-  payload: P;
-}): ActionCreator<P, T, A>;
 //#endregion
-export { Keys as A, WithPayload as C, anyEventType as D, Tracer as E, TraceEvent as F, TraceLogger as I, UnsubscribeCallback as L, Phase as M, Task as N, EffectName as O, Trace as P, WithContext as S, createBus as T, EventPayload as _, AnyEvent as a, Off as b, Command as c, ContextOf as d, ContextOption as f, EventLike as g, EventKey as h, Action as i, PayloadOf as j, EventMap as k, Commands as l, Emittable as m, FreeActionCreator as n, Bus as o, Emit as p, createAction as r, BusOptions as s, ActionCreator as t, Context as u, Handler as v, WithType as w, On as x, HandlerRef as y };
+export { EventsOf as A, anyEventType as B, ContextOf as C, EventKey as D, Emittable as E, WithContext as F, WithType as I, commandCall as L, HandlerRef as M, Off as N, EventLike as O, On as P, createBus as R, Context as S, Emit as T, Bus as _, EffectName as a, CommandCall as b, PayloadOf as c, Trace as d, TraceEvent as f, AnyEvent as g, Action as h, WithPayload as i, Handler as j, EventPayload as k, Phase as l, UnsubscribeCallback as m, Free as n, EventMap as o, TraceLogger as p, FreeActionCreator as r, Keys as s, ActionCreator as t, Task as u, BusOptions as v, ContextOption as w, Commands as x, Command as y, Tracer as z };