nanoeffects 0.3.0 → 0.5.0

package/README.md

@@ -5,93 +5,91 @@
 [![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`.
+A small event bus for JavaScript apps. Each handler runs as a **task** with an `AbortSignal`, so you can cancel in-flight work. Policies (`latest`, `debounce`, …) and effects (`retry`, `timeout`, …) are plain functions you pass to `on`.
 
-```ts
-import { createBus } from "nanoeffects";
+## Install
 
-type Events = { greet: string };
+```bash
+npm install nanoeffects
+```
+
+ESM only, no dependencies, types included.
 
-const bus = createBus<Events>();
+Want to try it first? [Open the playground](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/playground): a search box with `debounce` and `latest`, running in your browser, no install. More playgrounds (React) and recipes: [Examples](examples/README.md).
 
-const unbind = bus.on("greet", (name) => console.log(`hello ${name}`));
+## Create a bus
+
+Subscribe with `on`, send with `emit`. `on` returns a function that unsubscribes.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // event bus; each handler call is a task
+
+const unbind = bus.on("greet", (name) => {
+  console.log(`hello ${name}`);
+});
 
 bus.emit("greet", "Ada"); // hello Ada
-unbind(); // `on` returns the unsubscribe function, as in nanoevents
+unbind();
 ```
 
-`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:
+That is enough for a small app or a widget. The handler’s second argument is a task context (`signal`, `emit`, …). See the [Guide](docs/guide.md).
 
-```ts
-bus.emit("greet", "Ada");
-bus.emit({ type: "greet", payload: "Ada" });
-bus.emit(double, 21); // a command: runs, returns 42
-```
+## Abort overlapping work
 
-Then the same bus with a policy, no other change:
+In a SPA, a newer search should abort the older one. Wrap the handler in `latest` and pass `ctx.signal` to `fetch` (and similar APIs).
 
-```ts
+```js
+import { createBus } from "nanoeffects";
 import { latest } from "nanoeffects/policies";
 
-// a newer search aborts the older one
+const bus = createBus();
+
+// latest — a newer run aborts the older one
 bus.on(
   "search",
   latest(async (query, ctx) => {
+    // signal — lets latest cancel this request, not only drop its result
     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.
+Same `on` / `emit`. Replace `api.search` with your own request.
 
-## Install
+## Get a result from `emit`
 
-```bash
-npm install nanoeffects
-```
+A **command** is like an event, but `emit` runs its handler and returns the result (a promise if the handler is async).
 
-ESM only, no dependencies, types included.
-
-## Entries
-
-| 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                                                |
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
 
-## The task context
+const bus = createBus();
 
-`bus.on(event, handler)` calls `handler(payload, ctx)`. Each call is a task:
+// createCommand — emit runs the handler and returns what it returns
+const double = createCommand("math/double", (value) => value * 2);
 
-| `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                              |
+const answer = bus.emit(double(21)); // 42
+```
 
-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.
+More (contracts, jobs, modules): [Actions](docs/actions.md).
 
 ## Docs
 
-[**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)
+Start with the [Guide](docs/guide.md) (bus → policies → effects → modules). Or jump by need:
 
-## Development
+| Need | Page |
+| ---- | ---- |
+| Async UI races (search, submit) | [Policies](docs/policies.md) |
+| Retry, timeout, wait for events | [Effects](docs/effects.md) |
+| Domain logic off the UI | [Actions, commands, modules](docs/actions.md) |
+| Redux / Zustand / MobX | [Stores](docs/stores.md) |
 
-```bash
-pnpm verify   # what CI runs: types, lint, tests, build, integration, package checks, size
-```
+[Full index, package entries, tracing](docs/README.md) · [Examples](examples/README.md)
 
-[`AGENTS.md`](AGENTS.md) describes the structure and the rules of the code, for people and AI assistants.
+- **Tiny.** `createBus` is about 1.3 kB gzip; other entries load only when imported.
+- **Cancellation first.** Aborting a task aborts its children and drops its result.
+- **One model** instead of hand-rolled `AbortController`, lodash debounce, and retry glue.

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

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

package/dist/actions.d.ts

@@ -1,5 +1,74 @@
-import { N as Task, k as EventMap, n as FreeActionCreator, r as createAction, t as ActionCreator } from "./action-Bdfp-Wvd.js";
-import { a as modulePlugin, c as bindHandler, i as createModule, l as commandsPlugin, n as ModuleApi, o as Binding, r as ModuleContext, s as MadeCommand, t as Module, u as createCommand } from "./module-I1ixyJzx.js";
+import { D as EventKey, _ as Bus, c as PayloadOf, n as Free, o as EventMap, r as FreeActionCreator, t as ActionCreator, u as Task } from "./action-creator-DOWcbXpy.js";
+import { a as modulePlugin, c as bindHandler, i as createModule, l as commandsPlugin, n as ModuleApi, o as Binding, r as ModuleContext, s as MadeCommand, t as Module, u as createCommand } from "./module-DCJl-qfi.js";
+//#region src/actions/action.d.ts
+/**
+ * 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));
+ * ```
+ */
+export declare function createAction<P = Free, T extends string = string>(type: T): [P] extends [Free] ? FreeActionCreator<T> : ActionCreator<P, T>;
+export declare function createAction<A extends unknown[], P, T extends string = string>(type: T, prepare: (...args: A) => {
+  payload: P;
+}): ActionCreator<P, T, A>;
+//#endregion
+//#region src/actions/emitter.d.ts
+/** What `emitterPlugin` adds to the bus. */
+type EmitterApi<E extends EventMap> = {
+  /**
+   * Turns an action creator into a function that emits its action on this
+   * bus, to pass as a callback. The function takes what the creator takes.
+   */
+  emitter: {
+    /** A creator without a payload type: the payload comes from the event map. */
+    <K extends EventKey<E>>(creator: FreeActionCreator<K>): (...payload: PayloadOf<E[K]>) => void;
+    <P, T extends string, A extends unknown[]>(creator: ActionCreator<P, T, A>): (...args: A) => void;
+  };
+};
+/**
+ * Adds `bus.emitter(creator)`: a function that emits the action of `creator`
+ * on this bus. Use it where something wants a callback, such as the
+ * subscription of a state manager, instead of `(value) => bus.emit(creator(value))`.
+ * The creator stays a plain `createAction`, so `bus.emit(creator(value))` and
+ * `bus.on(creator, …)` work as before. Returns the same bus.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { createAction, emitterPlugin } from "nanoeffects/actions";
+ *
+ * const bus = createBus().use(emitterPlugin());
+ * const nameChanged = createAction<string>("name/changed");
+ * const emitNameChanged = bus.emitter(nameChanged);
+ *
+ * // nanostores: the store calls it with the new value
+ * $name.listen(emitNameChanged);
+ * ```
+ */
+export declare const emitterPlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus<E> & EmitterApi<E>;
+//#endregion
 //#region src/actions/job.d.ts
 type Creator = {
   (...args: never[]): {
@@ -29,13 +98,13 @@ type Job<P, R, T extends string, S extends Outcome, F extends Outcome> = MadeCom
  * 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
+ * `bus.emit(job(payload))` returns a promise of the result. An error of the
  * handler always counts as handled: it goes to `job.fail` 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.
+ * job builds `{ type, payload }` like a command; it does not run the handler.
  *
  * @example
  * ```ts
@@ -45,7 +114,7 @@ type Job<P, R, T extends string, S extends Outcome, F extends Outcome> = MadeCom
  * });
  *
  * bus.on(loadUser.success, (user) => render(user));
- * bus.emit(loadUser, "1"); // loadUser.success(user) or loadUser.fail(error) comes later
+ * bus.emit(loadUser("1")); // loadUser.success(user) or loadUser.fail(error) comes later
  * ```
  */
 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?: {
@@ -55,4 +124,4 @@ export declare const createJob: <P = void, R = void, T extends string = string,
   fail?: F;
 }) => Job<P, R, T, S, F>;
 //#endregion
-export { type ActionCreator, type Binding, type FreeActionCreator, type Job, type Module, type ModuleApi, type ModuleContext, bindHandler, commandsPlugin, createAction, createCommand, createModule, modulePlugin };
+export { type ActionCreator, type Binding, type EmitterApi, type FreeActionCreator, type Job, type Module, type ModuleApi, type ModuleContext, bindHandler, commandsPlugin, createCommand, createModule, modulePlugin };

package/dist/actions.js

@@ -1 +1 @@
-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,match:t=>t.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(e);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 t.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 Object.assign((e,t)=>t?s(r,e,t):d(()=>r(e)),{type:e,match:r.match,wrap:e=>(t,n)=>s(e,t,n),success:i,fail: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 `commandsPlugin()`");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,c as commandsPlugin,i as createAction,o as createCommand,f as createJob,p as createModule,m as modulePlugin};
+import{t as e}from"./onAbort-BgMfspK4.js";import{i as t,n}from"./context-CK0ZomWt.js";import{t as r}from"./event-0RIBGYqS.js";import{r as i}from"./bus-BAs9x7IQ.js";function a(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 o=class extends Error{};const s=(e,t)=>{let n=t=>t.type===e;function r(n,r){if(typeof r==`object`){if(!t)throw new o(`No handler for command "${e}"`);return t(n,r)}return i(a,e,n)}let a=Object.assign(r,{type:e,match:n});return a},c=(e,t)=>[e,t],l=(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(e);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 t.commands=o,o},u=()=>e=>{function t(t){return(...n)=>{let r=t(...n);e.emit(r)}}return Object.assign(e,{emitter:t})},d=e=>typeof e==`string`?a(e):e,f=(e,t,n)=>{let r=e.emit;r(Reflect.apply(t,null,[n]))},p=e=>{try{return Promise.resolve(e())}catch(e){if(e instanceof o)throw e;return Promise.reject(e)}},m=(e,t,n={})=>{let r=s(e,t),a=d(n.success??`${e}/success`),o=d(n.fail??`${e}/fail`),c=(e,t,n)=>{let r=n;return p(()=>Reflect.apply(e,null,[t,n])).then(e=>(f(r,a,e),e),e=>{f(r,o,e)})},l=e=>(t,n)=>c(e,t,n);function u(t,n){return typeof n==`object`?c(r,t,n):i(m,e,t)}let m=Object.assign(u,{type:e,match:r.match,wrap:l,success:a,fail:o});return m},h=(e,t)=>({name:e,setup:t}),g=(r=[])=>i=>{let a=i.commands??l()(i),o={handle:(...e)=>{if(!a.handle)throw Error("modulePlugin: the `commands` of the bus is not a registry from `commandsPlugin()`");return Reflect.apply(a.handle,null,e)}},s=n({event:{type:`app`,payload:void 0},bus:i,tracer:i.trace}),c=n=>{let r=/* @__PURE__ */ new Map,i=/* @__PURE__ */ new Map;return{mount:a=>{let s=r.get(a);if(s)return s;let l=i.get(a.name);l&&r.get(l)?.();let u=t(n,a.name),d=u.ctx,f=c(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=c(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(),createModule:h}};export{c as bindHandler,l as commandsPlugin,a as createAction,s as createCommand,m as createJob,h as createModule,u as emitterPlugin,g as modulePlugin};

package/dist/bus-BAs9x7IQ.js

@@ -0,0 +1 @@
+import{n as e}from"./onAbort-BgMfspK4.js";import{a as t,n,r}from"./context-CK0ZomWt.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={},n=n=>(t[n]=void 0,e[n]??=/* @__PURE__ */ new Map,e[n]),r=(e,t)=>{let r=n(e),i=r.get(t)??0;i>1?r.set(t,i-1):t?r.delete(t):r.clear()};return{get:n=>(t[n]??=[...e[n]??[]].flatMap(([e,t])=>Array(t).fill(e)),t[n]),add:(e,t)=>{let i=n(e);return i.set(t,(i.get(t)??0)+1),()=>{r(e,t)}},remove:r,clear:()=>{for(let t of Reflect.ownKeys(e))delete e[t];for(let e of Reflect.ownKeys(t))delete t[e]}}},l=Symbol(`nanoeffects.commandCall`),u=(e,t,n)=>{let r={type:t,payload:n};return Object.defineProperty(r,l,{value:e,enumerable:!1}),r},d=e=>{if(typeof e==`function`)return e;if(typeof e==`object`&&e&&l in e)return e[l]},f=(e,t,n)=>Reflect.apply(e,null,[t,n]),p=(s={})=>{let l=c(),u=(e,t)=>l.add(o(e),t),p=(e,t)=>{let n=u(e,(e,r)=>(n(),t(e,r)));return n},m=(e,t)=>{e===void 0?l.clear():l.remove(o(e),t)},h=(t,a)=>{let{onError:o}=s,{ctx:c}=n({event:a,bus:g,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)}},g={on:u,once:p,off:m,emit:(e,i)=>{let c=o(e),u=a(e,i),p={type:c,payload:u},m=d(e),_=[...l.get(c),...l.get(`*`)];_.length===0&&!m&&s.onUnhandled?.(p);for(let e of _)h(e,p);if(m){let{ctx:e}=n({event:p,bus:g,tracer:s.trace,parent:{ref:r()}}),i=g.commands?.run??f;return t(e,`command`,()=>i(m,u,e))}},use:e=>e(g),ctx:s.context,trace:s.trace};return g};export{s as i,p as n,u as r,l as t};

package/dist/{context-DlA80GOA.js → context-CK0ZomWt.js}

@@ -1 +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};
+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?.ctx,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 s?.addContext?.(x),_&&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,ctx: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/context-plugin-B0sLWOxR.d.ts

@@ -0,0 +1,34 @@
+import { C as ContextOf, F as WithContext, _ as Bus, o as EventMap } from "./action-creator-DOWcbXpy.js";
+//#region src/core/context-plugin.d.ts
+/** What a function that makes the fields of a task gets to see. */
+type ContextTask = {
+  type: string;
+  payload?: unknown;
+};
+/**
+ * `unknown` when none of the `fields` is already a context field of the bus,
+ * else `never`: the call does not compile. Used as `bus: Bus<E> & NoClash<…>`.
+ */
+type NoClash<Fields extends object, E extends EventMap> = [keyof Fields & keyof ContextOf<E>] extends [never] ? unknown : never;
+/**
+ * Puts `fields` on the context of every task of the bus: a store, a client, a
+ * logger. The types come from the value, so the event map needs no
+ * `WithContext`. Returns the same bus, typed with the fields. A function gets
+ * `{ type, payload }` of the task and returns its fields.
+ *
+ * Several uses merge with each other, with the `context` option of `createBus`
+ * and with `effectsPlugin`. A name that the bus already has is a type error. The
+ * fields of the library (`signal`, `emit`, `run`, …) win, and a field that the
+ * context already has is not replaced.
+ *
+ * @example
+ * ```ts
+ * type Events = { "user/loaded": User };
+ *
+ * const bus = createBus<Events>().use(contextPlugin({ store }));
+ * bus.on("user/loaded", (user, { store }) => store.put(user)); // ctx.store: Store
+ * ```
+ */
+declare const contextPlugin: <Fields extends object>(fields: Fields | ((task: ContextTask) => Fields)) => <E extends EventMap>(bus: Bus<E> & NoClash<Fields, E>) => Bus<E & WithContext<Fields>>;
+//#endregion
+export { NoClash as n, contextPlugin as r, ContextTask as t };

package/dist/dev.d.ts

@@ -1,5 +1,5 @@
-import { L as UnsubscribeCallback, k as EventMap, o as Bus } from "./action-Bdfp-Wvd.js";
-import { n as ModuleApi } from "./module-I1ixyJzx.js";
+import { _ as Bus, m as UnsubscribeCallback, o as EventMap } from "./action-creator-DOWcbXpy.js";
+import { n as ModuleApi } from "./module-DCJl-qfi.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">;