nanoeffects 0.5.0 → 0.7.0

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

@@ -1,3 +1,29 @@
+//#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
@@ -83,14 +109,21 @@ type Emit<E extends EventMap> = {
   <K extends EventKey<E>>(event: K, ...payload: PayloadOf<E[K]>): void;
   /** 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;
+  /** A scope as the second argument replaces context fields for the tasks of this emit; see `scopePlugin`. */
+  <P, R, F>(call: CommandCall<P, R> & WithScope<F>, scope?: EmitScope<E, F>): R;
+  <P, R>(call: CommandCall<P, R>, scope?: EmitScope<E>): R;
   <K extends EventKey<E>, R>(event: Handler<E, R, K>, ...payload: PayloadOf<E[K]>): R;
-  (event: EventLike<E>): void;
+  <F>(event: EventLike<E> & WithScope<F>, scope?: EmitScope<E, F>): void;
+  (event: EventLike<E>, scope?: EmitScope<E>): void;
 };
 type On<E extends EventMap> = {
   (event: AnyEvent, fn: Task<EventPayload<E>, E>): UnsubscribeCallback;
   <K extends EventKey<E>>(event: K, fn: Task<E[K], E>): UnsubscribeCallback;
   /** An action creator without a payload type: the payload comes from the event map. */
+  /** The creators and commands that carry a scope come first: the handler sees their fields. */
+  <K extends EventKey<E>, F>(creator: FreeActionCreator<K, F> & WithScope<F>, fn: Task<E[K], WithFields<E, F>>): UnsubscribeCallback;
+  <P, F>(creator: ActionCreator<P, string, PayloadOf<P>, F> & WithScope<F>, fn: Task<P, WithFields<E, F>>): UnsubscribeCallback;
+  <P, F>(command: Command<P, unknown> & WithScope<F>, fn: Task<P, WithFields<E, F>>): UnsubscribeCallback;
   <K extends EventKey<E>>(creator: FreeActionCreator<K>, fn: Task<E[K], E>): UnsubscribeCallback;
   /** An action creator: the payload comes from it, so an event map is not needed. */
   <P>(creator: ActionCreator<P>, fn: Task<P, E>): UnsubscribeCallback;
@@ -191,6 +224,10 @@ interface Bus<E extends EventMap> {
   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;
+  /** Puts the fields of a module's scope on the context of one of its tasks; `scopePlugin` sets it. Without it a module's scope is ignored. */
+  applyScope?: ((ctx: object, scope: Scope) => void) | undefined;
+  /** Wraps a handler so it runs with the fields of a module's scope; `scopePlugin` sets it. */
+  fitScope?: ((scope: Scope, fn: unknown) => unknown) | undefined;
 }
 type BusOptions<E extends EventMap> = {
   /** Tracing of every task phase; make it with `createTracer` from `nanoeffects/trace`. */
@@ -228,31 +265,76 @@ type BusOptions<E extends EventMap> = {
 };
 declare const createBus: <Events extends EventMap>(options?: BusOptions<Events>) => Bus<Events>;
 //#endregion
-//#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>];
+//#region src/core/effect-types.d.ts
+/** What an effect needs of the task it runs for: its signal. A task context fits, and so does `{ signal }`. */
+type Signaled = {
+  signal: AbortSignal;
+};
+/** An effect: a function whose first parameter takes `{ signal }`, like `retry(ctx, fn)`. */
+type SignalFirst = (ctx: Signaled, ...args: never[]) => unknown;
+/** The effects of a scope or of `effectsPlugin`, by the name they get on the context. */
+type Effects = Record<string, SignalFirst>;
+declare const bound: unique symbol;
 /**
- * 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 })`.
+ * An effect that says what it looks like once it is bound to a task (without
+ * the `ctx` parameter). A plain effect has its first parameter removed, which
+ * erases its generics; this type keeps them, because `F` is carried as it is.
+ * It changes the checker only: the function is the same at run time.
+ *
+ * @example
+ * ```ts
+ * type First = <T>(items: T[]) => T; // how a handler calls it
+ * const first: Effect<First> = (ctx, items) => items[0];
+ * ```
  */
-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;
+type Effect<F extends (...args: never[]) => unknown> = ((ctx: Signaled, ...args: Parameters<F>) => ReturnType<F>) & {
+  readonly [bound]?: F;
+};
+/** The bound form of a plain effect: the first parameter is gone, and so are its generics. */
+type Strip<F> = F extends ((ctx: never, ...args: infer A) => infer R) ? (...args: A) => R : never;
+/** The bound type an `Effect<F>` carries, or `Strip` of a plain function. */
+type BoundForm<F> = typeof bound extends keyof F ? NonNullable<F[typeof bound & keyof F]> : Strip<F>;
+//#endregion
+//#region src/core/scope-types.d.ts
+declare const scopeFields: unique symbol;
+/** What an action creator, a command or a call knows of the scope it was made with: its fields, for the checker. */
+type WithScope<F> = {
+  readonly [scopeFields]: F;
+};
+/** `X`, marked with the scope fields `F` it carries; `X` itself when there are none, so unscoped types stay as they were. */
+type Carrying<X, F> = X & ([unknown] extends [F] ? unknown : WithScope<F>);
+/**
+ * What a task gets on top of the context of its bus, for one place: every key
+ * is a context value and goes on `ctx` as it is, except `$effects`, whose
+ * functions (each takes `{ signal }` first) are bound to the task. Made work by
+ * `scopePlugin` from `nanoeffects/scope`; without it a scope is ignored.
+ *
+ * @example
+ * ```ts
+ * const scope = { cache, $effects: { race } }; // ctx.cache, and ctx.race bound to the task
+ * ```
+ */
+type Scope = {
+  readonly $effects?: Effects;
+  readonly [field: string]: unknown;
+};
+/**
+ * What a call may replace of what it already has: the fields of the bus and
+ * those of its own scope, and its effects. The types must match the ones they
+ * replace; a field that neither declares has no type to check against, so it is
+ * an error.
+ */
+type EmitScope<E extends EventMap, F = unknown> = ([unknown] extends [ContextOf<E> & F] ? unknown : Partial<ContextOf<E> & F>) & {
+  $effects?: Partial<Effects>;
+};
+/** `A` with the fields of `B` replacing those of the same name, not intersected with them. */
+type Merge<A, B> = Omit<A, keyof B> & B;
+/**
+ * The event map `E` with the fields `F` of a scope on top of its context
+ * fields; `E` itself when there are none. A field of the scope replaces the
+ * one of the bus in the type too.
+ */
+type WithFields<E extends EventMap, F> = [unknown] extends [F] ? E : Omit<E, keyof WithContext<object>> & WithContext<Merge<ContextOf<E>, F>>;
 //#endregion
 //#region src/core/action-creator.d.ts
 type WithPayload<E extends EventMap, K extends Keys<E>> = undefined extends E[K] ? {
@@ -271,15 +353,15 @@ type Free = typeof free;
  * it is given, and the bus checks it against its event map, so
  * `createAction("user/loaded")` needs no generics and keeps its literal type.
  */
-interface FreeActionCreator<T extends string> {
-  (): {
+interface FreeActionCreator<T extends string, F = unknown> {
+  (): Carrying<{
     type: T;
     payload: undefined;
-  };
-  <P>(payload: P): {
+  }, F>;
+  <P>(payload: P): Carrying<{
     type: T;
     payload: P;
-  };
+  }, F>;
   readonly type: T;
   /** Tells whether an action is one of this creator. */
   match(action: {
@@ -295,8 +377,8 @@ interface FreeActionCreator<T extends string> {
  * Makes actions of one type. It also works as the event of that type:
  * `bus.on(creator, fn)` and `bus.emit(creator(payload))`.
  */
-interface ActionCreator<P = void, T extends string = string, A extends unknown[] = PayloadOf<P>> {
-  (...args: A): Made<P, T>;
+interface ActionCreator<P = void, T extends string = string, A extends unknown[] = PayloadOf<P>, F = unknown> {
+  (...args: A): Carrying<Made<P, T>, F>;
   readonly type: T;
   /** Tells whether an action is one of this creator, and narrows its type. */
   match(action: {
@@ -306,4 +388,4 @@ interface ActionCreator<P = void, T extends string = string, A extends unknown[]
   toString(): T;
 }
 //#endregion
-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 };
+export { HandlerRef as A, EventMap as B, Emit as C, EventPayload as D, EventLike as E, commandCall as F, Trace as G, PayloadOf as H, createBus as I, UnsubscribeCallback as J, TraceEvent as K, Tracer as L, On as M, WithContext as N, EventsOf as O, WithType as P, anyEventType as R, ContextOption as S, EventKey as T, Phase as U, Keys as V, Task as W, Command as _, EmitScope as a, Context as b, WithScope as c, Effects as d, Signaled as f, BusOptions as g, Bus as h, WithPayload as i, Off as j, Handler as k, BoundForm as l, AnyEvent as m, Free as n, Scope as o, Action as p, TraceLogger as q, FreeActionCreator as r, WithFields as s, ActionCreator as t, Effect as u, CommandCall as v, Emittable as w, ContextOf as x, Commands as y, EffectName as z };

package/dist/actions.d.ts

@@ -1,6 +1,8 @@
-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";
+import { B as EventMap, H as PayloadOf, T as EventKey, W as Task, c as WithScope, h as Bus, n as Free, o as Scope, r as FreeActionCreator, t as ActionCreator } from "./action-creator-Bd4TBZgl.js";
+import { n as Scoped, t as FieldsOfScope } from "./types-BJ0fzV1p.js";
+import { a as modulePlugin, c as MadeCommand, d as createCommand, i as createModule, l as bindHandler, n as ModuleApi, o as Binding, r as ModuleContext, s as CarryingCalls, t as Module, u as commandsPlugin } from "./module-DZ5ngUrM.js";
 //#region src/actions/action.d.ts
+type ScopedCreator<P, T extends string, F> = [P] extends [Free] ? FreeActionCreator<T, F> & WithScope<F> : ActionCreator<P, T, PayloadOf<P>, F> & WithScope<F>;
 /**
  * Creates an action creator, as in Redux Toolkit.
  *
@@ -13,6 +15,9 @@ import { a as modulePlugin, c as bindHandler, i as createModule, l as commandsPl
  *   generic: `createAction<User, "user/loaded">("user/loaded")`.
  * - With `prepare` the arguments of the creator can differ from the payload,
  *   and both types are inferred.
+ * - A scope as the last argument, `{ cache, $effects: { race } }`, gives the
+ *   listeners of its calls those context fields; it works on a bus that uses `scopePlugin`
+ *   from `nanoeffects/scope` and is ignored on any other.
  *
  * @example
  * ```ts
@@ -33,6 +38,10 @@ export declare function createAction<P = Free, T extends string = string>(type:
 export declare function createAction<A extends unknown[], P, T extends string = string>(type: T, prepare: (...args: A) => {
   payload: P;
 }): ActionCreator<P, T, A>;
+export declare function createAction<P = Free, T extends string = string, S extends Scope = Record<never, never>>(type: T, scope: S): ScopedCreator<P, T, FieldsOfScope<EventMap, S>>;
+export declare function createAction<A extends unknown[], P, T extends string, S extends Scope>(type: T, prepare: (...args: A) => {
+  payload: P;
+}, scope: S): ActionCreator<P, T, A, FieldsOfScope<EventMap, S>> & WithScope<FieldsOfScope<EventMap, S>>;
 //#endregion
 //#region src/actions/emitter.d.ts
 /** What `emitterPlugin` adds to the bus. */
@@ -93,6 +102,9 @@ type Job<P, R, T extends string, S extends Outcome, F extends Outcome> = MadeCom
  * effect. It returns the command, with the two actions on it: `job.success` and
  * `job.fail`.
  *
+ * A scope as the last argument, `{ cache, $effects: { race } }`, gives the handler
+ * and the listeners of the outcome those context fields; see `scopePlugin`.
+ *
  * `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
@@ -117,11 +129,13 @@ type Job<P, R, T extends string, S extends Outcome, F extends Outcome> = MadeCom
  * 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?: {
+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`, X extends Scope = Record<never, never>>(type: T, handler?: Task<P, Scoped<E, X>, 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>;
+},
+/** Context values and `$effects` for the handler and for the listeners of the outcome; see `scopePlugin`. */
+scope?: X) => CarryingCalls<Job<P, R, T, S, F>, P, Promise<Awaited<R> | undefined>, FieldsOfScope<E, X>>;
 //#endregion
 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-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};
+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";import{t as a}from"./scope-key-B7l7mUS5.js";const o=(e,t)=>(t&&Object.defineProperty(e,a,{value:t}),e),s=(e,t)=>({...e,...t,$effects:{...e.$effects,...t.$effects}}),c=e=>Reflect.get(e,a);function l(e,t,n){let r=typeof t==`function`?t:void 0,i=typeof t==`function`?n:t;return Object.assign(o((...t)=>o({type:e,payload:r?r(...t).payload:t[0]},i),i),{type:e,match:t=>t.type===e,toString:()=>e})}var u=class extends Error{};function d(e,t,n){let r=t=>t.type===e;function a(r,a){if(typeof a==`object`){if(!t)throw new u(`No handler for command "${e}"`);return t(r,a)}return o(i(c,e,r),n)}let s=Object.assign(a,{type:e,match:r}),c=o(s,n);return c}const f=(e,t)=>[e,t],p=(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},m=()=>e=>{function t(t){return(...n)=>{let r=t(...n);e.emit(r)}}return Object.assign(e,{emitter:t})},h=e=>typeof e==`string`?l(e):e,g=(e,t,n,r)=>{let i=c(t);e.emit(Reflect.apply(t,null,[n]),r&&i?s(r,i):r)},_=e=>{try{return Promise.resolve(e())}catch(e){if(e instanceof u)throw e;return Promise.reject(e)}},v=(e,t,n={},r)=>{let a=d(e,t),s=h(n.success??`${e}/success`),c=h(n.fail??`${e}/fail`),l=(e,t,n)=>{let i=n;return _(()=>Reflect.apply(e,null,[t,n])).then(e=>(g(i,s,e,r),e),e=>{g(i,c,e,r)})},u=e=>(t,n)=>l(e,t,n);function f(t,n){return typeof n==`object`?l(a,t,n):o(i(m,e,t),r)}let p=Object.assign(f,{type:e,match:a.match,wrap:u,success:s,fail:c}),m=o(p,r);return m};function y(e,t,n){return n?{name:e,setup:t,scope:n}:{name:e,setup:t}}const b=(e,t)=>n=>t?e.fitScope?.(t,n)??n:n,x=(e,t,n)=>{n&&e.applyScope?.(t,n)},S=(e,t,n)=>Array.isArray(t)?[t.map(([t,n])=>[t,e(n)]),n]:[t,e(n)],C=(e,t)=>{let n=e.on;return(...e)=>{let[r,i]=e;return Reflect.apply(n,null,[r,t(i)])}},w=e=>(t,...n)=>{e.run(t,...n).catch(t=>{if(!e.signal.aborted)throw t})},T=(r=[])=>i=>{let a=i.commands??p()(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,a=/* @__PURE__ */ new Map;return{mount:s=>{let l=r.get(s);if(l)return l;let u=a.get(s.name);u&&r.get(u)?.();let d=t(n,s.name),f=d.ctx,p=c(f),m=()=>{r.delete(s),a.get(s.name)===s&&a.delete(s.name),f.abort(),d.unlink()};r.set(s,m),a.set(s.name,s);let h=s.scope,g=b(i,h),_=(t,n)=>{let r=Reflect.apply(o.handle,null,S(g,t,n));return e(f,r),r},v=(...e)=>{let t=e.map(e=>typeof e==`function`?_(e,e):p.mount(e));return()=>{for(let e of t)e()}},y=w(f),T=C(f,g);try{x(i,f,h),s.setup(Object.assign(f,{handle:_,use:v,spawn:y,on:T}))}catch(e){throw m(),e}return m},unmount:e=>r.get(e)?.(),isMounted:e=>r.has(e)}},l=c(s.ctx);for(let e of r)l.mount(e);return{commands:a,mount:e=>(s.ctx.signal.throwIfAborted(),l.mount(e)),unmount:l.unmount,isMounted:l.isMounted,dispose:()=>s.ctx.abort(),createModule:y}};export{f as bindHandler,p as commandsPlugin,l as createAction,d as createCommand,v as createJob,y as createModule,m as emitterPlugin,T as modulePlugin};

package/dist/{notrace/context-plugin-B0sLWOxR.d.ts → context-plugin-BVNKqkIx.d.ts}

@@ -1,4 +1,4 @@
-import { C as ContextOf, F as WithContext, _ as Bus, o as EventMap } from "./action-creator-DOWcbXpy.js";
+import { B as EventMap, N as WithContext, h as Bus, x as ContextOf } from "./action-creator-Bd4TBZgl.js";
 //#region src/core/context-plugin.d.ts
 /** What a function that makes the fields of a task gets to see. */
 type ContextTask = {

package/dist/dev.d.ts

@@ -1,5 +1,5 @@
-import { _ as Bus, m as UnsubscribeCallback, o as EventMap } from "./action-creator-DOWcbXpy.js";
-import { n as ModuleApi } from "./module-DCJl-qfi.js";
+import { B as EventMap, J as UnsubscribeCallback, h as Bus } from "./action-creator-Bd4TBZgl.js";
+import { n as ModuleApi } from "./module-DZ5ngUrM.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">;

package/dist/effects.d.ts

@@ -1,91 +1,10 @@
-import { F as WithContext, S as Context, _ as Bus, o as EventMap, s as Keys, u as Task } from "./action-creator-DOWcbXpy.js";
-import { n as NoClash } from "./context-plugin-B0sLWOxR.js";
-//#region src/utils/delay.d.ts
-/**
- * Resolves after `ms`, or rejects early if `ctx.signal` aborts. `ms` can be a
- * function that returns the number of ms, called once when the delay starts:
- * handy for a random pause (jitter).
- *
- * @example
- * ```ts
- * await delay({}, 500);
- *
- * // 200 to 400 ms
- * await delay({}, () => 200 + Math.random() * 200);
- *
- * // inside a task: stops waiting when the task is aborted
- * bus.on("retry", async (_, ctx) => {
- *   await delay(ctx, 1000);
- *   await load();
- * });
- * ```
- */
-export declare const delay: (ctx: {
-  signal?: AbortSignal | undefined;
-}, ms: number | (() => number)) => Promise<void>;
-//#endregion
+import { B as EventMap, W as Task, u as Effect } from "./action-creator-Bd4TBZgl.js";
+import { a as RaceStarter, c as all, d as delay, i as take, l as EffectContext, n as effectsPlugin, o as race, r as TakeOptions, s as allSettled, u as Starter } from "./plugin-DQNPBcxx.js";
 //#region src/utils/onAbort.d.ts
 export declare const onAbort: (ctx: {
   signal?: AbortSignal | undefined;
 }, fn: (reason: unknown) => void) => (() => void);
 //#endregion
-//#region src/effects/run.d.ts
-/** Context passed into `race` / `all` effect starters. */
-type EffectContext = {
-  signal: AbortSignal;
-  abort: (reason?: unknown) => void;
-};
-type Starter<T> = (ctx: EffectContext) => T | PromiseLike<T>;
-//#endregion
-//#region src/effects/all.d.ts
-/**
- * Runs all starters; waits for every result. On failure or parent abort, cancels the rest.
- *
- * @example
- * ```ts
- * bus.on("load", async (id, ctx) => {
- *   const { user, posts } = await all(ctx, {
- *     user: ({ signal }) => fetchUser(id, { signal }),
- *     posts: ({ signal }) => fetchPosts(id, { signal }),
- *   });
- *
- *   // arrays work too: const [user, posts] = await all(ctx, [getUser, getPosts]);
- * });
- * ```
- */
-export declare function all<T extends Record<string, Starter<unknown>>>(ctx: {
-  signal?: AbortSignal;
-}, effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
-export declare function all<const T extends readonly Starter<unknown>[]>(ctx: {
-  signal?: AbortSignal;
-}, effects: T): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
-//#endregion
-//#region src/effects/allSettled.d.ts
-/**
- * Runs all starters and waits for every one to settle, whether it succeeds or
- * fails: nothing is cancelled when a starter fails. The result has, for each
- * starter, `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`.
- * Only an abort of `ctx` rejects it, with the abort reason.
- *
- * @example
- * ```ts
- * bus.on("load", async (id, ctx) => {
- *   const { user, posts } = await allSettled(ctx, {
- *     user: ({ signal }) => fetchUser(id, { signal }),
- *     posts: ({ signal }) => fetchPosts(id, { signal }),
- *   });
- *
- *   if (user.status === "fulfilled") render(user.value);
- * });
- * ```
- */
-export declare function allSettled<T extends Record<string, Starter<unknown>>>(ctx: {
-  signal?: AbortSignal;
-}, effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
-export declare function allSettled<const T extends readonly Starter<unknown>[]>(ctx: {
-  signal?: AbortSignal;
-}, effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
-//#endregion
 //#region src/effects/backoff.d.ts
 type BackoffOptions = {
   /** Pause before the second attempt, in ms. Default 100. */
@@ -151,124 +70,6 @@ export declare const cancellable: <T = void>(ctx: {
   signal: AbortSignal;
 }, executor: CancellableExecutor<T>) => Promise<T>;
 //#endregion
-//#region src/effects/race.d.ts
-type RaceStarter<T> = Starter<T>;
-/**
- * Runs all starters; first to settle wins, losers are cancelled via `ctx.abort`.
- * The result holds only the winner's value, under its key or index.
- *
- * @example
- * ```ts
- * bus.on("load", async (id, ctx) => {
- *   const result = await race(ctx, {
- *     data: ({ signal }) => fetchData(id, { signal }),
- *     timeout: ({ signal }) => delay({ signal }, 5000),
- *   });
- *
- *   if ("timeout" in result) throw new Error("timed out");
- *   render(result.data);
- * });
- * ```
- */
-export declare function race<T extends Record<string, RaceStarter<unknown>>>(ctx: {
-  signal?: AbortSignal;
-}, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
-export declare function race<const T extends readonly RaceStarter<unknown>[]>(ctx: {
-  signal?: AbortSignal;
-}, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
-//#endregion
-//#region src/effects/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,
- * });
- * ```
- */
-export 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>;
-export 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>;
-};
-type Helpers = Partial<Supported>;
-type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H & keyof Bound<E>]: Bound<E>[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),
- *   });
- * });
- * ```
- */
-export 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
 //#region src/effects/poll.d.ts
 type PollOptions = {
   /** Also call `fn` at once, not only after the first `ms`. Default `false`. */
@@ -378,4 +179,4 @@ export declare function timeout<T>(ctx: {
   signal?: AbortSignal;
 }, ms: number, starter: Starter<T>): Promise<T>;
 //#endregion
-export type { BackoffOptions, CancellableExecutor, CancellableHandle, EffectContext, PollOptions, RaceStarter, RetryOptions, TakeOptions };
+export { type BackoffOptions, type CancellableExecutor, type CancellableHandle, type Effect, type EffectContext, type PollOptions, type RaceStarter, type RetryOptions, type TakeOptions, all, allSettled, delay, effectsPlugin, race, take };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { A as EventsOf, B as anyEventType, C as ContextOf, D as EventKey, E as Emittable, F as WithContext, I as WithType, L as commandCall, M as HandlerRef, N as Off, O as EventLike, P as On, R as createBus, S as Context, T as Emit, _ as Bus, a as EffectName, b as CommandCall, c as PayloadOf, d as Trace, f as TraceEvent, g as AnyEvent, h as Action, i as WithPayload, j as Handler, k as EventPayload, l as Phase, m as UnsubscribeCallback, o as EventMap, p as TraceLogger, s as Keys, u as Task, v as BusOptions, w as ContextOption, x as Commands, y as Command, z as Tracer } from "./action-creator-DOWcbXpy.js";
-import { n as NoClash, r as contextPlugin, t as ContextTask } from "./context-plugin-B0sLWOxR.js";
+import { A as HandlerRef, B as EventMap, C as Emit, D as EventPayload, E as EventLike, F as commandCall, G as Trace, H as PayloadOf, I as createBus, J as UnsubscribeCallback, K as TraceEvent, L as Tracer, M as On, N as WithContext, O as EventsOf, P as WithType, R as anyEventType, S as ContextOption, T as EventKey, U as Phase, V as Keys, W as Task, _ as Command, b as Context, g as BusOptions, h as Bus, i as WithPayload, j as Off, k as Handler, m as AnyEvent, p as Action, q as TraceLogger, v as CommandCall, w as Emittable, x as ContextOf, y as Commands, z as EffectName } from "./action-creator-Bd4TBZgl.js";
+import { n as NoClash, r as contextPlugin, t as ContextTask } from "./context-plugin-BVNKqkIx.js";
 export { type Action, type AnyEvent, type Bus, type BusOptions, type Command, type CommandCall, type Commands, type Context, type ContextOf, type ContextOption, type ContextTask, type EffectName, type Emit, type Emittable, type EventKey, type EventLike, type EventMap, type EventPayload, type EventsOf, type Handler, type HandlerRef, type Keys, type NoClash, type Off, type On, type PayloadOf, type Phase, type Task, type Trace, type TraceEvent, type TraceLogger, type Tracer, type UnsubscribeCallback, type WithContext, type WithPayload, type WithType, anyEventType, commandCall, contextPlugin, createBus };

package/dist/{module-DCJl-qfi.d.ts → module-DZ5ngUrM.d.ts}

@@ -1,4 +1,5 @@
-import { S as Context, _ as Bus, c as PayloadOf, m as UnsubscribeCallback, o as EventMap, u as Task, y as Command } from "./action-creator-DOWcbXpy.js";
+import { B as EventMap, H as PayloadOf, J as UnsubscribeCallback, W as Task, _ as Command, b as Context, c as WithScope, h as Bus, o as Scope, v as CommandCall } from "./action-creator-Bd4TBZgl.js";
+import { n as Scoped, t as FieldsOfScope } from "./types-BJ0fzV1p.js";
 //#region src/actions/command.d.ts
 /** What `createCommand` returns: a command that also tells whether an action is of its type. */
 type MadeCommand<P, R, T extends string> = Command<P, R> & {
@@ -12,6 +13,10 @@ type MadeCommand<P, R, T extends string> = Command<P, R> & {
     payload: P;
   };
 };
+/** `Made`, called so that its calls carry the scope fields `F`; `Made` itself when there are none. */
+type CarryingCalls<Made, P, R, F> = [unknown] extends [F] ? Made : ((payload: P) => CommandCall<P, R> & WithScope<F>) & Made & WithScope<F>;
+/** A command made with a scope: its calls carry the fields of that scope, for the checker. */
+type ScopedCommand<P, R, T extends string, F> = ((payload: P) => CommandCall<P, R> & WithScope<F>) & MadeCommand<P, R, T> & WithScope<F>;
 /**
  * Creates a command: a typed request for a result. Calling it builds
  * `{ type, payload }` like `createAction`. `bus.emit(command(payload))` (or
@@ -28,6 +33,11 @@ type MadeCommand<P, R, T extends string> = Command<P, R> & {
  * `command.match(action)` tells whether an action has the type of the command,
  * as it does for an action creator.
  *
+ * A scope as the third argument, `{ cache, $effects: { race } }`, puts those fields on
+ * the context of the handler and of the listeners of the command; the handler
+ * sees them typed. It works on a bus that uses `scopePlugin` from
+ * `nanoeffects/scope` and is ignored on any other.
+ *
  * @example
  * ```ts
  * const getUser = createCommand("user/get", (id: string, { signal }) =>
@@ -42,7 +52,8 @@ type MadeCommand<P, R, T extends string> = Command<P, R> & {
  * commands.handle(getUser, async () => fakeUser); // in a test
  * ```
  */
-declare const createCommand: <P = void, R = void, T extends string = string, E extends EventMap = EventMap>(type: T, handler?: Task<P, E, R>) => MadeCommand<P, R, T>;
+declare function createCommand<P = void, R = void, T extends string = string, E extends EventMap = EventMap>(type: T, handler?: Task<P, E, R>): MadeCommand<P, R, T>;
+declare function createCommand<P, R, T extends string, S extends Scope = Record<never, never>>(type: T, handler: Task<P, Scoped<EventMap, S>, R>, scope: S): ScopedCommand<P, R, T, FieldsOfScope<EventMap, S>>;
 /** 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>];
 /**
@@ -117,6 +128,8 @@ type ModuleContext<E extends EventMap = EventMap> = Context<E> & {
 type Module<E extends EventMap = EventMap> = {
   readonly name: string;
   readonly setup: (m: ModuleContext<E>) => void;
+  /** Fields for everything the module owns; see `scopePlugin`. */
+  readonly scope?: Scope;
 };
 /**
  * Describes one domain of an app: the commands it handles, the events it
@@ -137,7 +150,8 @@ type Module<E extends EventMap = EventMap> = {
  * });
  * ```
  */
-declare const createModule: <E extends EventMap = EventMap>(name: string, setup: (m: ModuleContext<E>) => void) => Module<E>;
+declare function createModule<E extends EventMap = EventMap>(name: string, setup: (m: ModuleContext<E>) => void): Module<E>;
+declare function createModule<E extends EventMap, S extends Scope = Record<never, never>>(name: string, setup: (m: ModuleContext<Scoped<E, S>>) => void, scope: S): Module<E>;
 type Registry<E extends EventMap> = ReturnType<ReturnType<typeof commandsPlugin<E>>>;
 /** What `modulePlugin` returns. */
 type ModuleApi<E extends EventMap = EventMap> = {
@@ -155,6 +169,7 @@ type ModuleApi<E extends EventMap = EventMap> = {
    * mounted, with no link to this bus.
    */
   createModule(name: string, setup: (m: ModuleContext<E>) => void): Module<E>;
+  createModule<S extends Scope = Record<never, never>>(name: string, setup: (m: ModuleContext<Scoped<E, S>>) => void, scope: S): Module<E>;
 };
 /**
  * The plugin that assembles an app from modules: `bus.use(modulePlugin(modules))`
@@ -192,4 +207,4 @@ type ModuleApi<E extends EventMap = EventMap> = {
  */
 declare const modulePlugin: <E extends EventMap>(modules?: readonly Module<E>[]) => (bus: Bus<E>) => ModuleApi<E>;
 //#endregion
-export { modulePlugin as a, bindHandler as c, createModule as i, commandsPlugin as l, ModuleApi as n, Binding as o, ModuleContext as r, MadeCommand as s, Module as t, createCommand as u };
+export { modulePlugin as a, MadeCommand as c, createCommand as d, createModule as i, bindHandler as l, ModuleApi as n, Binding as o, ModuleContext as r, CarryingCalls as s, Module as t, commandsPlugin as u };