nanoeffects 0.25.0 → 0.27.0

package/dist/{module-B5V47MZ0.d.ts → module-WX0Gngnt.d.ts}

@@ -1,5 +1,5 @@
-import { 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, y as Commands, z as EventMap } from "./action-creator-Bpa8BUS9.js";
-import { n as ScopeSlots, r as Scoped, t as FieldsOfScope } from "./types-DWjyeii7.js";
+import { G as PayloadOf, H as EventMap, R as commandCall, S as Context, Z as UnsubscribeCallback, b as Command, c as Scope, g as Actions, q as Task, u as WithScope, v as Bus, x as CommandCall } from "./action-creator-D_c223C7.js";
+import { n as ScopeSlots, r as Scoped } from "./types-Bf-LX_tE.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> & {
@@ -17,67 +17,46 @@ type MadeCommand<P, R, T extends string> = Command<P, R> & {
 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>;
+/** A command (or its type) with the handler to bind to it; `setHandler` makes one. */
+type Binding<E extends EventMap = EventMap> = readonly [Command<never, unknown> | string, Task<never, E, unknown>];
 /**
- * Creates a command: a typed request for a result. Calling it builds
- * `{ type, payload }` like `createAction`. `bus.emit(command(payload))` (or
- * `bus.emit(command, payload)`) runs its handler as a task, with a context, and
- * returns what the handler returns. Listeners of the command's type are told
- * first, as for any event.
- *
- * The handler is optional. A command without one is only a contract, and the
- * bus gets its implementation from the `commands` registry (see
- * `commandsPlugin` and `bindHandler`). A handler bound there wins over the one
- * the command was created with, so a test can give a bus its own implementation.
- *
- * A handler can be wrapped in a policy, e.g. `latest(fn)`.
- * `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.
+ * Pairs an action with the handler to bind to it, for `actionsPlugin`. For a
+ * command (an action made with a handler, or with a `Call` type) it checks that
+ * the handler fits; any other action is accepted with a handler of any payload.
  *
  * @example
  * ```ts
- * const getUser = createCommand("user/get", (id: string, { signal }) =>
- *   fetchUser(id, { signal }),
- * );
- * const sendMail = createCommand<Mail, void>("mail/send"); // implemented elsewhere
- *
- * const bus = createBus<Events>();
- * bus.use(commandsPlugin([bindHandler(sendMail, smtpSend)]));
- * const user = await bus.emit(getUser("1"));
- *
- * commands.handle(getUser, async () => fakeUser); // in a test
+ * bus.use(actionsPlugin([setHandler(sendMail, smtpSend)]));
  * ```
  */
-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> | undefined, 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>];
+declare function setHandler<P, R, E extends EventMap>(command: Command<P, R>, fn: Task<P, E, R>): Binding<E>;
+declare function setHandler<A extends {
+  readonly type: string;
+}, E extends EventMap>(action: A, fn: LooseHandler<A, E>): Binding<E>;
 /**
- * Pairs a command with the handler to bind to it, for `commandsPlugin`. It
- * checks that the handler fits the command.
- *
- * @example
- * ```ts
- * bus.use(commandsPlugin([bindHandler(sendMail, smtpSend)]));
- * ```
+ * The handler an action that is not a command can have: any. A command
+ * (a creator whose calls are command calls) is not accepted here, so its own
+ * overload checks the handler against its payload and result.
  */
-declare const bindHandler: <P, R, E extends EventMap>(command: Command<P, R>, fn: Task<P, E, R>) => Binding<E>;
-/** The registry of handlers that `commandsPlugin` returns: `run` for the bus, `handle` to bind more. */
-interface Registry$1<E extends EventMap> extends Commands {
+type LooseHandler<A, E extends EventMap> = A extends ((...args: never[]) => {
+  readonly [commandCall]: unknown;
+}) ? never : Task<never, E, unknown>;
+/** The registry of handlers that `actionsPlugin` returns: `run` for the bus, `handle` to bind more. */
+interface Registry$1<E extends EventMap> extends Actions {
   handle<P, R>(command: Command<P, R>, fn: Task<P, E, R>): UnsubscribeCallback;
+  /** Also an action made without a handler: what is emitted for its type runs `fn` and returns its result. */
+  handle<A extends {
+    readonly type: string;
+  }>(action: A, fn: LooseHandler<A, E>): UnsubscribeCallback;
   handle(type: string, fn: Task<never, E, unknown>): UnsubscribeCallback;
   handle(bindings: readonly Binding<E>[]): UnsubscribeCallback;
 }
 /**
  * The plugin that gives a bus the handlers bound to commands:
- * `bus.use(commandsPlugin(bindings))` makes the registry, sets it as the
+ * `bus.use(actionsPlugin(bindings))` makes the registry, sets it as the
  * commands of the bus and returns it. Each bus has its own, so each test can
  * have its own implementation. `handle` binds more later and returns the
- * function that unbinds. A second `commandsPlugin` on the same bus binds its
+ * function that unbinds. A second `actionsPlugin` on the same bus binds its
  * list in the registry that is there and returns it, so the order of the
  * plugins does not matter. A `commands` that is not such a registry (a custom
  * runner) is replaced.
@@ -88,13 +67,13 @@ interface Registry$1<E extends EventMap> extends Commands {
  * @example
  * ```ts
  * const bus = createBus<Events>();
- * const commands = bus.use(commandsPlugin([bindHandler(sendMail, smtpSend)]));
+ * const commands = bus.use(actionsPlugin([setHandler(sendMail, smtpSend)]));
  *
  * const unbind = commands.handle(getUser, async () => fakeUser);
  * unbind(); // the command's own handler is back
  * ```
  */
-declare const commandsPlugin: <E extends EventMap>(bindings?: readonly Binding<E>[]) => (bus: Bus<E>) => Registry$1<E>;
+declare const actionsPlugin: <E extends EventMap>(bindings?: readonly Binding<E>[]) => (bus: Bus<E>) => Registry$1<E>;
 //#endregion
 //#region src/actions/module.d.ts
 /**
@@ -106,6 +85,10 @@ declare const commandsPlugin: <E extends EventMap>(bindings?: readonly Binding<E
 type ModuleContext<E extends EventMap = EventMap> = Context<E> & {
   /** Binds the handler of a command, or a list of them; undone on unmount. */
   handle<P, R>(command: Command<P, R>, fn: Task<P, E, R>): UnsubscribeCallback;
+  /** Also an action made without a handler: the handler answers it as it would a command. */
+  handle<A extends {
+    readonly type: string;
+  }>(action: A, fn: LooseHandler<A, E>): UnsubscribeCallback;
   handle(type: string, fn: Task<never, E, unknown>): UnsubscribeCallback;
   handle(bindings: readonly Binding<E>[]): UnsubscribeCallback;
   /**
@@ -141,7 +124,7 @@ type Module<E extends EventMap = EventMap> = {
  * ```ts
  * export const userModule = createModule<Events>("user", (m) => {
  *   m.handle(getUser, fetchUser);
- *   m.handle([bindHandler(sendMail, smtpSend)]);
+ *   m.handle([setHandler(sendMail, smtpSend)]);
  *   m.use(authModule);
  *
  *   m.on(loginRequested, (user, ctx) => ctx.emit(userLoaded(user)));
@@ -153,7 +136,7 @@ type Module<E extends EventMap = EventMap> = {
  */
 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>>>;
+type Registry<E extends EventMap> = ReturnType<ReturnType<typeof actionsPlugin<E>>>;
 /**
  * The modules of an app as the plugins that report on them see them: the part
  * of what `modulePlugin` returns that `devPlugin` wraps.
@@ -176,7 +159,7 @@ interface WithApp {
 /** What `modulePlugin` returns. */
 type ModuleApi<E extends EventMap = EventMap> = {
   /** The registry of command handlers of the bus: the one it was made with, or the app's own. */
-  commands: Registry<E>;
+  actions: Registry<E>;
   /**
    * Mounts modules, in the order given, and returns the function that unmounts them, last
    * mounted first. A module that is mounted already is not run again. If one of them throws,
@@ -198,15 +181,15 @@ type ModuleApi<E extends EventMap = EventMap> = {
 };
 /**
  * The plugin that assembles an app from modules: `bus.use(modulePlugin(modules))`
- * returns `mount`, `unmount`, `isMounted`, `dispose` and `commands` for the
+ * returns `mount`, `unmount`, `isMounted`, `dispose` and `actions` for the
  * modules that come and go, and mounts `modules`, in the order given, on the
  * first use of the app or of the bus: the first `bus.emit`, or the first call
  * of one of its methods. By then every plugin is on the bus, so the plugins can
  * be used in any order. The `on`, `once` and `off` calls made in between are
  * held and made right after the modules, so the listeners of a module stay
  * ahead of them. The bus runs the commands that the modules bind: the registry
- * that the bus has is used (a later `commandsPlugin` binds in it), otherwise the
- * app attaches its own, as `app.commands`. The app is also `bus.app`.
+ * that the bus has is used (a later `actionsPlugin` binds in it), otherwise the
+ * app attaches its own, as `app.actions`. The app is also `bus.app`.
  *
  * A module is known by its `name`: mounting a module whose name is taken
  * replaces the mounted one, which is unmounted first. That is what hot reload
@@ -231,10 +214,10 @@ type ModuleApi<E extends EventMap = EventMap> = {
  * });
  *
  * bus.emit(getUser, "1");
- * app.commands.handle(getUser, fakeUser); // in a test
+ * app.actions.handle(getUser, fakeUser); // in a test
  * app.dispose();
  * ```
  */
 declare const modulePlugin: <E extends EventMap>(modules?: readonly Module<E>[]) => (bus: Bus<E> & ScopeSlots & WithApp) => ModuleApi<E>;
 //#endregion
-export { createModule as a, CarryingCalls as c, commandsPlugin as d, createCommand as f, WithApp as i, MadeCommand as l, ModuleApi as n, modulePlugin as o, ModuleContext as r, Binding as s, Module as t, bindHandler as u };
+export { createModule as a, CarryingCalls as c, actionsPlugin as d, setHandler as f, WithApp as i, MadeCommand as l, ModuleApi as n, modulePlugin as o, ModuleContext as r, Binding as s, Module as t, ScopedCommand as u };

package/dist/notrace/{action-creator-D2CotugT.d.ts → action-creator-Bux7Zzsl.d.ts}

@@ -49,7 +49,7 @@ interface Tracer<Ref extends object = object> {
 /** Subscribes to every event; handlers receive the payload of any of them. */
 type AnyEvent = typeof anyEventType;
 type EventKey<E extends EventMap> = Keys<E>;
-type EventPayload<E extends EventMap> = E[EventKey<E>];
+type EventPayload<E extends EventMap> = DataOf<E[EventKey<E>]>;
 type WithType<K extends string> = {
   type: K;
 };
@@ -69,7 +69,7 @@ type WithSignal = {
 type HandlerRef<E extends EventMap, Response = unknown> = (action: Action<E>) => Response;
 type Handler<E extends EventMap, Response = unknown, K extends EventKey<E> = EventKey<E>> = { [P in K]: {
   type: P;
-  (payload: E[P]): Response;
+  (payload: DataOf<E[P]>): Response;
 }; }[K];
 type Action<E extends EventMap> = {
   type: EventKey<E>;
@@ -103,35 +103,45 @@ type Command<P = never, R = unknown> = {
   readonly wrap?: (run: (payload: never, ctx: never) => unknown) => (payload: never, ctx: never) => unknown;
 };
 /**
- * What the bus needs to run commands. The implementation, `commandsPlugin` in
- * `nanoeffects/actions`, holds the handlers bound to commands and runs the
- * right one, so a bus without `commands` carries none of that.
+ * What the bus needs to run the handlers of actions. The implementation,
+ * `actionsPlugin` in `nanoeffects/actions`, holds the handlers bound to
+ * actions and runs the right one, so a bus without `actions` carries none of
+ * that. `bound` tells, for an event type, whether a handler is bound to it: an
+ * action with no handler of its own is a command only then. A runner that has
+ * no `bound` runs commands only.
  */
-interface Commands {
+interface Actions {
   run(command: Command, payload: unknown, ctx: unknown): unknown;
+  bound?(type: string): Command | undefined;
 }
 /** Anything `emit` takes as its first argument: an event type, an action or a command. */
 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;
+  /**
+   * On a bus without an event map the caller can say what a handler bound for
+   * the type returns: `bus.emit<string>("user/getId")`. With a map the parameter
+   * is `never`, so this form is not taken and no check of names or payloads is lost.
+   */
+  <R = void>(type: string extends EventKey<E> ? string : never, ...payload: unknown[]): R;
+  <K extends EventKey<E>>(event: K, ...payload: PayloadOf<DataOf<E[K]>>): ResultOf<E[K]>;
   /** Before Handler: a command is callable too, and must return its result type. */
   <P, R>(command: Command<P, R>, ...payload: PayloadOf<P>): 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;
+  <K extends EventKey<E>, R>(event: Handler<E, R, K>, ...payload: PayloadOf<DataOf<E[K]>>): R;
   <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>, options?: ListenerOptions): UnsubscribeCallback;
-  <K extends EventKey<E>>(event: K, fn: Task<E[K], E>, options?: ListenerOptions): UnsubscribeCallback;
+  <K extends EventKey<E>>(event: K, fn: Task<DataOf<E[K]>, E>, options?: ListenerOptions): 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>>, options?: ListenerOptions): UnsubscribeCallback;
+  <K extends EventKey<E>, F>(creator: FreeActionCreator<K, F> & WithScope<F>, fn: Task<DataOf<E[K]>, WithFields<E, F>>, options?: ListenerOptions): UnsubscribeCallback;
   <P, F>(creator: ActionCreator<P, string, PayloadOf<P>, F> & WithScope<F>, fn: Task<P, WithFields<E, F>>, options?: ListenerOptions): UnsubscribeCallback;
   <P, F>(command: Command<P, unknown> & WithScope<F>, fn: Task<P, WithFields<E, F>>, options?: ListenerOptions): UnsubscribeCallback;
-  <K extends EventKey<E>>(creator: FreeActionCreator<K>, fn: Task<E[K], E>, options?: ListenerOptions): UnsubscribeCallback;
+  <K extends EventKey<E>>(creator: FreeActionCreator<K>, fn: Task<DataOf<E[K]>, E>, options?: ListenerOptions): UnsubscribeCallback;
   /** An action creator: the payload comes from it, so an event map is not needed. */
   <P>(creator: ActionCreator<P>, fn: Task<P, E>, options?: ListenerOptions): UnsubscribeCallback;
   /** A command: the payload comes from it too. */
@@ -140,7 +150,7 @@ type On<E extends EventMap> = {
     type: K;
   }>(event: Event & {
     type: K;
-  }, fn: Task<E[K], E>, options?: ListenerOptions): UnsubscribeCallback;
+  }, fn: Task<DataOf<E[K]>, E>, options?: ListenerOptions): UnsubscribeCallback;
 };
 type Off<E extends EventMap> = {
   /** Removes every listener of every event (including `"*"`). */
@@ -148,12 +158,12 @@ type Off<E extends EventMap> = {
   (event: AnyEvent): void;
   (event: AnyEvent, fn: Task<EventPayload<E>, E>): void;
   <K extends EventKey<E>>(event: K): void;
-  <K extends EventKey<E>>(event: K, fn: Task<E[K], E>): void;
+  <K extends EventKey<E>>(event: K, fn: Task<DataOf<E[K]>, E>): void;
   <K extends EventKey<E>, Event extends {
     type: K;
   }>(event: Event & {
     type: K;
-  }, fn: Task<E[K], E>): void;
+  }, fn: Task<DataOf<E[K]>, E>): void;
   <P>(command: Command<P, unknown>, fn?: Task<P, E>): void;
 };
 declare const contextKey: unique symbol;
@@ -224,10 +234,10 @@ interface Bus<E extends EventMap> {
    * no list of them. See `modulePlugin` in `nanoeffects/actions`.
    */
   use<R>(plugin: (bus: Bus<E>) => R): R;
-  /** `BusOptions.context` and `.trace`, and `commands`, for what makes tasks of its own, like `modulePlugin`. */
+  /** `BusOptions.context` and `.trace`, and `actions`, for what makes tasks of its own, like `modulePlugin`. */
   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;
+  /** What runs the handlers of actions; `actionsPlugin` and `modulePlugin` set it. Without one a command runs its own handler. */
+  actions?: Actions | 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;
@@ -245,8 +255,8 @@ type BusOptions<E extends EventMap> = {
   onError?: (error: unknown, event: Action<E>) => void;
   /**
    * Called when an event is emitted and nobody listens to it: the usual sign
-   * of a typo in an event name. Not called for commands, which always have a
-   * handler to run. Typically a warning in development only.
+   * of a typo in an event name. Not called for commands, nor for an action with
+   * a handler bound in `actions`, which always have a handler to run. Typically a warning in development only.
    *
    * @example
    * ```ts
@@ -336,15 +346,33 @@ type Merge<A, B> = Omit<A, keyof B> & B;
 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] ? {
+type WithPayload<E extends EventMap, K extends Keys<E>> = undefined extends DataOf<E[K]> ? {
   type: K;
-  payload?: E[K];
+  payload?: DataOf<E[K]>;
 } : {
   type: K;
-  payload: E[K];
+  payload: DataOf<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 callBrand: unique symbol;
+/**
+ * A payload type together with the type of what a handler of the action
+ * returns, for an event map or `createAction`:
+ * `type Events = { "user/getId": Call<void, string> }`, and then
+ * `bus.emit("user/getId")` is a `string`. A type only: it adds nothing to a
+ * bundle, and an entry that is not a `Call` means a payload, with no result.
+ */
+type Call<P = void, R = void> = {
+  readonly [callBrand]: {
+    payload: P;
+    result: R;
+  };
+};
+/** The payload type of an entry of an event map: the `P` of a `Call<P, R>`, the entry itself otherwise. */
+type DataOf<T> = T extends Call<infer P, unknown> ? P : T;
+/** What `emit` returns for an entry of an event map: the `R` of a `Call<P, R>`, `void` otherwise. */
+type ResultOf<T> = T extends Call<unknown, infer R> ? R : void;
 declare const free: unique symbol;
 type Free = typeof free;
 /**
@@ -387,4 +415,4 @@ interface ActionCreator<P = void, T extends string = string, A extends unknown[]
   toString(): T;
 }
 //#endregion
-export { On as A, EventKey as C, Handler as D, EventsOf as E, EventMap as F, Keys as I, PayloadOf as L, WithSignal as M, WithType as N, HandlerRef as O, createBus as P, Task as R, Emittable as S, EventPayload as T, Commands as _, Scope as a, ContextOption as b, BoundForm as c, Action as d, AnyEvent as f, CommandCall as g, Command as h, WithPayload as i, WithContext as j, Off as k, Effect as l, BusOptions as m, Free as n, WithFields as o, Bus as p, FreeActionCreator as r, WithScope as s, ActionCreator as t, Effects as u, Context as v, EventLike as w, Emit as x, ContextOf as y, UnsubscribeCallback as z };
+export { Off as A, Task as B, Emittable as C, EventsOf as D, EventPayload as E, commandCall as F, createBus as I, EventMap as L, WithContext as M, WithSignal as N, Handler as O, WithType as P, Keys as R, Emit as S, EventLike as T, UnsubscribeCallback as V, Command as _, WithPayload as a, ContextOf as b, WithScope as c, Effects as d, Action as f, BusOptions as g, Bus as h, FreeActionCreator as i, On as j, HandlerRef as k, BoundForm as l, AnyEvent as m, Call as n, Scope as o, Actions as p, Free as r, WithFields as s, ActionCreator as t, Effect as u, CommandCall as v, EventKey as w, ContextOption as x, Context as y, PayloadOf as z };