nanoeffects 0.33.0 → 0.35.0

package/llms-full.txt

@@ -394,7 +394,7 @@ Use strings for the plain case. Use objects when other code already builds actio
 
 **Problem.** The handler of an action is in the file of the feature, but a test needs a fake, or another layer owns the work. If the handler sits in `createAction`, the event file is tied to the work.
 
-**What to do.** Create the action without a handler: it is an event. Bind the real handler with `setHandler` when the bus is made. Later, `actions.handle` binds a newer handler that wins until you remove it.
+**What to do.** Create the action without a handler: it is an event. Bind the real handler with `actions.handle` when the bus is made. A later `actions.handle` binds a newer handler that wins until you remove it.
 
 ```js
 // user.js
@@ -406,16 +406,16 @@ export const getUser = createAction("user/get"); // no handler yet: an event
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
-import { actionsPlugin, setHandler } from "nanoeffects/actions";
+import { actionsPlugin } from "nanoeffects/actions";
 import { getUser } from "./user";
 
 export const bus = createBus();
 
-// setHandler — binds the real handler to the action
-const realUser = setHandler(getUser, (id) => api.user(id));
-
 // actionsPlugin — the registry of bound handlers of this bus
-export const actions = bus.use(actionsPlugin([realUser]));
+export const actions = bus.use(actionsPlugin());
+
+// actions.handle — binds the real handler to the action
+actions.handle(getUser, (id) => api.user(id));
 ```
 
 ```js
@@ -1312,7 +1312,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 |
@@ -1772,7 +1772,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
 
@@ -2002,7 +2002,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.
 
@@ -3049,15 +3049,21 @@ export const sendMail = createAction("mail/send");
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
-import { actionsPlugin, setHandler } from "nanoeffects/actions";
-import { sendMail } from "./mail";
+import { actionsPlugin } from "nanoeffects/actions";
 
 export const bus = createBus();
 
-// actionsPlugin — the registry of handlers of this bus; setHandler pairs an action with its work
-export const actions = bus.use(
-  actionsPlugin([setHandler(sendMail, smtpSend)]),
-);
+// actionsPlugin — the registry of handlers of this bus
+export const actions = bus.use(actionsPlugin());
+```
+
+```js
+// mail-handlers.js
+import { actions } from "./bus";
+import { sendMail } from "./mail";
+
+// actions.handle — binds the work to the action on this bus
+actions.handle(sendMail, smtpSend);
 ```
 
 ```js
@@ -3071,7 +3077,7 @@ unbind();
 
 A handler bound in the registry makes `bus.emit(sendMail(mail))` run it and return its result, the same as for an action that carries its handler. The listeners of the type are told first. With no handler bound, `sendMail` is an event again.
 
-The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the handler that the action carries. `bus.use(actionsPlugin())` sets `bus.actions`. A second `actionsPlugin` binds its list in that registry and returns it. There is no `actions` option in `createBus`; assign a custom runner with `bus.actions = { run }`, and add `bound(type)` to it to answer for actions that have no handler of their own.
+The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the handler that the action carries. `bus.use(actionsPlugin())` sets `bus.actions`. A second `actionsPlugin` returns that registry. There is no `actions` option in `createBus`; assign a custom runner with `bus.actions = { run }`, and add `bound(type)` to it to answer for actions that have no handler of their own.
 
 ### The result type of a bound handler
 
@@ -4617,6 +4623,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)
@@ -5412,6 +5459,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.
@@ -5514,6 +5606,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.
@@ -5694,7 +5827,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.
@@ -7407,25 +7540,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";
@@ -7433,10 +7577,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 })),
   }),
 );
 ```
@@ -7508,7 +7669,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/package.json

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