nanoeffects 0.13.0 → 0.15.0

package/docs/plugins.md

@@ -24,7 +24,8 @@ These four cover what most apps need: shared dependencies, effects, commands and
 Every task gets the same fields on `ctx`: a store, an API client, a logger. The types come from the values. More in [Context fields](context.md).
 
 ```js
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
 
 // contextPlugin — every handler gets ctx.store
 const bus = createBus().use(contextPlugin({ store }));
@@ -41,7 +42,9 @@ import { createBus } from "nanoeffects";
 import { delay, effectsPlugin, race } from "nanoeffects/effects";
 
 // effectsPlugin — race and delay are bound to the task of each handler
-const bus = createBus().use(effectsPlugin({ race, delay }));
+const effects = effectsPlugin({ race, delay });
+
+const bus = createBus().use(effects);
 
 bus.on("load", async (id, { race, delay }) => {
   const result = await race({
@@ -147,8 +150,12 @@ With a tracer on the bus, the plugin lets a trace say which subscription began a
 import { createBus } from "nanoeffects";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
+// createTracer: sends each trace event to the logger; consoleLogger: prints one line each
+const trace = createTracer(consoleLogger());
+
 // tracePlugin — names the roots, groups and listeners of the trace
-const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+const bus = createBus({ trace })
+  .use(tracePlugin());
 
 bus.on("name/changed", saveName, { traceId: "saveNotifier" }); // a listener you can find in the log
 ```
@@ -232,7 +239,8 @@ One bus with every plugin that does not need React, in a file of its own. The ev
 
 ```js
 // bus.js
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
 import {
   commandsPlugin,
   emitterPlugin,

package/docs/stores.md

@@ -131,8 +131,9 @@ The bus, the events, the handlers and the link from the store to the bus are the
 
 ```js
 // bus.js
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
 import { emitterPlugin } from "nanoeffects/actions";
+import { contextPlugin } from "nanoeffects/context";
 import { store } from "./store";
 
 export const bus = createBus()
@@ -513,8 +514,9 @@ export const query = createValue("");
 
 ```js
 // bus.js
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
 import { emitterPlugin } from "nanoeffects/actions";
+import { contextPlugin } from "nanoeffects/context";
 import { query } from "./query";
 
 // emitterPlugin adds bus.emitter; contextPlugin puts `query` on every task as ctx.query

package/docs/tracing.md

@@ -1,6 +1,8 @@
 # Trace tasks
 
-Reference for long-lived apps that need to observe task phases, Redux DevTools, or a build without tracing. Not part of onboarding.
+Find out what your app did and why: which events were emitted, which calls a policy cancelled or dropped, which request failed. You see it in the browser console, in Redux DevTools, or in the Performance panel.
+
+Tracing is optional. A bus works the same without it, and it costs almost nothing until you turn it on. If you only want to see what happens while you develop, jump to [Show every emit](#show-every-emit) and [Configure Redux DevTools](#configure-redux-devtools); the rest of the page is for apps that need to follow a flow or turn tracing off in a build.
 
 ## Attach a tracer
 
@@ -64,7 +66,10 @@ bus.on("load", async (id, ctx) => {
 import { createBus } from "nanoeffects";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
-export const bus = createBus({ trace: createTracer(consoleLogger()) })
+// createTracer: sends each trace event to the logger; consoleLogger: prints one line each
+const trace = createTracer(consoleLogger());
+
+export const bus = createBus({ trace })
   .use(tracePlugin()); // tracePlugin: reports each emit as an event
 ```
 
@@ -93,7 +98,9 @@ import { createAction, emitterPlugin } from "nanoeffects/actions";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
 // createTracer: reports every task phase to the console
-const bus = createBus({ trace: createTracer(consoleLogger()) })
+const trace = createTracer(consoleLogger());
+
+const bus = createBus({ trace })
   .use(tracePlugin()) // tracePlugin: makes the root task that traceId names
   .use(emitterPlugin());
 
@@ -134,8 +141,12 @@ import { createBus } from "nanoeffects";
 import { createCommand } from "nanoeffects/actions";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
+// createTracer: sends each trace event to the logger; consoleLogger: prints one line each
+const trace = createTracer(consoleLogger());
+
 // tracePlugin: reads traceGroupId from the scope of a call
-const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+const bus = createBus({ trace })
+  .use(tracePlugin());
 
 // the scope names the flow; traceGroupId is for the tracer, not a field of ctx
 const pay = createCommand("checkout/pay", async () => {}, {
@@ -161,7 +172,11 @@ Give the listener a `traceId` when you register it. The plugin makes each call o
 import { createBus } from "nanoeffects";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
-const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+// createTracer: sends each trace event to the logger; consoleLogger: prints one line each
+const trace = createTracer(consoleLogger());
+
+const bus = createBus({ trace })
+  .use(tracePlugin());
 
 // traceId: the name of this listener in the trace
 bus.on("name/changed", saveName, { traceId: "saveNotifier" });
@@ -268,7 +283,10 @@ export const bus = createBus({ trace: createTracer(logger) })
 import { reduxDevtools } from "nanoeffects/trace";
 
 // debugging a race: which calls did a policy cancel or drop?
-reduxDevtools({ name: "app", policies: ["cancel", "drop"] });
+reduxDevtools({
+  name: "app",
+  policies: ["cancel", "drop"],
+});
 
 // every stage of every policy, one function for the choice
 reduxDevtools({
@@ -277,10 +295,18 @@ reduxDevtools({
 });
 
 // the old log: every stage, and the effects below the handlers
-reduxDevtools({ name: "app", policies: true, depth: 1, payload: "all" });
+reduxDevtools({
+  name: "app",
+  policies: true,
+  depth: 1,
+  payload: "all",
+});
 
 // keep the payloads out of the extension
-reduxDevtools({ name: "app", payload: "none" });
+reduxDevtools({
+  name: "app",
+  payload: "none",
+});
 ```
 
 With two quick `search` emits and a `latest` handler, the default list is `search`, `search`. With `policies: true` it adds the `latest` stages of each call, for example `search/latest/cancel` for the first one.

package/docs/typescript.md

@@ -70,8 +70,9 @@ At runtime the bus still gives the task its fields. Only the checker does not kn
 <!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
 ```ts
 // bus.ts
-import { type Context, contextPlugin, createBus, type EventsOf } from "nanoeffects";
+import { type Context, createBus, type EventsOf } from "nanoeffects";
 import { modulePlugin } from "nanoeffects/actions";
+import { contextPlugin } from "nanoeffects/context";
 import { effectsPlugin, race } from "nanoeffects/effects";
 
 // Events: event name → payload; nothing about ctx is written here

package/llms-full.txt

@@ -559,6 +559,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
 | `nanoeffects/actions` | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin`, `commandsPlugin` |
 | `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events |
+| `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value |
 | `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` |
 | `nanoeffects/oop` | `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` |
 | `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one command, action, job, module or `emit` (the types `Scope`, `Effect`) |
@@ -609,7 +610,8 @@ These four cover what most apps need: shared dependencies, effects, commands and
 Every task gets the same fields on `ctx`: a store, an API client, a logger. The types come from the values. More in [Context fields](context.md).
 
 ```js
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
 
 // contextPlugin — every handler gets ctx.store
 const bus = createBus().use(contextPlugin({ store }));
@@ -626,7 +628,9 @@ import { createBus } from "nanoeffects";
 import { delay, effectsPlugin, race } from "nanoeffects/effects";
 
 // effectsPlugin — race and delay are bound to the task of each handler
-const bus = createBus().use(effectsPlugin({ race, delay }));
+const effects = effectsPlugin({ race, delay });
+
+const bus = createBus().use(effects);
 
 bus.on("load", async (id, { race, delay }) => {
   const result = await race({
@@ -732,8 +736,12 @@ With a tracer on the bus, the plugin lets a trace say which subscription began a
 import { createBus } from "nanoeffects";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
+// createTracer: sends each trace event to the logger; consoleLogger: prints one line each
+const trace = createTracer(consoleLogger());
+
 // tracePlugin — names the roots, groups and listeners of the trace
-const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+const bus = createBus({ trace })
+  .use(tracePlugin());
 
 bus.on("name/changed", saveName, { traceId: "saveNotifier" }); // a listener you can find in the log
 ```
@@ -817,7 +825,8 @@ One bus with every plugin that does not need React, in a file of its own. The ev
 
 ```js
 // bus.js
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
 import {
   commandsPlugin,
   emitterPlugin,
@@ -1121,7 +1130,7 @@ const bus = createBus(); // the bus: events and handlers
 // latest: a newer search aborts the request in flight
 const searchLatest = latest(async (query, { signal }) => {
   const items = await api.search(query, { signal });
-  bus.emit("results", items);
+  render(items);
 });
 
 // debounce: run after 300 ms without a new "typed"
@@ -1145,7 +1154,11 @@ const searchOnce = timeout(5000, (query, { signal }) => api.search(query, { sign
 // retry: up to 4 attempts, backoff makes the pause longer each time
 const searchWithRetry = retry(searchOnce, {
   times: 4,
-  delay: backoff({ base: 200, max: 5000, jitter: true }),
+  delay: backoff({
+    base: 200,
+    max: 5000,
+    jitter: true,
+  }),
 });
 
 // latest: a newer search aborts the whole retry chain
@@ -1201,13 +1214,11 @@ const bus = createBus(); // the bus: events and handlers
 const searchLatest = latest(async (query, { signal }) => {
   // signal: pass it on so the browser cancels the request itself
   const items = await api.search(query, { signal });
-  bus.emit("results", items);
+  render(items);
 });
 
 // debounce: run searchLatest after 300 ms without a new "typed"
 bus.on("typed", debounce(300, searchLatest));
-
-bus.on("results", (items) => render(items));
 ```
 
 What to replace: `api.search` is your own request function. It must accept `{ signal }` and give it to `fetch`. `render` shows the items.
@@ -1542,7 +1553,11 @@ import { backoff, retry } from "nanoeffects/effects";
 const loadWithRetry = retry(loadUser, {
   times: 5,
   // backoff — pause 200, 400, 800, … ms, never over 5 s, a random part of it
-  delay: backoff({ base: 200, max: 5000, jitter: true }),
+  delay: backoff({
+    base: 200,
+    max: 5000,
+    jitter: true,
+  }),
 });
 ```
 
@@ -1565,8 +1580,11 @@ If handlers call the same helpers often, put them on the task once. A handler th
 import { createBus } from "nanoeffects";
 import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
 
-// effectsPlugin — add race, all and delay to the context of every task; returns the same bus
-const bus = createBus().use(effectsPlugin({ race, all, delay }));
+// effectsPlugin — add race, all and delay to the context of every task
+const effects = effectsPlugin({ race, all, delay });
+
+// use returns the same bus, typed with the new fields
+const bus = createBus().use(effects);
 
 bus.on("load", async (id, { race, all, delay }) => {
   // race — same as race(ctx, …)
@@ -2189,8 +2207,9 @@ The bus, the events, the handlers and the link from the store to the bus are the
 
 ```js
 // bus.js
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
 import { emitterPlugin } from "nanoeffects/actions";
+import { contextPlugin } from "nanoeffects/context";
 import { store } from "./store";
 
 export const bus = createBus()
@@ -2571,8 +2590,9 @@ export const query = createValue("");
 
 ```js
 // bus.js
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
 import { emitterPlugin } from "nanoeffects/actions";
+import { contextPlugin } from "nanoeffects/context";
 import { query } from "./query";
 
 // emitterPlugin adds bus.emitter; contextPlugin puts `query` on every task as ctx.query
@@ -3101,10 +3121,11 @@ To give fields to **one** command, action, job or module, or to replace them for
 
 ## Type the fields (optional)
 
-In TypeScript, `contextPlugin` puts the fields on every task of **this** bus and takes their types from the value you pass. The event map holds only events. It does not wire anything across the app — another bus can have different fields or none.
+In TypeScript, `contextPlugin` (from `nanoeffects/context`) puts the fields on every task of **this** bus and takes their types from the value you pass. The event map holds only events. It does not wire anything across the app — another bus can have different fields or none.
 
 ```ts
-import { contextPlugin, createBus } from "nanoeffects";
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
 
 // Events — event name → payload
 type Events = { save: Draft };
@@ -3408,7 +3429,12 @@ Source: docs/oop.md
 
 # 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.
+Use this page when **your domain logic lives in classes**: a service, a store or a controller that needs the bus inside its methods. There are two ways to give a class the methods of a bus, and both remember what each instance subscribed to, so `dispose()` ends it all:
+
+| You want | Use |
+| -------- | --- |
+| every `new Service()` to be an independent emitter | `extends Emitter` |
+| the instances to share a bus, or to use plugins | `extends extendBus(bus)` |
 
 If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-modules): a module is the same idea without a class.
 
@@ -3416,7 +3442,68 @@ If your logic is plain functions, stay with [modules](actions.md#mount-domains-w
 
 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
+## Make an independent emitter with `Emitter`
+
+`Emitter` is a base class. Every instance of a class that extends it has a bus of its own: the events of one instance never reach another. It is the shape of Node's `EventEmitter`.
+
+```js
+// video-service.js
+import { Emitter } from "nanoeffects/oop";
+
+// Emitter — a base class: each new VideoService() gets on, once, off, emit, dispose and its own bus
+export class VideoService extends Emitter {
+  constructor() {
+    super();
+    // this.on — a subscription of this instance; dispose() removes it
+    this.on("played", () => console.log("playing"));
+  }
+}
+```
+
+```js
+import { VideoService } from "./video-service";
+
+const first = new VideoService();
+const second = new VideoService();
+first.on("paused", () => console.log("first paused"));
+second.emit("paused"); // nothing: the instances do not share a bus
+first.emit("paused"); // logs "first paused"
+first.dispose(); // its subscriptions are gone
+```
+
+What you get:
+
+- `on`, `once`, `off`, `emit`, `dispose` and `bus` (the bus of that instance). `instance[Symbol.dispose]()` does the same as `dispose()`, so `using video = new VideoService()` works where the runtime supports it.
+- `@On` and `@Once` work on its methods (see below). They are subscribed when the base constructor runs, so before the fields of your subclass.
+- `on`, `once`, `off` and `emit` are bound to the instance, so `const { emit } = video` works. A subclass replaces one with an arrow property (`emit = (…) => …`); TypeScript does not let it redeclare one as a method. `dispose` is a method and can be overridden as usual.
+- No methods of plugins: the bus is made inside, so no plugin is on it. For plugins, or for a bus that several instances or classes share, use `extendBus` (next sections).
+- For a stream of one event, see [`Subject`](observable.md#read-and-write-one-event-with-a-subject) and [Stream an event with a `Subject`](#stream-an-event-with-a-subject).
+
+### Type the events (optional)
+
+`Emitter` takes the events of the class as a type parameter.
+
+```ts
+// video-service.ts
+import { Emitter } from "nanoeffects/oop";
+
+// VideoEvents — checker only: the payload of each event of this class
+type VideoEvents = { "video/time": number; "video/paused": void };
+
+export class VideoService extends Emitter<VideoEvents> {
+  constructor() {
+    super();
+    // seconds is a number because "video/time" carries one
+    this.on("video/time", (seconds) => console.log(seconds));
+  }
+}
+
+const video = new VideoService();
+video.emit("video/time", 12); // checked against VideoEvents
+video.emit("video/paused"); // no payload
+```
+
+## Give a class the methods of a shared 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`.
 
@@ -3477,9 +3564,33 @@ What you get:
 - `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.
 
+### Extend the result with no class of your own
+
+`extendBus(bus)` without a class returns a class with the methods of that bus and nothing else. Extend it as it is.
+
+```js
+// service.js
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
+
+const bus = createBus(); // the bus that the services share
+
+// extendBus(bus) — a class with on, once, off, emit and dispose over this bus
+export class AudioService extends extendBus(bus) {
+  constructor() {
+    super();
+    this.on("muted", () => console.log("muted")); // ends with dispose()
+  }
+}
+
+const audio = new AudioService();
+bus.emit("muted"); // the instances share this bus: logs "muted"
+audio.dispose();
+```
+
 ## Let the class make its bus
 
-Leave the bus out and the class gets its own, shared by all of its instances.
+Leave the bus out and the class gets its own, shared by all of its instances. That is one bus for each class; `Emitter` makes one for each instance.
 
 ```js
 // notifier.js
@@ -3521,6 +3632,37 @@ 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.
 
+## Stream an event with a `Subject`
+
+Problem: a service hands one of its events to code written for streams, and the stream subscription should end with the service. `createObserve(this.bus)` would not: it subscribes through the bus, so `dispose()` does not know it.
+
+Pass `this` to `Subject` as the source. The subject subscribes through `this.on`, so the subscription belongs to the instance ([Read and write one event with a Subject](observable.md#read-and-write-one-event-with-a-subject)).
+
+```js
+// typing.js
+import { createBus } from "nanoeffects";
+import { Subject } from "nanoeffects/observable";
+import { extendBus } from "nanoeffects/oop";
+
+const bus = createBus(); // the bus: events and handlers
+
+class TypingBase {
+  constructor() {
+    this.typed = new Subject(this, "typed"); // Subject — the event "typed" as a stream; this is the source
+    this.typed.subscribe((text) => console.log(text));
+  }
+}
+
+const Typing = extendBus(bus, TypingBase); // extendBus — a class with on, emit and dispose
+
+const typing = new Typing();
+typing.typed.next("a"); // logs "a"
+typing.dispose(); // ends the subscription of the Subject too
+typing.typed.next("b"); // nothing is logged
+```
+
+In TypeScript, declare `on` and `emit` in the class (`declare on: BusMethods<typeof bus>["on"]`, see [Type the instances](#type-the-instances-optional)) so that `this` fits as the source.
+
 ## 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.
@@ -3693,7 +3835,8 @@ service.emit("order/placed", { id: "o1" }); // checked against Events
 
 - `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.
+- `Emitter` has no methods of plugins, because its bus is made inside. Use `extendBus(bus)` for them.
+- Mixing the methods into an object that exists, and decorators for fields or parameters are not part of this entry.
 
 ---
 Source: docs/typescript.md
@@ -3770,8 +3913,9 @@ At runtime the bus still gives the task its fields. Only the checker does not kn
 <!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
 ```ts
 // bus.ts
-import { type Context, contextPlugin, createBus, type EventsOf } from "nanoeffects";
+import { type Context, createBus, type EventsOf } from "nanoeffects";
 import { modulePlugin } from "nanoeffects/actions";
+import { contextPlugin } from "nanoeffects/context";
 import { effectsPlugin, race } from "nanoeffects/effects";
 
 // Events: event name → payload; nothing about ctx is written here
@@ -4540,7 +4684,9 @@ Source: docs/tracing.md
 
 # Trace tasks
 
-Reference for long-lived apps that need to observe task phases, Redux DevTools, or a build without tracing. Not part of onboarding.
+Find out what your app did and why: which events were emitted, which calls a policy cancelled or dropped, which request failed. You see it in the browser console, in Redux DevTools, or in the Performance panel.
+
+Tracing is optional. A bus works the same without it, and it costs almost nothing until you turn it on. If you only want to see what happens while you develop, jump to [Show every emit](#show-every-emit) and [Configure Redux DevTools](#configure-redux-devtools); the rest of the page is for apps that need to follow a flow or turn tracing off in a build.
 
 ## Attach a tracer
 
@@ -4604,7 +4750,10 @@ bus.on("load", async (id, ctx) => {
 import { createBus } from "nanoeffects";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
-export const bus = createBus({ trace: createTracer(consoleLogger()) })
+// createTracer: sends each trace event to the logger; consoleLogger: prints one line each
+const trace = createTracer(consoleLogger());
+
+export const bus = createBus({ trace })
   .use(tracePlugin()); // tracePlugin: reports each emit as an event
 ```
 
@@ -4633,7 +4782,9 @@ import { createAction, emitterPlugin } from "nanoeffects/actions";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
 // createTracer: reports every task phase to the console
-const bus = createBus({ trace: createTracer(consoleLogger()) })
+const trace = createTracer(consoleLogger());
+
+const bus = createBus({ trace })
   .use(tracePlugin()) // tracePlugin: makes the root task that traceId names
   .use(emitterPlugin());
 
@@ -4674,8 +4825,12 @@ import { createBus } from "nanoeffects";
 import { createCommand } from "nanoeffects/actions";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
+// createTracer: sends each trace event to the logger; consoleLogger: prints one line each
+const trace = createTracer(consoleLogger());
+
 // tracePlugin: reads traceGroupId from the scope of a call
-const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+const bus = createBus({ trace })
+  .use(tracePlugin());
 
 // the scope names the flow; traceGroupId is for the tracer, not a field of ctx
 const pay = createCommand("checkout/pay", async () => {}, {
@@ -4701,7 +4856,11 @@ Give the listener a `traceId` when you register it. The plugin makes each call o
 import { createBus } from "nanoeffects";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
-const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+// createTracer: sends each trace event to the logger; consoleLogger: prints one line each
+const trace = createTracer(consoleLogger());
+
+const bus = createBus({ trace })
+  .use(tracePlugin());
 
 // traceId: the name of this listener in the trace
 bus.on("name/changed", saveName, { traceId: "saveNotifier" });
@@ -4808,7 +4967,10 @@ export const bus = createBus({ trace: createTracer(logger) })
 import { reduxDevtools } from "nanoeffects/trace";
 
 // debugging a race: which calls did a policy cancel or drop?
-reduxDevtools({ name: "app", policies: ["cancel", "drop"] });
+reduxDevtools({
+  name: "app",
+  policies: ["cancel", "drop"],
+});
 
 // every stage of every policy, one function for the choice
 reduxDevtools({
@@ -4817,10 +4979,18 @@ reduxDevtools({
 });
 
 // the old log: every stage, and the effects below the handlers
-reduxDevtools({ name: "app", policies: true, depth: 1, payload: "all" });
+reduxDevtools({
+  name: "app",
+  policies: true,
+  depth: 1,
+  payload: "all",
+});
 
 // keep the payloads out of the extension
-reduxDevtools({ name: "app", payload: "none" });
+reduxDevtools({
+  name: "app",
+  payload: "none",
+});
 ```
 
 With two quick `search` emits and a `latest` handler, the default list is `search`, `search`. With `policies: true` it adds the `latest` stages of each call, for example `search/latest/cancel` for the first one.
@@ -4929,6 +5099,56 @@ bus.on(queryChanged, (query) => console.log("search for", query));
 
 The Observable can come from anywhere, not only from `createObserve`. `subscription.unsubscribe()` stops it; the bus does not know about it. Pass the callback to `subscribe` as it is, and do not call `bus.emitter(...)` inside the operators on every value.
 
+## Read and write one event with a Subject
+
+Problem: `createObserve` only reads. Code written for streams often also needs to push a value into the same event, and passing a bus and an event name around for that is clumsy.
+
+`Subject` is one event of a bus as one object. `subscribe` listens, `next` emits. It has no `complete`, no `error` and no replay: an event of a bus does not end, and the bus keeps no values.
+
+```js
+import { createBus } from "nanoeffects";
+import { Subject } from "nanoeffects/observable";
+
+const bus = createBus(); // the bus: events and handlers
+
+const typed = new Subject(bus, "typed"); // Subject — the event "typed" as a stream you can also write to
+
+const subscription = typed.subscribe((text) => console.log(text)); // like bus.on("typed", …)
+typed.next("hello"); // like bus.emit("typed", "hello"): bus.on handlers and subscribers both run
+subscription.unsubscribe(); // removes this subscription only
+```
+
+- `next` works when you take it off the subject, so `input.addEventListener("input", (event) => typed.next(event.target.value))` and `store.subscribe(typed.next)` need no wrapper.
+- A subscriber that is added later does not get a value emitted before. Add `startWith` or `shareReplay` in RxJS when it should.
+- RxJS takes a `Subject` as it takes `createObserve`: `from(typed)`. It is not an RxJS `Subject` (no `error`, `complete` or `pipe`), so it does not fit where that type is wanted.
+
+### Extend it for a named stream
+
+Problem: the event name is repeated wherever the stream is made. A subclass fixes it once.
+
+```js
+import { createBus } from "nanoeffects";
+import { Subject } from "nanoeffects/observable";
+
+class TypedText extends Subject {
+  constructor(bus) {
+    super(bus, "typed"); // the event is fixed by the class
+  }
+
+  next(text) {
+    super.next(text.trim()); // a method of the subclass replaces the one of Subject
+  }
+}
+
+const bus = createBus(); // the bus: events and handlers
+const typed = new TypedText(bus);
+typed.next("  hello "); // emits "typed" with "hello"
+```
+
+### Use it inside a class with a bus
+
+A class made with `extendBus` has its own `on` and `emit`. Pass `this` as the source and the subscription belongs to the instance, so `dispose()` ends it ([Classes with a bus](oop.md)).
+
 ## Do the work in a handler, not in `switchMap`
 
 An Observable is good for shaping values. A request is better in a handler with a policy, because the handler has a `signal` and the trace shows it. Split it: RxJS ends at the value, the bus starts the work.

package/llms.txt

@@ -36,7 +36,7 @@ Rules that generated code often gets wrong:
 - [Build a sign-up form in React](docs/react.md): a form with a username check, a submit that cannot fire twice, and retry; `usePolicy` keeps a debounced handler between renders
 - [Context fields](docs/context.md): put a store or client on every task
 - [Scopes](docs/scope.md): fields for one command, action, job, module or `emit`, and a way to replace them in a test
-- [Use the bus from a class](docs/oop.md): `extendBus`, `@WithBus`, `@On`, `@Once`, and `dispose()` for the subscriptions of an instance
+- [Use the bus from a class](docs/oop.md): `Emitter`, `extendBus`, `@WithBus`, `@On`, `@Once`, and `dispose()` for the subscriptions of an instance
 
 ## TypeScript
 
@@ -53,5 +53,5 @@ Rules that generated code often gets wrong:
 
 - [Semantics](docs/semantics.md): exact rules of emit, abort and ordering
 - [Trace tasks](docs/tracing.md): loggers, Redux DevTools, the `notrace` build
-- [Turn events into Observables](docs/observable.md): `createObserve`
+- [Turn events into Observables](docs/observable.md): `createObserve`, `Subject`
 - [Hot reload and development diagnostics](docs/hmr.md): `devPlugin`