nanoeffects 0.6.0 → 0.8.0

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
 ```

package/docs/hmr.md

@@ -21,7 +21,7 @@ A `bus.on` outside a module returns the function that unsubscribes: hand it to t
 
 ## Report leaks with `devPlugin`
 
-`bus.use(devPlugin({ app }))` reports what is easy to miss while developing:
+`bus.use(devPlugin())` reports what is easy to miss while developing:
 
 ```js
 import { createBus } from "nanoeffects";
@@ -29,13 +29,14 @@ import { modulePlugin } from "nanoeffects/actions";
 import { devPlugin } from "nanoeffects/dev";
 
 const bus = createBus();
-const app = bus.use(modulePlugin([userModule]));
+bus.use(modulePlugin([userModule]));
 // devPlugin — warn on piled-up listeners; log module mount/replace/unmount
-bus.use(devPlugin({ app }));
+// (it finds the app of modulePlugin on the bus, in either order of the two)
+bus.use(devPlugin());
 ```
 
 - **Listeners that pile up.** When more than `maxListeners` (default `10`) listeners of one event were added and not unsubscribed, one warning names the event and the count. The count follows the function that `on` returns; `bus.off(event, fn)` is not seen.
-- **Modules.** With `app` it logs `module "user" mounted`, `replaced` when a module of the same name was mounted, and `unmounted`. Only what goes through `app.mount` and `app.unmount` is reported, not sub-modules.
+- **Modules.** For the app of `modulePlugin` (or the `app` option) it logs `module "user" mounted`, `replaced` when a module of the same name was mounted, and `unmounted`. Only what goes through `app.mount` and `app.unmount` is reported, not sub-modules.
 - **Options.** `leaks: false` and `modules: false` switch a diagnostic off; `maxListeners` sets the limit; `log` receives the messages instead of the console.
 - **Disconnect.** `bus.use(devPlugin(...))` returns the function that stops the diagnostics and puts `bus.on` and `app.mount` back.
 
@@ -43,6 +44,6 @@ It changes no behavior: it wraps `bus.on`, `app.mount`, and `app.unmount` and ad
 
 ### Keep the import in production
 
-`nanoeffects/dev` is a no-op in a production build. `package.json` maps it to an empty build under the `production` export condition (Vite and webpack set that in production mode), so `bus.use(devPlugin({ app }))` can stay without a guard: it touches nothing and costs a few bytes.
+`nanoeffects/dev` is a no-op in a production build. `package.json` maps it to an empty build under the `production` export condition (Vite and webpack set that in production mode), so `bus.use(devPlugin())` can stay without a guard: it touches nothing and costs a few bytes.
 
 If you want even the call gone, guard it (`if (import.meta.env.DEV)` in Vite). An app that does not import the entry does not carry it.

package/docs/migrating-from-effector.md

@@ -73,16 +73,26 @@ The store (`$items`) is not here. Keep it in Effector and update it from the `fo
 
 Without Effector, something must hold `$items`. A Zustand store does it: `create` replaces `createStore`, and `setState` replaces `.on(searchFx.doneData, …)`. The handler writes the result to the store directly, so the `found` event is not needed. A component reads the store with a selector, as `useUnit($items)` did.
 
-```jsx
-// search-zustand.jsx
-import { create } from "zustand";
+```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { debounce, latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus: only the bus
+```
+
+```js
+// search-store.js
+import { create } from "zustand";
 
 // create — Zustand: the store replaces $items
-const useSearchStore = create(() => ({ items: [] }));
+export const useSearchStore = create(() => ({ items: [] }));
+```
 
-const bus = createBus(); // the bus: events and handlers
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { useSearchStore } from "./search-store";
 
 // latest — a newer query aborts the request in flight; debounce — wait 300 ms of quiet
 const search = latest(async (query, { signal }) => {
@@ -91,6 +101,12 @@ const search = latest(async (query, { signal }) => {
 });
 
 bus.on("query-changed", debounce(300, search));
+```
+
+```jsx
+// Search.jsx
+import { bus } from "./bus";
+import { useSearchStore } from "./search-store";
 
 export function Search() {
   const items = useSearchStore((state) => state.items); // Zustand: a selector reads items
@@ -166,13 +182,18 @@ formSubmitted.watch((event) => {
 });
 ```
 
-The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus, in its own file:
+The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus and the handler, each in its own file:
 
 ```js
-// form-bus.js
+// bus.js
 import { createBus } from "nanoeffects";
 
-export const bus = createBus(); // the bus: events and their handlers
+export const bus = createBus(); // the bus: only the bus
+```
+
+```js
+// form-handlers.js
+import { bus } from "./bus";
 
 // bus.on — the job of sendFormFx: runs when the form is submitted
 bus.on("form/submitted", (values) => {
@@ -185,7 +206,8 @@ Then the form. `useState` does the work of `$form`, `fieldUpdate` and `prepend`;
 ```jsx
 // App.jsx
 import { useState } from "react";
-import { bus } from "./form-bus"; // the bus of the previous snippet
+import { bus } from "./bus"; // the bus of the previous snippet
+import "./form-handlers"; // registers the handler; the app does this once, when it starts
 
 function Field({ name, type, label, value, onChange }) {
   return (
@@ -255,16 +277,27 @@ Retrying a failed network request, and cancelling when the form closes, are in [
 
 Keep the Effector stores, and run the effects on the bus. A store calls the bus through `bus.emitter`, and the handler sends the result back as an event that the store listens to.
 
-<!-- docs-check: skip - needs effector, which the project does not depend on -->
 ```js
-import { createEvent, createStore } from "effector";
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { latest } from "nanoeffects/policies";
+import { emitterPlugin } from "nanoeffects/actions";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
 
-const queryChanged = createAction("query/changed"); // a plain action creator
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("query/changed"); // a plain action creator
+```
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+import { createEvent, createStore } from "effector";
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
 
 const found = createEvent(); // Effector: the result comes back as an event
 const $items = createStore([]).on(found, (_, items) => items);

package/docs/migrating-from-rxjs.md

@@ -90,16 +90,27 @@ Keep RxJS where a stream is how you think, and let events cross to the bus in ei
 
 **RxJS to bus.** `bus.emitter(action)` returns a callback that emits the action, so it is the argument of `subscribe` ([Stores](stores.md) has the plugin).
 
-<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
 ```js
-import { combineLatest } from "rxjs";
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { latest } from "nanoeffects/policies";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// filters.js
+import { createAction } from "nanoeffects/actions";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+export const filtersChanged = createAction("filters/changed"); // a plain action creator
+```
 
-const filtersChanged = createAction("filters/changed"); // a plain action creator
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { combineLatest } from "rxjs";
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { filtersChanged } from "./filters";
 
 // RxJS: combine two streams into one value; nanoeffects does not do that
 const subscription = combineLatest([query$, category$]).subscribe(

package/docs/oop.md

@@ -0,0 +1,286 @@
+# Use the bus from a class
+
+Use this page when **your domain logic lives in classes**: a service, a store or a controller that needs the bus inside its methods. A class made with `extendBus` has `on`, `emit` and the other methods of the bus, and remembers what each instance subscribed to, so `dispose()` ends it all.
+
+If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-modules): a module is the same idea without a class.
+
+## The problem without it
+
+A class that listens to the bus keeps a reference to it, and keeps every unsubscribe function in a list to call when the object goes away. Forget one and the old object keeps handling events. `extendBus` does both for you.
+
+## Give a class the methods of a bus
+
+`extendBus(bus, Base)` returns a subclass of `Base`. Its instances have the methods of the bus, and the arguments of `new` go to the constructor of `Base`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus that the services of the app share
+export const bus = createBus();
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — the events of the search domain
+export const queryChanged = createAction("search/query-changed");
+export const resultsLoaded = createAction("search/results-loaded");
+```
+
+```js
+// search-service.js
+import { extendBus } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged, resultsLoaded } from "./search";
+
+class SearchServiceBase {
+  constructor(api) {
+    this.api = api;
+    // this.on — a subscription of this instance; dispose() removes it
+    this.on(queryChanged, (query, ctx) => this.search(query, ctx)); // an arrow keeps this
+  }
+
+  async search(query, { signal, emit }) {
+    const items = await this.api.search(query, { signal });
+    emit(resultsLoaded(items));
+  }
+}
+
+// extendBus — a subclass whose instances have on, once, off, emit and dispose
+export const SearchService = extendBus(bus, SearchServiceBase);
+```
+
+```js
+import { queryChanged } from "./search";
+import { SearchService } from "./search-service";
+
+const service = new SearchService(api); // the arguments go to SearchServiceBase
+service.emit(queryChanged("nano")); // the same bus as bus.emit
+service.dispose(); // its subscriptions are gone
+```
+
+What you get:
+
+- The class keeps the name of `Base`, and its instances are instances of `Base`.
+- `on`, `once`, `off` and `emit` act on the bus. They can be destructured: `const { emit } = service`.
+- The other methods of the bus, such as `emitter` from [`emitterPlugin`](plugins.md), are there too. Only the plugins used **before** `extendBus` count: the names are taken when it runs.
+- `bus` is the bus, and `Class.bus` is the same one.
+- `this.on` works in the constructor of `Base`. The methods exist on the prototype of the subclass, which is the prototype of the instance already.
+
+## Let the class make its bus
+
+Leave the bus out and the class gets its own, shared by all of its instances.
+
+```js
+// notifier.js
+import { extendBus } from "nanoeffects/oop";
+
+class NotifierBase {}
+
+// extendBus without a bus — a new bus for this class; two classes have two buses
+export const Notifier = extendBus(NotifierBase);
+
+const first = new Notifier();
+const second = new Notifier();
+second.on("notified", (message) => console.log(message));
+first.emit("notified", "hello"); // the instances share Notifier.bus
+```
+
+Pass a bus when you need plugins (`contextPlugin`, `scopePlugin`) or when several classes talk to each other.
+
+## End the subscriptions with `dispose`
+
+`dispose()` removes every subscription made through `this.on` and `this.once` of that instance, and nothing else. It is safe to call twice. `instance[Symbol.dispose]()` does the same, so `using service = new SearchService(api)` works where the runtime supports it.
+
+```js
+// dispose.js
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
+
+const bus = createBus();
+const Service = extendBus(bus, class {});
+
+const service = new Service();
+const stop = service.on("ping", () => console.log("service heard it"));
+bus.on("ping", () => console.log("the bus heard it")); // not a subscription of the service
+
+service.dispose();
+bus.emit("ping"); // only "the bus heard it"
+stop(); // the function on returned still works, and does nothing now
+```
+
+A subscription that you removed yourself (the function `on` returned, `this.off`, or a `once` that fired) is forgotten, so the instance holds nothing for it.
+
+## Keep a method of your own
+
+The class wins any clash of names. If `Base` has `emit`, `dispose`, `on` or `bus`, yours stays and the bus method is not added. A `Base` with its own `dispose` would never end the subscriptions, so call `disposeBus(this)` from there.
+
+```js
+// cache.js
+import { createBus } from "nanoeffects";
+import { disposeBus, extendBus } from "nanoeffects/oop";
+
+const bus = createBus();
+
+class CacheBase {
+  dispose() {
+    this.items.clear(); // your own cleanup
+    disposeBus(this); // disposeBus — ends the subscriptions of this instance
+  }
+
+  items = new Map();
+}
+
+export const Cache = extendBus(bus, CacheBase);
+```
+
+`disposeBus` does nothing for a value that is not an instance of such a class.
+
+## Subscribe a method with `@On` and `@Once`
+
+A decorator turns a method into a handler of an event for each instance, with `this` bound. You write no `this.on` in the constructor, and `dispose()` ends the subscription too.
+
+The bus and the events are the same as above, in TypeScript:
+
+```ts
+// bus.ts
+import { createBus } from "nanoeffects";
+
+export const bus = createBus();
+```
+
+```ts
+// search.ts
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction<string>("search/query-changed");
+export const resultsLoaded = createAction<string[]>("search/results-loaded");
+```
+
+```ts
+// search-service.ts
+import { latest } from "nanoeffects/policies";
+import { extendBus, On, Once } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged, resultsLoaded } from "./search";
+
+class SearchServiceBase {
+  // On — this method handles queryChanged for each instance, this is the instance;
+  // latest — each new query aborts the one before it
+  @On(queryChanged, latest)
+  async search(query: string, { signal, emit }: { signal: AbortSignal; emit: (event: unknown) => void }) {
+    const items = await api.search(query, { signal });
+    emit(resultsLoaded(items));
+  }
+
+  // Once — runs for the first event only
+  @Once("search/ready")
+  ready() {
+    console.log("first ready");
+  }
+}
+
+export const SearchService = extendBus(bus, SearchServiceBase);
+```
+
+Things to know:
+
+- The event is a name, an action creator or a command, as for `bus.on`. For a creator or a command the payload of the method is checked against it.
+- The second argument, `wrap`, takes the bound handler and returns the one to subscribe: `latest`, or `(handler) => debounce(300, handler)`. A policy needs it: `latest(this.search)` wraps the function without `this`, and the bound handler is what `wrap` gets.
+- The subscriptions are made right after the constructor of `Base`. An event that is emitted inside that constructor does not reach them.
+- A subclass inherits them. A method that a subclass overrides is subscribed only if the override is decorated.
+- On a class that `extendBus` did not make, a decorator does nothing.
+- Both the decorators of the language and `experimentalDecorators` work. Your compiler has to support the one you use: TypeScript 5 or newer for the first, and the `experimentalDecorators` option for the second.
+
+## Decorate the class with `@WithBus`
+
+`@WithBus(bus)` does what `extendBus(bus, Base)` does, as a class decorator. `@WithBus()` makes a bus for the class.
+
+<!-- docs-check: continue -->
+
+```ts
+// search-service.ts
+import { type BusMethods, On, WithBus } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+
+// TypeScript does not change the type of a decorated class, so say what it gets;
+// checker only: at run time WithBus already adds the methods
+interface SearchService extends BusMethods<typeof bus> {}
+
+// WithBus — replaces the class by extendBus(bus, SearchService)
+@WithBus(bus)
+class SearchService {
+  @On(queryChanged)
+  search(query: string) {
+    console.log(query);
+  }
+}
+
+export { SearchService };
+```
+
+Prefer `extendBus(bus, Base)` when you can: its types come from the call and need no `interface`.
+
+## Pass a method by hand
+
+A handler given to `this.on` is called as the bus calls it, with no `this`. A method passed bare loses `this`, as in plain JavaScript:
+
+```js
+// handlers.js
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
+
+class BaseWithHandler {
+  name = "handler";
+
+  handle() {
+    console.log(this?.name);
+  }
+
+  listen() {
+    this.on("ping", this.handle); // this is lost: prints undefined
+    this.on("ping", () => this.handle()); // an arrow keeps it
+  }
+}
+
+export const Listener = extendBus(createBus(), BaseWithHandler);
+```
+
+Use an arrow or a decorated method. The library does not bind `this` for you: a policy such as `latest(this.handle)` wraps the function, so binding would work in half of the cases.
+
+## Type the instances (optional)
+
+`extendBus` returns a class that takes the arguments of `Base`, and its instances are `Base` plus `BusMethods<typeof bus>`: the function members of the bus (`on`, `emit`, and those of plugins used before) with `dispose` and `bus`. A member of `Base` with the same name keeps its own type.
+
+```ts
+// service.ts
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
+
+type Events = { "order/placed": { id: string } };
+
+// Events — checker only: the payloads of the bus
+const bus = createBus<Events>();
+
+class OrderServiceBase {
+  name: string;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+export const OrderService = extendBus(bus, OrderServiceBase);
+
+const service = new OrderService("main"); // the constructor of OrderServiceBase
+service.emit("order/placed", { id: "o1" }); // checked against Events
+```
+
+## What is not done
+
+- `this` is not bound in a handler that you pass by hand (see above).
+- The methods of a plugin used after `extendBus` are not on the class. Use the plugins first, then `extendBus`.
+- One bus for each instance, mixing the methods into an object that exists, and decorators for fields or parameters are not part of this entry.