nanoeffects 0.5.0 → 0.6.0

package/dist/notrace/plugin-B0AXKusc.d.ts

@@ -0,0 +1,207 @@
+import { R as EventMap, c as BoundForm, j as WithContext, p as Bus, u as Effects, v as Context, z as Keys } from "./action-creator-DKG_sIia.js";
+import { n as NoClash } from "./context-plugin-Dt1IgVo8.js";
+//#region src/utils/delay.d.ts
+/**
+ * Resolves after `ms`, or rejects early if `ctx.signal` aborts. `ms` can be a
+ * function that returns the number of ms, called once when the delay starts:
+ * handy for a random pause (jitter).
+ *
+ * @example
+ * ```ts
+ * await delay({}, 500);
+ *
+ * // 200 to 400 ms
+ * await delay({}, () => 200 + Math.random() * 200);
+ *
+ * // inside a task: stops waiting when the task is aborted
+ * bus.on("retry", async (_, ctx) => {
+ *   await delay(ctx, 1000);
+ *   await load();
+ * });
+ * ```
+ */
+declare const delay: (ctx: {
+  signal?: AbortSignal | undefined;
+}, ms: number | (() => number)) => Promise<void>;
+//#endregion
+//#region src/effects/run.d.ts
+/** Context passed into `race` / `all` effect starters. */
+type EffectContext = {
+  signal: AbortSignal;
+  abort: (reason?: unknown) => void;
+};
+type Starter<T> = (ctx: EffectContext) => T | PromiseLike<T>;
+//#endregion
+//#region src/effects/all.d.ts
+/**
+ * Runs all starters; waits for every result. On failure or parent abort, cancels the rest.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const { user, posts } = await all(ctx, {
+ *     user: ({ signal }) => fetchUser(id, { signal }),
+ *     posts: ({ signal }) => fetchPosts(id, { signal }),
+ *   });
+ *
+ *   // arrays work too: const [user, posts] = await all(ctx, [getUser, getPosts]);
+ * });
+ * ```
+ */
+declare function all<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+declare function all<const T extends readonly Starter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+//#endregion
+//#region src/effects/allSettled.d.ts
+/**
+ * Runs all starters and waits for every one to settle, whether it succeeds or
+ * fails: nothing is cancelled when a starter fails. The result has, for each
+ * starter, `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`.
+ * Only an abort of `ctx` rejects it, with the abort reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const { user, posts } = await allSettled(ctx, {
+ *     user: ({ signal }) => fetchUser(id, { signal }),
+ *     posts: ({ signal }) => fetchPosts(id, { signal }),
+ *   });
+ *
+ *   if (user.status === "fulfilled") render(user.value);
+ * });
+ * ```
+ */
+declare function allSettled<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+declare function allSettled<const T extends readonly Starter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+//#endregion
+//#region src/effects/race.d.ts
+type RaceStarter<T> = Starter<T>;
+/**
+ * Runs all starters; first to settle wins, losers are cancelled via `ctx.abort`.
+ * The result holds only the winner's value, under its key or index.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const result = await race(ctx, {
+ *     data: ({ signal }) => fetchData(id, { signal }),
+ *     timeout: ({ signal }) => delay({ signal }, 5000),
+ *   });
+ *
+ *   if ("timeout" in result) throw new Error("timed out");
+ *   render(result.data);
+ * });
+ * ```
+ */
+declare function race<T extends Record<string, RaceStarter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+declare function race<const T extends readonly RaceStarter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+//#endregion
+//#region src/effects/take.d.ts
+type TakeOptions<P> = {
+  /**
+   * Wait for the first payload this accepts; others are skipped. A type guard
+   * (`(payload): payload is T`) narrows the type of the result to `T`.
+   */
+  predicate?: (payload: P) => boolean;
+  /** Stop waiting when this aborts, e.g. the signal of a `race` starter. */
+  signal?: AbortSignal | undefined;
+};
+/**
+ * Waits for the next `event` on the bus and resolves with its payload. It sees
+ * only events emitted after the call, takes only one, and unsubscribes when it
+ * is done. If `ctx` (or `options.signal`) aborts first, it unsubscribes and
+ * rejects with the abort reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("login", async (user, ctx) => {
+ *   const reason = await take(ctx, "logout");
+ *   cleanup(user, reason);
+ * });
+ *
+ * // wait for a matching event, but not longer than 5 s
+ * const done = await timeout(ctx, 5000, ({ signal }) =>
+ *   take(ctx, "saved", { signal, predicate: (id) => id === draftId }),
+ * );
+ *
+ * // a type guard narrows the result: `failed` is `{ ok: false }`
+ * const failed = await take(ctx, "result", {
+ *   predicate: (result): result is { ok: false } => !result.ok,
+ * });
+ * ```
+ */
+declare function take<E extends EventMap, K extends Keys<E>, T extends E[K]>(ctx: Context<E>, event: K, options: TakeOptions<E[K]> & {
+  predicate: (payload: E[K]) => payload is T;
+}): Promise<T>;
+declare function take<E extends EventMap, K extends Keys<E>>(ctx: Context<E>, event: K, options?: TakeOptions<E[K]>): Promise<E[K]>;
+//#endregion
+//#region src/effects/plugin.d.ts
+/** The effects that `effectsPlugin` can put on `ctx`. */
+type Supported = {
+  race: typeof race;
+  all: typeof all;
+  allSettled: typeof allSettled;
+  take: typeof take;
+  delay: typeof delay;
+};
+type Results = Record<string, Starter<unknown>>;
+type List = readonly Starter<unknown>[];
+/** Each supported effect without its leading `ctx` argument. `take` knows the events of the bus. */
+type Bound<E extends EventMap> = {
+  race: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+  };
+  all: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+  };
+  allSettled: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+  };
+  take: <K extends Keys<E>>(event: K, options?: TakeOptions<E[K]>) => Promise<E[K]>;
+  delay: (ms: number | (() => number)) => Promise<void>;
+};
+/** Any function whose first parameter takes `{ signal }` can go on the context, not only the built-in ones. */
+type Helpers = Effects;
+/**
+ * The effects as a handler sees them: the built-in ones keep their hand-written
+ * types, any other loses its first parameter, or has the type `Effect<F>` says.
+ */
+type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H]: K extends keyof Bound<E> ? H[K] extends Supported[K] ? Bound<E>[K] : BoundForm<H[K]> : BoundForm<H[K]>; };
+/**
+ * Puts the effects you pass on the context of every task of the bus, bound to
+ * that task, so a handler can write `({ race })` instead of `race(ctx, …)`.
+ * The key is the name of the effect: `race`, `all`, `allSettled`, `take`,
+ * `delay`. Returns the same bus, typed with the new fields.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
+ *
+ * const bus = createBus().use(effectsPlugin({ race, delay }));
+ *
+ * bus.on("load", async (id, { race, delay }) => {
+ *   const result = await race({
+ *     data: ({ signal }) => fetchData(id, { signal }),
+ *     timeout: () => delay(5000),
+ *   });
+ * });
+ * ```
+ */
+declare const effectsPlugin: <H extends Helpers>(helpers: H) => <E extends EventMap>(bus: Bus<E> & NoClash<BoundOf<H, E>, E>) => Bus<E & WithContext<BoundOf<H, E>>>;
+//#endregion
+export { RaceStarter as a, all as c, delay as d, take as i, EffectContext as l, effectsPlugin as n, race as o, TakeOptions as r, allSettled as s, BoundOf as t, Starter as u };

package/dist/notrace/policies.d.ts

@@ -1,4 +1,4 @@
-import { o as EventMap, u as Task } from "./action-creator-DOWcbXpy.js";
+import { H as Task, R as EventMap } from "./action-creator-DKG_sIia.js";
 //#region src/policies/keyed.d.ts
 /** Options shared by every policy that can keep its state per key. */
 type KeyOption<P> = {

package/dist/notrace/redux.d.ts

@@ -1,4 +1,4 @@
-import { _ as Bus, o as EventMap } from "./action-creator-DOWcbXpy.js";
+import { R as EventMap, p as Bus } from "./action-creator-DKG_sIia.js";
 //#region src/store/redux/middleware.d.ts
 /** What Redux passes through a middleware: an action is a plain object with a `type`. */
 type ReduxAction = {

package/dist/observable.d.ts

@@ -1,4 +1,4 @@
-import { _ as Bus, o as EventMap, s as Keys } from "./action-creator-DOWcbXpy.js";
+import { B as EventMap, V as Keys, h as Bus } from "./action-creator-c292nK7v.js";
 //#region src/observable.d.ts
 declare global {
   interface SymbolConstructor {

package/dist/plugin-CCYlC0XS.d.ts

@@ -0,0 +1,207 @@
+import { B as EventMap, N as WithContext, V as Keys, b as Context, d as Effects, h as Bus, l as BoundForm } from "./action-creator-c292nK7v.js";
+import { n as NoClash } from "./context-plugin-1pYmSQEG.js";
+//#region src/utils/delay.d.ts
+/**
+ * Resolves after `ms`, or rejects early if `ctx.signal` aborts. `ms` can be a
+ * function that returns the number of ms, called once when the delay starts:
+ * handy for a random pause (jitter).
+ *
+ * @example
+ * ```ts
+ * await delay({}, 500);
+ *
+ * // 200 to 400 ms
+ * await delay({}, () => 200 + Math.random() * 200);
+ *
+ * // inside a task: stops waiting when the task is aborted
+ * bus.on("retry", async (_, ctx) => {
+ *   await delay(ctx, 1000);
+ *   await load();
+ * });
+ * ```
+ */
+declare const delay: (ctx: {
+  signal?: AbortSignal | undefined;
+}, ms: number | (() => number)) => Promise<void>;
+//#endregion
+//#region src/effects/run.d.ts
+/** Context passed into `race` / `all` effect starters. */
+type EffectContext = {
+  signal: AbortSignal;
+  abort: (reason?: unknown) => void;
+};
+type Starter<T> = (ctx: EffectContext) => T | PromiseLike<T>;
+//#endregion
+//#region src/effects/all.d.ts
+/**
+ * Runs all starters; waits for every result. On failure or parent abort, cancels the rest.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const { user, posts } = await all(ctx, {
+ *     user: ({ signal }) => fetchUser(id, { signal }),
+ *     posts: ({ signal }) => fetchPosts(id, { signal }),
+ *   });
+ *
+ *   // arrays work too: const [user, posts] = await all(ctx, [getUser, getPosts]);
+ * });
+ * ```
+ */
+declare function all<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+declare function all<const T extends readonly Starter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+//#endregion
+//#region src/effects/allSettled.d.ts
+/**
+ * Runs all starters and waits for every one to settle, whether it succeeds or
+ * fails: nothing is cancelled when a starter fails. The result has, for each
+ * starter, `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`.
+ * Only an abort of `ctx` rejects it, with the abort reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const { user, posts } = await allSettled(ctx, {
+ *     user: ({ signal }) => fetchUser(id, { signal }),
+ *     posts: ({ signal }) => fetchPosts(id, { signal }),
+ *   });
+ *
+ *   if (user.status === "fulfilled") render(user.value);
+ * });
+ * ```
+ */
+declare function allSettled<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+declare function allSettled<const T extends readonly Starter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+//#endregion
+//#region src/effects/race.d.ts
+type RaceStarter<T> = Starter<T>;
+/**
+ * Runs all starters; first to settle wins, losers are cancelled via `ctx.abort`.
+ * The result holds only the winner's value, under its key or index.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const result = await race(ctx, {
+ *     data: ({ signal }) => fetchData(id, { signal }),
+ *     timeout: ({ signal }) => delay({ signal }, 5000),
+ *   });
+ *
+ *   if ("timeout" in result) throw new Error("timed out");
+ *   render(result.data);
+ * });
+ * ```
+ */
+declare function race<T extends Record<string, RaceStarter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+declare function race<const T extends readonly RaceStarter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+//#endregion
+//#region src/effects/take.d.ts
+type TakeOptions<P> = {
+  /**
+   * Wait for the first payload this accepts; others are skipped. A type guard
+   * (`(payload): payload is T`) narrows the type of the result to `T`.
+   */
+  predicate?: (payload: P) => boolean;
+  /** Stop waiting when this aborts, e.g. the signal of a `race` starter. */
+  signal?: AbortSignal | undefined;
+};
+/**
+ * Waits for the next `event` on the bus and resolves with its payload. It sees
+ * only events emitted after the call, takes only one, and unsubscribes when it
+ * is done. If `ctx` (or `options.signal`) aborts first, it unsubscribes and
+ * rejects with the abort reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("login", async (user, ctx) => {
+ *   const reason = await take(ctx, "logout");
+ *   cleanup(user, reason);
+ * });
+ *
+ * // wait for a matching event, but not longer than 5 s
+ * const done = await timeout(ctx, 5000, ({ signal }) =>
+ *   take(ctx, "saved", { signal, predicate: (id) => id === draftId }),
+ * );
+ *
+ * // a type guard narrows the result: `failed` is `{ ok: false }`
+ * const failed = await take(ctx, "result", {
+ *   predicate: (result): result is { ok: false } => !result.ok,
+ * });
+ * ```
+ */
+declare function take<E extends EventMap, K extends Keys<E>, T extends E[K]>(ctx: Context<E>, event: K, options: TakeOptions<E[K]> & {
+  predicate: (payload: E[K]) => payload is T;
+}): Promise<T>;
+declare function take<E extends EventMap, K extends Keys<E>>(ctx: Context<E>, event: K, options?: TakeOptions<E[K]>): Promise<E[K]>;
+//#endregion
+//#region src/effects/plugin.d.ts
+/** The effects that `effectsPlugin` can put on `ctx`. */
+type Supported = {
+  race: typeof race;
+  all: typeof all;
+  allSettled: typeof allSettled;
+  take: typeof take;
+  delay: typeof delay;
+};
+type Results = Record<string, Starter<unknown>>;
+type List = readonly Starter<unknown>[];
+/** Each supported effect without its leading `ctx` argument. `take` knows the events of the bus. */
+type Bound<E extends EventMap> = {
+  race: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+  };
+  all: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+  };
+  allSettled: {
+    <T extends Results>(effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+    <const T extends List>(effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+  };
+  take: <K extends Keys<E>>(event: K, options?: TakeOptions<E[K]>) => Promise<E[K]>;
+  delay: (ms: number | (() => number)) => Promise<void>;
+};
+/** Any function whose first parameter takes `{ signal }` can go on the context, not only the built-in ones. */
+type Helpers = Effects;
+/**
+ * The effects as a handler sees them: the built-in ones keep their hand-written
+ * types, any other loses its first parameter, or has the type `Effect<F>` says.
+ */
+type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H]: K extends keyof Bound<E> ? H[K] extends Supported[K] ? Bound<E>[K] : BoundForm<H[K]> : BoundForm<H[K]>; };
+/**
+ * Puts the effects you pass on the context of every task of the bus, bound to
+ * that task, so a handler can write `({ race })` instead of `race(ctx, …)`.
+ * The key is the name of the effect: `race`, `all`, `allSettled`, `take`,
+ * `delay`. Returns the same bus, typed with the new fields.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
+ *
+ * const bus = createBus().use(effectsPlugin({ race, delay }));
+ *
+ * bus.on("load", async (id, { race, delay }) => {
+ *   const result = await race({
+ *     data: ({ signal }) => fetchData(id, { signal }),
+ *     timeout: () => delay(5000),
+ *   });
+ * });
+ * ```
+ */
+declare const effectsPlugin: <H extends Helpers>(helpers: H) => <E extends EventMap>(bus: Bus<E> & NoClash<BoundOf<H, E>, E>) => Bus<E & WithContext<BoundOf<H, E>>>;
+//#endregion
+export { RaceStarter as a, all as c, delay as d, take as i, EffectContext as l, effectsPlugin as n, race as o, TakeOptions as r, allSettled as s, BoundOf as t, Starter as u };

package/dist/policies.d.ts

@@ -1,4 +1,4 @@
-import { o as EventMap, u as Task } from "./action-creator-DOWcbXpy.js";
+import { B as EventMap, W as Task } from "./action-creator-c292nK7v.js";
 //#region src/policies/keyed.d.ts
 /** Options shared by every policy that can keep its state per key. */
 type KeyOption<P> = {

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { D as EventKey, _ as Bus, o as EventMap, r as FreeActionCreator, t as ActionCreator } from "./action-creator-DOWcbXpy.js";
+import { B as EventMap, T as EventKey, h as Bus, r as FreeActionCreator, t as ActionCreator } from "./action-creator-c292nK7v.js";
 //#region src/react/plugin.d.ts
 /** What `reactPlugin` adds to the bus. */
 /** Tells whether two values are the same: `Object.is` unless the caller gives another. */

package/dist/redux.d.ts

@@ -1,4 +1,4 @@
-import { _ as Bus, o as EventMap } from "./action-creator-DOWcbXpy.js";
+import { B as EventMap, h as Bus } from "./action-creator-c292nK7v.js";
 //#region src/store/redux/middleware.d.ts
 /** What Redux passes through a middleware: an action is a plain object with a `type`. */
 type ReduxAction = {

package/dist/scope-key-B7l7mUS5.js

@@ -0,0 +1 @@
+const e=Symbol.for(`nanoeffects.scope`);export{e as t};

package/dist/scope.d.ts

@@ -0,0 +1,58 @@
+import { B as EventMap, a as EmitScope, d as Effects, f as Signaled, h as Bus, o as Scope, u as Effect } from "./action-creator-c292nK7v.js";
+import { n as Scoped } from "./types-mLaAx-EZ.js";
+//#region src/scope/effect.d.ts
+/**
+ * Marks a function whose first parameter is `{ signal }` as an effect, so that
+ * as a value of a scope it is bound to the task: `ctx.first(items)`
+ * calls `first(ctx, items)`. The type is the function without that parameter,
+ * generics included, which `effects` cannot do: no annotation is needed, and
+ * JavaScript editors show the exact hint.
+ *
+ * Only `scopePlugin` binds it; the function itself is returned unchanged.
+ * Call it where the function is declared, not inline in the scope: TypeScript
+ * does not infer the fields of a scope from a generic call written there.
+ *
+ * @example
+ * ```ts
+ * const first = effect(<T>(ctx: { signal: AbortSignal }, items: T[]) => items[0]);
+ *
+ * const getUser = createCommand(
+ *   "user/get",
+ *   (id: string, { first }) => first([id]), // first: <T>(items: T[]) => T
+ *   { first },
+ * );
+ * ```
+ */
+export declare const effect: <A extends unknown[], R>(fn: (ctx: Signaled, ...args: A) => R) => ((...args: A) => R);
+//#endregion
+//#region src/scope/plugin.d.ts
+/**
+ * Switches scopes on for a bus: the scope given to a command, a job, an
+ * action or a module (an object whose keys go on `ctx`, with `effects` bound to
+ * the task), and the second argument of `emit`, put fields on
+ * the context of the tasks they are for. A stronger layer replaces a field of
+ * the same name: `emit`, then action / command / job, then module, then the bus.
+ * Fields of the library (`signal`, `emit`, `run`, …) are never replaced. Returns
+ * the same bus.
+ *
+ * Use it after `effectsPlugin`, which assigns its effects over those of a scope
+ * when it comes later, and before `modulePlugin`, which mounts its modules when
+ * it is used. Without this plugin a scope is ignored.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { createCommand } from "nanoeffects/actions";
+ * import { scopePlugin } from "nanoeffects/scope";
+ *
+ * const bus = createBus().use(scopePlugin()); // scopes work on this bus
+ *
+ * const getUser = createCommand("user/get", (id: string, { http }) => http.get(id), {
+ *   http, // a field of this command only
+ * });
+ * bus.emit(getUser("1"), { http: fakeHttp }); // this call only
+ * ```
+ */
+export declare const scopePlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus<E>;
+//#endregion
+export type { Effect, Effects, EmitScope, Scope, Scoped, Signaled };

package/dist/scope.js

@@ -0,0 +1 @@
+import{t as e}from"./scope-key-B7l7mUS5.js";const t=/* @__PURE__ */ new WeakSet,n=e=>(t.add(e),e),r=/* @__PURE__ */ new Set([`signal`,`abort`,`emit`,`on`,`off`,`run`,`type`,`payload`]),i=Symbol(`nanoeffects.scope.entry`),a=[],o=/* @__PURE__ */ new WeakSet,s=(e,n)=>{if(!n)return;for(let i of Object.keys(n)){let a=n[i];if(i!==`effects`&&!r.has(i)){let n=a;e[i]=typeof a==`function`&&t.has(a)?c(e,n):a}}let i=n.effects??{};for(let t of Object.keys(i)){let n=i[t];r.has(t)||(e[t]=c(e,n))}},c=(e,t)=>(...n)=>t(e,...n),l=(e,t)=>{s(e,t.module);for(let n of t.call)s(e,n)},u=t=>{if(typeof t==`object`&&t||typeof t==`function`)return Reflect.get(t,e)},d=e=>typeof e==`object`&&!!e,f=(e,t)=>{let n=u(e),r=d(e)?t[0]:void 0;if(!(n||r))return;let i=n&&r?[n,r]:[n??r];return{type:typeof e==`string`?e:e.type,payload:d(e)?e.payload:t[0],layers:i}},p=()=>e=>{let t,n=e=>{let n=e.run;if(o.has(n))return;let a=(a,...o)=>{let s=t;t=void 0;try{return n((t,n)=>{let o=e[i];return o&&r(n,o.call,o.module),a(t,n)},...o)}finally{t=s}};o.add(a),e.run=a},r=(e,t,r)=>{let a={call:t,module:r};e[i]=a,l(e,a),n(e)},s=e.addContext;e.addContext=e=>{s?.(e);let n=e;t&&n.type===t.type&&Object.is(n.payload,t.payload)&&r(n,t.layers,void 0)},e.applyScope=(e,t)=>{let n=e,o=n[i]?.call??a;r(n,o,t)},e.fitScope=(t,n)=>(r,i)=>(e.applyScope?.(i,t),Reflect.apply(n,null,[r,i]));let c=e.emit;return e.emit=(e,...n)=>{let r=f(e,n);if(!(r||t))return c(e,...n);let i=t;t=r;try{return d(e)?c(e):c(e,...n)}finally{t=i}},e};export{n as effect,p as scopePlugin};

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-import { d as Trace, f as TraceEvent, p as TraceLogger, z as Tracer } from "./action-creator-DOWcbXpy.js";
+import { G as Trace, K as TraceEvent, L as Tracer, q as TraceLogger } from "./action-creator-c292nK7v.js";
 //#region src/trace/console.d.ts
 type ConsoleLoggerOptions = {
   /** Defaults to `globalThis.console`. */

package/dist/types-mLaAx-EZ.d.ts

@@ -0,0 +1,15 @@
+import { B as EventMap, d as Effects, o as Scope, s as WithFields } from "./action-creator-c292nK7v.js";
+import { t as BoundOf } from "./plugin-CCYlC0XS.js";
+//#region src/scope/types.d.ts
+type BoundEffects<E extends EventMap, S extends Scope> = S extends {
+  effects: infer H extends Effects;
+} ? BoundOf<H, E> : unknown;
+/** The fields a scope gives a task: its values as they are and its `effects` bound; `unknown` for an empty scope. */
+type FieldsOfScope<E extends EventMap, S extends Scope> = [keyof S] extends [never] ? unknown : Omit<S, "effects"> & BoundEffects<E, S>;
+/**
+ * The event map `E` with the fields of a scope on top of its context fields.
+ * A field the scope sets replaces the one of the bus in the type too.
+ */
+type Scoped<E extends EventMap, S extends Scope> = WithFields<E, FieldsOfScope<E, S>>;
+//#endregion
+export { Scoped as n, FieldsOfScope as t };

package/docs/actions.md

@@ -152,3 +152,27 @@ app.dispose(); // unmounts every module
   - `use` — bring sub-modules and commands that carry a handler; the returned function undoes that call.
   - `spawn` — background task, aborted on unmount.
 - A command that carries a handler keeps answering after unmount (`use` only tracks registration). Use `handle` for a handler that must live only as long as the module.
+
+## Give a command, an action or a module its own fields
+
+A command can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`effects` binds functions to the task), as the last argument of `createCommand`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { scopePlugin } from "nanoeffects/scope";
+
+// scopePlugin — makes the scope of a command work on this bus
+const bus = createBus().use(scopePlugin());
+
+// the third argument — fields of this command only
+const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
+  api,
+});
+
+// a test replaces them for one call
+const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
+bus.emit(getUser("1"), { api: fakeApi });
+```
+
+The handler gets the fields typed. Without `scopePlugin` the scope is ignored. The full picture, with jobs, actions, modules and which value wins, is in [scopes](scope.md).

package/docs/context.md

@@ -21,6 +21,8 @@ Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may
 
 To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
 
+To give fields to **one** command, action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
+
 ## Type the fields (optional)
 
 In TypeScript, `contextPlugin` puts the fields on every task of **this** bus and takes their types from the value you pass. The event map holds only events. It does not wire anything across the app — another bus can have different fields or none.

package/docs/effects.md

@@ -166,8 +166,9 @@ bus.on("load", async (id, { race, all, delay }) => {
 });
 ```
 
-- Supported: `race`, `all`, `allSettled`, `take`, `delay`. The key is the effect name.
-- `retry`, `timeout` and `poll` are not supported: bound to the task they would look like their handler wrappers.
+- The key is the name the effect gets on `ctx`. `race`, `all`, `allSettled`, `take` and `delay` are typed by hand.
+- Your own function works too if its first parameter is `{ signal }` (an *effect*): `effectsPlugin({ fetchJson })` gives `ctx.fetchJson(url)`. TypeScript removes the first parameter from its type; for a generic function see [keep a generic effect generic](scope.md#keep-a-generic-effect-generic).
+- Leave `retry`, `timeout` and `poll` out: bound to the task they would look like their handler wrappers.
 - Fields from `createBus({ context })` stay. TypeScript rejects an effect whose name is already a context field of the bus, including one added by an earlier `effectsPlugin`.
 - Free forms keep working: `race(ctx, …)`.
 

package/docs/guide.md

@@ -47,6 +47,28 @@ bus.on("tick", () => {});
 bus.off(); // clear every subscription
 ```
 
+### Listen to every event
+
+`bus.on("*", fn)` runs for every event of the bus. It is for logging, debugging, or forwarding events elsewhere. The handler gets the payload and the task context as usual, and `ctx.type` is the name of the event.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus();
+
+// "*" — runs for every event, after the listeners of that event
+const unbind = bus.on("*", (payload, ctx) => {
+  console.log(ctx.type, payload);
+});
+
+bus.emit("greet", "Ada"); // greet Ada
+bus.emit("moved", { x: 1, y: 2 }); // moved { x: 1, y: 2 }
+unbind();
+```
+
+- An event that only `"*"` listens to counts as heard, so `onUnhandled` does not fire for it.
+- `bus.off("*")` removes every `"*"` listener; `bus.off()` clears the whole bus, `"*"` included.
+
 ## 2. Use the handler context
 
 The second argument is the **task** context for this call. Emit further events through it. Pass `ctx.signal` to `fetch` when you cancel work.

package/docs/package.md

@@ -8,6 +8,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
 | `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
 | `nanoeffects/actions` | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin`, `commandsPlugin` |
+| `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one command, action, job, module or `emit` (the types `Scope`, `Effect`) |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve` |
 | `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |