nanoeffects 0.14.0 → 0.16.0

package/docs/observable.md

@@ -70,6 +70,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/docs/oop.md

@@ -1,6 +1,11 @@
 # 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.
 
@@ -8,7 +13,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`.
 
@@ -69,9 +135,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
@@ -113,6 +203,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.
@@ -285,4 +406,5 @@ 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.

package/docs/package.md

@@ -11,10 +11,10 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `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/oop` | `Emitter`, `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`) |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
-| `nanoeffects/observable` | `createObserve` |
+| `nanoeffects/observable` | `createObserve`, `Subject` |
 | `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
 | `nanoeffects/dev` | `devPlugin` (no-op in production) |
 | `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) |

package/docs/plugins.md

@@ -42,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({
@@ -148,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
 ```

package/docs/tracing.md

@@ -66,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
 ```
 
@@ -95,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());
 
@@ -136,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 () => {}, {
@@ -163,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" });
@@ -270,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({
@@ -279,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.
@@ -290,7 +314,7 @@ With two quick `search` emits and a `latest` handler, the default list is `searc
 ### Write your own logger
 
 ```ts
-import type { TraceLogger } from "nanoeffects";
+import type { TraceLogger } from "nanoeffects/trace";
 
 const errorsOnly = (): TraceLogger => (event) => {
   if (event.phase === "error") {