nanoeffects 0.25.0 → 0.26.0

package/dist/actions.d.ts

@@ -1,6 +1,6 @@
 import { H as PayloadOf, T as EventKey, W as Task, c as WithScope, h as Bus, n as Free, o as Scope, r as FreeActionCreator, t as ActionCreator, z as EventMap } from "./action-creator-Bpa8BUS9.js";
-import { r as Scoped, t as FieldsOfScope } from "./types-DWjyeii7.js";
-import { a as createModule, c as CarryingCalls, d as commandsPlugin, f as createCommand, l as MadeCommand, n as ModuleApi, o as modulePlugin, r as ModuleContext, s as Binding, t as Module, u as bindHandler } from "./module-B5V47MZ0.js";
+import { r as Scoped, t as FieldsOfScope } from "./types-Bkuhnkq6.js";
+import { a as createModule, c as CarryingCalls, d as commandsPlugin, f as createCommand, l as MadeCommand, n as ModuleApi, o as modulePlugin, r as ModuleContext, s as Binding, t as Module, u as bindHandler } from "./module-B6rg5NIb.js";
 import { t as OriginOptions } from "./origin-key-CxK0SkeG.js";
 //#region src/actions/action.d.ts
 type ScopedCreator<P, T extends string, F> = [P] extends [Free] ? FreeActionCreator<T, F> & WithScope<F> : ActionCreator<P, T, PayloadOf<P>, F> & WithScope<F>;

package/dist/dev.d.ts

@@ -1,5 +1,5 @@
 import { J as UnsubscribeCallback, h as Bus, z as EventMap } from "./action-creator-Bpa8BUS9.js";
-import { i as WithApp, n as ModuleApi } from "./module-B5V47MZ0.js";
+import { i as WithApp, n as ModuleApi } from "./module-B6rg5NIb.js";
 //#region src/dev/types.d.ts
 /** The parts of what `modulePlugin` returned that the diagnostics report. */
 type ReportedApp<E extends EventMap> = Pick<ModuleApi<E>, "mount" | "unmount" | "isMounted">;

package/dist/effects.d.ts

@@ -1,5 +1,5 @@
 import { P as WithSignal, W as Task, b as Context, u as Effect, z as EventMap } from "./action-creator-Bpa8BUS9.js";
-import { a as RaceStarter, c as all, d as GroupOptions, f as Starter, i as take, l as ChildOf, m as delay, n as effectsPlugin, o as race, p as StarterOf, r as TakeOptions, s as allSettled, u as EffectContext } from "./plugin-B6UQyoVd.js";
+import { a as RaceStarter, c as all, d as GroupOptions, f as Starter, i as take, l as ChildOf, m as delay, n as effectsPlugin, o as race, p as StarterOf, r as TakeOptions, s as allSettled, u as EffectContext } from "./plugin-D-j1DarG.js";
 //#region src/utils/onAbort.d.ts
 export declare const onAbort: (ctx: {
   signal?: AbortSignal | undefined;

package/dist/{module-B5V47MZ0.d.ts → module-B6rg5NIb.d.ts}

@@ -1,5 +1,5 @@
 import { H as PayloadOf, J as UnsubscribeCallback, W as Task, _ as Command, b as Context, c as WithScope, h as Bus, o as Scope, v as CommandCall, y as Commands, z as EventMap } from "./action-creator-Bpa8BUS9.js";
-import { n as ScopeSlots, r as Scoped, t as FieldsOfScope } from "./types-DWjyeii7.js";
+import { n as ScopeSlots, r as Scoped, t as FieldsOfScope } from "./types-Bkuhnkq6.js";
 //#region src/actions/command.d.ts
 /** What `createCommand` returns: a command that also tells whether an action is of its type. */
 type MadeCommand<P, R, T extends string> = Command<P, R> & {

package/dist/notrace/actions.d.ts

@@ -1,5 +1,5 @@
 import { C as EventKey, F as EventMap, L as PayloadOf, R as Task, _ as Commands, a as Scope, g as CommandCall, h as Command, n as Free, o as WithFields, p as Bus, r as FreeActionCreator, s as WithScope, t as ActionCreator, u as Effects, v as Context, z as UnsubscribeCallback } from "./action-creator-D2CotugT.js";
-import { t as BoundOf } from "./plugin-ks-oNq5n.js";
+import { t as BoundOf } from "./plugin-Dz6hq8Jg.js";
 import { t as OriginOptions } from "./origin-key-CxK0SkeG.js";
 //#region src/scope/types.d.ts
 /**

package/dist/notrace/effects.d.ts

@@ -1,5 +1,5 @@
 import { F as EventMap, M as WithSignal, R as Task, l as Effect, v as Context } from "./action-creator-D2CotugT.js";
-import { a as RaceStarter, c as all, d as GroupOptions, f as Starter, i as take, l as ChildOf, m as delay, n as effectsPlugin, o as race, p as StarterOf, r as TakeOptions, s as allSettled, u as EffectContext } from "./plugin-ks-oNq5n.js";
+import { a as RaceStarter, c as all, d as GroupOptions, f as Starter, i as take, l as ChildOf, m as delay, n as effectsPlugin, o as race, p as StarterOf, r as TakeOptions, s as allSettled, u as EffectContext } from "./plugin-Dz6hq8Jg.js";
 //#region src/utils/onAbort.d.ts
 export declare const onAbort: (ctx: {
   signal?: AbortSignal | undefined;

package/dist/notrace/{plugin-ks-oNq5n.d.ts → plugin-Dz6hq8Jg.d.ts}

@@ -71,7 +71,7 @@ type Starter<T, Child = EffectContext> = (child: Child) => T | PromiseLike<T>;
  * bus.on("open", async (_, ctx) => race(ctx, { load, user }));
  * ```
  */
-type StarterOf$1<E extends EventMap, R = unknown> = Starter<R, Context<E>>;
+type StarterOf<E extends EventMap, R = unknown> = Starter<R, Context<E>>;
 /** Options of `all` and `allSettled`. */
 type GroupOptions = {
   /** At most this many starters run at once; the next starts when one settles. Default: no limit. */
@@ -132,6 +132,7 @@ declare function allSettled<Child, T extends Record<string, Starter<unknown, Chi
 declare function allSettled<Child, const T extends readonly Starter<unknown, Child>[]>(effects: T): (child: Child) => Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
 //#endregion
 //#region src/effects/race.d.ts
+/** @deprecated Use `StarterOf<Events, Result>`; this name goes in 1.0.0. */
 type RaceStarter<T, Child = EffectContext> = Starter<T, Child>;
 /**
  * Runs all starters; first to settle wins, losers are cancelled via `ctx.abort`.
@@ -152,12 +153,12 @@ type RaceStarter<T, Child = EffectContext> = Starter<T, Child>;
  */
 declare function race<C extends {
   signal?: AbortSignal;
-}, T extends Record<string, RaceStarter<unknown, ChildOf<C>>>>(ctx: C, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+}, T extends Record<string, Starter<unknown, ChildOf<C>>>>(ctx: C, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
 declare function race<C extends {
   signal?: AbortSignal;
-}, const T extends readonly RaceStarter<unknown, ChildOf<C>>[]>(ctx: C, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
-declare function race<Child, T extends Record<string, RaceStarter<unknown, Child>>>(effects: T): (child: Child) => Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
-declare function race<Child, const T extends readonly RaceStarter<unknown, Child>[]>(effects: T): (child: Child) => Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+}, const T extends readonly Starter<unknown, ChildOf<C>>[]>(ctx: C, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+declare function race<Child, T extends Record<string, Starter<unknown, Child>>>(effects: T): (child: Child) => Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+declare function race<Child, const T extends readonly Starter<unknown, Child>[]>(effects: T): (child: Child) => Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
 //#endregion
 //#region src/effects/take.d.ts
 type TakeOptions<P> = {
@@ -259,9 +260,9 @@ type Helpers = Effects;
  * The effects as a handler sees them: the built-in ones keep their hand-written
  * types, any other loses its first parameter, or has the type `Effect<F>` says.
  */
-type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H]: K extends keyof Bound<E, StarterOf<H, E>> ? H[K] extends Supported[K] ? Bound<E, StarterOf<H, E>>[K] : BoundForm<H[K]> : BoundForm<H[K]>; };
+type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H]: K extends keyof Bound<E, BoundStarter<H, E>> ? H[K] extends Supported[K] ? Bound<E, BoundStarter<H, E>>[K] : BoundForm<H[K]> : BoundForm<H[K]>; };
 /** What a starter of a bound `race` / `all` / `allSettled` gets: the context of its child, with the same bound effects. */
-type StarterOf<H extends Helpers, E extends EventMap> = Context<E> & BoundOf<H, E>;
+type BoundStarter<H extends Helpers, E extends EventMap> = Context<E> & BoundOf<H, E>;
 /**
  * Puts the effects you pass on the context of every task of the bus, bound to
  * that task, so a handler can write `({ race })` instead of `race(ctx, …)`.
@@ -285,4 +286,4 @@ type StarterOf<H extends Helpers, E extends EventMap> = Context<E> & BoundOf<H,
  */
 declare const effectsPlugin: <H extends Helpers>(helpers: H) => <E extends EventMap>(bus: Bus<E> & NoClash<BoundOf<H, E>, E>) => Bus<E & WithContext<BoundOf<H, E>>>;
 //#endregion
-export { RaceStarter as a, all as c, GroupOptions as d, Starter as f, take as i, ChildOf as l, delay as m, effectsPlugin as n, race as o, StarterOf$1 as p, TakeOptions as r, allSettled as s, BoundOf as t, EffectContext as u };
+export { RaceStarter as a, all as c, GroupOptions as d, Starter as f, take as i, ChildOf as l, delay as m, effectsPlugin as n, race as o, StarterOf as p, TakeOptions as r, allSettled as s, BoundOf as t, EffectContext as u };

package/dist/{plugin-B6UQyoVd.d.ts → plugin-D-j1DarG.d.ts}

@@ -65,7 +65,7 @@ type Starter<T, Child = EffectContext> = (child: Child) => T | PromiseLike<T>;
  * bus.on("open", async (_, ctx) => race(ctx, { load, user }));
  * ```
  */
-type StarterOf$1<E extends EventMap, R = unknown> = Starter<R, Context<E>>;
+type StarterOf<E extends EventMap, R = unknown> = Starter<R, Context<E>>;
 /** Options of `all` and `allSettled`. */
 type GroupOptions = {
   /** At most this many starters run at once; the next starts when one settles. Default: no limit. */
@@ -126,6 +126,7 @@ declare function allSettled<Child, T extends Record<string, Starter<unknown, Chi
 declare function allSettled<Child, const T extends readonly Starter<unknown, Child>[]>(effects: T): (child: Child) => Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
 //#endregion
 //#region src/effects/race.d.ts
+/** @deprecated Use `StarterOf<Events, Result>`; this name goes in 1.0.0. */
 type RaceStarter<T, Child = EffectContext> = Starter<T, Child>;
 /**
  * Runs all starters; first to settle wins, losers are cancelled via `ctx.abort`.
@@ -146,12 +147,12 @@ type RaceStarter<T, Child = EffectContext> = Starter<T, Child>;
  */
 declare function race<C extends {
   signal?: AbortSignal;
-}, T extends Record<string, RaceStarter<unknown, ChildOf<C>>>>(ctx: C, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+}, T extends Record<string, Starter<unknown, ChildOf<C>>>>(ctx: C, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
 declare function race<C extends {
   signal?: AbortSignal;
-}, const T extends readonly RaceStarter<unknown, ChildOf<C>>[]>(ctx: C, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
-declare function race<Child, T extends Record<string, RaceStarter<unknown, Child>>>(effects: T): (child: Child) => Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
-declare function race<Child, const T extends readonly RaceStarter<unknown, Child>[]>(effects: T): (child: Child) => Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+}, const T extends readonly Starter<unknown, ChildOf<C>>[]>(ctx: C, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+declare function race<Child, T extends Record<string, Starter<unknown, Child>>>(effects: T): (child: Child) => Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+declare function race<Child, const T extends readonly Starter<unknown, Child>[]>(effects: T): (child: Child) => Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
 //#endregion
 //#region src/effects/take.d.ts
 type TakeOptions<P> = {
@@ -253,9 +254,9 @@ type Helpers = Effects;
  * The effects as a handler sees them: the built-in ones keep their hand-written
  * types, any other loses its first parameter, or has the type `Effect<F>` says.
  */
-type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H]: K extends keyof Bound<E, StarterOf<H, E>> ? H[K] extends Supported[K] ? Bound<E, StarterOf<H, E>>[K] : BoundForm<H[K]> : BoundForm<H[K]>; };
+type BoundOf<H extends Helpers, E extends EventMap> = { [K in keyof H]: K extends keyof Bound<E, BoundStarter<H, E>> ? H[K] extends Supported[K] ? Bound<E, BoundStarter<H, E>>[K] : BoundForm<H[K]> : BoundForm<H[K]>; };
 /** What a starter of a bound `race` / `all` / `allSettled` gets: the context of its child, with the same bound effects. */
-type StarterOf<H extends Helpers, E extends EventMap> = Context<E> & BoundOf<H, E>;
+type BoundStarter<H extends Helpers, E extends EventMap> = Context<E> & BoundOf<H, E>;
 /**
  * Puts the effects you pass on the context of every task of the bus, bound to
  * that task, so a handler can write `({ race })` instead of `race(ctx, …)`.
@@ -279,4 +280,4 @@ type StarterOf<H extends Helpers, E extends EventMap> = Context<E> & BoundOf<H,
  */
 declare const effectsPlugin: <H extends Helpers>(helpers: H) => <E extends EventMap>(bus: Bus<E> & NoClash<BoundOf<H, E>, E>) => Bus<E & WithContext<BoundOf<H, E>>>;
 //#endregion
-export { RaceStarter as a, all as c, GroupOptions as d, Starter as f, take as i, ChildOf as l, delay as m, effectsPlugin as n, race as o, StarterOf$1 as p, TakeOptions as r, allSettled as s, BoundOf as t, EffectContext as u };
+export { RaceStarter as a, all as c, GroupOptions as d, Starter as f, take as i, ChildOf as l, delay as m, effectsPlugin as n, race as o, StarterOf as p, TakeOptions as r, allSettled as s, BoundOf as t, EffectContext as u };

package/dist/scope.d.ts

@@ -1,5 +1,5 @@
 import { P as WithSignal, a as EmitScope, d as Effects, f as Signaled, h as Bus, o as Scope, u as Effect, z as EventMap } from "./action-creator-Bpa8BUS9.js";
-import { n as ScopeSlots, r as Scoped } from "./types-DWjyeii7.js";
+import { n as ScopeSlots, r as Scoped } from "./types-Bkuhnkq6.js";
 //#region src/scope/effect.d.ts
 /**
  * Marks a function whose first parameter is `{ signal }` as an effect, so that

package/dist/{types-DWjyeii7.d.ts → types-Bkuhnkq6.d.ts}

@@ -1,5 +1,5 @@
 import { d as Effects, o as Scope, s as WithFields, z as EventMap } from "./action-creator-Bpa8BUS9.js";
-import { t as BoundOf } from "./plugin-B6UQyoVd.js";
+import { t as BoundOf } from "./plugin-D-j1DarG.js";
 //#region src/scope/types.d.ts
 /**
  * The slots `scopePlugin` fills for `modulePlugin`. They are not on `Bus`: a bus

package/docs/README.md

@@ -42,6 +42,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 - [TypeScript in many files](typescript.md) — keep the types of the bus in commands and modules
 - [Errors and unheard events](errors.md)
 - [Package entries](package.md) — which import holds what
+- [Stability](stability.md) — which entries are stable, what is breaking, supported versions
 - [Plugins](plugins.md) — every plugin of a bus, what it returns, and the order to use them in
 - [Tracing](tracing.md) — loggers, Redux DevTools, `notrace`
 - [Observable](observable.md) — events as TC39 Observables

package/docs/effects.md

@@ -347,7 +347,7 @@ bus.on("open", async (id, ctx) => {
 });
 ```
 
-The same call with a payload and a context, `(payload, ctx)`, is the Task that `bus.on` and `ctx.run` use, and it does not change.
+The same call with a payload and a context, `(payload, ctx)`, is the Task that `bus.on` and `ctx.run` use, and it does not change. `retry`, `timeout` and `poll` therefore have three call forms: with `ctx`, as a Task, and as a starter. All three stay; [Stability](stability.md#rely-on-these-call-forms) says how they are told apart.
 
 **`all`, `allSettled` and `race` without `ctx` are starters too**, so a group nests in another group with no wrapper. Load two things, but give up after five seconds:
 
@@ -396,7 +396,7 @@ bus.on("sync", async (ids, ctx) => {
 });
 ```
 
-The result has the same order and shape as without the option. If one starter of `all` fails, the running ones are cancelled and the waiting ones are never called. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. A group starter inside another group takes no options; write `(child) => all(child, effects, { concurrency: 5 })` there.
+The result has the same order and shape as without the option. If one starter of `all` fails, the running ones are cancelled and the waiting ones are never called. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. The form without `ctx` takes no options, because a second argument would look like the form with `ctx`, so a group starter inside another group takes none; write `(child) => all(child, effects, { concurrency: 5 })` there.
 
 
 **A starter gets the context of its own child task.** Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the race ends, `child` is aborted and stops exactly this effect. The outer `ctx` is only for `race` itself. Your own API takes the signal in its options: `({ signal }) => fetchUser(id, { signal })`. The same holds for `all`, `allSettled` and `timeout`.

package/docs/oop.md

@@ -261,6 +261,8 @@ export const Cache = extendBus(bus, CacheBase);
 
 ## Subscribe a method with `@On` and `@Once`
 
+`On` here is a decorator. The main entry also exports a type named `On`, the type of `bus.on`; they are different things in different imports, and a file that needs both can rename one: `import { On as OnDecorator } from "nanoeffects/oop"`.
+
 A decorator turns a method into a handler of an event for each instance, with `this` bound. You write no `this.on` in the constructor, and `dispose()` ends the subscription too.
 
 The bus and the events are the same as above, in TypeScript:

package/docs/stability.md

@@ -0,0 +1,90 @@
+# 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`, `createCommand`, `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 | The types are written and checked with TypeScript 7. TypeScript 5.9 is used for the Vue tools and for the test of the exports. 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).

package/llms-full.txt

@@ -721,6 +721,100 @@ The package ships plain-text files for assistants that write code with it:
 
 Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. All match the installed version.
 
+---
+Source: docs/stability.md
+
+# 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`, `createCommand`, `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 | The types are written and checked with TypeScript 7. TypeScript 5.9 is used for the Vue tools and for the test of the exports. 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).
+
 ---
 Source: docs/plugins.md
 
@@ -1943,7 +2037,7 @@ bus.on("open", async (id, ctx) => {
 });
 ```
 
-The same call with a payload and a context, `(payload, ctx)`, is the Task that `bus.on` and `ctx.run` use, and it does not change.
+The same call with a payload and a context, `(payload, ctx)`, is the Task that `bus.on` and `ctx.run` use, and it does not change. `retry`, `timeout` and `poll` therefore have three call forms: with `ctx`, as a Task, and as a starter. All three stay; [Stability](stability.md#rely-on-these-call-forms) says how they are told apart.
 
 **`all`, `allSettled` and `race` without `ctx` are starters too**, so a group nests in another group with no wrapper. Load two things, but give up after five seconds:
 
@@ -1992,7 +2086,7 @@ bus.on("sync", async (ids, ctx) => {
 });
 ```
 
-The result has the same order and shape as without the option. If one starter of `all` fails, the running ones are cancelled and the waiting ones are never called. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. A group starter inside another group takes no options; write `(child) => all(child, effects, { concurrency: 5 })` there.
+The result has the same order and shape as without the option. If one starter of `all` fails, the running ones are cancelled and the waiting ones are never called. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. The form without `ctx` takes no options, because a second argument would look like the form with `ctx`, so a group starter inside another group takes none; write `(child) => all(child, effects, { concurrency: 5 })` there.
 
 
 **A starter gets the context of its own child task.** Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the race ends, `child` is aborted and stops exactly this effect. The outer `ctx` is only for `race` itself. Your own API takes the signal in its options: `({ signal }) => fetchUser(id, { signal })`. The same holds for `all`, `allSettled` and `timeout`.
@@ -4713,6 +4807,8 @@ export const Cache = extendBus(bus, CacheBase);
 
 ## Subscribe a method with `@On` and `@Once`
 
+`On` here is a decorator. The main entry also exports a type named `On`, the type of `bus.on`; they are different things in different imports, and a file that needs both can rename one: `import { On as OnDecorator } from "nanoeffects/oop"`.
+
 A decorator turns a method into a handler of an event for each instance, with `this` bound. You write no `this.on` in the constructor, and `dispose()` ends the subscription too.
 
 The bus and the events are the same as above, in TypeScript:

package/llms.txt

@@ -18,6 +18,7 @@ Rules that generated code often gets wrong:
 - [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): no dependencies and no global state for SDKs and Module Federation, and why not Redux, Effector or RxJS
 - [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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.25.0",
+	"version": "0.26.0",
 	"description": "Cancel stale async work and fix race conditions in event handlers: a typed event bus where every handler is a task with an AbortSignal, plus latest, debounce, throttle, queue, retry, timeout and poll. About 1.4 kB gzip.",
 	"keywords": [
 		"event-bus",