nanoeffects 0.7.0 → 0.8.0

package/dist/oop.d.ts

@@ -0,0 +1,131 @@
+import { B as EventMap, _ as Command, h as Bus, t as ActionCreator } from "./action-creator-BrZF6hXc.js";
+//#region src/oop/types.d.ts
+type Slots = "ctx" | "commands" | "trace" | "addContext" | "applyScope" | "fitScope" | "app" | "use";
+type AnyFunction = (...args: never[]) => unknown;
+/**
+ * The methods an instance of a class from `extendBus` gets: the function
+ * members of the bus (`on`, `once`, `off`, `emit`, and those of the plugins used
+ * before `extendBus`), `dispose`, and the bus itself as `bus`. A member of the
+ * class with the same name is kept and not replaced.
+ */
+type BusMethods<B> = { [K in keyof B as K extends Slots ? never : B[K] extends AnyFunction ? K : never]: B[K]; } & {
+  /** Removes every subscription made through `on` and `once` of this instance. */
+  dispose(): void;
+  [Symbol.dispose](): void;
+  readonly bus: B;
+};
+/** Any class that `extendBus` can extend. */
+type Constructor = new (...args: never[]) => object;
+/**
+ * The class `extendBus` returns: it takes the arguments of `C`, its instances
+ * are instances of `C` with the methods of `B` that `C` does not have, and its
+ * static members are those of `C` plus the bus.
+ */
+type Extended<C extends Constructor, B> = {
+  new (...args: ConstructorParameters<C>): InstanceType<C> & Omit<BusMethods<B>, keyof InstanceType<C>>;
+  readonly bus: B;
+  readonly prototype: InstanceType<C>;
+} & Omit<C, "prototype">;
+/** A wrapper for the handler of `@On` and `@Once`, such as `latest`. */
+type Wrap = (handler: (payload: unknown, ctx: unknown) => unknown) => unknown;
+type Handler<P> = (payload: P, ctx: never) => unknown;
+/**
+ * What `@On(event)` and `@Once(event)` return: a method decorator of the
+ * language and of `experimentalDecorators`. The payload of the method is
+ * checked against the event when the event is an action creator or a command.
+ */
+interface MethodDecorator<P> {
+  (value: Handler<P>, context: ClassMethodDecoratorContext): void;
+  (target: object, key: string | symbol, descriptor: TypedPropertyDescriptor<Handler<P>>): void;
+}
+/** The events a decorator takes. */
+type EventOf<P> = ActionCreator<P> | Command<P, unknown>;
+//#endregion
+//#region src/oop/decorators.d.ts
+/**
+ * A class decorator that does what `extendBus` does: `@WithBus(bus) class A {}`
+ * replaces `A` by `extendBus(bus, A)`, and `@WithBus() class A {}` by
+ * `extendBus(A)`. It works for the decorators of the language and for
+ * `experimentalDecorators`. TypeScript does not change the type of a decorated
+ * class, so declare what it gets next to it:
+ * `interface A extends BusMethods<typeof bus> {}`.
+ *
+ * @example
+ * ```ts
+ * interface SearchService extends BusMethods<typeof bus> {}
+ *
+ * @WithBus(bus)
+ * class SearchService {}
+ * ```
+ */
+export declare function WithBus<B extends object>(bus: B): <C extends Constructor>(Base: C) => Extended<C, B>;
+export declare function WithBus(): <C extends Constructor>(Base: C) => Extended<C, Bus<EventMap>>;
+/**
+ * Makes a method of a class from `extendBus` or `@WithBus` a handler of `event`
+ * for each instance, with `this` bound to the instance, from the construction
+ * until `dispose()`. `wrap` takes the bound handler and returns the one to
+ * subscribe, such as `latest`. An event emitted inside the constructor of the
+ * base class does not reach it: the subscription is made right after.
+ *
+ * @example
+ * ```ts
+ * class SearchServiceBase {
+ *   @On(queryChanged, latest) // a new query aborts the one before it
+ *   async search(query: string, { signal }: Context) {}
+ * }
+ * ```
+ */
+export declare function On<P>(event: EventOf<P>, wrap?: Wrap): MethodDecorator<P>;
+export declare function On(event: string, wrap?: Wrap): MethodDecorator<never>;
+/** Like `On`, but the handler runs at most once for an instance. */
+export declare function Once<P>(event: EventOf<P>, wrap?: Wrap): MethodDecorator<P>;
+export declare function Once(event: string, wrap?: Wrap): MethodDecorator<never>;
+//#endregion
+//#region src/oop/extend.d.ts
+/**
+ * Makes a class from `Base` whose instances have the methods of a bus, with the
+ * subscriptions made through an instance ended by `dispose()`. `new Extended(…)`
+ * runs the constructor of `Base`; the class has the name of `Base`, and its
+ * instances are instances of `Base`. The members of `Base` win: a method called
+ * `emit` or `dispose` in `Base` is kept, and `disposeBus(this)` ends the
+ * subscriptions from there.
+ *
+ * Without a bus, `extendBus(Base)` makes one for the class (`Extended.bus`),
+ * shared by its instances. The methods of the plugins used on `bus` before this
+ * call are on the instances too; the ones of plugins used later are not.
+ *
+ * @example
+ * ```ts
+ * class SearchServiceBase {
+ *   constructor(private api: Api) {
+ *     this.on("query/changed", (query) => this.load(query)); // ends with dispose()
+ *   }
+ *   load(query: string) {}
+ * }
+ *
+ * export const SearchService = extendBus(bus, SearchServiceBase);
+ * const service = new SearchService(api);
+ * service.dispose(); // its subscriptions are gone
+ * ```
+ */
+export declare function extendBus<C extends Constructor>(Base: C): Extended<C, Bus<EventMap>>;
+export declare function extendBus<B extends object, C extends Constructor>(bus: B, Base: C): Extended<C, B>;
+//#endregion
+//#region src/oop/subscriptions.d.ts
+/**
+ * Removes every subscription an instance made through `on` and `once`, and does
+ * nothing for any other value. A class with a `dispose` of its own calls it from
+ * there.
+ *
+ * @example
+ * ```ts
+ * class SearchService {
+ *   dispose() {
+ *     disposeBus(this); // the subscriptions of this instance are removed
+ *   }
+ * }
+ * ```
+ */
+export declare const disposeBus: (instance: unknown) => void;
+//#endregion
+export type { BusMethods, Extended, MethodDecorator };

package/dist/oop.js

@@ -0,0 +1 @@
+import{n as e}from"./bus-BAs9x7IQ.js";const t=/* @__PURE__ */ new WeakMap,n=e=>typeof e==`function`,r=e=>Reflect.ownKeys(e).flatMap(t=>{let r=Reflect.getOwnPropertyDescriptor(e,t)?.value;return n(r)?[{key:t,value:r}]:[]}),i=/* @__PURE__ */ new WeakMap,a=e=>{let n=i.get(e);if(n)return n;let a=/* @__PURE__ */ new Set,o=[];for(let n=e;n&&n!==Object.prototype;n=Reflect.getPrototypeOf(n))for(let{key:e,value:i}of r(n)){if(e===`constructor`||a.has(e))continue;a.add(e);let n=t.get(i);n&&o.push({key:e,method:i,spec:n})}return i.set(e,o),o},o=/* @__PURE__ */ new WeakMap,s=e=>typeof e==`object`&&!!e||typeof e==`function`,c=e=>{let t=o.get(e);if(t)return t;let n=/* @__PURE__ */ new Set;return o.set(e,n),n},l=e=>{if(typeof e==`string`)return e;if(s(e)){let t=Reflect.get(e,`type`);return typeof t==`string`?t:e}return e},u=(e,t,n)=>Reflect.apply(Reflect.get(e,t),e,n),d=(e,t,n,r)=>{let[i,a,...o]=r,s=c(e),l={event:i,handler:a,off:()=>{}},d=u(t,n,[i,n===`once`?(e,t)=>(s.delete(l),typeof a==`function`?Reflect.apply(a,null,[e,t]):void 0):a,...o]),f=typeof d==`function`?()=>d():()=>{};return l.off=f,s.add(l),()=>{s.delete(l),f()}},f=(e,t,n)=>{let[r,i]=n,a=c(e);r===void 0&&a.clear();for(let e of[...a])Object.is(l(e.event),l(r))&&(i===void 0||e.handler===i)&&(a.delete(e),e.off());return u(t,`off`,n)},p=e=>{if(!s(e))return;let t=o.get(e);if(t){o.delete(e);for(let e of t)e.off()}},m=/* @__PURE__ */ new Set([`on`,`once`,`off`,`emit`,`ctx`,`commands`,`trace`,`addContext`,`applyScope`,`fitScope`,`app`,`use`]),h=Reflect.get(Symbol,`dispose`),g=e=>typeof e==`function`,_=(e,t,n,r)=>{n in t||Object.defineProperty(e,n,{configurable:!0,enumerable:!1,...r})},v=/* @__PURE__ */ new WeakMap,y=(e,t)=>{let n=v.get(e);if(n)return n;let r={on:(...n)=>d(e,t,`on`,n),once:(...n)=>d(e,t,`once`,n),off:(...n)=>f(e,t,n)};return v.set(e,r),r},b=(e,t)=>(...n)=>Reflect.apply(Reflect.get(e,t),e,n),x=(e,t)=>{for(let{method:n,spec:r}of a(Reflect.getPrototypeOf(e)??{})){let i=(t,r)=>Reflect.apply(n,e,[t,r]),a=r.wrap?r.wrap(i):i;d(e,t,r.once?`once`:`on`,[r.event,a])}},S=(e,t,n)=>{for(let r of[`on`,`once`,`off`])_(e,t,r,{get(){return y(this,n)[r]}});_(e,t,`emit`,{value:b(n,`emit`)});for(let[r,i]of Object.entries(n))typeof i==`function`&&!m.has(r)&&_(e,t,r,{value:b(n,r)});let r=function(){p(this)};_(e,t,`dispose`,{value:r}),h&&_(e,t,h,{value:r}),_(e,t,`bus`,{get:()=>n})},C=(e,t)=>{let n=function(...r){let i=Reflect.construct(t,r,new.target??n);return x(i,e),i};return Object.setPrototypeOf(n,t),n.prototype=Object.create(t.prototype,{constructor:{value:n,writable:!0,configurable:!0}}),Object.defineProperty(n,"name",{value:t.name,configurable:!0}),`bus`in t||Object.defineProperty(n,"bus",{value:e,configurable:!0}),S(n.prototype,t.prototype,e),n};function w(t,n){if(g(t))return C(e(),t);if(!n)throw TypeError(`extendBus: pass the class to extend`);return C(t,n)}function T(e){return t=>e?w(e,t):w(t)}const E=e=>{let[t,n,r]=e;return typeof n==`string`||typeof n==`symbol`?Reflect.get(Object(r),`value`):t},D=(e,n,r)=>((...i)=>{let a=E(i);typeof a==`function`&&t.set(a,{event:e,wrap:n,once:r})});function O(e,t){return D(e,t,!1)}function k(e,t){return D(e,t,!0)}export{O as On,k as Once,T as WithBus,p as disposeBus,w as extendBus};

package/dist/{plugin-DQNPBcxx.d.ts → plugin-DkXCvsmB.d.ts}

@@ -1,5 +1,5 @@
-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-Bd4TBZgl.js";
-import { n as NoClash } from "./context-plugin-BVNKqkIx.js";
+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-BrZF6hXc.js";
+import { n as NoClash } from "./context-plugin--HkNN1ha.js";
 //#region src/utils/delay.d.ts
 /**
  * Resolves after `ms`, or rejects early if `ctx.signal` aborts. `ms` can be a

package/dist/policies.d.ts

@@ -1,4 +1,4 @@
-import { B as EventMap, W as Task } from "./action-creator-Bd4TBZgl.js";
+import { B as EventMap, W as Task } from "./action-creator-BrZF6hXc.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 { B as EventMap, T as EventKey, h as Bus, r as FreeActionCreator, t as ActionCreator } from "./action-creator-Bd4TBZgl.js";
+import { B as EventMap, T as EventKey, h as Bus, r as FreeActionCreator, t as ActionCreator } from "./action-creator-BrZF6hXc.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 { B as EventMap, h as Bus } from "./action-creator-Bd4TBZgl.js";
+import { B as EventMap, h as Bus } from "./action-creator-BrZF6hXc.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.d.ts

@@ -1,5 +1,5 @@
-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-Bd4TBZgl.js";
-import { n as Scoped } from "./types-BJ0fzV1p.js";
+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-BrZF6hXc.js";
+import { n as ScopeSlots, r as Scoped } from "./types-KavbvHix.js";
 //#region src/scope/effect.d.ts
 /**
  * Marks a function whose first parameter is `{ signal }` as an effect, so that
@@ -35,9 +35,8 @@ export declare function effect<A extends unknown[], R>(fn: (ctx: Signaled, ...ar
  * 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.
+ * It works in any order with the other plugins. Without this plugin a scope is
+ * ignored.
  *
  * @example
  * ```ts
@@ -53,6 +52,6 @@ export declare function effect<A extends unknown[], R>(fn: (ctx: Signaled, ...ar
  * bus.emit(getUser("1"), { http: fakeHttp }); // this call only
  * ```
  */
-export declare const scopePlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus<E>;
+export declare const scopePlugin: () => <E extends EventMap>(bus: Bus<E> & ScopeSlots) => Bus<E> & ScopeSlots;
 //#endregion
 export type { Effect, Effects, EmitScope, Scope, Scoped, Signaled };

package/dist/trace.d.ts

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

package/dist/{types-BJ0fzV1p.d.ts → types-KavbvHix.d.ts}

@@ -1,6 +1,16 @@
-import { B as EventMap, d as Effects, o as Scope, s as WithFields } from "./action-creator-Bd4TBZgl.js";
-import { t as BoundOf } from "./plugin-DQNPBcxx.js";
+import { B as EventMap, d as Effects, o as Scope, s as WithFields } from "./action-creator-BrZF6hXc.js";
+import { t as BoundOf } from "./plugin-DkXCvsmB.js";
 //#region src/scope/types.d.ts
+/**
+ * The slots `scopePlugin` fills for `modulePlugin`. They are not on `Bus`: a bus
+ * has them in its type once the plugin returned it.
+ */
+interface ScopeSlots {
+  /** Puts the fields of a module's scope on the context of one of its tasks. 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. */
+  fitScope?: ((scope: Scope, fn: unknown) => unknown) | undefined;
+}
 type BoundEffects<E extends EventMap, S extends Scope> = S extends {
   $effects: infer H extends Effects;
 } ? BoundOf<H, E> : unknown;
@@ -12,4 +22,4 @@ type FieldsOfScope<E extends EventMap, S extends Scope> = [keyof S] extends [nev
  */
 type Scoped<E extends EventMap, S extends Scope> = WithFields<E, FieldsOfScope<E, S>>;
 //#endregion
-export { Scoped as n, FieldsOfScope as t };
+export { ScopeSlots as n, Scoped as r, FieldsOfScope as t };

package/docs/README.md

@@ -27,6 +27,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 - [Actions, commands, jobs and modules](actions.md)
 - [Sign-up form in React](react.md) — one form: races, double submit, retry
 - [Context fields](context.md) — store or client on every task
+- [Use the bus from a class](oop.md) — `extendBus`, `@WithBus`, `@On`, and `dispose()` for the subscriptions of an instance
 - [TypeScript in many files](typescript.md) — keep the types of the bus in commands and modules
 - [Errors and unheard events](errors.md)
 - [Package entries](package.md) — which import holds what

package/docs/actions.md

@@ -8,14 +8,28 @@ Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
 
 ## Return a value from `emit` with a command
 
+The bus lives in one file and its events in another, so any module can import both without a cycle.
+
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 
-const bus = createBus();
+// createBus — one bus for the app
+export const bus = createBus();
+```
+
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
 
 // createCommand — emit runs the handler and returns its result
-const double = createCommand("math/double", (value) => value * 2);
+export const double = createCommand("math/double", (value) => value * 2);
+```
+
+```js
+import { bus } from "./bus";
+import { double } from "./math";
+
 bus.emit(double(21)); // 42
 ```
 
@@ -24,27 +38,30 @@ bus.emit(double(21)); // 42
 `nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
 
 ```js
+// user.js
 import { createAction, createCommand, createJob } from "nanoeffects/actions";
 
 // createAction — event with a payload (like RTK createAction)
-const userLoaded = createAction("user/loaded");
-const loadFailed = createAction("user/failed");
+export const userLoaded = createAction("user/loaded");
+export const loadFailed = createAction("user/failed");
 
 // createCommand with a handler — emit returns what the handler returns
-const getUser = createCommand("user/get", (id, { signal }) => {
+export const getUser = createCommand("user/get", (id, { signal }) => {
   return fetchUser(id, { signal });
 });
 
 // createCommand without a handler — a contract; register the work elsewhere
-const sendMail = createCommand("mail/send");
+export const sendMail = createCommand("mail/send");
 
 // createJob — command that also emits success / fail actions
-const loadUser = createJob("user/load", fetchUser, {
+export const loadUser = createJob("user/load", fetchUser, {
   success: userLoaded,
   fail: "user/failed",
 });
 ```
 
+These are the events of the user domain, in a file of their own (`user.js`). The bus is made in another file (`bus.js` below), and neither imports the other.
+
 ### Actions
 
 `createAction(type)` returns a creator. Without generics it keeps the literal type; the bus checks the payload against its event map. Without an event map, give the payload type: `createAction<User>("user/loaded")`.
@@ -65,22 +82,22 @@ Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(comm
 **Where handlers are registered.** The command may carry a handler. The bus can also take handlers from a registry (`commandsPlugin`). A handler bound there wins over the command’s own. Each bus (each test) has its own registry.
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import {
-  bindHandler,
-  commandsPlugin,
-  createCommand,
-} from "nanoeffects/actions";
-
-const sendMail = createCommand("mail/send");
-const getUser = createCommand("user/get");
+import { bindHandler, commandsPlugin } from "nanoeffects/actions";
+import { sendMail } from "./user";
 
-const bus = createBus();
+export const bus = createBus();
 
 // commandsPlugin — registry of handlers for this bus
-const commands = bus.use(
+export const commands = bus.use(
   commandsPlugin([bindHandler(sendMail, smtpSend)]),
 );
+```
+
+```js
+import { commands } from "./bus";
+import { getUser } from "./user";
 
 // later, e.g. in a test — latest binding wins
 const unbind = commands.handle(getUser, async () => fakeUser);
@@ -89,7 +106,7 @@ unbind();
 
 A command with no handler anywhere throws `No handler for command "..."` from `emit` (the call itself only builds the action).
 
-The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the command’s own handler. `bus.use(commandsPlugin())` sets `bus.commands`. A second plugin on the same bus replaces it. There is no `commands` option in `createBus`; assign a custom runner with `bus.commands = { run }`.
+The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the command’s own handler. `bus.use(commandsPlugin())` sets `bus.commands`. A second `commandsPlugin` binds its list in that registry and returns it. There is no `commands` option in `createBus`; assign a custom runner with `bus.commands = { run }`.
 
 ### Jobs
 
@@ -112,18 +129,20 @@ The registry lives in `nanoeffects/actions`, so a bus without one carries none o
 `bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, `commands`, and `createModule`: the same as `createModule` below, with the context fields of the bus typed (see [TypeScript](typescript.md)).
 
 ```js
-import { createBus } from "nanoeffects";
-import {
-  createCommand,
-  createModule,
-  modulePlugin,
-} from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get");
-const saveUser = createCommand("user/save", persistUser);
+export const getUser = createCommand("user/get");
+export const saveUser = createCommand("user/save", persistUser);
+```
+
+```js
+// user-module.js
+import { createModule } from "nanoeffects/actions";
+import { getUser, saveUser } from "./user";
 
 // createModule — one domain; unmount undoes everything below
-const userModule = createModule("user", (m) => {
+export const userModule = createModule("user", (m) => {
   m.handle(getUser, fetchUser);
   m.use(saveUser, authModule);
   m.on("login", (user, ctx) => {
@@ -133,10 +152,22 @@ const userModule = createModule("user", (m) => {
     /* background work; ends when the module unmounts */
   });
 });
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { userModule } from "./user-module";
 
-const bus = createBus();
+export const bus = createBus();
 // modulePlugin — mount modules on the bus
-const app = bus.use(modulePlugin([userModule]));
+export const app = bus.use(modulePlugin([userModule]));
+```
+
+```js
+import { app } from "./bus";
+import { getUser } from "./user";
 
 const unmount = app.mount(orderModule); // later, e.g. after a lazy import
 app.commands.handle(getUser, fakeUser); // in a test
@@ -147,6 +178,7 @@ app.dispose(); // unmounts every module
 - **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one (see [Hot reload](hmr.md)).
 - **Registry.** If `bus.use(commandsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`.
 - A disposed app cannot mount modules.
+- **The given modules are mounted on the first use** of the app or the bus (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`), so the plugins you use after `modulePlugin` still reach them. The `bus.on` calls made in between are held and made right after, so the listeners of a module stay ahead of them. See [using plugins in any order](plugins.md#use-them-in-any-order).
 - Module context = task context plus `handle`, `use`, and `spawn`:
   - `handle` — give a command a handler (contract, or override).
   - `use` — bring sub-modules and commands that carry a handler; the returned function undoes that call.
@@ -158,17 +190,29 @@ app.dispose(); // unmounts every module
 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
+// bus.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());
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
 // the third argument — fields of this command only
-const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
-  api,
-});
+export const getUser = createCommand(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 // a test replaces them for one call
 const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };

package/docs/guide.md

@@ -69,6 +69,74 @@ 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.
 
+### Pick events with a function
+
+To listen to a group of events, such as every `user/*` event, `"*"` and a check of `ctx.type` do the job but leave the check to you. `matchPlugin` lets `on` take a function that picks the events. The function gets `{ type, payload }` of each event, and the handler runs when it returns true.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { matchPlugin } from "nanoeffects/match";
+
+// matchPlugin — lets on, once and off take a function that picks the events
+export const bus = createBus().use(matchPlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+export const userLoaded = createAction("user/loaded");
+export const userFailed = createAction("user/failed");
+```
+
+```js
+// user-handlers.js
+import { bus } from "./bus";
+
+// the function picks the events; the handler gets the payload and the context of each
+bus.on(
+  (action) => action.type.startsWith("user/"),
+  (payload, ctx) => {
+    console.log(ctx.type, payload);
+  },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { userFailed, userLoaded } from "./user";
+
+bus.emit(userLoaded({ id: "1" })); // user/loaded { id: "1" }
+bus.emit("order/placed", 5); // not picked
+bus.emit(userFailed("boom")); // user/failed boom
+```
+
+- `once(fn, handler)` waits for the first event that `fn` accepts. `off(fn)` removes every handler of `fn`, and `off(fn, handler)` removes one.
+- An action creator or a command still means that one event: only a function with no `type` is a function that picks events.
+- The cost: the handler listens to `"*"`, so each event makes one task for each such subscription, also when the function says no, and an event that only such a subscription listens to counts as heard for `onUnhandled`. For a few known events, `on(creator, handler)` is cheaper.
+- It works in any order with the other plugins, `devPlugin` included.
+
+In TypeScript a function that is a type guard narrows the payload of the handler:
+
+```ts
+import { bus } from "./bus";
+
+type User = { id: string };
+
+// the guard says which event this is, and the handler gets its payload typed
+const isLoaded = (action: {
+  type: string;
+  payload: unknown;
+}): action is { type: "user/loaded"; payload: User } => action.type === "user/loaded";
+
+bus.on(isLoaded, (user) => console.log(user.id)); // user: User
+```
+
+`ctx.on` takes such a function at run time too, but its type does not know it yet.
+
 ## 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.
@@ -225,22 +293,42 @@ More in [Effects](effects.md).
 
 `emit` and `on` take a string, an object `{ type, payload }` (a Redux action fits), or a function with a `type` property (action creators and commands).
 
+From here on the bus is kept in one file and the events in files named after their domain (`move.js`, `math.js`), as in a real app: the events can then be imported anywhere without importing the bus.
+
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, createCommand } from "nanoeffects/actions";
 
-const bus = createBus();
+export const bus = createBus();
+```
+
+```js
+// move.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — names an event; calling it builds { type, payload }
+export const moved = createAction("moved");
+```
+
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
+
+// createCommand — like an action, but emit runs a handler and returns its result
+export const double = createCommand("math/double", (value) => value * 2);
+```
+
+```js
+import { bus } from "./bus";
+import { moved } from "./move";
+import { double } from "./math";
 
 bus.emit("moved", { x: 1, y: 2 });
 bus.emit({ type: "moved", payload: { x: 2, y: 2 } });
 
-// createAction — names an event; calling it builds { type, payload }
-const moved = createAction("moved");
 bus.emit(moved({ x: 3, y: 2 }));
 bus.on(moved, ({ x }) => console.log(x));
 
-// createCommand — like an action, but emit runs a handler and returns its result
-const double = createCommand("math/double", (value) => value * 2);
 bus.emit(double(21)); // 42
 ```
 
@@ -251,14 +339,25 @@ Use strings for the plain case. Use objects when other code already builds actio
 A command may carry its handler, or only be a **contract** (name + types) with the work registered elsewhere — another file, or a fake in a test.
 
 ```js
-import { createBus } from "nanoeffects";
-import { createCommand, commandsPlugin } from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // contract — no handler yet
+export const getUser = createCommand("user/get"); // contract — no handler yet
+```
 
-const bus = createBus();
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { commandsPlugin } from "nanoeffects/actions";
+
+export const bus = createBus();
 // commandsPlugin — registry of handlers for this bus
-const commands = bus.use(commandsPlugin());
+export const commands = bus.use(commandsPlugin());
+```
+
+```js
+import { bus, commands } from "./bus";
+import { getUser } from "./user";
 
 bus.emit(getUser("1")); // throws: No handler for command "user/get"
 
@@ -279,16 +378,27 @@ Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can reg
 **What you do.** `createModule(name, setup)` describes the feature. `bus.use(modulePlugin([…]))` mounts it. `app.unmount(module)` undoes everything the setup registered.
 
 ```js
-import { createBus } from "nanoeffects";
-import { createCommand, createModule, modulePlugin } from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // contract — no handler yet
-const double = createCommand("math/double", (value) => value * 2); // carries its handler
+export const getUser = createCommand("user/get"); // contract — no handler yet
+```
 
-const bus = createBus();
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
+
+export const double = createCommand("math/double", (value) => value * 2); // carries its handler
+```
+
+```js
+// greeting-module.js
+import { createModule } from "nanoeffects/actions";
+import { getUser } from "./user";
+import { double } from "./math";
 
 // createModule — one feature; name is stable for hot reload replace
-const greeting = createModule("greeting", (m) => {
+export const greeting = createModule("greeting", (m) => {
   // m.on — like bus.on, removed automatically on unmount
   m.on("greet", (name) => console.log(`hello ${name}`));
 
@@ -298,9 +408,23 @@ const greeting = createModule("greeting", (m) => {
   // m.use — register a command that already has a handler, for this module’s life
   m.use(double);
 });
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { greeting } from "./greeting-module";
 
+export const bus = createBus();
 // modulePlugin — mount modules on the bus
-const app = bus.use(modulePlugin([greeting]));
+export const app = bus.use(modulePlugin([greeting]));
+```
+
+```js
+import { app, bus } from "./bus";
+import { greeting } from "./greeting-module";
+
 bus.emit("greet", "Ada"); // hello Ada
 app.unmount(greeting); // greet listener and getUser binding are gone
 ```