nanoeffects 0.29.0 → 0.31.0

package/llms.txt

@@ -9,23 +9,23 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `graphLogger`, `tracePlugin`), `nanoeffects/guard` (`loopGuardPlugin`), `nanoeffects/dev`.
 - `bus.emit(action(payload))` runs the action's handler and returns its result. Plain events return nothing.
 
 ## Start here
 
 - [Guide](docs/guide.md): bus, handler context, policies, effects, actions and modules, step by step
+- [Common tasks](docs/recipes.md): the problem, a short solution and a link for each common task (a race, a double submit, a flaky network, a store, a framework), simplest first
 - [Start a project from a template](docs/starter.md): `npm create nanoeffects` makes a Vite project (`vanilla`, `react`, `vue-ts`, `svelte-ts` and others, in JavaScript or TypeScript) with a bus, `debounce` and `latest`
-- [Why nanoeffects exists](docs/motivation.md): logic and side effects outside UI components as plain async functions, no dependencies and no global state for SDKs and Module Federation, and why not redux-saga, RxJS, Redux or Effector
+- [Why nanoeffects exists](docs/motivation.md): logic and side effects outside UI components as plain async functions, DI by context, and no dependencies and no global state for micro-frontends and Module Federation
 - [Package entries](docs/package.md): which import holds what
-- [Stability](docs/stability.md): which entries are stable or unstable, what a breaking change is, the supported Node, TypeScript and framework versions, the call forms that stay
 - [Plugins](docs/plugins.md): every plugin of a bus, what `bus.use` returns, and the order to use them in
 
 ## Async UI and unreliable networks
 
 - [Policies](docs/policies.md): `latest`, `leading`, `debounce`, `throttle`, `queue`, and `key`; `withPolicy` makes one a plain function without a bus
 - [Cancel stale requests and fix race conditions](docs/cancel-stale-requests.md): an older response overwrites a newer one; `latest`, `debounce`, `retry`, `timeout` in one recipe
-- [Debounce a request and abort the previous one](docs/debounce-and-abort.md): `debounce` outside, `latest` inside, and when to use `throttle`
+- [Pause between requests](docs/debounce-and-abort.md): `debounce` outside, `latest` inside, and when to use `throttle`
 - [Prevent a double submit](docs/prevent-double-submit.md): `leading`, one run per item with `key`, retry only on network errors
 - [Effects and cancellation](docs/effects.md): `retry`, `timeout`, `poll`, `take`, `all`, `race`, `backoff`
 - [Errors and unheard events](docs/errors.md): `onError`, `onUnhandled`
@@ -39,10 +39,10 @@ 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; `useEventState` shows an event as state, `usePolicy` keeps a debounced handler between renders
 - [Build a chat with entities, features, modules and a small server](docs/chat-example.md): rooms, a history under `latest`, a send under `queue` and `retry`, a search with `allSettled` and `timeout`, new messages polled with `poll`
 - [Build a chat widget that listens only while it is open](docs/chat-widget.md): a bot widget for a site; opening mounts a module (handlers, polling, Escape), closing unmounts it and aborts running requests
+- [Examples](docs/examples.md): playgrounds, bigger projects, backend examples, recipes and TypeScript projects that live in `examples/`
 - [Use nanoeffects in a Vue app](docs/vue.md): `vuePlugin` adds `watchEmitter` (a value of a component to the bus) and `useEventRef` (an event as a ref)
 - [Use nanoeffects in a Svelte app](docs/svelte.md): `sveltePlugin` adds `eventStore` (an event as a Svelte store)
-- [Context fields](docs/context.md): put a store or client on every task
-- [Scopes](docs/scope.md): fields for one action, job, module or `emit`, and a way to replace them in a test
+- [Working with context](docs/context.md): put a store or client on every task, and give fields to one action, job, module or `emit` with a scope
 - [Use the bus from a class](docs/oop.md): `Emitter`, `extendBus`, `@WithBus`, `@On`, `@Once`, and `dispose()` for the subscriptions of an instance
 
 ## TypeScript
@@ -53,12 +53,15 @@ Rules that generated code often gets wrong:
 
 - [Coming from redux-saga](docs/migrating-from-saga.md)
 - [Coming from Effector](docs/migrating-from-effector.md)
-- [Coming from mitt, nanoevents or EventEmitter](docs/migrating-from-mitt.md): the same calls, plus cancellation for async handlers
+- [Coming from mitt and nanoevents](docs/migrating-from-mitt.md): the same calls, plus cancellation for async handlers
 - [Use nanoeffects next to RxJS](docs/migrating-from-rxjs.md)
 
 ## Reference
 
 - [Semantics](docs/semantics.md): exact rules of emit, abort and ordering
-- [Trace tasks](docs/tracing.md): loggers, Redux DevTools, the `notrace` build
+- [Keep the signal through a handler](docs/pass-the-signal.md): every way a policy handler loses `ctx.signal`, and the lint rules and `devPlugin` check that find it
+- [Trace tasks](docs/tracing.md): loggers, Redux DevTools, `graphLogger`, the `notrace` build
+- [Find and cut event loops](docs/debugging-loops.md): symptoms, `graphLogger`, the graph as Mermaid, Graphviz or JSON, Redux DevTools
+- [Cut a loop with loopGuardPlugin](docs/loop-guard.md): limits on repeats, depth and emits from outside
 - [Turn events into Observables](docs/observable.md): `createObserve`, `Subject`, `events` (an event as a `for await` loop)
 - [Hot reload and development diagnostics](docs/hmr.md): `devPlugin`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.29.0",
+	"version": "0.31.0",
 	"description": "Business logic and side effects outside UI components, as plain async functions. Tiny, no dependencies.",
 	"keywords": [
 		"event-bus",
@@ -35,7 +35,7 @@
 	"bugs": {
 		"url": "https://github.com/nanoeffects/nanoeffects/issues"
 	},
-	"homepage": "https://github.com/nanoeffects/nanoeffects#readme",
+	"homepage": "https://nanoeffects.github.io/nanoeffects/",
 	"engines": {
 		"node": ">=18"
 	},
@@ -106,6 +106,10 @@
 			"types": "./dist/oop.d.ts",
 			"import": "./dist/oop.js"
 		},
+		"./guard": {
+			"types": "./dist/guard.d.ts",
+			"import": "./dist/guard.js"
+		},
 		"./trace": {
 			"types": "./dist/trace.d.ts",
 			"import": "./dist/trace.js"
@@ -160,6 +164,7 @@
 		"templates:check": "node scripts/templates-check.mjs",
 		"docs:check": "node scripts/docs-check.mjs",
 		"llms:check": "node scripts/llms-full.mjs --check",
+		"docs:site": "pnpm --filter nanoeffects-docs-site build",
 		"smoke": "node scripts/smoke.mjs && node scripts/smoke.mjs --notrace",
 		"consumer-check": "node scripts/consumer-check.mjs"
 	},
@@ -177,6 +182,7 @@
 		"@types/react-dom": "^19.3.0",
 		"@types/ws": "^8.18.2",
 		"@vitejs/plugin-react": "^6.1.2",
+		"acorn": "^8.19.0",
 		"archunit": "^2.5.4",
 		"fastify": "^5.12.7",
 		"happy-dom": "^21.0.4",
@@ -216,7 +222,7 @@
 		{
 			"name": "policies (all)",
 			"path": "dist/policies.js",
-			"limit": "2.7 kB"
+			"limit": "2.71 kB"
 		},
 		{
 			"name": "effects (all)",
@@ -236,13 +242,24 @@
 		{
 			"name": "signal (plugin)",
 			"path": "dist/signal.js",
-			"limit": "0.7 kB"
+			"limit": "0.8 kB"
 		},
 		{
 			"name": "context (plugin)",
 			"path": "dist/context.js",
 			"limit": "0.4 kB"
 		},
+		{
+			"name": "guard (plugin)",
+			"path": "dist/guard.js",
+			"limit": "1 kB"
+		},
+		{
+			"name": "trace: graphLogger",
+			"path": "dist/trace.js",
+			"import": "{ graphLogger }",
+			"limit": "5 kB"
+		},
 		{
 			"name": "oop (class entry)",
 			"path": "dist/oop.js",
@@ -269,7 +286,7 @@
 			"ignore": [
 				"react"
 			],
-			"limit": "1.24 kB"
+			"limit": "1.25 kB"
 		},
 		{
 			"name": "svelte",
@@ -290,7 +307,7 @@
 		{
 			"name": "dev",
 			"path": "dist/dev.js",
-			"limit": "1 kB"
+			"limit": "2.2 kB"
 		},
 		{
 			"name": "dev (production)",

package/dist/context-DtUnzC-1.js

@@ -1 +0,0 @@
-import{t as e}from"./onAbort-BgMfspK4.js";const t=t=>{let n=new AbortController;return{controller:n,unlink:e({signal:t},e=>n.abort(e))}},n=Symbol(),r=typeof __NANOEFFECTS_TRACE__>`u`||__NANOEFFECTS_TRACE__,i=/* @__PURE__ */ new WeakMap;let a;const o=()=>a,s=()=>{},c=(e,t,n,a)=>{let o=r&&i.get(e);o&&o.tracer.report(o.ref,t,n,a)},l=(e,t)=>{let n=r&&i.get(e);n&&n.tracer.rename?.(n.ref,t)},u=(e,t)=>{let n=r&&i.get(e);return n?n.tracer.settler(n.ref,t):s},d=(e,t,n)=>{let a=r&&i.get(e);return a?a.tracer.run(a.ref,t,e.signal,n):n()},f=Symbol(`nanoeffects.addContext`),p=(e,t)=>typeof e==`function`?e(t):e,m=({event:o,bus:c,tracer:l,parent:u})=>{let{controller:h,unlink:g}=t(u?.signal),{signal:_}=h,v=r&&l?{tracer:l,ref:l.task(o,u?.ref)}:void 0,y=(...e)=>{if(_.aborted&&!S[n])return;let t=c?.emit,r=a;a=v?.ref;try{return t?.(...e)}finally{a=r}},b=(...t)=>{if(_.aborted)return s;let n=c?.on,r=n?.(...t);if(!r)return s;let i=e({signal:_},r);return()=>{i(),r()}},x=async(e,...t)=>{_.throwIfAborted();let n=t[0],r=m({event:{type:o.type,payload:n},bus:c,tracer:l,parent:{signal:_,ref:v?.ref}});try{return await d(r.ctx,`run`,()=>e(n,r.ctx))}finally{r.unlink()}},S={...p(c?.ctx,o),type:o.type,payload:o.payload,signal:_,abort:e=>h.abort(e),emit:y,on:b,off:c?.off??s,run:x,[f]:c?.addContext};return c?.addContext?.(S),v&&i.set(S,v),{ctx:S,unlink:g}},h=(e,t)=>{let n=r?i.get(e):void 0;return m({event:{type:t??e.type??``,payload:e.payload},bus:{emit:e.emit,on:e.on,off:e.off,ctx:e,addContext:Reflect.get(e,f)},tracer:n?.tracer,parent:{signal:e.signal,ref:n?.ref}})};export{l as a,r as c,h as i,n as l,m as n,d as o,o as r,c as s,u as t};

package/docs/scope.md

@@ -1,278 +0,0 @@
-# Pin context fields to an action, a module or a call
-
-Optional, for domain logic. Use it when one action needs its own client, one module its own logger, or one test its own fake, and a field on the whole bus ([context fields](context.md)) is too wide.
-
-A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`, `logger`), except one: `$effects`. Its functions take `{ signal }` as the first parameter, like `retry(ctx, fn)`, and go on `ctx` bound to the task, so you call `ctx.fetchJson(url)` instead of `fetchJson(ctx, url)`.
-
-You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
-
-## On this page
-
-- [Turn scopes on](#turn-scopes-on)
-- [Give an action its own fields](#give-an-action-its-own-fields)
-- [Bind an effect to the task](#bind-an-effect-to-the-task)
-- [Replace a field for one call](#replace-a-field-for-one-call)
-- [Give an action, a job or a module its own fields](#give-an-action-a-job-or-a-module-its-own-fields)
-- [Which value wins](#which-value-wins)
-- [Keep a generic effect generic](#keep-a-generic-effect-generic)
-- [Type the fields (optional)](#type-the-fields-optional)
-- [Limits](#limits)
-
-## Turn scopes on
-
-Scopes are a plugin, so a bus that does not use them pays nothing.
-
-```js
-// bus.js
-import { createBus } from "nanoeffects";
-import { scopePlugin } from "nanoeffects/scope";
-
-// scopePlugin — makes the scopes below work on this bus; returns the same bus
-export const bus = createBus().use(scopePlugin());
-```
-
-The bus is in one file and the actions in files named after their domain, so the next example imports `bus` from here. Each section after it keeps its own `bus.js` and domain file, as if it were an app of its own.
-
-- Without `scopePlugin` a scope is **ignored**: no error and no warning. If a field is missing from `ctx`, check this first.
-- Use it in any order with the other plugins: a scope wins over `effectsPlugin`, `contextPlugin` and `createBus({ context })`.
-
-## Give an action its own fields
-
-<!-- docs-check: continue -->
-
-```js
-// user.js
-import { createAction } from "nanoeffects/actions";
-
-// createAction — third argument is the scope of this action
-export const getUser = createAction(
-  "user/get",
-  (id, { api, cache }) => {
-    // api and cache are on ctx for this action only
-    return cache.get(id) ?? api.getUser(id);
-  },
-  { api, cache: new Map() },
-);
-```
-
-```js
-import { bus } from "./bus";
-import { getUser } from "./user";
-
-const user = await bus.emit(getUser("1")); // the handler has api and cache
-```
-
-The listeners of `"user/get"` get the same fields when the action is emitted, because the fields belong to the call.
-
-## Bind an effect to the task
-
-An effect is a function with `{ signal }` as its first parameter. In `$effects` it is bound to the task, so it stops with the task.
-
-```js
-// feed.js
-import { createAction } from "nanoeffects/actions";
-import { delay, race } from "nanoeffects/effects";
-
-// your own effect: first parameter is the task (only its signal is used)
-const fetchJson = (ctx, url) =>
-  fetch(url, { signal: ctx.signal }).then((response) => response.json());
-
-export const loadFeed = createAction(
-  "feed/load",
-  (url, { fetchJson, race, delay }) =>
-    // race, delay, fetchJson — bound to this task: no ctx argument
-    race({
-      feed: () => fetchJson(url),
-      timeout: () => delay(5000),
-    }),
-  // $effects — built-in and your own functions share one object
-  { $effects: { fetchJson, race, delay } },
-);
-```
-
-```js
-// bus.js
-import { createBus } from "nanoeffects";
-import { scopePlugin } from "nanoeffects/scope";
-
-export const bus = createBus().use(scopePlugin());
-```
-
-```js
-import { bus } from "./bus";
-import { loadFeed } from "./feed";
-
-const result = await bus.emit(loadFeed("/feed"));
-```
-
-- Put in `$effects` only functions that take `ctx` first. A plain function (a formatter, a logger) belongs in `context`.
-- A function under any other key is copied as it is; a function in `$effects` is bound.
-- `$effects` is the one name with a meaning. A field called `effects` is an ordinary field: `{ effects: { retries: 3 } }` puts that object on `ctx`, and nothing in it is bound.
-
-## Replace a field for one call
-
-The second argument of `emit` is a scope for the tasks of **that** call. It is the usual way to give a test a fake.
-
-```js
-// bus.js
-import { createBus } from "nanoeffects";
-import { scopePlugin } from "nanoeffects/scope";
-
-export const bus = createBus().use(scopePlugin());
-```
-
-```js
-// user.js
-import { createAction } from "nanoeffects/actions";
-
-export const getUser = createAction(
-  "user/get",
-  (id, { api }) => api.getUser(id),
-  { api },
-);
-```
-
-```js
-import { bus } from "./bus";
-import { getUser } from "./user";
-
-// the real api for this call
-await bus.emit(getUser("1"));
-
-// the second argument — a fake api, for this call only
-const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
-await bus.emit(getUser("1"), { api: fakeApi });
-```
-
-Rules for the second argument:
-
-- It works with the call of an action (`emit(getUser("1"), scope)`, `ctx.emit(loaded(user), scope)`).
-- It does not work with the string form: in `emit("user/get", payload)` the second argument is the payload.
-- It can replace `$effects` too: `{ $effects: { delay: instantDelay } }`.
-- Fields of the library (`signal`, `emit`, …) in it are ignored.
-
-## Give an action, a job or a module its own fields
-
-```js
-// user.js
-import { createAction, createJob } from "nanoeffects/actions";
-
-// createAction — the listeners of this action's calls get the fields
-export const userLoaded = createAction("user/loaded", { store });
-
-// createJob — the scope is the fourth argument, after the outcomes;
-// the handler and the listeners of the outcome get its fields
-export const loadUser = createJob(
-  "user/load",
-  fetchUser,
-  { success: userLoaded, fail: "user/failed" },
-  { logger },
-);
-```
-
-```js
-// audit-module.js
-import { createModule } from "nanoeffects/actions";
-import { userLoaded } from "./user";
-
-// createModule — third argument; everything the module owns gets the fields:
-// m.on listeners, m.handle handlers, m.spawn tasks
-export const auditModule = createModule(
-  "audit",
-  (m) => {
-    m.on(userLoaded, (user, { logger }) => logger.info(user.id));
-  },
-  { logger },
-);
-```
-
-If the outcome action (`success` or `fail`) has a scope of its own, its listeners see the job's fields with the action's own fields over them; the handler of the job sees only the job's.
-
-A module scope does not leak: a listener registered outside the module does not see it.
-
-## Which value wins
-
-When several places set the same field, the strongest one wins:
-
-| Strength | Where it is set |
-| -------- | --------------- |
-| 1 (strongest) | the second argument of `emit` |
-| 2 | the scope of the action or job |
-| 3 | the scope of the module that owns the handler |
-| 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
-
-The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`, `payload`) are never replaced. The name `traceGroupId` is reserved: the tracer reads it, and it is not put on `ctx` ([Follow one flow](tracing.md#follow-one-flow-with-a-tracegroupid)). A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
-
-## Keep a generic effect generic
-
-In `$effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
-
-`effect(fn)`: mark the function where you declare it, then put it in the scope like any other value. No annotation, so a JavaScript editor shows the exact hint too.
-
-```js
-// pick.js
-import { createAction } from "nanoeffects/actions";
-import { effect } from "nanoeffects/scope";
-
-// effect — marks the function, so a scope binds it to the task; the editor keeps its generic
-const first = effect((ctx, items) => items[0]);
-
-export const pick = createAction("pick", (items, { first }) => first(items), {
-  first, // a plain key of the scope, not an entry of `$effects`
-});
-```
-
-Call `effect` where you declare the function, as above, and not inline in the scope: TypeScript does not infer the scope from a generic call written there.
-
-`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `$effects`.
-
-```ts
-import { createAction } from "nanoeffects/actions";
-import type { Effect } from "nanoeffects/effects";
-
-// First — checker-only: how a handler calls the effect (no ctx)
-type First = <T>(items: T[]) => T;
-
-// Effect<First> — the function takes the task first and is typed as First once bound
-const first: Effect<First> = (ctx, items) => items[0];
-
-const pick = createAction(
-  "pick",
-  (id: string, { first }) => first([id]), // string
-  { $effects: { first } },
-);
-```
-
-`Effect<F>` and `effect` change what the checker sees. At run time the function is the same.
-
-## Type the fields (optional)
-
-A handler of an action, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
-
-```ts
-import { createAction } from "nanoeffects/actions";
-
-type User = { id: string; name: string };
-
-const getUser = createAction(
-  "user/get",
-  async (id: string, ctx) => {
-    ctx.cache; // Map<string, User>, from the scope below
-    return ctx.cache.get(id);
-  },
-  { cache: new Map<string, User>() },
-);
-```
-
-- A field of a scope replaces a field of the same name from the bus in the type too.
-- An override in `emit` must match the type of the field it replaces: `emit(getUser("1"), { cache: 1 })` is an error.
-- A field that no scope and no bus declares has no type to check against, so `emit(call, { unknown: 1 })` is an error in TypeScript.
-- `bus.on(creator, fn)` for an action with a scope types `ctx` with its fields.
-
-## Limits
-
-- No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
-- The fields of the bus are not in the handler of an action made with `createAction(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
-- The string form of `emit` takes no scope.
-- `effect(fn)` works only as a value of a scope, not as an entry of `$effects`.
-- A scope on an action, job or module is typed without the events of a bus, so `take` in its `$effects` takes any event name.

package/docs/stability.md

@@ -1,90 +0,0 @@
-# Know what is stable
-
-Use this page to decide what you can rely on. It says which imports are stable, what counts as a breaking change, which versions are supported, and which call forms stay.
-
-## See which entries are stable
-
-A stable entry follows the rules below. An unstable entry can change in any minor release; every change is written in the [CHANGELOG](../CHANGELOG.md), and nothing promises a deprecation period first.
-
-| Import | Status | Note |
-| ------ | ------ | ---- |
-| `nanoeffects` | Stable | `createBus` and the types of a bus |
-| `nanoeffects/effects` | Stable | `retry`, `timeout`, `poll`, `take`, `delay`, `all`, `allSettled`, `race`, `backoff`, `cancellable`, `effectsPlugin` |
-| `nanoeffects/policies` | Stable | `latest`, `leading`, `debounce`, `throttle`, `queue`, `withPolicy` |
-| `nanoeffects/actions` | Stable | `createAction`, `createJob`, `createModule` and their plugins |
-| `nanoeffects/trace` | Stable: the contract | `Tracer`, `Trace`, `TraceEvent`, `TraceLogger`, `Phase`, `EffectName` and `tracePlugin` |
-| `nanoeffects/trace` | Unstable: the tools | `createTracer`, `consoleLogger`, `performanceLogger`, `createTraceRecorder`, `reduxDevtools` and their option types |
-| `nanoeffects/scope` | Unstable | `scopePlugin`, `effect` |
-| `nanoeffects/match` | Unstable | `matchPlugin` |
-| `nanoeffects/signal` | Unstable | `signalPlugin` |
-| `nanoeffects/context` | Unstable | `contextPlugin` |
-| `nanoeffects/oop` | Unstable | `Emitter`, `extendBus`, `On`, `Once`, `WithBus`, `disposeBus` |
-| `nanoeffects/observable` | Unstable | `createObserve`, `Subject` |
-| `nanoeffects/redux` | Unstable | `createEffectsMiddleware` |
-| `nanoeffects/react` | Unstable | `reactPlugin`, `usePolicy` |
-| `nanoeffects/svelte` | Unstable | `sveltePlugin` |
-| `nanoeffects/vue` | Unstable | `vuePlugin` |
-| `nanoeffects/dev` | Unstable | `devPlugin` |
-
-The adapters (`react`, `vue`, `svelte`, `redux`) are unstable because they follow the APIs of other libraries and have had little use. They can become stable after the library has been in use for a while.
-
-## Know what is a breaking change
-
-For a stable entry, these changes are breaking:
-
-- A change in what a call does at run time.
-- A change in a type that stops code that compiled before from compiling.
-- A removed or renamed export.
-
-A stricter type that only finds mistakes in code that was already wrong is not breaking. It ships in a minor release with a note in the CHANGELOG.
-
-These are not covered by the promise:
-
-- Any unstable entry.
-- The text of the messages of `nanoeffects/dev`.
-- The payload details of trace events. The shape of an event (`id`, `parentId`, `rootId`, `type`, `effect`, `phase`) is covered; the contents of `payload` are not.
-
-Before version 1.0.0, a breaking change ships in a minor release under `### Breaking` in the CHANGELOG. From 1.0.0 it ships only in a major release.
-
-A deprecated export keeps working and is removed only in a major release. `RaceStarter` is deprecated: use `StarterOf` instead.
-
-## Check the supported versions
-
-| What | Supported |
-| ---- | --------- |
-| Node.js, the library | 18, 20, 22 and 24 (a smoke test runs the built package on each) |
-| Node.js, the dev tools and the trace in a browser | 22 and newer |
-| TypeScript | 5.9 and 7. The built declaration files are type-checked with TypeScript 5.9 in CI, and the source with TypeScript 7. Older versions are not tested. |
-| React | 18 or newer (`nanoeffects/react`) |
-| Vue | 3.3 or newer (`nanoeffects/vue`) |
-| Svelte | 5 or newer (`nanoeffects/svelte`) |
-
-The library has no dependencies. React, Vue and Svelte are optional peer dependencies of their own entries only.
-
-## Rely on these call forms
-
-`retry`, `timeout` and `poll` have three call forms, and all three stay:
-
-```js
-import { createBus } from "nanoeffects";
-import { race, retry } from "nanoeffects/effects";
-
-const bus = createBus();
-
-bus.on("open", async (id, ctx) => {
-  // with ctx: you pass the context, and the function takes the signal from it
-  const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), { times: 3 });
-
-  // as a starter: a group (race, all, allSettled, timeout) calls it with its child
-  const result = await race(ctx, {
-    user: retry((_, { signal }) => fetchUser(id, { signal }), { times: 3 }),
-  });
-});
-
-// as a Task: a function of (payload, ctx), which bus.on and ctx.run call
-bus.on("reload", retry((id, { signal }) => fetchUser(id, { signal }), { times: 3 }));
-```
-
-The forms are told apart by the arguments: a context first is the form with `ctx`; a function called with a payload and a context is the Task; the same function called by a group with one argument, its child, is the starter. The rule is part of the contract and does not depend on how many parameters your function declares.
-
-`all` and `allSettled` take options only in the form with `ctx`, `all(ctx, effects, { concurrency })`. The form without `ctx` has one argument, so a second one would look like the `ctx` form. `race` takes no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. See [Effects](effects.md#run-several-starters-together).