nanoeffects 0.1.0 → 0.2.1

package/README.md

@@ -1,36 +1,53 @@
 # nanoeffects
 
-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.
+[![npm](https://img.shields.io/npm/v/nanoeffects)](https://www.npmjs.com/package/nanoeffects)
+[![CI](https://github.com/nanoeffects/nanoeffects/actions/workflows/ci.yml/badge.svg)](https://github.com/nanoeffects/nanoeffects/actions/workflows/ci.yml)
+[![size](https://img.shields.io/bundlephobia/minzip/nanoeffects)](https://bundlephobia.com/package/nanoeffects)
+[![license](https://img.shields.io/npm/l/nanoeffects)](LICENSE)
+
+A small typed event bus. Handlers are tasks with an `AbortSignal`, and policies (`latest`, `debounce`, `throttle`, `queue`) and effects (`retry`, `timeout`) are plain functions that go straight into `on`.
 
 ```ts
 import { createBus } from "nanoeffects";
-import { latest } from "nanoeffects/policies";
-import { retry } from "nanoeffects/effects";
 
-type Events = { search: string; results: Item[] };
+type Events = { greet: string };
 
 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
-	}),
-);
+const unbind = bus.on("greet", (name) => console.log(`hello ${name}`));
 
-bus.emit("search", "nano");
+bus.emit("greet", "Ada"); // hello Ada
+unbind(); // `on` returns the unsubscribe function, as in nanoevents
 ```
 
-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.
+`emit` takes the event as a string, as an object `{ type, payload }` (a Redux action fits as it is), or as a function with a `type`, a command that runs and returns its result:
 
-- **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.
+```ts
+bus.emit("greet", "Ada");
+bus.emit({ type: "greet", payload: "Ada" });
+bus.emit(double, 21); // a command: runs, returns 42
+```
+
+Then the same bus with a policy, no other change:
+
+```ts
+import { latest } from "nanoeffects/policies";
+
+// a newer search aborts the older one
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query, { signal: ctx.signal });
+    ctx.emit("results", items);
+  }),
+);
+```
+
+- **Tiny.** `createBus` is about 1.2 kB gzip; every other entry is bundled only when imported.
+- **Cancellation first.** Aborting a task aborts its children and `ctx.on` subscriptions and drops its result.
+- **One model** instead of `AbortController`, lodash `debounce`, `p-queue` and a hand-written retry.
+- **Typed** commands, actions, jobs and modules; **traced** with Redux DevTools; the trace can be cut out of the build.
+- **Checked** against lodash on random call sequences, and against known issues of RxJS, p-queue, p-retry and effector.
 
 ## Install
 
@@ -38,59 +55,43 @@ What it is for: the glue between events and async work in an app, where the usua
 npm install nanoeffects
 ```
 
-ESM only, no dependencies. Types are included.
+ESM only, no dependencies, types 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:
+| Import                   | What is in it                                                                 |
+| ------------------------ | ----------------------------------------------------------------------------- |
+| `nanoeffects`            | `createBus`, the types                                                        |
+| `nanoeffects/policies`   | `latest`, `leading`, `debounce`, `throttle`, `queue`                          |
+| `nanoeffects/effects`    | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`      |
+| `nanoeffects/actions`    | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin` |
+| `nanoeffects/redux`      | `createEffectsMiddleware`                                                     |
+| `nanoeffects/observable` | `createObserve`: an event as an Observable (RxJS)                             |
+| `nanoeffects/dev`        | `devPlugin`: warnings about listeners that pile up and messages about modules; a no-op in production |
+| `nanoeffects/trace`      | `createTracer` and the loggers                                                |
 
-| `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                                                    |
+## The task context
 
-`emit` is a synchronous loop over the handlers, and `bus.on` returns the function that unsubscribes.
+`bus.on(event, handler)` calls `handler(payload, ctx)`. Each call is a task:
 
-**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.
+| `ctx`             | Meaning                                                  |
+| ----------------- | -------------------------------------------------------- |
+| `signal`, `abort` | the signal of the task, and a way to abort it            |
+| `emit`            | emit as this task; does nothing after an abort           |
+| `on`, `off`       | subscribe; the subscription ends when the task aborts    |
+| `run(fn, ...)`    | a child task, aborted with this one                      |
+| `type`, `payload` | the event the task works on                              |
 
-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.
+The event map (`type Events = { name: Payload }`) is optional: `createBus()` takes any string event with an `unknown` payload. `createAction("user/loaded")` takes its payload type from the map, and `createAction<User>("user/loaded")` gives it when there is none.
 
-## Where to go next
+## Docs
 
-- [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.
+[**Guide**](docs/guide.md) · [Policies](docs/policies.md) · [Effects](docs/effects.md) · [Actions, commands, modules](docs/actions.md) · [Context fields](docs/context.md) · [Errors](docs/errors.md) · [Tracing](docs/tracing.md) · [Redux, Zustand, MobX](docs/stores.md) · [Observable](docs/observable.md) · [Hot reload and dev diagnostics](docs/hmr.md) · [Semantics](docs/semantics.md) · [Examples](examples)
 
 ## 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/
+pnpm verify   # what CI runs: types, lint, tests, build, integration, package checks, size
 ```
 
-[`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.
+[`AGENTS.md`](AGENTS.md) describes the structure and the rules of the code, for people and AI assistants.

package/dist/{action-BM-UdmJr.d.ts → action-rqZEnRIp.d.ts}

@@ -175,19 +175,19 @@ 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`. */
+  /**
+   * Calls `plugin` with the bus and returns what it returns: an api, a
+   * function that undoes it. A plugin is any function of the bus; the bus keeps
+   * no list of them. See `modulePlugin` in `nanoeffects/actions`.
+   */
+  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;
-  /** What runs the commands; `registerModules` sets it when the bus was made without. */
+  /** What runs the commands; `createCommands(bus)` and `modulePlugin` set it. Without one a command runs its own handler. */
   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;
   /**
@@ -214,9 +214,10 @@ type BusOptions<E extends EventMap> = {
   /**
    * 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.
+   * 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>;
 };

package/dist/actions.d.ts

@@ -1,196 +1,58 @@
-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
+import { N as Task, c as Command, k as EventMap, n as FreeActionCreator, r as createAction, t as ActionCreator } from "./action-rqZEnRIp.js";
+import { a as modulePlugin, c as createCommand, i as createModule, l as createCommands, n as ModuleApi, o as Binding, r as ModuleContext, s as bindHandler, t as Module } from "./module-BSCdR9D1.js";
 //#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;
+type Creator = {
+  (...args: never[]): {
+    type: string;
+    payload?: unknown;
+  };
+  readonly type: string;
 };
-/**
- * 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;
+type Outcome = string | Creator;
+/** What `createJob` returns: the command of the job and the actions of its outcome. */
+type Job<P, R, T extends string, S extends Outcome, F extends Outcome> = {
+  command: Command<P, Promise<Awaited<R> | undefined>> & {
+    readonly type: T;
+  };
+  /** Made from a string with the result as its payload, or the creator that was given. */
+  successAction: S extends string ? ActionCreator<Awaited<R>, S> : S;
+  /** Made from a string with the error as its payload, or the creator that was given. */
+  failAction: F extends string ? ActionCreator<unknown, F> : F;
 };
 /**
- * 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.
+ * Creates a job: a command whose outcome is sent on as actions. When the
+ * handler succeeds, `successAction(result)` is emitted on the bus, and when it
+ * fails, `failAction(error)`. It is made for the case where nobody waits for
+ * the result and the bus carries it on, like `createAsyncThunk` or an effector
+ * effect. It returns the three together: `{ command, successAction, failAction }`.
+ *
+ * `success` and `fail` are a type string, from which the job makes an action
+ * creator with `createAction`, or an action creator that exists already, which
+ * is used and returned as it is. A missing one is made with the type
+ * `<type>/success` or `<type>/fail`.
+ *
+ * `bus.emit(command, payload)` returns a promise of the result. An error of the
+ * handler always counts as handled: it goes to `failAction` and the promise
+ * resolves with `undefined`; a command is the tool for a result that must reject.
+ * The actions are emitted as the task that ran the job, also for a handler bound
+ * with `commands.handle`, and are skipped once the task is aborted. A missing
+ * handler is not an outcome: `emit` throws `MissingHandlerError`. Calling the
+ * command directly runs only its handler.
  *
  * @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)
+ * const { command: loadUser, successAction: userLoaded, failAction: userFailed } =
+ *   createJob("user/load", fetchUser, { success: "user/loaded", fail: "user/failed" });
  *
- * bus.emit(getUser, "1");
- * app.commands.handle(getUser, fakeUser); // in a test
- * app.dispose();
+ * bus.on(userLoaded, (user) => render(user));
+ * bus.emit(loadUser, "1"); // userLoaded(user) or userFailed(error) comes later
  * ```
  */
-export declare const registerModules: <E extends EventMap>(bus: Bus<E>, modules?: readonly Module<E>[]) => ModuleApi<E>;
+export declare const createJob: <P = void, R = void, T extends string = string, E extends EventMap = EventMap, S extends Outcome = `${T}/success`, F extends Outcome = `${T}/fail`>(type: T, handler?: Task<P, E, R>, outcomes?: {
+  /** Gets the result when the handler succeeds: a type to make an action creator of, or an action creator. */
+  success?: S;
+  /** Gets the error when the handler fails: a type to make an action creator of, or an action creator. */
+  fail?: F;
+}) => Job<P, R, T, S, F>;
 //#endregion
-export { type ActionCreator, type Binding, type FreeActionCreator, type Module, type ModuleApi, type ModuleContext, createAction };
+export { type ActionCreator, type Binding, type FreeActionCreator, type Job, type Module, type ModuleApi, type ModuleContext, bindHandler, createAction, createCommand, createCommands, createModule, modulePlugin };

package/dist/actions.js

@@ -1 +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};
+import{t as e}from"./onAbort-BgMfspK4.js";import{i as t,n}from"./context-DlA80GOA.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({event:{type:e,payload:r}}).ctx)},{type:e}),s=(e,t)=>[e,t],c=(e,t=[])=>{let n=/* @__PURE__ */ new Map,i=(e,t)=>{let r={fn:t};return n.set(e,[...n.get(e)??[],r]),()=>{let t=(n.get(e)??[]).filter(e=>e!==r);t.length>0?n.set(e,t):n.delete(e)}};function a(e,t){if(t)return i(r(e),t);let n=e.map(([e,t])=>i(r(e),t));return()=>{for(let e of n)e()}}a(t);let o={run:(e,t,r)=>{let i=(n.get(e.type)??[]).at(-1)?.fn,a=i&&e.wrap?e.wrap(i):i??e;return Reflect.apply(a,null,[t,r])},handle:a};return e.commands=o,o},l=e=>typeof e==`string`?i(e):e,u=(e,t,n)=>{let r=e.emit;r(Reflect.apply(t,null,[n]))},d=e=>{try{return Promise.resolve(e())}catch(e){if(e instanceof a)throw e;return Promise.reject(e)}},f=(e,t,n={})=>{let r=o(e,t),i=l(n.success??`${e}/success`),a=l(n.fail??`${e}/fail`),s=(e,t,n)=>{let r=n;return d(()=>Reflect.apply(e,null,[t,n])).then(e=>(u(r,i,e),e),e=>{u(r,a,e)})};return{command:Object.assign((e,t)=>t?s(r,e,t):d(()=>r(e)),{type:e,wrap:e=>(t,n)=>s(e,t,n)}),successAction:i,failAction:a}},p=(e,t)=>({name:e,setup:t}),m=(r=[])=>i=>{let a=i.commands??c(i),o={handle:(...e)=>{if(!a.handle)throw Error("modulePlugin: the `commands` of the bus is not a registry from `createCommands()`");return Reflect.apply(a.handle,null,e)}},s=n({event:{type:`app`,payload:void 0},bus:i,tracer:i.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(e=>typeof e==`function`?m(e,e):f.mount(e));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 r)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,f as createJob,p as createModule,m as modulePlugin};

package/dist/bus-CRnlwmQ4.js

@@ -0,0 +1 @@
+import{n as e}from"./onAbort-BgMfspK4.js";import{a as t,n,r}from"./context-DlA80GOA.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({event:a,bus:m,tracer:s.trace,parent:{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({event:f,bus:m,tracer:s.trace,parent:{ref:r()}}),a=m.commands?.run??l;return t(i,`command`,()=>a(e,d,i))}},use:e=>e(m),context:s.context,trace:s.trace};return m};export{s as n,u as t};

package/dist/context-DlA80GOA.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=({event:a,bus:s,tracer:c,parent: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({event:{type:a.type,payload:n},bus:s,tracer:c,parent:{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({event:{type:t??e.type??``,payload:e.payload},bus:{emit:e.emit,on:e.on,off:e.off,context:e},tracer:i?.tracer,parent:{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/dev.d.ts

@@ -0,0 +1,46 @@
+import { L as UnsubscribeCallback, k as EventMap, o as Bus } from "./action-rqZEnRIp.js";
+import { n as ModuleApi } from "./module-BSCdR9D1.js";
+//#region src/dev/types.d.ts
+/** The parts of what `modulePlugin` returned that the diagnostics report. */
+type ReportedApp<E extends EventMap> = Pick<ModuleApi<E>, "mount" | "unmount" | "isMounted">;
+type DevOptions<E extends EventMap = EventMap> = {
+  /** Warn when more listeners than this are added to one event and not unsubscribed. Default 10. */
+  maxListeners?: number;
+  /** Check the number of listeners. Default `true`. */
+  leaks?: boolean;
+  /** Report the modules of `app` that are mounted, replaced and unmounted. Default `true`. */
+  modules?: boolean;
+  /** Receives every message. Default: `console.warn` for leaks and `console.info` for modules. */
+  log?: (message: string) => void;
+  /** What `modulePlugin` returned, to report its modules. */
+  app?: ReportedApp<E>;
+};
+/** A plugin that connects the diagnostics to a bus; the function it returns disconnects them. */
+type DevPlugin = <E extends EventMap>(options?: DevOptions<E>) => (bus: Bus<E>) => UnsubscribeCallback;
+//#endregion
+//#region src/dev/plugin.d.ts
+/**
+ * A plugin with development diagnostics for a bus, used while the app is built
+ * and while its files are reloaded:
+ *
+ * - **Listeners that pile up.** When more than `maxListeners` listeners are
+ *   added to one event and not unsubscribed, one warning names the event and
+ *   the count: a file that was reloaded and subscribes again, or an
+ *   unsubscribe that is never called. The count follows the function that `on`
+ *   returns; `bus.off(event, fn)` is not seen.
+ * - **Modules.** With `app` (what `modulePlugin` returned) it reports a
+ *   module that is mounted, replaced by name and unmounted.
+ *
+ * It wraps `bus.on`, `app.mount` and `app.unmount`; the function that `bus.use` returns
+ * puts the originals back. In a production build `nanoeffects/dev` is a no-op, so
+ * the call can stay as it is.
+ *
+ * @example
+ * ```ts
+ * const app = bus.use(modulePlugin([userModule]));
+ * const disconnect = bus.use(devPlugin({ app })); // warnings and messages in the console while developing
+ * ```
+ */
+export declare const devPlugin: DevPlugin;
+//#endregion
+export type { DevOptions, DevPlugin };

package/dist/dev.js

@@ -0,0 +1 @@
+import{t as e}from"./event-0RIBGYqS.js";const t=`[nanoeffects]`,n=(e={})=>t=>{let{maxListeners:n=10,leaks:a=!0,modules:o=!0,app:s}=e,c=e.log??(e=>console.warn(e)),l=e.log??(e=>console.info(e)),u=[];return a&&u.push(r(t,n,c)),o&&s&&u.push(i(s,l)),()=>{for(let e of u.splice(0))e()}},r=(n,r,i)=>{let a=n.on,o=/* @__PURE__ */ new Map,s=/* @__PURE__ */ new Set;return n.on=(...c)=>{let[l]=c,u=e(l),d=(o.get(u)??0)+1;o.set(u,d),d>r&&!s.has(u)&&(s.add(u),i(`${t} ${d} listeners of "${u}" were added and not unsubscribed (more than ${r}). A file that is reloaded and subscribes again, or an unsubscribe that is never called?`));let f=Reflect.apply(a,n,c),p=!1;return()=>{if(!p){p=!0;let e=(o.get(u)??1)-1;o.set(u,e),e<=r&&s.delete(u)}f()}},()=>{n.on=a}},i=(e,n)=>{let{mount:r,unmount:i}=e,a=/* @__PURE__ */ new Map;return e.mount=i=>{let o=a.get(i.name);if(o===i&&e.isMounted(i))return r(i);let s=o!==void 0&&e.isMounted(o),c=r(i);return a.set(i.name,i),n(`${t} module "${i.name}" ${s?`replaced`:`mounted`}`),()=>{e.isMounted(i)&&n(`${t} module "${i.name}" unmounted`),c()}},e.unmount=r=>{e.isMounted(r)&&n(`${t} module "${r.name}" unmounted`),i(r)},()=>{e.mount=r,e.unmount=i}};export{n as devPlugin};