nanoeffects 0.14.0 → 0.15.0

package/dist/observable.d.ts

@@ -17,4 +17,33 @@ export interface Subscribable<T> {
 export type Observable<T> = Subscribable<T> & {};
 export type Observe<E extends EventMap> = <K extends Keys<E>>(event: K) => Observable<E[K]>;
 export declare const createObserve: <E extends EventMap>(bus: Bus<E>) => Observe<E>;
+/**
+ * What a `Subject` reads and writes: the `on` and `emit` of a bus. An instance
+ * of a class made by `extendBus` or `Emitter` fits as well, and its `on` keeps
+ * the subscription for `dispose()`.
+ */
+export type Source<E extends EventMap> = Pick<Bus<E>, "on" | "emit">;
+/**
+ * One event of a source as an Observable that can also push a payload back:
+ * `subscribe` is `source.on(event, …)` and `next` is `source.emit(event, payload)`.
+ * It never completes, fails or replays, and it can be extended.
+ *
+ * @example
+ * ```ts
+ * const typed = new Subject(bus, "typed"); // Subject — the event "typed" of the bus as a stream
+ * const subscription = typed.subscribe((text) => console.log(text));
+ * typed.next("hello"); // the same as bus.emit("typed", "hello")
+ * subscription.unsubscribe();
+ * ```
+ */
+export declare class Subject<E extends EventMap, K extends Keys<E>> implements Observable<E[K]> {
+  [$$observable]: () => Subscribable<E[K]>;
+  readonly source: Source<E>;
+  readonly event: K;
+  constructor(source: Source<E>, event: K);
+  subscribe(observer: Observer<E[K]>): {
+    unsubscribe(): void;
+  };
+  next(payload: E[K]): void;
+}
 //#endregion

package/dist/observable.js

@@ -1 +1 @@
-const e=typeof Symbol==`function`&&Symbol.observable||`@@observable`,t=t=>n=>({subscribe:e=>({unsubscribe:t.on(n,t=>{typeof e==`function`?e(t):e.next?.(t)})}),[e](){return this}});export{e as $$observable,t as createObserve};
+const e=typeof Symbol==`function`&&Symbol.observable||`@@observable`,t=e=>t=>{typeof e==`function`?e(t):e.next?.(t)},n=n=>r=>({subscribe:e=>({unsubscribe:n.on(r,t(e))}),[e](){return this}});var r=class{source;event;constructor(e,t){this.source=e,this.event=t,this.next=this.next.bind(this)}subscribe(e){return{unsubscribe:this.source.on(this.event,t(e))}}next(e){let t=this.source.emit;Reflect.apply(t,this.source,[this.event,e])}[e](){return this}};export{e as $$observable,r as Subject,n as createObserve};

package/dist/oop.d.ts

@@ -87,7 +87,51 @@ export declare function Once<P>(event: EventOf<P>, options: ListenerOptions): Me
 export declare function Once(event: string, wrap?: Wrap, options?: ListenerOptions): MethodDecorator<never>;
 export declare function Once(event: string, options: ListenerOptions): MethodDecorator<never>;
 //#endregion
+//#region src/oop/emitter.d.ts
+/**
+ * A base class whose every instance is an independent emitter: it has `on`,
+ * `once`, `off`, `emit`, `dispose` and its own `bus`, typed by the event map
+ * `E`. Events of one instance never reach another instance. A subscription
+ * made through `this.on` or `this.once`, a method decorated with `@On` or
+ * `@Once`, and a `Subject` made over `this` all end with `dispose()`.
+ *
+ * `on`, `once`, `off` and `emit` are bound to the instance, so they can be
+ * taken off it (`const { emit } = video`). A subclass replaces one with an
+ * arrow property; TypeScript does not let it redeclare one as a method.
+ *
+ * It has no methods of plugins, because its bus is made inside. For a bus that
+ * instances share, or for plugins, use `extendBus(bus)`.
+ *
+ * @example
+ * ```ts
+ * type VideoEvents = { "video/time": number };
+ *
+ * class VideoService extends Emitter<VideoEvents> {
+ *   constructor() {
+ *     super();
+ *     this.on("video/time", (seconds) => console.log(seconds)); // ends with dispose()
+ *   }
+ * }
+ *
+ * const video = new VideoService();
+ * video.emit("video/time", 12);
+ * video.dispose(); // its subscriptions are gone
+ * ```
+ */
+export declare class Emitter<E extends EventMap = EventMap> {
+  on: Bus<E>["on"];
+  once: Bus<E>["once"];
+  off: Bus<E>["off"];
+  emit: Bus<E>["emit"];
+  [Symbol.dispose]: () => void;
+  constructor();
+  get bus(): Bus<E>;
+  /** Removes every subscription made through `on` and `once` of this instance. */
+  dispose(): void;
+}
+//#endregion
 //#region src/oop/extend.d.ts
+declare class Empty {}
 /**
  * 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(…)`
@@ -100,6 +144,9 @@ export declare function Once(event: string, options: ListenerOptions): MethodDec
  * 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.
  *
+ * `extendBus(bus)` with no class returns a class over an empty base, to extend
+ * as it is: `class Service extends extendBus(bus) {}`.
+ *
  * @example
  * ```ts
  * class SearchServiceBase {
@@ -116,6 +163,7 @@ export declare function Once(event: string, options: ListenerOptions): MethodDec
  */
 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>;
+export declare function extendBus<B extends object>(bus: B): Extended<typeof Empty, B>;
 //#endregion
 //#region src/oop/subscriptions.d.ts
 /**

package/dist/oop.js

@@ -1 +1 @@
-import{r as e}from"./bus-Cdw5ajKF.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,o=r.once?`once`:`on`;d(e,t,o,[r.event,a,r.options])}},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)=>((...a)=>{let o=E(a);if(typeof o==`function`){let a=typeof n==`function`?n:void 0,s=typeof n==`function`?r:n??r;t.set(o,{event:e,wrap:a,once:i,options:s})}});function O(e,t,n){return D(e,t,n,!1)}function k(e,t,n){return D(e,t,n,!0)}export{O as On,k as Once,T as WithBus,p as disposeBus,w as extendBus};
+import{r as e}from"./bus-Cdw5ajKF.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`;var _=class{};const v=(e,t,n,r)=>{n in t||Object.defineProperty(e,n,{configurable:!0,enumerable:!1,...r})},y=/* @__PURE__ */ new WeakMap,b=(e,t)=>{let n=y.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 y.set(e,r),r},x=(e,t)=>(...n)=>Reflect.apply(Reflect.get(e,t),e,n),S=(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,o=r.once?`once`:`on`;d(e,t,o,[r.event,a,r.options])}},C=(e,t,n)=>{for(let r of[`on`,`once`,`off`])v(e,t,r,{get(){return b(this,n)[r]}});v(e,t,`emit`,{value:x(n,`emit`)});for(let[r,i]of Object.entries(n))typeof i==`function`&&!m.has(r)&&v(e,t,r,{value:x(n,r)});let r=function(){p(this)};v(e,t,`dispose`,{value:r}),h&&v(e,t,h,{value:r}),v(e,t,`bus`,{get:()=>n})},w=(e,t)=>{let n=function(...r){let i=Reflect.construct(t,r,new.target??n);return S(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}),C(n.prototype,t.prototype,e),n};function T(t,n){return g(t)?w(e(),t):w(t,n??_)}function E(e){return t=>e?T(e,t):T(t)}const D=e=>{let[t,n,r]=e;return typeof n==`string`||typeof n==`symbol`?Reflect.get(Object(r),`value`):t},O=(e,n,r,i)=>((...a)=>{let o=D(a);if(typeof o==`function`){let a=typeof n==`function`?n:void 0,s=typeof n==`function`?r:n??r;t.set(o,{event:e,wrap:a,once:i,options:s})}});function k(e,t,n){return O(e,t,n,!1)}function A(e,t,n){return O(e,t,n,!0)}const j=/* @__PURE__ */ new WeakMap,M=t=>{let n=j.get(t);if(n)return n;let r=e();return j.set(t,r),r},N=[`on`,`once`,`off`,`emit`],P=e=>{for(let t of N){let n=Reflect.get(e,t);Reflect.set(e,t,n.bind(e))}};var F=class{constructor(){P(this),S(this,M(this))}get bus(){return M(this)}dispose(){p(this)}};const I={on(...e){return d(this,M(this),`on`,e)},once(...e){return d(this,M(this),`once`,e)},off(...e){return f(this,M(this),e)},emit(...e){let t=M(this);return Reflect.apply(Reflect.get(t,`emit`),t,e)}};for(let e of N)Object.defineProperty(F.prototype,e,{configurable:!0,writable:!0,value:I[e]});h&&Object.defineProperty(F.prototype,h,{configurable:!0,value:function(){this.dispose()}});export{F as Emitter,k as On,A as Once,E as WithBus,p as disposeBus,T as extendBus};

package/docs/cancel-stale-requests.md

@@ -60,7 +60,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"
@@ -84,7 +84,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

package/docs/debounce-and-abort.md

@@ -25,13 +25,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.

package/docs/effects.md

@@ -124,7 +124,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,
+  }),
 });
 ```
 
@@ -147,8 +151,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, …)

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/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.

package/llms-full.txt

@@ -628,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({
@@ -734,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
 ```
@@ -1124,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"
@@ -1148,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
@@ -1204,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.
@@ -1545,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,
+  }),
 });
 ```
 
@@ -1568,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, …)
@@ -3414,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.
 
@@ -3422,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`.
 
@@ -3483,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
@@ -3527,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.
@@ -3699,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
@@ -4613,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
 ```
 
@@ -4642,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());
 
@@ -4683,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 () => {}, {
@@ -4710,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" });
@@ -4817,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({
@@ -4826,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.
@@ -4938,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`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.14.0",
+	"version": "0.15.0",
 	"description": "Cancel stale async work and fix race conditions in event handlers: a typed event bus where every handler is a task with an AbortSignal, plus latest, debounce, throttle, queue, retry, timeout and poll. About 1.4 kB gzip.",
 	"keywords": [
 		"event-bus",
@@ -226,7 +226,7 @@
 		{
 			"name": "oop (class entry)",
 			"path": "dist/oop.js",
-			"limit": "2.5 kB"
+			"limit": "2.6 kB"
 		},
 		{
 			"name": "scope (plugin and effect)",