nanoeffects 0.0.0-stage → 0.2.0

package/dist/effects.d.ts

@@ -0,0 +1,284 @@
+import { A as Keys, N as Task, k as EventMap, u as Context } from "./action-rqZEnRIp.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();
+ * });
+ * ```
+ */
+export declare const delay: (ctx: {
+  signal?: AbortSignal | undefined;
+}, ms: number | (() => number)) => Promise<void>;
+//#endregion
+//#region src/utils/onAbort.d.ts
+export declare const onAbort: (ctx: {
+  signal?: AbortSignal | undefined;
+}, fn: (reason: unknown) => void) => (() => 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]);
+ * });
+ * ```
+ */
+export declare function all<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+export 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);
+ * });
+ * ```
+ */
+export declare function allSettled<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+export 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/cancellable.d.ts
+type CancellableHandle<T> = {
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+  /** Registers a cleanup that runs if the promise is cancelled before it settles. */
+  onCancel: (cleanup: () => void) => void;
+};
+type CancellableExecutor<T> = (handle: CancellableHandle<T>) => void;
+/**
+ * A promise tied to `ctx.signal`. It works like `new Promise`, but the
+ * executor gets one object, `{ resolve, reject, onCancel }`. If the signal
+ * aborts before the promise settles, the cleanups run (last registered first)
+ * and the promise rejects with the abort reason. If the signal is already
+ * aborted, the executor does not run. After the promise settles, the abort
+ * listener is removed and the cleanups are dropped.
+ *
+ * @example
+ * ```ts
+ * bus.on(
+ *   "wait",
+ *   latest((_, ctx) =>
+ *     cancellable(ctx, ({ resolve, onCancel }) => {
+ *       const timer = setTimeout(resolve, 5000);
+ *       onCancel(() => clearTimeout(timer));
+ *     }),
+ *   ),
+ * );
+ * ```
+ */
+export declare const cancellable: <T = void>(ctx: {
+  signal: AbortSignal;
+}, executor: CancellableExecutor<T>) => Promise<T>;
+//#endregion
+//#region src/effects/poll.d.ts
+type PollOptions = {
+  /** Also call `fn` at once, not only after the first `ms`. Default `false`. */
+  leading?: boolean;
+  /**
+   * Start the pause after a call finishes, so calls never overlap. By default
+   * the calls come every `ms` whatever the duration of `fn`.
+   */
+  waitForFn?: boolean;
+};
+/**
+ * Calls a function every `ms`, like patronum `interval`: the first call comes
+ * after `ms` (with `leading` also at once), and the next ticks keep a steady
+ * rate whatever the duration of the function, so a slow one may overlap with
+ * the next call (`waitForFn` starts each pause when the call ends instead). An
+ * error stops the polling and rejects; an abort of the caller ends it without
+ * an error and clears the timer. Two forms:
+ *
+ * - `poll(ms, task, options)` wraps a Task `(payload, ctx) => result` and
+ *   returns a Task. Each call gets a context of its own, a child of the
+ *   caller's: `bus.on("watch", poll(10_000, refresh))`.
+ * - `poll(ctx, fn, ms, options)` is for one call inside a body; `fn` gets the
+ *   number of the call, starting at 0.
+ *
+ * `ms` can be a function of the number of the call that the pause leads to, for
+ * a growing or random pause: `(call) => Math.min(1000 * 2 ** call, 60_000)`.
+ *
+ * @example
+ * ```ts
+ * bus.on("watch", poll(10_000, (_, { signal }) => refresh({ signal })));
+ *
+ * bus.on("watch", async (_, ctx) => {
+ *   await poll(ctx, () => refresh(), 10_000);
+ * });
+ * ```
+ */
+type PollMs = number | ((call: number) => number);
+export declare function poll<P, E extends EventMap, R>(ms: PollMs, task: Task<P, E, R>, options?: PollOptions): Task<P, E, Promise<void>>;
+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. */
+  times?: number;
+  /**
+   * Pause before the next attempt, in ms: a number, or a function of the
+   * number of the attempt that just failed and its error. Default 0.
+   */
+  delay?: number | ((attempt: number, error: unknown) => number);
+  /** Return `false` to stop retrying and throw `error`. Default: always retry. */
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+/**
+ * Calls a function until it succeeds or `times` attempts are used, then throws
+ * the last error. If the caller aborts, retrying stops and the result rejects
+ * with the abort reason. Two forms:
+ *
+ * - `retry(task, options)` wraps a Task `(payload, ctx) => result` and returns
+ *   a Task. Each attempt gets a context of its own, a child of the caller's, so
+ *   it can go straight into `on` and into `ctx.run`:
+ *   `bus.on("load", latest(retry(load, { times: 4 })))`. The number of the
+ *   attempt is not passed; use the other form when it is needed.
+ * - `retry(ctx, fn, options)` is for one call inside a body. `fn` gets the
+ *   number of the attempt, starting at 1.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", latest(retry(loadUser, { times: 4, delay: (attempt) => 2 ** attempt * 100 })));
+ *
+ * bus.on("load", async (id, ctx) => {
+ *   const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), { times: 4 });
+ * });
+ * ```
+ */
+type RetryFn<T> = (attempt: number) => T | PromiseLike<T>;
+export declare function retry<P, E extends EventMap, R>(task: Task<P, E, R>, options?: RetryOptions): Task<P, E, Promise<Awaited<R>>>;
+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
+ * with a `TimeoutError` (a `DOMException`, like `AbortSignal.timeout`), even if
+ * it ignores the signal. If the caller aborts, rejects with its reason. Two
+ * forms:
+ *
+ * - `timeout(ms, task)` wraps a Task `(payload, ctx) => result` and returns a
+ *   Task. The Task gets a context of its own whose `signal` the time limit
+ *   aborts: `bus.on("load", latest(timeout(5000, load)))`.
+ * - `timeout(ctx, ms, starter)` is for one call inside a body; `starter` gets
+ *   `{ signal, abort }`.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", timeout(5000, (id, { signal }) => fetchData(id, { signal })));
+ *
+ * bus.on("load", async (id, ctx) => {
+ *   const data = await timeout(ctx, 5000, ({ signal }) => fetchData(id, { signal }));
+ * });
+ * ```
+ */
+export declare function timeout<P, E extends EventMap, R>(ms: number, task: Task<P, E, R>): Task<P, E, Promise<Awaited<R>>>;
+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 };

package/dist/effects.js

@@ -0,0 +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};

package/dist/event-0RIBGYqS.js

@@ -0,0 +1 @@
+const e=e=>typeof e==`string`?e:e.type,t=(e,t)=>typeof e==`object`?e.payload:t;export{t as n,e as t};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+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-rqZEnRIp.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 };

package/dist/index.js

@@ -0,0 +1 @@
+export{n as anyEventType,t as createBus}from"./bus-CRnlwmQ4.js";

package/dist/module-BSCdR9D1.d.ts

@@ -0,0 +1,167 @@
+import { L as UnsubscribeCallback, N as Task, c as Command, j as PayloadOf, k as EventMap, o as Bus, u as Context } from "./action-rqZEnRIp.js";
+//#region src/actions/command.d.ts
+/**
+ * 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.
+ *
+ * The handler is optional. A command without one is only a contract, and the
+ * bus gets its implementation from the `commands` registry (see
+ * `createCommands` 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.
+ *
+ * @example
+ * ```ts
+ * const getUser = createCommand("user/get", (id: string, { signal }) =>
+ *   fetchUser(id, { signal }),
+ * );
+ * const sendMail = createCommand<Mail, void>("mail/send"); // implemented elsewhere
+ *
+ * const commands = createCommands([bindHandler(sendMail, smtpSend)]);
+ * const bus = createBus({ commands });
+ * const user = await bus.emit(getUser, "1");
+ *
+ * commands.handle(getUser, async () => fakeUser); // in a test
+ * ```
+ */
+declare const createCommand: <P = void, R = void, T extends string = string, E extends EventMap = EventMap>(type: T, handler?: Task<P, E, R>) => Command<P, R> & {
+  readonly type: T;
+};
+/** A command (or its type) with the handler to bind to it; `bindHandler` makes one. */
+type Binding<E extends EventMap = EventMap> = readonly [Command<never, unknown> | string, Task<never, E, unknown>];
+/**
+ * Pairs a command with the handler to bind to it, for `createCommands`. It
+ * checks that the handler fits the command.
+ *
+ * @example
+ * ```ts
+ * createCommands([bindHandler(sendMail, smtpSend)]);
+ * ```
+ */
+declare const bindHandler: <P, R, E extends EventMap>(command: Command<P, R>, fn: Task<P, E, R>) => Binding<E>;
+/**
+ * The handlers bound to commands of `bus`: it makes the registry, sets it as
+ * the commands of the bus and returns it. Each bus has its own, so each test
+ * can have its own implementation. `handle` binds more later and returns the
+ * function that unbinds. A second `createCommands(bus)` replaces the registry
+ * of that bus.
+ *
+ * What the bus runs for a command: the handler bound last, else the one the
+ * command was created with, else it throws `No handler for command "..."`.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus<Events>();
+ * const commands = createCommands(bus, [bindHandler(sendMail, smtpSend)]);
+ *
+ * const unbind = commands.handle(getUser, async () => fakeUser);
+ * unbind(); // the command's own handler is back
+ * ```
+ */
+declare const createCommands: <E extends EventMap>(bus: Bus<E>, bindings?: readonly Binding<E>[]) => {
+  run: (command: Command, payload: unknown, ctx: unknown) => unknown;
+  handle: {
+    <P, R>(command: Command<P, R>, fn: Task<P, E, R>): UnsubscribeCallback;
+    (type: string, fn: Task<never, E, unknown>): UnsubscribeCallback;
+    (bindings: readonly Binding<E>[]): UnsubscribeCallback;
+  };
+};
+//#endregion
+//#region src/actions/module.d.ts
+/**
+ * What a module's `setup` gets: the context of the module's task, so `on`,
+ * `emit` and `run` work as in a handler, plus `handle` to bind commands, `use`
+ * to mount sub-modules and `spawn` to start a background task. Everything the
+ * module does is undone when it is unmounted.
+ */
+type ModuleContext<E extends EventMap = EventMap> = Context<E> & {
+  /** Binds the handler of a command, or a list of them; undone on unmount. */
+  handle<P, R>(command: Command<P, R>, fn: Task<P, E, R>): UnsubscribeCallback;
+  handle(type: string, fn: Task<never, E, unknown>): UnsubscribeCallback;
+  handle(bindings: readonly Binding<E>[]): UnsubscribeCallback;
+  /**
+   * Brings sub-modules and commands, in any order. A sub-module is mounted and
+   * unmounted with this one. A command is bound to the handler it carries, for
+   * as long as this module is mounted; a command that answers by itself keeps
+   * answering after the module is gone, since the handler is its own. The
+   * 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;
+  /**
+   * 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.
+   */
+  spawn<P>(fn: Task<P, E, unknown>, ...payload: PayloadOf<P>): void;
+};
+type Module<E extends EventMap = EventMap> = {
+  readonly name: string;
+  readonly setup: (m: ModuleContext<E>) => void;
+};
+/**
+ * Describes one domain of an app: the commands it handles, the events it
+ * listens to, its sub-modules and its background tasks. The `name` shows up as
+ * the type of the module's tasks in the trace.
+ *
+ * @example
+ * ```ts
+ * export const userModule = createModule<Events>("user", (m) => {
+ *   m.handle(getUser, fetchUser);
+ *   m.handle([bindHandler(sendMail, smtpSend)]);
+ *   m.use(authModule);
+ *
+ *   m.on(loginRequested, (user, ctx) => ctx.emit(userLoaded(user)));
+ *   m.spawn(async (_, ctx) => {
+ *     for (;;) await handleNext(await take(ctx, "job"));
+ *   });
+ * });
+ * ```
+ */
+declare const createModule: <E extends EventMap = EventMap>(name: string, setup: (m: ModuleContext<E>) => void) => Module<E>;
+type Registry<E extends EventMap> = ReturnType<typeof createCommands<E>>;
+/** What `modulePlugin` returns. */
+type ModuleApi<E extends EventMap = EventMap> = {
+  /** The registry of command handlers of the bus: the one it was made with, or the app's own. */
+  commands: Registry<E>;
+  /** Mounts a module and returns the function that unmounts it; a module that is mounted already is not run again. */
+  mount(module: Module<E>): UnsubscribeCallback;
+  unmount(module: Module<E>): void;
+  isMounted(module: Module<E>): boolean;
+  /** Unmounts every module; a disposed app cannot mount modules. */
+  dispose(): void;
+};
+/**
+ * The plugin that assembles an app from modules: `bus.use(modulePlugin(modules))`
+ * mounts `modules` at once, in the order given, and returns `mount`, `unmount`,
+ * `isMounted`, `dispose` and `commands` for the modules that come and go later. The bus runs the commands that the
+ * modules bind: if `createCommands(bus)` was called before, that registry is
+ * used, otherwise the app attaches its own, as `app.commands`.
+ *
+ * A module is known by its `name`: mounting a module whose name is taken
+ * replaces the mounted one, which is unmounted first. That is what hot reload
+ * needs (see `docs/hmr.md`): the new version of a module file mounts again and
+ * the old version goes away with its subscriptions, commands and tasks.
+ *
+ * Unmounting undoes everything the module did: its subscriptions, its bound
+ * commands, its sub-modules and its background tasks. `dispose` unmounts them
+ * all, and a disposed app cannot mount modules.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus<Events>();
+ * const app = bus.use(modulePlugin([userModule]));
+ *
+ * const unmount = app.mount(orderModule); // later, e.g. after a lazy import
+ * unmount(); // or app.unmount(orderModule)
+ *
+ * bus.emit(getUser, "1");
+ * app.commands.handle(getUser, fakeUser); // in a test
+ * app.dispose();
+ * ```
+ */
+declare const modulePlugin: <E extends EventMap>(modules?: readonly Module<E>[]) => (bus: Bus<E>) => ModuleApi<E>;
+//#endregion
+export { modulePlugin as a, createCommand as c, createModule as i, createCommands as l, ModuleApi as n, Binding as o, ModuleContext as r, bindHandler as s, Module as t };