nanoeffects 0.0.0-stage → 0.1.0

package/dist/effects.d.ts

@@ -0,0 +1,244 @@
+import { A as Keys, k as EventMap, u as Context } from "./action-BM-UdmJr.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 `fn` 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 `fn`, so a slow `fn` may overlap with the next call
+ * (`waitForFn` starts each pause when the call ends instead). `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)`.
+ *
+ * It stops when `ctx` aborts: the result then resolves, it does not reject, and
+ * the pending timer is cleared. If a call throws, polling stops and the result
+ * rejects.
+ *
+ * @example
+ * ```ts
+ * bus.on("watch", async (_, ctx) => {
+ *   await poll(ctx, () => refresh(), 5000);
+ *   cleanup(); // the task was aborted
+ * });
+ * ```
+ */
+export declare const poll: (ctx: {
+  signal: AbortSignal;
+}, fn: (tick: number) => unknown, ms: number | ((call: number) => number), 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;
+};
+export declare const retry: <T>(ctx: {
+  signal?: AbortSignal;
+}, fn: (attempt: number) => T | PromiseLike<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 `starter`; if it takes longer than `ms`, aborts its signal and rejects
+ * with a `TimeoutError` (a `DOMException`, like `AbortSignal.timeout`), even
+ * if the starter ignores the signal. If `ctx` aborts, rejects with its reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const data = await timeout(ctx, 5000, ({ signal }) => fetchData(id, { signal }));
+ * });
+ * ```
+ */
+export declare const 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-BXQ6Einm.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=e=>Array.isArray(e)?Array(e.length):{},d=(e,o,s)=>{s?.signal?.throwIfAborted();let c=r(s??{}),u=a(c.ctx,o);return i(c.ctx,o,`start`),t(c.ctx,()=>u(`cancel`)),{tasks:Object.entries(e).map(([e,t])=>{let i=r(c.ctx),a={signal:i.ctx.signal,abort:i.ctx.abort};return[e,new Promise(e=>e(n(i.ctx,`run`,()=>t(a)))).finally(i.unlink)]}),cancelAll:()=>c.ctx.abort(),unfollowParent:c.unlink,settle:u,until:e=>l(e,s)}};async function f(e,t){let n=d(t,`all`,e);try{let e=await n.until(Promise.all(n.tasks.map(([,e])=>e))),r=u(t);for(let[t,[i]]of n.tasks.entries())r[i]=e[t];return n.settle(`done`),r}catch(e){throw n.settle(`error`,e),n.cancelAll(),e}finally{n.unfollowParent()}}const p=e=>e.then(e=>({status:`fulfilled`,value:e}),e=>({status:`rejected`,reason:e}));async function m(e,t){let n=d(t,`allSettled`,e);try{let e=await n.until(Promise.all(n.tasks.map(([,e])=>p(e)))),r=u(t);for(let[t,[i]]of n.tasks.entries())r[i]=e[t];return n.settle(`done`),r}catch(e){throw n.settle(`error`,e),n.cancelAll(),e}finally{n.unfollowParent()}}const h=(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)}}),g=async(e,n,o)=>{n?.signal?.throwIfAborted();let{ctx:s,unlink:c}=r(n??{}),u=a(s,e);i(s,e,`start`),t(s,()=>u(`cancel`));try{let e=await l(o(s),n);return u(`done`),e}catch(e){throw u(`error`,e),e}finally{c()}},_=async(e,t)=>{let{ctx:i,unlink:a}=r(e);try{return await n(i,`run`,t)}finally{a()}},v=(e,n,r,i={})=>{if(e.signal.aborted)return Promise.resolve();let a=i.leading??!1,c=i.waitForFn??!1;return g(`poll`,e,e=>new Promise((i,l)=>{let u=0,d=null,f=()=>{d!==null&&(o(d),d=null)},p=e=>{try{d=s(m,typeof r==`function`?r(e):r)}catch(e){f(),l(e)}},m=()=>{d=null,c||p(u+1),h()},h=()=>{let t=u++;_(e,()=>n(t)).then(()=>{c&&!e.signal.aborted&&p(u)},e=>{f(),l(e)})};t(e,f),a?(h(),c||p(u)):p(0)})).catch(t=>{if(!e.signal.aborted)throw t})};async function y(e,t){let n=u(t);if(Object.keys(t).length===0)return n;let r=d(t,`race`,e);try{let[e,t]=await r.until(Promise.race(r.tasks.map(([e,t])=>t.then(t=>[e,t]))));return n[e]=t,r.settle(`done`),n}catch(e){throw r.settle(`error`,e),e}finally{r.unfollowParent(),r.cancelAll()}}const b=(e,t,n)=>typeof e==`function`?e(t,n):e,x=e=>({times:e.times??3,delay:e.delay??0,shouldRetry:e.shouldRetry??(()=>!0)}),S=(e,t,n={})=>g(`retry`,e,async e=>{let{times:r,delay:i,shouldRetry:a}=x(n);for(let n=1;;n++)try{return await _(e,()=>t(n))}catch(t){if(e.signal.throwIfAborted(),n>=r||!a(t,n))throw t;let o=b(i,n,t);o>0&&await c(e,o)}}),C=(e,n,r={})=>g(`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))})),w=(e,t,i)=>g(`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({signal:a.ctx.signal,abort:a.ctx.abort}))),a.ctx)}finally{o(c),a.unlink()}});export{f as all,m as allSettled,h as cancellable,c as delay,t as onAbort,v as poll,y as race,S as retry,C as take,w 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-CaxrMD1A.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/index.d.ts

@@ -0,0 +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-BM-UdmJr.js";
+import "./index-CaxrMD1A.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-RUiw8f9p.js";

package/dist/notrace/action-BM-UdmJr.d.ts

@@ -0,0 +1,302 @@
+//#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
+//#region src/core/tracer.d.ts
+/**
+ * What the bus needs from tracing. The implementation, `createTracer` in
+ * `nanoeffects/trace`, holds all the machinery (ids, events, loggers), so a
+ * bus without `trace` carries none of it. `Ref` is an opaque handle that
+ * `task` makes for each task.
+ */
+interface Tracer<Ref extends object = object> {
+  /** Registers a task and returns its handle; `parent` is the handle of its parent task. */
+  task(event: {
+    type: string;
+    payload?: unknown;
+  }, parent?: Ref): Ref;
+  /** Reports a phase of a task. */
+  report(ref: Ref, effect: EffectName, phase: Phase, error?: unknown): void;
+  /** Returns `settle(phase, error?)` that reports only the first phase it gets. */
+  settler(ref: Ref, effect: EffectName): (phase: Phase, error?: unknown) => void;
+  /**
+   * Runs `fn`, reporting `start` and then `done` / `error` of its (sync or
+   * async) result, or `cancel` if `signal` aborts first.
+   */
+  run<R>(ref: Ref, effect: EffectName, signal: AbortSignal, fn: () => R): R;
+}
+//#endregion
+//#region src/core/bus.d.ts
+/** Subscribes to every event; handlers receive the payload of any of them. */
+type AnyEvent = typeof anyEventType;
+type EventKey<E extends EventMap> = Keys<E>;
+type EventPayload<E extends EventMap> = E[EventKey<E>];
+type WithType<K extends string> = {
+  type: K;
+};
+type HandlerRef<E extends EventMap, Response = unknown> = (action: Action<E>) => Response;
+type Handler<E extends EventMap, Response = unknown, K extends EventKey<E> = EventKey<E>> = { [P in K]: {
+  type: P;
+  (payload: E[P]): Response;
+}; }[K];
+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
+ * `createCommand` in `nanoeffects/actions`.
+ */
+type Command<P = never, R = unknown> = {
+  (payload: P, ctx?: never): 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;
+};
+/**
+ * What the bus needs to run commands. The implementation, `createCommands` in
+ * `nanoeffects/actions`, holds the handlers bound to commands and runs the
+ * right one, so a bus without `commands` carries none of that.
+ */
+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 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;
+  <P, R>(command: Command<P, R>, ...payload: PayloadOf<P>): R;
+  (event: EventLike<E>): void;
+};
+type On<E extends EventMap> = {
+  (event: AnyEvent, fn: Task<EventPayload<E>, E>): UnsubscribeCallback;
+  <K extends EventKey<E>>(event: K, fn: Task<E[K], E>): UnsubscribeCallback;
+  /** An action creator without a payload type: the payload comes from the event map. */
+  <K extends EventKey<E>>(creator: FreeActionCreator<K>, fn: Task<E[K], E>): UnsubscribeCallback;
+  /** An action creator: the payload comes from it, so an event map is not needed. */
+  <P>(creator: ActionCreator<P>, fn: Task<P, E>): UnsubscribeCallback;
+  /** A command: the payload comes from it too. */
+  <P>(command: Command<P, unknown>, fn: Task<P, E>): UnsubscribeCallback;
+  <K extends EventKey<E>, Event extends {
+    type: K;
+  }>(event: Event & {
+    type: K;
+  }, fn: Task<E[K], E>): UnsubscribeCallback;
+};
+type Off<E extends EventMap> = {
+  (event: AnyEvent): void;
+  (event: AnyEvent, fn: Task<EventPayload<E>, E>): void;
+  <K extends EventKey<E>>(event: K): void;
+  <K extends EventKey<E>>(event: K, fn: Task<E[K], E>): void;
+  <K extends EventKey<E>, Event extends {
+    type: K;
+  }>(event: Event & {
+    type: K;
+  }, fn: Task<E[K], E>): void;
+  <P>(command: Command<P, unknown>, fn?: Task<P, E>): void;
+};
+declare const contextKey: unique symbol;
+/**
+ * Your own fields of every task context, in the event map: add it to the
+ * events with `&` and give the values in `createBus({ context })`. The fields
+ * are in the context of every task of that bus, and the compiler checks them.
+ *
+ * @example
+ * ```ts
+ * type Events = { save: Draft } & WithContext<{ store: Store }>;
+ *
+ * const bus = createBus<Events>({ context: { store } });
+ * bus.on("save", (draft, { store }) => store.put(draft));
+ * ```
+ */
+type WithContext<Fields extends object> = {
+  readonly [contextKey]?: Fields;
+};
+/** The fields that the event map `E` adds to the context of a task. */
+type ContextOf<E extends EventMap> = typeof contextKey extends keyof E ? NonNullable<E[typeof contextKey]> : unknown;
+/** Fields for the context of every task, or a function that makes them for one task. */
+type ContextOption<E extends EventMap> = ContextOf<E> | ((event: {
+  type: string;
+  payload?: unknown;
+}) => ContextOf<E>);
+/** Task context inside an effect. */
+type Context<E extends EventMap> = EventLike<E> & ContextOf<E> & {
+  signal: AbortSignal;
+  /** Abort this task (and attached children). */
+  abort: (reason?: unknown) => void;
+  /** Emit as this task; no-op after the task is aborted. */
+  emit: Emit<E>;
+  /**
+   * Subscribe as this task. The subscription is removed when the task aborts;
+   * after that this is a no-op that returns a no-op.
+   */
+  on: On<E>;
+  /** Same as the bus `off`. */
+  off: Off<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>>;
+};
+interface Bus<E extends EventMap> {
+  on: On<E>;
+  off: Off<E>;
+  emit: Emit<E>;
+  /** `BusOptions.context`, `.trace` and `.commands`, for what makes tasks of its own, like `registerModules`. */
+  readonly context?: ContextOption<E> | undefined;
+  /** What runs the commands; `registerModules` sets it when the bus was made without. */
+  commands?: Commands | undefined;
+  readonly trace?: Tracer | undefined;
+}
+type BusOptions<E extends EventMap> = {
+  /**
+   * Runs commands: make it with `createCommands` from `nanoeffects/actions`.
+   * Without it an event that is a function runs as it is, with the payload and
+   * the task context.
+   */
+  commands?: Commands;
+  /** Tracing of every task phase; make it with `createTracer` from `nanoeffects/trace`. */
+  trace?: never;
+  /**
+   * Receives errors of handlers: thrown ones and rejections of async ones.
+   * Without it handlers run like in a plain loop: the first error stops the
+   * rest and is thrown to the caller of `emit`, and rejections of async
+   * handlers are left unhandled. With it every handler runs and errors go
+   * here; an `onError` that throws is logged to `console.error`.
+   */
+  onError?: (error: unknown, event: Action<E>) => void;
+  /**
+   * Called when an event is emitted and nobody listens to it: the usual sign
+   * of a typo in an event name. Not called for commands, which always have a
+   * handler to run. Typically a warning in development only.
+   *
+   * @example
+   * ```ts
+   * createBus<Events>({
+   *   onUnhandled: import.meta.env.DEV ? ({ type }) => console.warn(`Nobody listens to "${type}"`) : void 0,
+   * });
+   * ```
+   */
+  onUnhandled?: (event: Action<E>) => void;
+  /**
+   * Fields added to the context of every task of this bus, its child tasks
+   * and the tasks of effects included: a store, a logger, a client. Their
+   * types come from `WithContext` in the event map. The fields of the library win over
+   * these when the names are the same. A function gets `{ type, payload }` of
+   * the task and returns its fields, for fields that depend on the task.
+   */
+  context?: ContextOption<E>;
+};
+declare const createBus: <Events extends EventMap>(options?: BusOptions<Events>) => Bus<Events>;
+//#endregion
+//#region src/actions/action.d.ts
+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;
+type Free = typeof free;
+/**
+ * A creator whose payload type was not given: each call has the type of what
+ * it is given, and the bus checks it against its event map, so
+ * `createAction("user/loaded")` needs no generics and keeps its literal type.
+ */
+interface FreeActionCreator<T extends string> {
+  (): {
+    type: T;
+    payload: undefined;
+  };
+  <P>(payload: P): {
+    type: T;
+    payload: P;
+  };
+  readonly type: T;
+  /** Tells whether an action is one of this creator. */
+  match(action: {
+    type: string;
+    payload?: unknown;
+  }): action is {
+    type: T;
+    payload: unknown;
+  };
+  toString(): T;
+}
+/**
+ * Makes actions of one type. It also works as the event of that type:
+ * `bus.on(creator, fn)` and `bus.emit(creator(payload))`.
+ */
+interface ActionCreator<P = void, T extends string = string, A extends unknown[] = PayloadOf<P>> {
+  (...args: A): Made<P, T>;
+  readonly type: T;
+  /** Tells whether an action is one of this creator, and narrows its type. */
+  match(action: {
+    type: string;
+    payload?: 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 };