nanoeffects 0.7.0 → 0.9.0

package/docs/debounce-and-abort.md

@@ -0,0 +1,106 @@
+# Debounce a request and abort the previous one
+
+Read this page if you debounce user input (a search box, an autosave, a resize handler) and you also want the request in flight to stop when a new one starts. `debounce` alone waits for a pause. It does not cancel a request that already started. This page shows the two policies together, the order to put them in, and when to use `throttle` instead.
+
+## Know what each policy does
+
+| Policy | What it does | What it does not do |
+| ------ | ------------ | ------------------- |
+| `debounce(ms, fn)` | runs `fn` after `ms` without a new call | does not cancel a run that already started |
+| `latest(fn)` | aborts the previous run when a new one starts | does not wait for a pause |
+
+Use both for a search box. `debounce` sends fewer requests. `latest` cancels the slow one when the user types again after the pause.
+
+## Combine them
+
+Put `debounce` outside and `latest` inside. The event waits for a pause first. When the run starts, it aborts the previous run.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer run aborts the older request
+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);
+});
+
+// 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.
+
+Result: typing `a`, `ab`, `abc` within 300 ms sends one request for `abc`. If the user types `abcd` while that request runs, the request for `abc` is aborted and one for `abcd` starts after the pause.
+
+## Run the first call at once
+
+By default `debounce` waits even before the first call. For an input where the first key press should react at once, add `leading: true`. The first call of a burst runs immediately, and the last one runs after the pause.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const showSuggestions = (query) => console.log("suggest", query);
+
+// debounce with leading: the first call runs at once, the last one after 300 ms of quiet
+bus.on("typed", debounce(300, showSuggestions, { leading: true }));
+```
+
+`leading` and `trailing` follow lodash. All combinations: [Policies](policies.md#configure-debounce-and-throttle).
+
+## Use throttle for continuous input
+
+`debounce` never runs while calls keep coming. For a scroll or a drag you want updates during the movement. Use `throttle`: at most one run per period.
+
+```js
+import { createBus } from "nanoeffects";
+import { throttle } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const saveScroll = (position) => localStorage.setItem("scroll", String(position));
+
+// throttle: at most one run per 100 ms while "scrolled" keeps coming
+bus.on("scrolled", throttle(100, saveScroll));
+```
+
+## Debounce without a bus
+
+If the page has no bus, wrap the same pair with `withPolicy`. The result is a plain function that you call from an input handler.
+
+```js
+import { debounce, latest, withPolicy } from "nanoeffects/policies";
+
+// latest: a newer run aborts the older request
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  console.log(items);
+});
+
+// withPolicy: debounce by 300 ms, called as a plain function
+const onTyped = withPolicy(debounce(300, searchLatest));
+
+onTyped("a");
+onTyped("ab"); // only "ab" runs, 300 ms later
+
+// cancel: drop a pending call and abort a running request, for example on page leave
+onTyped.cancel();
+```
+
+In a React component use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders), which also cancels on unmount.
+
+## Check these when it does not cancel
+
+- The request did not get `signal`. `latest` then drops the old result but the request goes on.
+- The order is reversed. Write `debounce(300, latest(handler))`, as above, so `debounce` receives the events and `latest` guards the request.
+- Several inputs share one event. Give each its own event name, or use `{ key }`, for example `latest(handler, { key: (input) => input.id })`.
+
+Related: [Cancel stale requests](cancel-stale-requests.md), [Policies](policies.md).

package/docs/guide.md

@@ -69,6 +69,74 @@ unbind();
 - An event that only `"*"` listens to counts as heard, so `onUnhandled` does not fire for it.
 - `bus.off("*")` removes every `"*"` listener; `bus.off()` clears the whole bus, `"*"` included.
 
+### Pick events with a function
+
+To listen to a group of events, such as every `user/*` event, `"*"` and a check of `ctx.type` do the job but leave the check to you. `matchPlugin` lets `on` take a function that picks the events. The function gets `{ type, payload }` of each event, and the handler runs when it returns true.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { matchPlugin } from "nanoeffects/match";
+
+// matchPlugin — lets on, once and off take a function that picks the events
+export const bus = createBus().use(matchPlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+export const userLoaded = createAction("user/loaded");
+export const userFailed = createAction("user/failed");
+```
+
+```js
+// user-handlers.js
+import { bus } from "./bus";
+
+// the function picks the events; the handler gets the payload and the context of each
+bus.on(
+  (action) => action.type.startsWith("user/"),
+  (payload, ctx) => {
+    console.log(ctx.type, payload);
+  },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { userFailed, userLoaded } from "./user";
+
+bus.emit(userLoaded({ id: "1" })); // user/loaded { id: "1" }
+bus.emit("order/placed", 5); // not picked
+bus.emit(userFailed("boom")); // user/failed boom
+```
+
+- `once(fn, handler)` waits for the first event that `fn` accepts. `off(fn)` removes every handler of `fn`, and `off(fn, handler)` removes one.
+- An action creator or a command still means that one event: only a function with no `type` is a function that picks events.
+- The cost: the handler listens to `"*"`, so each event makes one task for each such subscription, also when the function says no, and an event that only such a subscription listens to counts as heard for `onUnhandled`. For a few known events, `on(creator, handler)` is cheaper.
+- It works in any order with the other plugins, `devPlugin` included.
+
+In TypeScript a function that is a type guard narrows the payload of the handler:
+
+```ts
+import { bus } from "./bus";
+
+type User = { id: string };
+
+// the guard says which event this is, and the handler gets its payload typed
+const isLoaded = (action: {
+  type: string;
+  payload: unknown;
+}): action is { type: "user/loaded"; payload: User } => action.type === "user/loaded";
+
+bus.on(isLoaded, (user) => console.log(user.id)); // user: User
+```
+
+`ctx.on` takes such a function at run time too, but its type does not know it yet.
+
 ## 2. Use the handler context
 
 The second argument is the **task** context for this call. Emit further events through it. Pass `ctx.signal` to `fetch` when you cancel work.
@@ -149,7 +217,7 @@ const searchLatest = latest(async (query, { signal }) => {
 bus.on("search", debounce(300, searchLatest));
 ```
 
-Full options: [Policies](policies.md).
+Full options: [Policies](policies.md). No bus? A policy also works as a plain function: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
 
 ## 5. Add retry and timeout
 
@@ -225,22 +293,42 @@ More in [Effects](effects.md).
 
 `emit` and `on` take a string, an object `{ type, payload }` (a Redux action fits), or a function with a `type` property (action creators and commands).
 
+From here on the bus is kept in one file and the events in files named after their domain (`move.js`, `math.js`), as in a real app: the events can then be imported anywhere without importing the bus.
+
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, createCommand } from "nanoeffects/actions";
 
-const bus = createBus();
+export const bus = createBus();
+```
+
+```js
+// move.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — names an event; calling it builds { type, payload }
+export const moved = createAction("moved");
+```
+
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
+
+// createCommand — like an action, but emit runs a handler and returns its result
+export const double = createCommand("math/double", (value) => value * 2);
+```
+
+```js
+import { bus } from "./bus";
+import { moved } from "./move";
+import { double } from "./math";
 
 bus.emit("moved", { x: 1, y: 2 });
 bus.emit({ type: "moved", payload: { x: 2, y: 2 } });
 
-// createAction — names an event; calling it builds { type, payload }
-const moved = createAction("moved");
 bus.emit(moved({ x: 3, y: 2 }));
 bus.on(moved, ({ x }) => console.log(x));
 
-// createCommand — like an action, but emit runs a handler and returns its result
-const double = createCommand("math/double", (value) => value * 2);
 bus.emit(double(21)); // 42
 ```
 
@@ -251,14 +339,25 @@ Use strings for the plain case. Use objects when other code already builds actio
 A command may carry its handler, or only be a **contract** (name + types) with the work registered elsewhere — another file, or a fake in a test.
 
 ```js
-import { createBus } from "nanoeffects";
-import { createCommand, commandsPlugin } from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // contract — no handler yet
+export const getUser = createCommand("user/get"); // contract — no handler yet
+```
 
-const bus = createBus();
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { commandsPlugin } from "nanoeffects/actions";
+
+export const bus = createBus();
 // commandsPlugin — registry of handlers for this bus
-const commands = bus.use(commandsPlugin());
+export const commands = bus.use(commandsPlugin());
+```
+
+```js
+import { bus, commands } from "./bus";
+import { getUser } from "./user";
 
 bus.emit(getUser("1")); // throws: No handler for command "user/get"
 
@@ -279,16 +378,27 @@ Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can reg
 **What you do.** `createModule(name, setup)` describes the feature. `bus.use(modulePlugin([…]))` mounts it. `app.unmount(module)` undoes everything the setup registered.
 
 ```js
-import { createBus } from "nanoeffects";
-import { createCommand, createModule, modulePlugin } from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // contract — no handler yet
-const double = createCommand("math/double", (value) => value * 2); // carries its handler
+export const getUser = createCommand("user/get"); // contract — no handler yet
+```
 
-const bus = createBus();
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
+
+export const double = createCommand("math/double", (value) => value * 2); // carries its handler
+```
+
+```js
+// greeting-module.js
+import { createModule } from "nanoeffects/actions";
+import { getUser } from "./user";
+import { double } from "./math";
 
 // createModule — one feature; name is stable for hot reload replace
-const greeting = createModule("greeting", (m) => {
+export const greeting = createModule("greeting", (m) => {
   // m.on — like bus.on, removed automatically on unmount
   m.on("greet", (name) => console.log(`hello ${name}`));
 
@@ -298,9 +408,23 @@ const greeting = createModule("greeting", (m) => {
   // m.use — register a command that already has a handler, for this module’s life
   m.use(double);
 });
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { greeting } from "./greeting-module";
 
+export const bus = createBus();
 // modulePlugin — mount modules on the bus
-const app = bus.use(modulePlugin([greeting]));
+export const app = bus.use(modulePlugin([greeting]));
+```
+
+```js
+import { app, bus } from "./bus";
+import { greeting } from "./greeting-module";
+
 bus.emit("greet", "Ada"); // hello Ada
 app.unmount(greeting); // greet listener and getUser binding are gone
 ```

package/docs/hmr.md

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

package/docs/migrating-from-effector.md

@@ -20,7 +20,7 @@ nanoeffects has no store. `createStore` can be replaced by any store you like, f
 | event call `loaded(user)` | `bus.emit("loaded", user)` |
 | `createEffect(handler)` | a handler: `bus.on(event, handler)` |
 | effect with `done` and `fail` | [`createJob`](actions.md): emits the success and fail actions |
-| `effect.pending` | not provided: keep a flag in your store, or read it from [Tracing](tracing.md) |
+| `effect.pending` | `job.pending`, `job.success`, `job.fail` and `job.cancel`: set and clear the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)) |
 | `sample({ clock, fn, target })` | `bus.on(clock, handler)` and `ctx.emit(target, …)` |
 | `sample({ source: $store, clock })` | read the store from a [context field](context.md) in the handler |
 | `sample({ filter })` | an `if` in the handler |
@@ -73,16 +73,26 @@ The store (`$items`) is not here. Keep it in Effector and update it from the `fo
 
 Without Effector, something must hold `$items`. A Zustand store does it: `create` replaces `createStore`, and `setState` replaces `.on(searchFx.doneData, …)`. The handler writes the result to the store directly, so the `found` event is not needed. A component reads the store with a selector, as `useUnit($items)` did.
 
-```jsx
-// search-zustand.jsx
-import { create } from "zustand";
+```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { debounce, latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus: only the bus
+```
+
+```js
+// search-store.js
+import { create } from "zustand";
 
 // create — Zustand: the store replaces $items
-const useSearchStore = create(() => ({ items: [] }));
+export const useSearchStore = create(() => ({ items: [] }));
+```
 
-const bus = createBus(); // the bus: events and handlers
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { useSearchStore } from "./search-store";
 
 // latest — a newer query aborts the request in flight; debounce — wait 300 ms of quiet
 const search = latest(async (query, { signal }) => {
@@ -91,6 +101,12 @@ const search = latest(async (query, { signal }) => {
 });
 
 bus.on("query-changed", debounce(300, search));
+```
+
+```jsx
+// Search.jsx
+import { bus } from "./bus";
+import { useSearchStore } from "./search-store";
 
 export function Search() {
   const items = useSearchStore((state) => state.items); // Zustand: a selector reads items
@@ -166,13 +182,18 @@ formSubmitted.watch((event) => {
 });
 ```
 
-The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus, in its own file:
+The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus and the handler, each in its own file:
 
 ```js
-// form-bus.js
+// bus.js
 import { createBus } from "nanoeffects";
 
-export const bus = createBus(); // the bus: events and their handlers
+export const bus = createBus(); // the bus: only the bus
+```
+
+```js
+// form-handlers.js
+import { bus } from "./bus";
 
 // bus.on — the job of sendFormFx: runs when the form is submitted
 bus.on("form/submitted", (values) => {
@@ -185,7 +206,8 @@ Then the form. `useState` does the work of `$form`, `fieldUpdate` and `prepend`;
 ```jsx
 // App.jsx
 import { useState } from "react";
-import { bus } from "./form-bus"; // the bus of the previous snippet
+import { bus } from "./bus"; // the bus of the previous snippet
+import "./form-handlers"; // registers the handler; the app does this once, when it starts
 
 function Field({ name, type, label, value, onChange }) {
   return (
@@ -255,16 +277,27 @@ Retrying a failed network request, and cancelling when the form closes, are in [
 
 Keep the Effector stores, and run the effects on the bus. A store calls the bus through `bus.emitter`, and the handler sends the result back as an event that the store listens to.
 
-<!-- docs-check: skip - needs effector, which the project does not depend on -->
 ```js
-import { createEvent, createStore } from "effector";
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { latest } from "nanoeffects/policies";
+import { emitterPlugin } from "nanoeffects/actions";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
 
-const queryChanged = createAction("query/changed"); // a plain action creator
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("query/changed"); // a plain action creator
+```
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+import { createEvent, createStore } from "effector";
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
 
 const found = createEvent(); // Effector: the result comes back as an event
 const $items = createStore([]).on(found, (_, items) => items);
@@ -285,7 +318,7 @@ bus.on(
 ## What is different
 
 - **No state.** There is no `createStore`, `combine`, `restore`, `$store.map`. The bus holds listeners only. Take a store such as Zustand for state ([Stores](stores.md)).
-- **No `pending`.** A running task is visible through [Tracing](tracing.md), not through a store. A flag in your store set at the start and the end of the handler does the job.
+- **`pending` is an action, not a store.** `createJob` sends `pending` when the handler starts, and `success`, `fail` or `cancel` when it ends; you keep the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)). With a policy such as `latest` around the handler the flag is not exact yet, which that section explains. A running task is also visible through [Tracing](tracing.md).
 - **Cancellation is the default tool.** An Effector effect runs every call to the end. Here `latest` and `ctx.signal` stop what is no longer needed.
 - **Events are matched by name, not by identity.** An event is a string or a `createAction` creator, not a unit that you import and call. Two modules agree on the name.
 - **No graph.** `sample` and `forward` build a static graph. A bus subscribes handlers at runtime and the call order is the order of `on`.

package/docs/migrating-from-mitt.md

@@ -0,0 +1,97 @@
+# Coming from mitt, nanoevents or EventEmitter
+
+Read this page if your app uses a small event emitter (`mitt`, `nanoevents`, Node's `EventEmitter`, `tiny-emitter`) and its handlers start to do async work: requests, timers, retries. It maps the calls, shows what you gain, and shows what to check before you switch.
+
+## When to switch
+
+An emitter calls a function and forgets it. That is enough while handlers are synchronous. Switch when handlers start async work and you hit one of these:
+
+- an older request finishes after a newer one and overwrites its result;
+- you keep `AbortController` objects by hand;
+- you write debounce, throttle or retry around handlers yourself;
+- you cannot tell which event started which request.
+
+If handlers stay synchronous, keep your emitter. nanoeffects costs about 1.4 kB gzip (1.3 kB brotli), close to the small emitters.
+
+## Find the equivalent
+
+| mitt / EventEmitter | nanoeffects |
+| ------------------- | ----------- |
+| `emitter.on("a", handler)` | `bus.on("a", handler)` |
+| `emitter.off("a", handler)` | call the function that `bus.on` returned, or `bus.off("a")` for all handlers of `a` |
+| `emitter.emit("a", payload)` | `bus.emit("a", payload)` |
+| `emitter.once("a", handler)` | `bus.once("a", handler)` |
+| `on("*", (type, payload) => …)` | `bus.on("*", (payload, ctx) => …)`: the event name is `ctx.type` (see the [Guide](guide.md)) |
+| `emitter.all.clear()` | `bus.off()` |
+
+Two differences to know:
+
+- `bus.on` returns the unsubscribe function. You do not need to keep the handler to remove it.
+- The handler gets a second argument, the task context: `(payload, ctx)`. You can ignore it until you need `ctx.signal` or `ctx.emit`.
+
+## Move a handler
+
+Before, with `mitt`:
+
+<!-- docs-check: skip - needs mitt, which the project does not depend on -->
+```js
+import mitt from "mitt";
+
+const emitter = mitt();
+
+emitter.on("search", async (query) => {
+  const items = await api.search(query);
+  emitter.emit("results", items);
+});
+
+emitter.emit("search", "abc");
+```
+
+After, with nanoeffects. The first step changes only the import and the constructor:
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // event bus; each handler call is a task
+
+bus.on("search", async (query) => {
+  const items = await api.search(query);
+  bus.emit("results", items);
+});
+
+bus.emit("search", "abc");
+```
+
+The second step fixes the race. Wrap the handler in `latest` and pass the signal to the request:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // event bus; each handler call is a task
+
+// latest: a newer "search" aborts the older run
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal }); // signal cancels the request
+    bus.emit("results", items);
+  }),
+);
+
+bus.emit("search", "abc");
+```
+
+More cases (pause, retry, timeout): [Cancel stale requests](cancel-stale-requests.md).
+
+## Check the differences
+
+| Topic | Emitter | nanoeffects |
+| ----- | ------- | ----------- |
+| Handler order | order of subscription | order of subscription |
+| Error in a handler | depends on the library | the first error stops the rest and is thrown from `emit`; set `onError` to isolate handlers ([Errors](errors.md)) |
+| Async handler rejects | usually an unhandled rejection | not handled without `onError`; set `onError` to catch it |
+| Event without a listener | ignored | ignored; set `onUnhandled` to be told |
+| Types | event map in a type parameter | event map in a type parameter ([TypeScript](typescript.md)) |
+
+The exact rules of `emit`, abort and ordering: [Semantics](semantics.md).

package/docs/migrating-from-rxjs.md

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