nanoeffects 0.8.0 → 0.9.0

package/dist/signal.d.ts

@@ -0,0 +1,51 @@
+import { B as EventMap, C as Emit, E as EventLike, a as EmitScope, c as WithScope, h as Bus, v as CommandCall } from "./action-creator-BrZF6hXc.js";
+//#region src/signal/plugin.d.ts
+/** What the second argument of `emit` takes besides the fields of a scope. */
+type SignalOption = {
+  /** Aborts the tasks that this `emit` starts, with its reason, when it aborts. */
+  signal?: AbortSignal;
+};
+/** `emit` of a bus with `signalPlugin`: the call forms take `{ signal }` as their second argument. */
+type SignalEmit<E extends EventMap> = Emit<E> & {
+  <P, R, F>(call: CommandCall<P, R> & WithScope<F>, options: SignalOption & EmitScope<E, F>): R;
+  <P, R>(call: CommandCall<P, R>, options: SignalOption & EmitScope<E>): R;
+  (event: EventLike<E>, options: SignalOption & EmitScope<E>): void;
+};
+/** A bus with `signalPlugin`: the same bus, with the `emit` that takes a signal. */
+type SignalBus<E extends EventMap> = Bus<E> & {
+  emit: SignalEmit<E>;
+};
+/**
+ * Lets `bus.emit(call, { signal })` tie the tasks that this emit starts to an
+ * outside `AbortSignal`: when it aborts, their `ctx.signal` aborts with the same
+ * reason, so a handler, `latest`, `retry` and `timeout` stop as for any abort. It
+ * is made for libraries that own the request and give you a signal, such as the
+ * `queryFn` of React Query. The tasks that count are those made while the call
+ * to `emit` runs (the command or job and the listeners of its type, and their
+ * `ctx.run` children); a separate `emit` that a handler makes later is not
+ * linked. `emit` returns what it returns without the plugin.
+ *
+ * For a command or a job the link ends when its promise settles; a handler
+ * that returns without a promise is finished with the call, so it is not
+ * linked after it. For an event the link stays until the signal aborts, so
+ * give each request its own signal.
+ *
+ * `{ signal }` can share the object with the fields of a scope (see
+ * `scopePlugin`); `signal` is never put on `ctx` by a scope. Without this
+ * plugin the signal is ignored. Returns the same bus, typed with the new `emit`.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { signalPlugin } from "nanoeffects/signal";
+ *
+ * const bus = createBus().use(signalPlugin()); // emit takes a signal now
+ *
+ * // React Query aborts `signal` when the component unmounts or the key changes
+ * const queryFn = ({ signal }: { signal: AbortSignal }) =>
+ *   bus.emit(getUser("1"), { signal });
+ * ```
+ */
+export declare const signalPlugin: () => <E extends EventMap>(bus: Bus<E>) => SignalBus<E>;
+//#endregion
+export type { SignalBus, SignalEmit, SignalOption };

package/dist/signal.js

@@ -0,0 +1 @@
+import{t as e}from"./onAbort-BgMfspK4.js";import{n as t}from"./promise-CSLpzwSR.js";import{n}from"./bus-CkTHUAvq.js";const r=e=>typeof e==`object`&&!!e,i=(e,t)=>{let n=t[0];if(!r(n)||!r(e)&&typeof e!=`function`)return;let i=Reflect.get(n,`signal`);return i instanceof AbortSignal?i:void 0},a=(r,i,a,o)=>{let s=e({signal:r},e=>{for(let{target:t}of i)t.abort(e)});return t(o)?o.then(s,s):n(a)&&s(),o},o=()=>e=>{let t,n,r=e.addContext;e.addContext=e=>{r?.(e),t?.push({target:e}),n?.aborted&&e.abort(n.reason)};let o=e.emit;return e.emit=(e,...r)=>{let s=i(e,r);if(!(s||t))return o(e,...r);let c=t,l=n,u=[];t=s?u:void 0,n=s;let d;try{d=o(e,...r)}finally{t=c,n=l}return s?a(s,u,e,d):d},e};export{o as signalPlugin};

package/dist/with-policy-CqUS-VWW.d.ts

@@ -0,0 +1,30 @@
+import { B as EventMap, H as PayloadOf, W as Task } from "./action-creator-BrZF6hXc.js";
+//#region src/policies/with-policy.d.ts
+/** What `withPolicy` returns: the task as a plain function that can be cancelled. */
+type PolicyFunction<P, R> = {
+  (...args: PayloadOf<P>): Promise<Awaited<R> | undefined>;
+  /** Aborts every call that has not finished. Calls made after it work as before. */
+  cancel: (reason?: unknown) => void;
+  /** Same as `cancel`; present where `Symbol.dispose` exists, for `using`. */
+  [Symbol.dispose]?: () => void;
+};
+/**
+ * Makes a policy (or any task) a plain function that needs no bus and no
+ * context. The returned function keeps the state of the policy between calls,
+ * so a debounced one waits across calls. `cancel()` aborts what is pending or
+ * running; calls after it work again. The callback keeps the `(payload, ctx)`
+ * shape; `ctx.signal`, `ctx.abort` and `ctx.run` work, `ctx.emit` and `ctx.on`
+ * do nothing because there is no bus.
+ *
+ * @example
+ * ```ts
+ * const onChange = withPolicy(debounce(300, (query: string) => search(query)));
+ *
+ * onChange("re");
+ * onChange("redux"); // only this one runs, 300 ms after it
+ * onChange.cancel(); // or nothing runs at all
+ * ```
+ */
+declare const withPolicy: <P, R>(task: Task<P, EventMap, R>) => PolicyFunction<P, R>;
+//#endregion
+export { withPolicy as n, PolicyFunction as t };

package/dist/with-policy-DBV9dh2F.js

@@ -0,0 +1 @@
+import{n as e}from"./context-COgyNlrC.js";const t=Reflect.get(Symbol,`dispose`),n=n=>{let r=new AbortController,i=async(...t)=>{let i=t[0],{ctx:a,unlink:o}=e({event:{type:`withPolicy`,payload:i},parent:{signal:r.signal}});try{return await n(i,a)}finally{o()}},a=e=>{r.abort(e),r=new AbortController},o=Object.assign(i,{cancel:a});return t&&Reflect.set(o,t,()=>a()),o};export{n as t};

package/docs/README.md

@@ -4,6 +4,8 @@
 
 The [Guide](guide.md) is the ladder: small bus → policies for async UI → effects when you need them → commands and modules for domain logic off the UI.
 
+Why the library exists, and when to pick it over Redux, Effector or RxJS (SDKs, shared libraries, Module Federation): [Why nanoeffects exists](motivation.md).
+
 Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-checked and tested).
 
 ## Jump by project need
@@ -16,6 +18,10 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 | Domain logic off the UI | [Actions, commands, modules](actions.md) |
 | Already on Redux / Zustand / MobX / Pinia | [Stores](stores.md) |
 | A React form with async checks | [Build a sign-up form in React](react.md) |
+| Old responses overwrite new ones | [Cancel stale requests](cancel-stale-requests.md) |
+| Debounced input that must also cancel the old request | [Debounce and abort](debounce-and-abort.md) |
+| A second click sends a second request | [Prevent a double submit](prevent-double-submit.md) |
+| Using mitt, nanoevents or EventEmitter | [Coming from mitt](migrating-from-mitt.md) |
 | Moving from redux-saga | [Coming from redux-saga](migrating-from-saga.md) |
 | Using RxJS | [Use nanoeffects next to RxJS](migrating-from-rxjs.md) |
 | Moving from Effector | [Coming from Effector](migrating-from-effector.md) |

package/docs/actions.md

@@ -110,15 +110,84 @@ The registry lives in `nanoeffects/actions`, so a bus without one carries none o
 
 ### Jobs
 
-`createJob(type, handler, { success, fail })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.success` and `loadUser.fail` on it.
+`createJob(type, handler, { pending, success, fail, cancel })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.pending`, `loadUser.success`, `loadUser.fail` and `loadUser.cancel` on it.
 
+- When the handler starts, emits `loadUser.pending(payload)`.
 - On success, emits `loadUser.success(result)`.
 - On failure, emits `loadUser.fail(error)`.
-- `success` / `fail` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/success` or `<type>/fail`.
+- When the task is aborted before the handler settles, emits `loadUser.cancel(reason)` instead of `success` or `fail`. After `pending`, exactly one of the three follows.
+- `pending` / `success` / `fail` / `cancel` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/pending`, `<type>/success`, `<type>/fail` or `<type>/cancel`.
 - `bus.emit(loadUser(id))` returns a promise of the result. Handler errors are always handled: they go to `fail` and the promise resolves with `undefined`. For a result that must reject, use a command.
-- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). Nothing is sent after abort.
-- A missing handler is not an outcome: `emit` throws `No handler for command "..."`.
+- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). `success` and `fail` are not sent after abort; `cancel` is, once the handler settles.
+- A missing handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent.
 - Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
+- The outcomes are events like any other: with `onUnhandled` set on the bus, it is called for a `pending` or a `cancel` that nobody listens to.
+
+## Show a loading state with a job
+
+**Problem.** A spinner needs a flag that is `true` while a request runs. Setting it by hand in the handler (`loading = true`, then `try` / `finally`) breaks when the task is aborted: `ctx.emit` does nothing after an abort, so a flag that is cleared through the bus stays `true`.
+
+**When.** The UI shows a loading state for a request, and the request can be aborted (a page is left, `ctx.abort()` is called). Skip it when nothing shows the state.
+
+A job sends one action when the handler starts and one when it ends, whatever way it ends. A store sets the flag on `pending` and clears it on `success`, `fail` and `cancel`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus the app shares
+export const bus = createBus();
+```
+
+```js
+// user.js
+import { createJob } from "nanoeffects/actions";
+
+// createJob — a command that also sends pending, success, fail and cancel
+export const loadUser = createJob("user/load", fetchUser);
+```
+
+```js
+// user-store.js
+import { bus } from "./bus";
+import { loadUser } from "./user";
+
+export const state = { loading: false, user: null };
+
+// pending — the handler starts: show the spinner
+bus.on(loadUser.pending, () => {
+  state.loading = true;
+});
+
+// success — the handler returned a user
+bus.on(loadUser.success, (user) => {
+  state.loading = false;
+  state.user = user;
+});
+
+// fail — the handler threw
+bus.on(loadUser.fail, () => {
+  state.loading = false;
+});
+
+// cancel — the task was aborted: the only way to clear the flag then
+bus.on(loadUser.cancel, () => {
+  state.loading = false;
+});
+```
+
+```js
+// page.js
+import { bus } from "./bus";
+import { loadUser } from "./user";
+
+// emit — runs the job; state.loading is true as soon as it returns
+bus.emit(loadUser("1"));
+```
+
+`cancel` is sent when the handler settles, not at the moment of the abort. A handler that stops on `ctx.signal` (as `fetch` does) settles at once. A handler that ignores the signal sends `cancel` when it finishes, and one that never finishes sends nothing.
+
+**Limit: policies.** A policy such as `latest`, `leading`, `throttle` or `queue` wraps the handler, inside the job. The job does not know what the policy decides, so `pending` is sent for every call. A call that the policy drops, and a run that `latest` replaces, then close with `success(undefined)`, not with `cancel`. A flag set by `pending` is exact for a job without a policy, and for an abort of the task or of its parent. With a policy, count the calls or use the result of `emit`.
 
 ## Mount domains with modules
 

package/docs/cancel-stale-requests.md

@@ -0,0 +1,111 @@
+# Cancel stale requests and fix race conditions
+
+Read this page if an older response can overwrite a newer one: a search box that shows the results of the previous query, a filter that flickers, a form that submits twice. It shows the cause, the fix with `latest`, and how to add a pause, a retry and a timeout. It needs only the bus from the [README](../README.md).
+
+## See the problem
+
+A user types `ab`, then `abc`. Two requests start. If the one for `ab` is slower, it finishes last and its results replace the right ones.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// Without a policy every "search" starts its own request, and the slowest one wins.
+bus.on("search", async (query) => {
+  const items = await api.search(query);
+  bus.emit("results", items);
+});
+```
+
+Checking a counter by hand (`if (id !== lastId) return`) hides the old result, but the old request still runs. Calling `controller.abort()` by hand works, but you must keep the controller somewhere and abort it before each new call.
+
+## Keep only the latest request
+
+Wrap the handler in `latest`. A new `"search"` aborts the task of the previous one, and an aborted task delivers no result.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer "search" aborts the older run
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    // signal: pass it on so the browser cancels the request, not only drops the result
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+
+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`. Without it, `latest` still ignores the old result, but the request keeps running.
+
+Result: `emit("search", "ab")` followed by `emit("search", "abc")` shows only the results for `abc`, and the request for `ab` is cancelled.
+
+## Wait for a pause in typing
+
+Add `debounce` outside `latest`. The search starts after 300 ms without a new keystroke.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+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);
+});
+
+// debounce: run after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+```
+
+## Retry a failed request and limit its time
+
+Use `retry` and `timeout` around the request. The pause grows with each attempt.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { backoff, retry, timeout } from "nanoeffects/effects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// timeout: abort one attempt after 5 s
+const searchOnce = timeout(5000, (query, { signal }) => api.search(query, { signal }));
+
+// 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 }),
+});
+
+// latest: a newer search aborts the whole retry chain
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await ctx.run(searchWithRetry, query); // ctx.run: a child task, aborted with this one
+    ctx.emit("results", items);
+  }),
+);
+```
+
+## Pick another policy for another race
+
+| Situation | Policy |
+| --------- | ------ |
+| Only the newest result matters (search, filter, tab switch) | `latest` |
+| A second click while the first call runs must be ignored (submit, pay) | `leading` |
+| Every call must run, one after another (save, upload) | `queue` |
+| Calls come in bursts and you want one at the end | `debounce` |
+| Calls come in bursts and you want one per period | `throttle` |
+| Each user or item has its own race | add `{ key }`, for example `latest(handler, { key })` |
+
+All policies and their options: [Policies](policies.md). The same step by step in a form: [Build a sign-up form in React](react.md).

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

@@ -217,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
 

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 |
@@ -318,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/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).