nanoeffects 0.7.0 → 0.9.0

package/docs/motivation.md

@@ -0,0 +1,41 @@
+# Why nanoeffects exists
+
+Read this page if you build an SDK, a core library or a micro-frontend shell and wonder why you would pick a new event bus. It explains the constraints the library was made for. It does not teach the API: start with the [Guide](guide.md).
+
+## The problem: a shared dependency is a shared risk
+
+A shared library (an SDK, a core package, a platform shell) is loaded by many apps. Whatever it depends on, the apps depend on too. State and event libraries are the worst case, because they keep **internal state and identity** (a store, a context, a class). Two copies or two versions of them do not merge: they silently stop seeing each other.
+
+Module Federation makes this visible. Each remote can bring its own copy unless every team agrees on a `singleton` and a version range. The [Nx guide on library versions](https://nx.dev/docs/kb/manage-library-versions-with-module-federation) lists the result: libraries with internal state conflict, and a missing method in one version breaks callers written for another.
+
+Real cases from the libraries nanoeffects was compared with:
+
+| Library | What goes wrong | Source |
+| ------- | --------------- | ------ |
+| Redux, React Redux | A shared component library uses `react-redux`. Every micro-frontend must use the same version of that library, or `react-redux` "breaks weirdly". | [react-redux#1949](https://github.com/reduxjs/react-redux/issues/1949) |
+| Redux | A store is reachable only under a `Provider`. Each sub-app needs its own provider, and a second one must not be created when a module is injected. Reducers duplicated between the host and a module add to it. | [Redux on Module Federation](https://dev.to/manomano-tech-team/how-to-work-with-redux-on-module-federation-13gm) |
+| Effector | A library that uses `effector-react/scope` and is bundled into another project gets two instances. Its `Provider` is not seen by `useStore` of the app: "no scope found". | [effector#727](https://github.com/effector/effector/issues/727) |
+| RxJS | Two copies give two `Observable` classes. Types of one version do not fit the other, and operators added to one copy are missing on the other. The advice is "one version in `node_modules`". | [RxJS#2984](https://github.com/ReactiveX/rxjs/issues/2984), [neo4j-javascript-driver#978](https://github.com/neo4j/neo4j-javascript-driver/issues/978) |
+
+A library that is **not** a shared singleton cannot break this way. nanoeffects has no dependencies and no module-level state: a bus is an object you create. Two copies, or two versions, of the package in one page are two independent buses. Nothing is registered globally, no `Provider` is needed, and the host app does not have to pick a version for you.
+
+## Why not the alternatives
+
+| Option | Why it did not fit |
+| ------ | ------------------ |
+| Redux (with sagas) | A store and a provider shared by every consumer, which is the risk above. `redux-saga` also has no cheap way to get an answer back from an event: effects talk through the store. |
+| Effector | A graph with global identity. A version or scope mismatch between the SDK and the app reaches the whole infrastructure. |
+| Zustand | Good state, but it is a store, not a way to run and cancel work. It is the natural place to hold state next to nanoeffects: see [Stores](stores.md). |
+| RxJS | Flexible, but learning its ecosystem (operators, subjects, schedulers) is a high entry cost for every developer who touches the SDK. The package is also not small: [Bundlephobia](https://bundlephobia.com/package/rxjs) reports 17.3 kB minified and gzipped for 7.8.2. |
+
+## What the library does instead
+
+- **No dependencies, no global state.** It is safe to ship inside an SDK next to whatever the host app runs. It does not need a `singleton` entry in the Module Federation config.
+- **Small enough for a strict budget.** SDKs often get a few kilobytes for all third-party code. `createBus` is about 1.4 kB gzip (1.3 kB brotli); policies, effects and commands are separate entries you import only when you need them. See [Package entries](package.md).
+- **Simple first.** `on` and `emit` are the whole model. Cancellation, retry and the rest are plain functions on top. The [Guide](guide.md) and [Coming from redux-saga](migrating-from-saga.md) map the familiar names.
+- **`emit` can return an answer.** A [command](actions.md) is an event whose handler returns a result, so one module can ask another and wait for the reply. Events alone cannot do that, and it was the main thing missing from the Redux-based options.
+- **Easy to debug.** Event-driven code is hard to follow: you see an effect and not the event that caused it. Every task knows its parent, so [tracing](tracing.md) shows the chain of events, with loggers for the console, the Performance panel and Redux DevTools.
+
+## When this is not the right tool
+
+nanoeffects holds no state. If you need a store, keep Redux, Zustand or Effector and let the bus run the async work: [Stores](stores.md). If you already have streams everywhere, keep RxJS: [Use nanoeffects next to RxJS](migrating-from-rxjs.md).

package/docs/observable.md

@@ -1,24 +1,138 @@
 # Turn events into Observables
 
-Use this page only when you already work in Observables / RxJS. Prefer `bus.on` with policies for cancellation and tracing.
+Use this page when your app already works with Observables or RxJS and you want a bus event as a stream. If you start from scratch, prefer `bus.on` with policies: they cancel work and show up in traces.
 
 `createObserve(bus)` from `nanoeffects/observable` turns a bus event into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is. Nothing here depends on them.
 
+## Turn an event into a stream
+
+Problem: a search box emits `typed` on every key. You want to wait for a pause and skip repeats with operators you already know.
+
 <!-- docs-check: skip - needs rxjs, which the project does not depend on -->
 ```js
-import { from } from "rxjs";
-import { debounceTime, distinctUntilChanged, switchMap } from "rxjs/operators";
+import { createBus } from "nanoeffects";
 import { createObserve } from "nanoeffects/observable";
+import { from } from "rxjs";
+import { debounceTime, distinctUntilChanged } from "rxjs/operators";
 
-const observe = createObserve(bus); // Observable per event name
+const bus = createBus(); // the bus: events and handlers
+const observe = createObserve(bus); // observe(event) gives an Observable per event name
 
-from(observe("typed"))
-  .pipe(debounceTime(300), distinctUntilChanged(), switchMap(searchRequest))
-  .subscribe((items) => bus.emit("results", items));
+const typed$ = from(observe("typed")); // RxJS wraps it with from()
+
+const subscription = typed$
+  .pipe(debounceTime(300), distinctUntilChanged())
+  .subscribe((query) => bus.emit("search", query)); // back into the bus
 ```
 
 - `observe(event)` returns an Observable of the payloads of that event. Each `subscribe` is a `bus.on` of its own; `unsubscribe()` removes it.
 - `subscribe` takes a function or an object with `next`.
-- The stream never completes and never fails: events are the only thing that arrives. Errors of the subscriber’s handler belong to the subscriber.
-- A subscription made this way is not tied to a task. End it yourself: `onAbort(ctx, subscription.unsubscribe)` inside a task, or with the signal of a module.
-- For cancellation, policies, and tracing, keep to `bus.on` with `latest`, `debounce`, `queue` — they know about tasks. The Observable is for places where a stream is already how you work.
+- Types follow the event map: `observe("typed")` is an `Observable<string>` when `typed` carries a string.
+
+## Send a stream into the bus
+
+Problem: `.subscribe((value) => bus.emit(action(value)))` repeats the bus and the action in every subscription. `bus.emitter(action)` from `emitterPlugin` returns that callback, so it is the argument of `subscribe`. It works with any source that takes a `next` function: an RxJS stream, a store callback, a DOM listener.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("search/queryChanged"); // a plain action creator
+```
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { fromEvent } from "rxjs";
+import { debounceTime, distinctUntilChanged, map } from "rxjs/operators";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+
+const input = document.querySelector("#search"); // the search box
+
+const subscription = fromEvent(input, "input")
+  .pipe(
+    map((event) => event.target.value),
+    debounceTime(300),
+    distinctUntilChanged(),
+  )
+  .subscribe(bus.emitter(queryChanged)); // calls bus.emit(queryChanged(value))
+
+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.
+
+## 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.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { latest } from "nanoeffects/policies";
+
+// RxJS: shape the values (debounce, skip repeats), then hand them to the bus
+from(observe("typed"))
+  .pipe(debounceTime(300), distinctUntilChanged())
+  .subscribe((query) => bus.emit("search", query));
+
+// nanoeffects: one cancellable request; a newer "search" aborts the old one
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+```
+
+`switchMap` drops the old inner stream. `latest` aborts the old task through `signal`, so a `fetch` that got the signal really stops.
+
+## Convert back to a stream or a promise
+
+| You need | Write |
+| -------- | ----- |
+| A stream of events, with operators | `from(observe("event"))` |
+| The next event as a promise | `firstValueFrom(from(observe("event")))`; inside a task `take(ctx, "event")` does the same and respects abort |
+| The events of a bus as an RxJS `Observable` class (for `instanceof` or `pipe` as a method) | `new Observable((subscriber) => observe("event").subscribe(subscriber))` |
+| A task's abort as a stream | `fromEvent(ctx.signal, "abort")`, for `takeUntil` |
+| The latest value to new subscribers | `from(observe("event")).pipe(shareReplay(1))`; the Observable replays nothing by itself |
+
+Events that fired before `subscribe` are lost: the Observable is hot, like `bus.on`. Add `startWith(initial)` or `shareReplay` when a late subscriber needs a value.
+
+## End the subscription
+
+A subscription from `observe` is not tied to a task. Nothing ends it for you. Pick one:
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { fromEvent, from } from "rxjs";
+import { takeUntil } from "rxjs/operators";
+import { onAbort } from "nanoeffects/effects";
+
+bus.on("screen-opened", (_, ctx) => {
+  // takeUntil: stop the stream when the task aborts
+  from(observe("typed"))
+    .pipe(takeUntil(fromEvent(ctx.signal, "abort")))
+    .subscribe((query) => bus.emit("search", query));
+
+  // or: onAbort calls unsubscribe for you
+  const subscription = observe("scrolled").subscribe(updatePosition);
+  onAbort(ctx, subscription.unsubscribe);
+});
+```
+
+Outside a task, call `subscription.unsubscribe()` yourself when the screen goes away, or use the signal of a module.
+
+## Know the limits
+
+- The stream never completes and never fails: events are the only thing that arrives. An error thrown by your subscriber is yours; the bus handles it only if `onError` is set ([Errors](errors.md)).
+- `observe` reads the bus when you call `subscribe`, not when you create it. Create it once, call it as often as needed.
+- Operators that keep state (`scan`, `buffer`, `window`) live in RxJS. The bus keeps no values. For the full split of work see [Use nanoeffects next to RxJS](migrating-from-rxjs.md).

package/docs/oop.md

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

package/docs/package.md

@@ -8,6 +8,9 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
 | `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/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`) |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve` |
@@ -19,9 +22,10 @@ The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists
 
 ## Give the docs to an AI assistant
 
-The package ships two plain-text files for assistants that write code with it:
+The package ships plain-text files for assistants that write code with it:
 
 - `llms.txt`: a short index. It states the rules that generated code often gets wrong and links to every page of these docs.
 - `llms-full.txt`: the same summary followed by the text of every linked page, in one file.
+- `skills/nanoeffects/SKILL.md`: a skill for assistants that support skills (for example Claude Code). It says when to suggest nanoeffects, when not to, and the same rules. Copy the folder to `.claude/skills/` in your project or to `~/.claude/skills/`.
 
-Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. Both match the installed version.
+Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. All match the installed version.