nanoeffects 0.34.0 → 0.36.0

package/llms-full.txt

@@ -568,6 +568,8 @@ Each task below starts with the problem, then a short solution. Where the page h
   - [A second click sends a second request](#a-second-click-sends-a-second-request)
   - [Messages must go out in order](#messages-must-go-out-in-order)
   - [A "Delete" button in a list blocks the other rows](#a-delete-button-in-a-list-blocks-the-other-rows)
+  - [Several components ask for the same data](#several-components-ask-for-the-same-data)
+  - [A form saves the same text twice](#a-form-saves-the-same-text-twice)
 - [An unreliable network and long flows](#an-unreliable-network-and-long-flows)
   - [A request fails sometimes: retry and backoff](#a-request-fails-sometimes-retry-and-backoff)
   - [A request hangs: timeout](#a-request-hangs-timeout)
@@ -575,6 +577,8 @@ Each task below starts with the problem, then a short solution. Where the page h
   - [Wait for another event inside a handler: take](#wait-for-another-event-inside-a-handler-take)
   - [Load several things at once: all](#load-several-things-at-once-all)
   - [Take the fastest answer: race](#take-the-fastest-answer-race)
+  - [An API allows only N requests per second](#an-api-allows-only-n-requests-per-second)
+  - [Many small events, one request](#many-small-events-one-request)
 - [Features and domain logic](#features-and-domain-logic)
   - [Get the result of emit](#get-the-result-of-emit)
   - [Group a feature with its handlers: modules](#group-a-feature-with-its-handlers-modules)
@@ -790,6 +794,49 @@ bus.on(
 
 More: [Policies, `key`](policies.md#key-isolate-state-by-key).
 
+### Several components ask for the same data
+
+A page shows a user in the header, in a sidebar and in a comment, and all three ask for user `1` in the same tick. That is three identical requests. `dedupe` makes the calls for one id share a single request. Use it for reads, not for writes.
+
+```js
+import { createBus } from "nanoeffects";
+import { dedupe } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// dedupe — a call for an id that is loading already waits for that request
+bus.on(
+  "user/needed",
+  dedupe(async (id, ctx) => {
+    const user = await api.getUser(id, { signal: ctx.signal });
+    ctx.emit("user/loaded", user);
+  }),
+);
+```
+
+More: [Policies, `dedupe`](policies.md#dedupe-share-one-run-between-equal-calls).
+
+### A form saves the same text twice
+
+A form saves on every change. A user types a letter and deletes it, and the same text goes to the server again. `distinct` skips a call whose payload equals the last one.
+
+```js
+import { createBus } from "nanoeffects";
+import { distinct } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// distinct — a text equal to the last saved one is skipped
+bus.on(
+  "draft/changed",
+  distinct(async (text, { signal }) => {
+    await api.saveDraft(text, { signal });
+  }),
+);
+```
+
+More: [Policies, `distinct`](policies.md#distinct-skip-a-repeated-payload).
+
 ## An unreliable network and long flows
 
 ### A request fails sometimes: retry and backoff
@@ -921,6 +968,49 @@ bus.on("user/opened", async (id, ctx) => {
 
 More: [`all`](effects.md#all), [`race`](effects.md#race).
 
+### An API allows only N requests per second
+
+A geocoding API allows 5 requests per second. A list of 40 addresses sends 40 requests at once, and most fail with `429`. `rateLimit` starts five and holds the rest until the window slides.
+
+```js
+import { createBus } from "nanoeffects";
+import { rateLimit } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// rateLimit — five requests may start per second, the others wait their turn
+bus.on(
+  "address/geocode",
+  rateLimit(5, 1000, async (address, ctx) => {
+    const place = await api.geocode(address, { signal: ctx.signal });
+    ctx.emit("address/found", place);
+  }),
+);
+```
+
+More: [Policies, `rateLimit`](policies.md#ratelimit-stay-under-a-quota).
+
+### Many small events, one request
+
+A page sends an analytics event on every click, 30 requests a minute. The server prefers one request with all of them. `batch` collects the events that come within a window and sends them together.
+
+```js
+import { createBus } from "nanoeffects";
+import { batch } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// batch — everything that comes within 500 ms goes in one request
+bus.on(
+  "analytics/event",
+  batch(500, async (events, { signal }) => {
+    await api.sendEvents(events, { signal });
+  }),
+);
+```
+
+More: [Policies, `batch`](policies.md#batch-send-many-calls-as-one).
+
 ## Features and domain logic
 
 ### Get the result of emit
@@ -1300,7 +1390,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | Import | What is in it |
 | ------ | ------------- |
 | `nanoeffects` | `createBus`, the types |
-| `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
+| `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue`, `dedupe`, `distinct`, `rateLimit`, `batch` |
 | `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
 
 ## Add the rest when you need it
@@ -1312,7 +1402,7 @@ Each row is optional. The "when" column says what need brings you to it.
 | `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` | `emit` must return a result, or domain logic leaves the UI |
 | `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events | `on` must take a function that picks events |
 | `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value | a store or client must be on every task |
-| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal`; `fromSignal` and `signalFetch`: a client or a `fetch` made from the signal of each task | an outside `AbortSignal` (request, React Query) must stop tasks, or a handler must not pass the signal by hand |
+| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal`; `signalFetch(ctx, url)`: a `fetch` that stops with its task; `fromSignal`: a client made from the signal of each task | an outside `AbortSignal` (request, React Query) must stop tasks, or a handler must not pass the signal by hand |
 | `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` | you write classes, not functions |
 | `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) | one action or module needs its own fields |
 | `nanoeffects/redux` | `createEffectsMiddleware` | you already use Redux |
@@ -1754,6 +1844,30 @@ Use this page when handlers overlap in a SPA (search-as-you-type, double submit,
 
 Start with `latest`. The table and sections below are the rest of the reference.
 
+## On this page
+
+- [`latest`: abort the previous run](#latest-abort-the-previous-run)
+- [Choose a policy](#choose-a-policy)
+- [Look up a policy](#look-up-a-policy)
+  - [`latest`](#latest)
+  - [`leading`](#leading)
+  - [`debounce`](#debounce)
+  - [`throttle`](#throttle)
+  - [`queue`](#queue)
+  - [`dedupe`](#dedupe)
+  - [`distinct`](#distinct)
+  - [`rateLimit`](#ratelimit)
+  - [`batch`](#batch)
+  - [`key`](#key)
+- [Configure debounce and throttle](#configure-debounce-and-throttle)
+- [`key`: isolate state by key](#key-isolate-state-by-key)
+- [Run calls one after another with `queue`](#run-calls-one-after-another-with-queue)
+- [`dedupe`: share one run between equal calls](#dedupe-share-one-run-between-equal-calls)
+- [`distinct`: skip a repeated payload](#distinct-skip-a-repeated-payload)
+- [`rateLimit`: stay under a quota](#ratelimit-stay-under-a-quota)
+- [`batch`: send many calls as one](#batch-send-many-calls-as-one)
+- [`withPolicy`: call a policy outside a bus](#withpolicy-call-a-policy-outside-a-bus)
+
 ## `latest`: abort the previous run
 
 ```js
@@ -1772,7 +1886,7 @@ bus.on(
 );
 ```
 
-Pass `signal` to `fetch` (and the like) so the request cancels. To not pass it at all, bind it once: with `ctx.fetch` the request stops with the handler and there is nothing to forget ([Keep the signal through a handler](pass-the-signal.md#bind-the-signal-once)).
+Pass `signal` to `fetch` (and the like) so the request cancels. To not pass it at all, bind it once: with `signalFetch(ctx, url)` the request stops with the handler and there is nothing to forget ([Keep the signal through a handler](pass-the-signal.md#bind-the-signal-once)).
 
 ## Choose a policy
 
@@ -1785,6 +1899,10 @@ Every policy accepts `key` in its options (see [`key`: isolate state by key](#ke
 | `debounce(ms, fn, options?)` | run after `ms` of quiet |
 | `throttle(ms, fn, options?)` | at most one run per `ms` |
 | `queue(fn, options?)` | one after another, in order |
+| `dedupe(fn, options?)` | calls with the same key share the run that is going |
+| `distinct(fn, options?)` | a call with the same payload as the last one is skipped |
+| `rateLimit(limit, ms, fn, options?)` | at most `limit` runs start per `ms`, the rest wait |
+| `batch(ms, fn, options?)` | payloads of one window go to `fn` as one array |
 
 Each policy has a short entry in [Look up a policy](#look-up-a-policy).
 
@@ -1832,6 +1950,38 @@ Signature: `queue(fn, options?)`.
 
 More: [Run calls one after another with `queue`](#run-calls-one-after-another-with-queue).
 
+### `dedupe`
+
+Calls with the same key that come while a run is going wait for that run and get its result. Nothing is cached.
+
+Signature: `dedupe(fn, options?)`.
+
+More: [`dedupe`: share one run between equal calls](#dedupe-share-one-run-between-equal-calls).
+
+### `distinct`
+
+A call whose payload equals the last one is skipped and resolves with `undefined`.
+
+Signature: `distinct(fn, options?)`.
+
+More: [`distinct`: skip a repeated payload](#distinct-skip-a-repeated-payload).
+
+### `rateLimit`
+
+At most `limit` runs start in any window of `ms`. The other calls wait for their turn.
+
+Signature: `rateLimit(limit, ms, fn, options?)`.
+
+More: [`rateLimit`: stay under a quota](#ratelimit-stay-under-a-quota).
+
+### `batch`
+
+Collects the payloads that come in a window of `ms` and calls `fn` once with all of them.
+
+Signature: `batch(ms, fn, options?)`.
+
+More: [`batch`: send many calls as one](#batch-send-many-calls-as-one).
+
 ### `key`
 
 An option of every policy. It splits the state of the policy by a property, for example by id: calls with different keys do not affect each other.
@@ -1917,6 +2067,134 @@ Every call returns a promise with the result of its own run. An error rejects on
 - When a running call aborts, its slot is freed at once and its result is dropped.
 - Pass `signal` into what `fn` does. A `fn` that ignores it can overlap with the next run.
 
+## `dedupe`: share one run between equal calls
+
+> **Level B or C.** Use it for reads that several parts of the screen start at the same time.
+
+**Problem.** Three components ask for user `1` in the same tick. Without a policy that is three identical requests.
+
+**When.** A read that is safe to repeat: a profile, a config, a list by id. For a write use [`leading`](prevent-double-submit.md) or [`queue`](#run-calls-one-after-another-with-queue): see the abort rule below.
+
+`dedupe` starts `fn` for the first call. A call with the same key that comes while that run is going waits for it and gets its result, or its error. When the run ends, `dedupe` forgets it, and the next call starts `fn` again. It is not a cache: it never returns an old value.
+
+```js
+import { dedupe, withPolicy } from "nanoeffects/policies";
+
+// dedupe — callers with the same id share one request
+const policy = dedupe((id, { signal }) => api.getUser(id, { signal }));
+
+// withPolicy — a plain function, so the example shows the result of each call
+const loadUser = withPolicy(policy);
+
+// two callers, one request: both get the same user
+const [first, second] = await Promise.all([loadUser(1), loadUser(1)]);
+```
+
+On a bus it looks the same, `bus.on("user/load", dedupe(handler))`. To get the result of `emit` use an action or a job ([Actions](actions.md)).
+
+| Option | Meaning |
+| ------ | ------- |
+| `key` | what makes two calls "the same". Default: the payload itself, compared like a `Map` key. Objects never match unless `key` says how. `key: () => "all"` shares one run between every call |
+
+**Abort:**
+
+- A caller whose task aborts resolves with `undefined`. The others go on.
+- The run belongs to the task of the first caller. If that task aborts while others still wait, the run is aborted and started again with the next caller, so `fn` can run twice for one request. That is fine for a read and wrong for a write.
+- Pass `signal` into what `fn` does, as for any policy.
+
+## `distinct`: skip a repeated payload
+
+> **Level B.** Use it when the same value keeps arriving and repeating the work is a waste.
+
+**Problem.** A form saves on every change. A user types a letter and deletes it, and the same text goes to the server again.
+
+`distinct` compares the payload of each call with the payload of the last call it let through. An equal payload is skipped: `fn` does not run and the call resolves with `undefined`. It remembers one payload, never a result.
+
+```js
+import { distinct, withPolicy } from "nanoeffects/policies";
+
+// distinct — runs only when the text differs from the last one it let through
+const policy = distinct(async (text) => {
+  await api.save(text);
+});
+const save = withPolicy(policy);
+
+await save("hello"); // runs
+await save("hello"); // skipped, resolves undefined
+await save("hello!"); // runs: the text changed
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `equals(previous, next)` | tells whether two payloads are the same. Default: `Object.is` |
+| `key` | each key remembers its own payload |
+
+- The payload counts as seen from the moment its run starts, so the same payload that arrives while the run goes is skipped too.
+- It is forgotten when the run fails or its task aborts, so a retry with the same payload runs.
+- The memory of a key stays after the run. Unlike other policies, `distinct` does not drop idle keys, so give `key` values from a bounded set (a form id, not a request id).
+
+## `rateLimit`: stay under a quota
+
+> **Level C.** Use it when an API allows N requests per period.
+
+**Problem.** A geocoding API allows 5 requests per second. A list of 40 addresses sends 40 requests at once, and most of them fail with `429`.
+
+`rateLimit(limit, ms, fn)` lets at most `limit` runs start in any window of `ms` milliseconds. The window slides: it is counted back from each call. A call over the limit waits and starts, in order, when the oldest start leaves the window.
+
+```js
+import { rateLimit, withPolicy } from "nanoeffects/policies";
+
+// rateLimit — 5 runs may start per second, the rest wait their turn
+const policy = rateLimit(5, 1000, (address, { signal }) => {
+  return api.geocode(address, { signal });
+});
+const geocode = withPolicy(policy);
+
+const addresses = ["10 Main St", "22 Oak Ave", "5 Pine Rd", "8 Elm St", "3 Lake Dr", "9 Hill Ln"];
+
+// the first five start at once, the sixth a second later
+const results = await Promise.all(addresses.map(geocode));
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `overflow` | `"wait"` (default) keeps a call until it can start. `"drop"` drops a call that finds the window full: it resolves with `undefined` |
+| `key` | each key has its own window, for example one per user |
+
+- It limits **starts**, not how many runs go at the same time, and it does not wait for a run to end. For both limits write `queue(rateLimit(5, 1000, fn), { concurrency: 2 })`: a call keeps its slot in the queue while it waits for the window.
+- A call whose task aborts while it waits leaves the line. Aborting a run that has started does not give its place in the window back: the request was sent.
+- A `limit` below 1 is 1.
+
+## `batch`: send many calls as one
+
+> **Level C.** Use it when work is cheaper in bulk: events for analytics, log lines, "get these ids".
+
+**Problem.** A page sends an analytics event for every click, 30 requests a minute. The server prefers one request with all of them.
+
+`batch(ms, fn)` opens a window of `ms` at the first call and collects the payloads that come in it. When the window closes, `fn` runs once with an array of them, in the order of the calls. The window does not move when more calls come, so a steady stream is sent every `ms`, not only when it stops.
+
+```js
+import { batch, withPolicy } from "nanoeffects/policies";
+
+// batch — fn gets an array of everything that came within 500 ms
+const policy = batch(500, async (events) => {
+  await api.sendEvents(events);
+});
+const track = withPolicy(policy);
+
+track({ name: "open" });
+track({ name: "click" }); // one request with both events, 500 ms after the first
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `maxSize` | send the batch at once when it holds this many payloads |
+| `key` | each key collects its own batch, for example one per user |
+
+- Every call resolves with what `fn` returned for its batch: the same value for all, or the same error. `batch` does not split an array result between callers.
+- A call whose task aborts while the batch is collecting leaves it and resolves with `undefined`. When every call has left, nothing runs.
+- `fn` gets the context of the first caller that is still waiting. If that task aborts while `fn` runs, the run is aborted and every caller of that batch resolves with `undefined`. The run is not repeated: part of a bulk call may have happened.
+
 ## `withPolicy`: call a policy outside a bus
 
 **Problem.** You want a debounced input handler or a "latest request wins" fetch for your own function, but the code has no bus: a DOM handler, a click callback, a function in a service. A policy needs a context on every call, so `debounce(300, search)("re")` does not work on its own.
@@ -2002,7 +2280,7 @@ bus.on("results", (items) => render(items));
 
 What to replace: `api.search` is your own request function. It must accept `{ signal }` and give it to `fetch`. Without it, `latest` still ignores the old result, but the request keeps running.
 
-To make the mistake impossible, bind the signal once: `contextPlugin({ fetch: fromSignal(signalFetch) })` gives every handler a `ctx.fetch` that stops with the handler ([how](pass-the-signal.md#bind-the-signal-once)). To find the requests that already forget it, use `devPlugin` while you develop, and `getLostSignalsCount(bus)` in a test ([how](pass-the-signal.md#count-lost-signals-in-a-test)).
+To make the mistake impossible, bind the signal once: `signalFetch(ctx, url)` is a `fetch` that stops with the handler, and `effectsPlugin({ fetch: signalFetch })` gives every handler a `ctx.fetch` of it ([how](pass-the-signal.md#bind-the-signal-once)). To find the requests that already forget it, use `devPlugin` while you develop, and `getLostSignalsCount(bus)` in a test ([how](pass-the-signal.md#count-lost-signals-in-a-test)).
 
 Result: `emit("search", "ab")` followed by `emit("search", "abc")` shows only the results for `abc`, and the request for `ab` is cancelled.
 
@@ -4623,6 +4901,47 @@ Steps 1 and 2 are required, step 3 is not. The last two sections are extra.
 
 You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
 
+The shortest version: a name field that asks the backend whether the name is free. The rest of the page builds a whole form from it.
+
+```js
+// username.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus, created once
+
+// the name check, outside the component; latest aborts the check of the previous name
+bus.on(
+  "username/typed",
+  latest(async (name, ctx) => {
+    const available = await api.usernameAvailable(name, { signal: ctx.signal });
+    ctx.emit("username/checked", available);
+  }),
+);
+```
+
+```jsx
+// NameField.jsx
+import { useEffect, useState } from "react";
+import { bus } from "./username";
+
+export function NameField() {
+  const [available, setAvailable] = useState(null); // null: not checked yet
+
+  // on returns the unbind function; returning it removes the listener on unmount
+  useEffect(() => bus.on("username/checked", setAvailable), []);
+
+  return (
+    <>
+      <input onChange={(event) => bus.emit("username/typed", event.target.value)} />
+      {available === false && <p>This name is taken</p>}
+    </>
+  );
+}
+```
+
+The handler knows nothing about React, and the component knows nothing about requests.
+
 ## On this page
 
 - [Problems of the form without a bus](#problems-of-the-form-without-a-bus)
@@ -5418,6 +5737,51 @@ Use this page when your app is in Vue 3 and a component has to talk to the bus:
 
 You need Vue 3.3 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
 
+The shortest version: a search box that shows what the handler found. No plugin is needed for this; the sections below add a helper that shortens the component.
+
+```js
+// search.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus, created once
+
+// the search logic, outside the component; latest aborts the previous request
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query, { signal: ctx.signal });
+    ctx.emit("found", items);
+  }),
+);
+```
+
+The handler knows nothing about the UI, and the component only sends `search` and listens to `found`.
+
+<!-- docs-check: skip - a .vue file -->
+```vue
+<script setup>
+import { onUnmounted, ref } from "vue";
+import { bus } from "./search";
+
+const items = ref([]);
+
+// on returns the unbind function; unmounting calls it
+const unbind = bus.on("found", (found) => {
+  items.value = found;
+});
+onUnmounted(unbind);
+</script>
+
+<template>
+  <input @input="bus.emit('search', $event.target.value)" />
+  <ul>
+    <li v-for="item in items" :key="item.id">{{ item.title }}</li>
+  </ul>
+</template>
+```
+
+
 ## Add the plugin to the bus
 
 **Problem.** Without help, a component writes `watch(query, (value) => bus.emit(queryChanged(value)))` and its own subscription in `onMounted` and `onUnmounted`. The same few lines are copied into every component, and each copy forgets something: the cleanup, the equality check, or the name of the subscription in the trace.
@@ -5520,6 +5884,47 @@ Use this page when your app is in Svelte 5 and a component has to show the resul
 
 You need Svelte 5 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
 
+The shortest version: a search box that shows what the handler found. No plugin is needed for this; the sections below add a helper that shortens the component.
+
+```js
+// search.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus, created once
+
+// the search logic, outside the component; latest aborts the previous request
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query, { signal: ctx.signal });
+    ctx.emit("found", items);
+  }),
+);
+```
+
+The handler knows nothing about the UI, and the component only sends `search` and listens to `found`.
+
+<!-- docs-check: skip - a .svelte file -->
+```svelte
+<script>
+  import { bus } from "./search";
+
+  let items = $state([]);
+
+  // on returns the unbind function; $effect calls it on cleanup
+  $effect(() => bus.on("found", (found) => (items = found)));
+</script>
+
+<input oninput={(event) => bus.emit("search", event.target.value)} />
+<ul>
+  {#each items as item (item.id)}
+    <li>{item.title}</li>
+  {/each}
+</ul>
+```
+
+
 ## Add the plugin to the bus
 
 **Problem.** A Svelte component reads a value with `$store`. An event of the bus is not a store, so without help the component writes its own `readable` and its own `bus.on`, and has to remember to stop listening. The same few lines are copied into every component.
@@ -5700,7 +6105,7 @@ bus.on("user/open", async (id, ctx) => {
 });
 ```
 
-- `signalFetch` from the same entry is a `fetch` bound to a signal, so `fetch: fromSignal(signalFetch)` gives every handler a `ctx.fetch` that stops with the task. [Bind the signal once](pass-the-signal.md#bind-the-signal-once)
+- For `fetch` you need no `fromSignal`: `signalFetch(ctx, url)` from the same entry stops with the task, and `effectsPlugin({ fetch: signalFetch })` gives every handler a `ctx.fetch`. [Bind the signal once](pass-the-signal.md#bind-the-signal-once)
 - `make` runs at the first read, so a handler that never uses `ctx.http` pays nothing for it.
 - A task that `ctx.run` starts builds its own value from its own signal, so aborting the child stops only the child's requests.
 - The field is not copied by `{ ...ctx }` and `Object.keys(ctx)` does not list it. Read `ctx.http` first if you copy a context.
@@ -7413,25 +7818,36 @@ A policy such as `latest` cancels an older call by aborting its `ctx.signal`. Th
 
 ## Bind the signal once
 
-The surest fix is a handler with no signal in it. Make the client from the signal of the task, once, and the handler calls `ctx.fetch` and cannot forget anything. `signalFetch` is a `fetch` bound to a signal; `fromSignal` builds it for each task.
+The surest fix is a handler that never writes a signal. `signalFetch` is a `fetch` that takes `ctx` first, like `retry(ctx, ...)`: the request carries `ctx.signal`, so there is nothing to forget.
 
 ```js
-// bus.js
-import { createBus } from "nanoeffects";
-import { contextPlugin } from "nanoeffects/context";
-import { fromSignal, signalFetch } from "nanoeffects/signal";
-import axios from "axios";
+// search-handlers.js
+import { latest } from "nanoeffects/policies";
+import { signalFetch } from "nanoeffects/signal";
+import { bus } from "./bus";
 
-// fromSignal — ctx.fetch is made from the signal of the task that reads it
-export const bus = createBus().use(
-  contextPlugin({
-    fetch: fromSignal(signalFetch),
-    // your own client too: it is made from the signal of each task
-    http: fromSignal((signal) => axios.create({ signal })),
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // signalFetch — fetch with ctx.signal: it stops when the policy cancels the handler
+    const response = await signalFetch(ctx, `/api?q=${query}`);
+    ctx.emit("results", await response.json());
   }),
 );
 ```
 
+To get `ctx.fetch` in every handler, put the effect on the context once. `effectsPlugin` binds it to each task, so the handler drops the `ctx` argument:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { effectsPlugin } from "nanoeffects/effects";
+import { signalFetch } from "nanoeffects/signal";
+
+// effectsPlugin — ctx.fetch is signalFetch bound to the task that reads it
+export const bus = createBus().use(effectsPlugin({ fetch: signalFetch }));
+```
+
 ```js
 // search-handlers.js
 import { latest } from "nanoeffects/policies";
@@ -7439,10 +7855,27 @@ import { bus } from "./bus";
 
 bus.on(
   "search",
-  latest(async (query, ctx) => {
-    // no signal here: ctx.fetch stops when the policy cancels the handler
-    const response = await ctx.fetch(`/api?q=${query}`);
-    ctx.emit("results", await response.json());
+  latest(async (query, { fetch, emit }) => {
+    // no signal and no ctx argument: fetch stops when the policy cancels the handler
+    const response = await fetch(`/api?q=${query}`);
+    emit("results", await response.json());
+  }),
+);
+```
+
+A client that is not an effect, such as an `axios` instance, is made from the signal of each task with `fromSignal`:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal } from "nanoeffects/signal";
+import axios from "axios";
+
+// fromSignal — ctx.http is made from the signal of the task that reads it
+export const bus = createBus().use(
+  contextPlugin({
+    http: fromSignal((signal) => axios.create({ signal })),
   }),
 );
 ```
@@ -7514,7 +7947,7 @@ Each row is a situation where the signal is easy to lose. The right column says
 | A function takes the signal and never uses it: `search(query, options) { return fetch(url); }` | Pass the signal on inside it. Only type information finds this in the linter; a test finds it for sure | types | |
 | The signal is wired by hand: `signal.addEventListener("abort", ...)` | Nothing, the handler is not checked step by step | accepted | |
 | `bus.emit` in a handler | Use `ctx.emit`: only it is dropped after the handler was cancelled | yes | |
-| A request that keeps running after the cancel, on Node | Pass the signal, or use `ctx.fetch` | | yes |
+| A request that keeps running after the cancel, on Node | Pass the signal, or use `signalFetch(ctx, url)` | | yes |
 | Results emitted after the cancel | The handler ignored the signal. Pass it, or check `ctx.signal.aborted` | | yes |
 | `ctx.on` after the cancel | The same | | yes |
 

package/llms.txt

@@ -23,7 +23,7 @@ Rules that generated code often gets wrong:
 
 ## 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
+- [Policies](docs/policies.md): `latest`, `leading`, `debounce`, `throttle`, `queue`, `dedupe`, `distinct`, `rateLimit`, `batch`, 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
 - [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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.34.0",
+	"version": "0.36.0",
 	"description": "Business logic and side effects outside UI components, as plain async functions. Tiny, no dependencies.",
 	"keywords": [
 		"event-bus",
@@ -226,7 +226,7 @@
 		{
 			"name": "policies (all)",
 			"path": "dist/policies.js",
-			"limit": "2.71 kB"
+			"limit": "3.71 kB"
 		},
 		{
 			"name": "effects (all)",
@@ -246,7 +246,7 @@
 		{
 			"name": "signal (plugin)",
 			"path": "dist/signal.js",
-			"limit": "0.8 kB"
+			"limit": "0.81 kB"
 		},
 		{
 			"name": "context (plugin)",