nanoeffects 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladimir Yazykov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# nanoeffects
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed event bus where every handler is a **task**: it gets a context with an `AbortSignal`, and the policies that decide what happens when calls overlap (`latest`, `debounce`, `throttle`, `queue`, ...) are plain functions around the handler.
+
+```ts
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { retry } from "nanoeffects/effects";
+
+type Events = { search: string; results: Item[] };
+
+const bus = createBus<Events>();
+
+// a new search aborts the previous one; the request is retried and cancelled with the task
+bus.on(
+	"search",
+	latest(async (query, ctx) => {
+		const items = await retry(ctx, () => api.search(query, { signal: ctx.signal }));
+		ctx.emit("results", items); // does nothing if this task was aborted meanwhile
+	}),
+);
+
+bus.emit("search", "nano");
+```
+
+What it is for: the glue between events and async work in an app, where the usual answer is a pile of `AbortController`s, `debounce` from lodash, `p-queue` and a hand-written retry. Here they share one model of cancellation and one trace.
+
+- **Tiny core.** `createBus` is about 1.2 kB gzip. Everything else is a separate entry and is bundled only when imported.
+- **Cancellation is the base of everything.** Aborting a task aborts its children, ends its `ctx.on` subscriptions and drops its result.
+- **Policies and effects are functions**: `latest`, `leading`, `debounce`, `throttle`, `queue`, `retry`, `timeout`, `poll`, `all`, `allSettled`, `race`, `take`.
+- **Typed commands, actions, jobs and modules** to describe what the app does apart from the code that does it.
+- **Tracing by design**: causal links between tasks, sampling, Redux DevTools, and a build that cuts all of it out.
+- **Checked against the libraries it replaces**: `throttle` and `debounce` are compared with lodash on random call sequences, and known issues of lodash, RxJS, p-queue, p-retry, bottleneck and effector are regression tests.
+
+## Install
+
+```bash
+npm install nanoeffects
+```
+
+ESM only, no dependencies. Types are included.
+
+## Entries
+
+| Import                  | What is in it                                                                          |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| `nanoeffects`           | `createBus`, the types (`Bus`, `Context`, `WithContext`, ...)                          |
+| `nanoeffects/policies`  | `latest`, `leading`, `debounce`, `throttle`, `queue`                                   |
+| `nanoeffects/effects`   | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `cancellable`, `onAbort` |
+| `nanoeffects/actions`   | `createAction`, `createCommand`, `createJob`, `createModule`, `registerModules`        |
+| `nanoeffects/redux`     | `createEffectsMiddleware`, `nanoeffectsMiddleware`: Redux actions to the bus, `ctx.store` in tasks |
+| `nanoeffects/observable` | `createObserve`: an event of the bus as an Observable (RxJS and others)               |
+| `nanoeffects/trace`     | `createTracer` and the loggers (Redux DevTools, console, performance)                  |
+
+## Handlers and the task context
+
+`bus.on(event, handler)` calls `handler(payload, ctx)` for every `bus.emit(event, payload)`. Each call is a task with its own context:
+
+| `ctx`            | Meaning                                                                        |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `signal`, `abort` | the abort signal of the task, and a way to abort it (and its children)         |
+| `emit`           | emit as this task; does nothing after the task is aborted                      |
+| `on`, `off`      | subscribe as this task; the subscription ends when the task aborts             |
+| `run(fn, ...)`   | a child task: aborted with this one, its errors go to this one                 |
+| `type`, `payload` | the event the task works on                                                    |
+
+`emit` is a synchronous loop over the handlers, and `bus.on` returns the function that unsubscribes.
+
+**The event map is optional.** Describe the events once, `type Events = { name: Payload }` (an event without data is `void`), and `createBus<Events>()` checks every `on` and `emit`. Or skip it: `createBus()` takes any string as an event and passes the payload as `unknown`. Actions and commands bring their own types, so they are typed on either kind of bus: `createAction("user/loaded")` needs no generics on a bus with an event map (the payload type comes from the map), and `createAction<User>("user/loaded")` gives it on a bus without one. On a bus with an event map, an action or a command that is emitted by its object must have its type in the map.
+
+The event map is optional. Describe the events once, `type Events = { name: Payload }` (an event without data is `void`), and `createBus<Events>()` checks every `on` and `emit`. Or skip it: `createBus()` takes any string as an event and passes the payload as `unknown`. Actions and commands bring their own types, so they are typed on either kind of bus.
+
+## Where to go next
+
+- [Policies](docs/policies.md): `latest`, `leading`, `debounce`, `throttle`, `queue`, and `key` for a state per key.
+- [Effects and cancellation](docs/effects.md): `retry`, `timeout`, `poll`, `take`, `all`, `race`, and `ctx.on`.
+- [Actions, commands, jobs and modules](docs/actions.md): describe what an app does apart from the code that does it.
+- [Your own fields in the context](docs/context.md): a store, a client or a logger in every task, with types.
+- [Errors and unheard events](docs/errors.md): `onError` and `onUnhandled`.
+- [Tracing](docs/tracing.md): causal traces, Redux DevTools, sampling, and a build without tracing.
+- [Redux, Zustand, MobX](docs/stores.md).
+- [Observable](docs/observable.md): events as streams for RxJS and others.
+- [Hot reload](docs/hmr.md): modules are replaced by name, so an edit does not pile up handlers.
+- [Semantics](docs/semantics.md): the rules that hold everywhere.
+- [`examples/`](examples): code that is type-checked together with the project.
+
+## Development
+
+```bash
+pnpm verify     # type check, lint, tests, build, integration tests, package checks, bundle size: what CI runs
+pnpm test       # vitest
+pnpm test:integration  # the real Redux Toolkit, Zustand, MobX, Jotai; Vite and webpack bundling the package
+pnpm check      # biome with the readability plugins in lint/
+```
+
+[`AGENTS.md`](AGENTS.md) (also read by Claude Code through `CLAUDE.md`) describes the structure, the decisions behind it and the rules of the code, for people and for AI assistants that work on the project.

package/dist/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?: Tracer;
+  /**
+   * 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 };

package/dist/actions.d.ts

@@ -0,0 +1,196 @@
+import { L as UnsubscribeCallback, N as Task, c as Command, j as PayloadOf, k as EventMap, m as Emittable, n as FreeActionCreator, o as Bus, r as createAction, t as ActionCreator, u as Context } from "./action-BM-UdmJr.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
+ * ```
+ */
+export 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)]);
+ * ```
+ */
+export declare const bindHandler: <P, R, E extends EventMap>(command: Command<P, R>, fn: Task<P, E, R>) => Binding<E>;
+/**
+ * The handlers bound to commands, for `createBus({ commands })`. Each bus gets
+ * its own, so each test can have its own implementation. `handle` binds more
+ * later and returns the function that unbinds.
+ *
+ * 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 commands = createCommands([bindHandler(sendMail, smtpSend)]);
+ * const bus = createBus<Events>({ commands });
+ *
+ * const unbind = commands.handle(getUser, async () => fakeUser);
+ * unbind(); // the command's own handler is back
+ * ```
+ */
+export declare const createCommands: <E extends EventMap = EventMap>(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/job.d.ts
+/**
+ * Creates a command whose outcome is sent on: when the handler succeeds, its
+ * result goes to `done`, and when it fails, the error goes to `fail`. Each is
+ * anything `emit` takes as its first argument, and receives the result (or the
+ * error) as the payload: an event type, an action creator, a command, or a
+ * plain action. It is made for the case where nobody waits for the result and
+ * the bus carries it on, like `createAsyncThunk` or an effector effect.
+ *
+ * `bus.emit(job, payload)` returns a promise of the result. When `fail` is set
+ * the error counts as handled: it goes to `fail` and the promise resolves with
+ * `undefined`; without `fail` the promise rejects. The outcome is routed by the
+ * bus, also for a handler bound with `commands.handle`, and is skipped once the
+ * task is aborted. Calling the job directly runs only its handler.
+ *
+ * @example
+ * ```ts
+ * const loaded = createAction<User>("user/loaded");
+ * const failed = createAction<Error>("user/failed");
+ *
+ * const loadUser = createJob("user/load", fetchUser, { done: loaded, fail: failed });
+ *
+ * bus.on(loaded, (user) => render(user));
+ * bus.emit(loadUser, "1"); // loaded(user) or failed(error) comes later
+ * ```
+ */
+export declare const createJob: <P = void, R = void, T extends string = string, E extends EventMap = EventMap>(type: T, handler?: Task<P, E, R>, outcomes?: {
+  /** Gets the result when the handler succeeds. */
+  done?: Emittable<E>;
+  /** Gets the error when the handler fails. */
+  fail?: Emittable<E>;
+}) => Command<P, Promise<Awaited<R> | undefined>> & {
+  readonly type: T;
+};
+//#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;
+  /**
+   * Mounts sub-modules; they are unmounted with this one. The returned function
+   * unmounts just these, e.g. when they were added later from a listener.
+   */
+  use(...modules: Module<E>[]): 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"));
+ *   });
+ * });
+ * ```
+ */
+export 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 `registerModules` 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;
+};
+/**
+ * Assembles an app from modules on `bus`: mounts `modules` at once, in the
+ * order given, and returns `mount`, `unmount`, `isMounted` and `dispose` for
+ * the modules that come and go later. The bus runs the commands that the
+ * modules bind: if it was made with `commands: createCommands()` that registry
+ * is used, otherwise the app brings 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 = registerModules(bus, [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();
+ * ```
+ */
+export declare const registerModules: <E extends EventMap>(bus: Bus<E>, modules?: readonly Module<E>[]) => ModuleApi<E>;
+//#endregion
+export { type ActionCreator, type Binding, type FreeActionCreator, type Module, type ModuleApi, type ModuleContext, createAction };

package/dist/actions.js

@@ -0,0 +1 @@
+import{t as e}from"./onAbort-BgMfspK4.js";import{i as t,n}from"./context-BXQ6Einm.js";import{t as r}from"./event-0RIBGYqS.js";function i(e,t){return Object.assign((...n)=>({type:e,payload:t?t(...n).payload:n[0]}),{type:e,match:t=>t.type===e,toString:()=>e})}var a=class extends Error{};const o=(e,t)=>Object.assign((r,i)=>{if(!t)throw new a(`No handler for command "${e}"`);return t(r,i??n({type:e,payload:r}).ctx)},{type:e}),s=(e,t)=>[e,t],c=(e=[])=>{let t=/* @__PURE__ */ new Map,n=(e,n)=>{let r={fn:n};return t.set(e,[...t.get(e)??[],r]),()=>{let n=(t.get(e)??[]).filter(e=>e!==r);n.length>0?t.set(e,n):t.delete(e)}};function i(e,t){if(t)return n(r(e),t);let i=e.map(([e,t])=>n(r(e),t));return()=>{for(let e of i)e()}}return i(e),{run:(e,n,r)=>{let i=(t.get(e.type)??[]).at(-1)?.fn,a=i&&e.wrap?e.wrap(i):i??e;return Reflect.apply(a,null,[n,r])},handle:i}},l=(e,t,n)=>{let r=e.emit;typeof t==`string`?r(t,n):typeof t==`function`?r(`match`in t?t.type:t,n):r({type:t.type,payload:n})},u=e=>{try{return Promise.resolve(e())}catch(e){if(e instanceof a)throw e;return Promise.reject(e)}},d=(e,t,n={})=>{let r=o(e,t),i=(e,t,r)=>{let i=r;return u(()=>Reflect.apply(e,null,[t,r])).then(e=>(n.done&&l(i,n.done,e),e),e=>{if(!n.fail)throw e;l(i,n.fail,e)})};return Object.assign((e,t)=>t?i(r,e,t):u(()=>r(e)),{type:e,wrap:e=>(t,n)=>i(e,t,n)})},f=(e,t)=>({name:e,setup:t}),p=(r,i=[])=>{let a=r.commands??c();r.commands??=a;let o={handle:(...e)=>{if(!a.handle)throw Error("registerModules: the `commands` of the bus is not a registry from `createCommands()`");return Reflect.apply(a.handle,null,e)}},s=n({type:`app`,payload:void 0},r,r.trace),l=n=>{let r=/* @__PURE__ */ new Map,i=/* @__PURE__ */ new Map;return{mount:a=>{let s=r.get(a);if(s)return s;let c=i.get(a.name);c&&r.get(c)?.();let u=t(n,a.name),d=u.ctx,f=l(d),p=()=>{r.delete(a),i.get(a.name)===a&&i.delete(a.name),d.abort(),u.unlink()};r.set(a,p),i.set(a.name,a);let m=(t,n)=>{let r=Reflect.apply(o.handle,null,[t,n]);return e(d,r),r},h=(...e)=>{let t=e.map(f.mount);return()=>{for(let e of t)e()}},g=(e,...t)=>{d.run(e,...t).catch(e=>{if(!d.signal.aborted)throw e})};try{a.setup(Object.assign(d,{handle:m,use:h,spawn:g}))}catch(e){throw p(),e}return p},unmount:e=>r.get(e)?.(),isMounted:e=>r.has(e)}},u=l(s.ctx);for(let e of i)u.mount(e);return{commands:a,mount:e=>(s.ctx.signal.throwIfAborted(),u.mount(e)),unmount:u.unmount,isMounted:u.isMounted,dispose:()=>s.ctx.abort()}};export{s as bindHandler,i as createAction,o as createCommand,c as createCommands,d as createJob,f as createModule,p as registerModules};

package/dist/bus-RUiw8f9p.js

@@ -0,0 +1 @@
+import{n as e}from"./onAbort-BgMfspK4.js";import{a as t,n,r}from"./context-BXQ6Einm.js";import{n as i}from"./promise-CSLpzwSR.js";import{n as a,t as o}from"./event-0RIBGYqS.js";const s=`*`,c=()=>{let e={},t=/* @__PURE__ */ new WeakSet,n=n=>{let r=e[n]??[];if(!t.has(r))return e[n]=r,r;let i=[...r];return e[n]=i,i},r=(t,r)=>{if(!r){e[t]=[];return}let i=(e[t]??[]).indexOf(r);i>=0&&n(t).splice(i,1)};return{get:n=>{let r=e[n]??[];return t.add(r),r},add:(e,t)=>(n(e).push(t),()=>{r(e,t)}),remove:r}},l=(e,t,n)=>Reflect.apply(e,null,[t,n]),u=(s={})=>{let u=c(),d=(e,t)=>u.add(o(e),t),f=(e,t)=>u.remove(o(e),t),p=(t,a)=>{let{onError:o}=s,{ctx:c}=n(a,m,s.trace,{ref:r()});if(!o){t(a.payload,c);return}let l=t=>{try{o(t,a)}catch(t){e(`onError failed`,t)}};try{let e=t(a.payload,c);i(e)&&Promise.resolve(e).catch(l)}catch(e){l(e)}},m={on:d,off:f,emit:(e,i)=>{let c=o(e),d=a(e,i),f={type:c,payload:d},h=[...u.get(c),...u.get(`*`)];h.length===0&&typeof e!=`function`&&s.onUnhandled?.(f);for(let e of h)p(e,f);if(typeof e==`function`){let{ctx:i}=n(f,m,s.trace,{ref:r()}),a=m.commands?.run??l;return t(i,`command`,()=>a(e,d,i))}},commands:s.commands,context:s.context,trace:s.trace};return m};export{s as n,u as t};

package/dist/context-BXQ6Einm.js

@@ -0,0 +1 @@
+import{t as e}from"./onAbort-BgMfspK4.js";const t=t=>{let n=new AbortController;return{controller:n,unlink:e({signal:t},e=>n.abort(e))}},n=typeof __NANOEFFECTS_TRACE__>`u`||__NANOEFFECTS_TRACE__,r=/* @__PURE__ */ new WeakMap;let i;const a=()=>i,o=()=>{},s=(e,t,i,a)=>{let o=n&&r.get(e);o&&o.tracer.report(o.ref,t,i,a)},c=(e,t)=>{let i=n&&r.get(e);return i?i.tracer.settler(i.ref,t):o},l=(e,t,i)=>{let a=n&&r.get(e);return a?a.tracer.run(a.ref,t,e.signal,i):i()},u=(e,t)=>typeof e==`function`?e(t):e,d=e=>e,f=(a,s,c,p)=>{let{controller:m,unlink:h}=t(p?.signal),{signal:g}=m,_=n&&c?{tracer:c,ref:c.task(a,p?.ref)}:void 0,v=(...e)=>{if(g.aborted)return;let t=s?.emit,n=i;i=_?.ref;try{return t?.(...e)}finally{i=n}},y=(...t)=>{if(g.aborted)return o;let n=s?.on,r=n?.(...t);if(!r)return o;let i=e({signal:g},r);return()=>{i(),r()}},b=async(e,...t)=>{g.throwIfAborted();let n=t[0],r=f({type:a.type,payload:n},s,c,{signal:g,ref:_?.ref});try{return await l(r.ctx,`run`,()=>e(n,r.ctx))}finally{r.unlink()}},x=d({...u(s?.context,a),type:a.type,payload:a.payload,signal:g,abort:e=>m.abort(e),emit:v,on:y,off:s?.off??o,run:b});return _&&r.set(x,_),{ctx:x,unlink:h}},p=(e,t)=>{let i=n?r.get(e):void 0;return f({type:t??e.type??``,payload:e.payload},{emit:e.emit,on:e.on,off:e.off,context:e},i?.tracer,{signal:e.signal,ref:i?.ref})};export{l as a,p as i,f as n,s as o,a as r,c as t};

package/dist/delay-CIHnOh_L.js

@@ -0,0 +1 @@
+import{t as e}from"./onAbort-BgMfspK4.js";const t=2**31-1,n=(e,n)=>{let r={id:null};if(n===1/0)return r;let i=n=>{r.id=setTimeout(()=>{n>t?i(n-t):(r.id=null,e())},Math.min(n,t))};return i(n>0?n:0),r},r=e=>{e.id!==null&&(clearTimeout(e.id),e.id=null)},i=(t,i)=>new Promise((a,o)=>{let s=n(()=>{c(),a()},typeof i==`function`?i():i),c=e(t,e=>{r(s),o(e)})});export{r as n,n as r,i as t};