nanoeffects 0.28.0 → 0.30.1

package/llms.txt

@@ -9,56 +9,59 @@ 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`.
-- `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
+- 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, commands and modules, step by step
+- [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`
 
 ## Domain logic and stores
 
-- [Actions, jobs and modules](docs/actions.md): `createAction`, `createAction`, `createJob`, `createModule`
+- [Actions, jobs and modules](docs/actions.md): `createAction` (with or without a handler), `createJob`, `createModule`
 - [Connect Redux, Zustand, MobX, or Pinia](docs/stores.md): the Redux middleware and callbacks of other stores
-- [Use nanoeffects with React Query and SWR](docs/query-libraries.md): call a command from `queryFn` or the SWR fetcher; `signalPlugin` passes the abort of the library to the task
+- [Use nanoeffects with React Query, SWR and RTK Query](docs/query-libraries.md): call an action from `queryFn` or the SWR fetcher; `signalPlugin` passes the abort of the library to the task; `fromSignal` clients, a live stream into the cache with `events`, refetch on a bus event
 - [Stop work on a server when the client leaves](docs/server.md): one `AbortController` for each request or socket, `signalPlugin`, a clean shutdown, and a queue worker; Fastify examples
 - [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 command, 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
 
-- [TypeScript in many files](docs/typescript.md): keep the types of the bus in commands and modules
+- [TypeScript in many files](docs/typescript.md): keep the types of the bus in actions and modules
 
 ## Coming from another library
 
 - [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
-- [Turn events into Observables](docs/observable.md): `createObserve`, `Subject`
+- [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.28.0",
+	"version": "0.30.1",
 	"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,12 +242,23 @@
 		{
 			"name": "signal (plugin)",
 			"path": "dist/signal.js",
-			"limit": "0.6 kB"
+			"limit": "0.7 kB"
 		},
 		{
 			"name": "context (plugin)",
 			"path": "dist/context.js",
-			"limit": "0.2 kB"
+			"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)",
@@ -261,7 +278,7 @@
 		{
 			"name": "observable",
 			"path": "dist/observable.js",
-			"limit": "0.5 kB"
+			"limit": "0.85 kB"
 		},
 		{
 			"name": "react",
@@ -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": "1.6 kB"
 		},
 		{
 			"name": "dev (production)",

package/skills/nanoeffects/SKILL.md

@@ -26,7 +26,7 @@ Do not write the setup by hand. `npm create nanoeffects@latest my-app -- --templ
 
 - `vanilla`, `react`: JavaScript, one search handler with `debounce` and `latest`.
 - `vanilla-ts`, `react-ts`: the same apps in TypeScript.
-- `domains-ts`: React and TypeScript with the logic split by domain (commands, a job, modules). Pick it for an app with several features.
+- `domains-ts`: React and TypeScript with the logic split by domain (actions, a job, modules). Pick it for an app with several features.
 
 In an existing project, start from `docs/cancel-stale-requests.md` (races) or `docs/guide.md`.
 
@@ -38,7 +38,7 @@ In an existing project, start from `docs/cancel-stale-requests.md` (races) or `d
 - Effects take `ctx` first: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`. The wrapper form is `retry(fn, options)`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
 - Import each part from its path: `nanoeffects`, `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/react`.
-- `bus.emit(command(payload))` returns the command's result. Plain events return nothing.
+- `bus.emit(action(payload))` returns the action's result. Plain events return nothing.
 - The bus keeps no values: an event emitted before a listener exists is lost. `useEventState(event, initial)` (`nanoeffects/react`) is state of one component, not a store. Share a value through a Context provider at the root or a state manager.
 
 ## Where to read more

package/dist/bus-DlpEluzd.js

@@ -1 +0,0 @@
-import{d as e,n as t,o as n,r}from"./context-UcmrAIhP.js";import{n as i,t as a}from"./event-DVcW0mME.js";const o=()=>{let e={},t={},n=n=>(t[n]=void 0,e[n]??=/* @__PURE__ */ new Map,e[n]),r=(e,t)=>{let r=n(e),i=r.get(t)??0;i>1?r.set(t,i-1):t?r.delete(t):r.clear()},i=()=>{e={},t={}},a=n=>n===void 0?Object.keys(e).flatMap(a):(t[n]??=[...e[n]??[]].flatMap(([e,t])=>Array(t).fill(e)),t[n]);return{get:a,add:(e,t)=>{let i=n(e);return i.set(t,(i.get(t)??0)+1),()=>r(e,t)},remove:r,clear:i}},s=Symbol(),c=(e,t,n)=>{let r={type:t,payload:n};return Object.defineProperty(r,s,{value:e,enumerable:!1}),r},l=e=>{if(typeof e==`function`)return e;if(typeof e==`object`&&e&&s in e)return e[s]},u=(e,t,n)=>Reflect.apply(e,null,[t,n]),d=(s={})=>{let c=o(),d=(e,t)=>c.add(a(e),t),f=(e,t)=>{let n=d(e,(e,r)=>(n(),t(e,r)));return n},p=(e,t)=>{e===void 0?c.clear():c.remove(a(e),t)},m=e=>t({event:e,bus:g,tracer:s.trace,parent:{ref:r()}}).ctx,h=(t,n)=>{let{onError:r}=s,i=m(n);if(!r){t(n.payload,i);return}let a=t=>{try{r(t,n)}catch(t){e(`onError failed`,t)}};try{let e=t(n.payload,i);typeof e?.then==`function`&&Promise.resolve(e).catch(a)}catch(e){a(e)}},g={get:c.get,on:d,off:p,once:f,emit:(e,t)=>{let r=a(e),o=i(e,t),d={type:r,payload:o},f=l(e);f||=g.actions?.bound?.(r);let p=[...c.get(r),...c.get(`*`)];p.length===0&&!f&&s.onUnhandled?.(d);for(let e of p)h(e,d);if(f){let e=m(d),t=g.actions?.run??u;return n(e,`command`,()=>t(f,o,e))}},use:e=>e(g),ctx:s.context,trace:s.trace};return g};export{d as n,c as r,l as t};

package/dist/context-UcmrAIhP.js

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

package/dist/context-types-hCKgU8sC.d.ts

@@ -1,14 +0,0 @@
-import { C as ContextOf, H as EventMap } from "./action-creator-CcAEvUnw.js";
-//#region src/core/context-types.d.ts
-/** What a function that makes the fields of a task gets to see. */
-type ContextTask = {
-  type: string;
-  payload?: unknown;
-};
-/**
- * `unknown` when none of the `fields` is already a context field of the bus,
- * else `never`: the call does not compile. Used as `bus: Bus<E> & NoClash<…>`.
- */
-type NoClash<Fields extends object, E extends EventMap> = [keyof Fields & keyof ContextOf<E>] extends [never] ? unknown : never;
-//#endregion
-export { NoClash as n, ContextTask as t };

package/docs/scope.md

@@ -1,266 +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)`.
-
-## 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 command 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, command 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, the function gets the signal
-  const user = await retry(ctx, ({ signal }) => fetchUser(id, { 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).