nanoeffects 0.21.0 → 0.23.0

package/docs/package.md

@@ -16,6 +16,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve`, `Subject` |
 | `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
+| `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) |
 | `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) |
 | `nanoeffects/dev` | `devPlugin` (no-op in production) |
 | `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) |

package/docs/server.md

@@ -0,0 +1,205 @@
+# Stop work on a server when the client leaves
+
+Read this page if you run a Node server (the examples use [Fastify](https://fastify.dev)) and want the work for a request, a socket or a queued job to stop when nobody needs it. It shows one pattern in three places: a request, a WebSocket and a worker.
+
+You need Node 18 or newer, `fastify` and `nanoeffects`. `api` below is your own client for another service: replace it with your requests.
+
+## Why a server needs this
+
+A browser tab that closes stops its own requests. A server does not: if a client leaves, the requests that the server made for it keep running, and so do their retries. On a busy server that is wasted work and a slower service for everyone else.
+
+The fix is one `AbortController` for each unit of work that the client owns, and one rule: **when the client goes, abort the controller.** `signalPlugin` lets `bus.emit` take that signal, so `timeout`, `retry` and the request itself stop.
+
+| Unit of work | Created when | Aborted when |
+| ------------ | ------------ | ------------ |
+| An HTTP request | the route starts | the connection closes before the answer |
+| A WebSocket | the socket connects | the socket closes |
+| A queued job | the job is accepted | the server shuts down |
+
+## Make the bus and the command
+
+The bus and the command live in files that know nothing about HTTP, so the same command can run in a route, a test or a worker.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// createBus — the bus the server shares
+// signalPlugin — lets emit take { signal }, so a closed connection can abort the work
+export const bus = createBus().use(signalPlugin());
+```
+
+The command loads a user. It tries the request up to three times, and gives up on each try after five seconds. `ctx.signal` is the signal of the task: it aborts when the controller of the request aborts.
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
+import { retry, timeout } from "nanoeffects/effects";
+
+// createCommand — a command with a handler: emit returns what the handler returns
+export const getUser = createCommand("user/get", async (id, ctx) => {
+  // one try: the request, with the signal of timeout so it can stop it
+  const load = ({ signal }) => api.getUser(id, { signal });
+  // timeout — fail the try after 5 s
+  const attempt = () => timeout(ctx, 5000, load);
+  // retry — up to 3 tries, 500 ms apart
+  return retry(ctx, attempt, { times: 3, delay: 500 });
+});
+```
+
+## Stop the work of a request
+
+<!-- docs-check: continue -->
+
+Make a controller when the route starts. Listen to `close` of the **response** (`reply.raw`): it ends when the connection ends. `request.raw` also emits `close`, but it does so when the request body has been read, not when the client leaves, so it is the wrong event here.
+
+```js
+// server.js
+import Fastify from "fastify";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export const app = Fastify();
+
+// the controllers of the requests that are still being answered, for the shutdown below
+export const inFlight = new Set();
+
+app.get("/users/:id", async (request, reply) => {
+  const controller = new AbortController();
+  inFlight.add(controller);
+
+  // close on the response — the connection ended; if the answer was not finished, the client left
+  reply.raw.on("close", () => {
+    inFlight.delete(controller);
+    if (!reply.raw.writableFinished) {
+      controller.abort();
+    }
+  });
+
+  try {
+    // emit with { signal } — aborting the controller aborts the command: timeout, retry and the request
+    const call = getUser(request.params.id);
+    return await bus.emit(call, { signal: controller.signal });
+  } catch (error) {
+    // nobody is left to answer when the client closed the connection
+    if (reply.raw.destroyed) {
+      return reply;
+    }
+    return reply.code(502).send({ error: String(error) });
+  }
+});
+```
+
+After an abort the command rejects with the abort reason. The `catch` above ignores it when the connection is gone, because there is nobody to answer.
+
+## Stop the server
+
+<!-- docs-check: continue -->
+
+Keep the controllers of the requests in flight in a set. On SIGTERM (what a container sends) or SIGINT (Ctrl+C), abort them all, then close the app. A request that is aborted this way answers with an error, and `app.close()` waits for the connections to end.
+
+```js
+// shutdown.js
+import { app, inFlight } from "./server";
+
+// SIGTERM is what a container sends, SIGINT is Ctrl+C
+for (const name of ["SIGTERM", "SIGINT"]) {
+  process.on(name, async () => {
+    for (const controller of inFlight) {
+      controller.abort();
+    }
+    await app.close();
+    process.exit(0);
+  });
+}
+```
+
+The route above fills `inFlight` and empties it in the `close` listener. The [api-server example](../examples/api-server) does the same, with a limit of two seconds for the close.
+
+## Tie a WebSocket to its work
+
+<!-- docs-check: continue -->
+
+A socket lasts minutes and carries several tasks (a subscription, a heartbeat), so the controller belongs to the socket and every `emit` for it gets the same signal. Closing the socket stops all of them.
+
+First the command. It sends a price now and then every second, until its task is aborted.
+
+```js
+// prices.js
+import { createCommand } from "nanoeffects/actions";
+import { poll } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+// createCommand — a command with a handler
+// latest — a new subscription stops the old one; key — but only the old one of the same socket
+export const watchPrices = createCommand(
+  "prices/watch",
+  latest(
+    async (call, ctx) => {
+      // poll — call the function now and every second, until the task is aborted
+      await poll(ctx, () => call.send(`${call.symbol}: ${Math.random()}`), 1000, {
+        leading: true,
+      });
+    },
+    { key: (call) => call.socketId },
+  ),
+);
+```
+
+Without the `key`, one policy serves the whole command, and a new subscription on one socket would stop the subscription on another.
+
+Then the route. Each socket gets an id and a controller.
+
+```js
+// sockets.js
+import websocket from "@fastify/websocket";
+import Fastify from "fastify";
+import { bus } from "./bus";
+import { watchPrices } from "./prices";
+
+const sockets = Fastify();
+sockets.register(websocket);
+
+let lastSocketId = 0;
+
+sockets.register(async (instance) => {
+  instance.get("/prices", { websocket: true }, (socket) => {
+    lastSocketId += 1;
+    const socketId = lastSocketId;
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    // close — the client left: stop everything started for this socket
+    socket.on("close", () => controller.abort());
+
+    socket.on("message", (data) => {
+      const send = (text) => socket.send(text);
+      const call = watchPrices({ socketId, symbol: String(data), send });
+      // emit with { signal } — the call stops when the socket closes
+      bus.emit(call, { signal });
+    });
+  });
+});
+```
+
+The [ws-server example](../examples/ws-server) adds a close for a silent socket, made of `race`, `take` and `delay`.
+
+## Run a queue worker
+
+A worker takes jobs from a client and answers at once, and the work goes on in the background. Use `createJob` with `queue` to limit how many run together, `retry` and `timeout` to give up, and the outcomes of the job (`pending`, `success`, `fail`, `cancel`) to count them. Give every `emit` of the job the same signal; aborting it at shutdown cancels the jobs that are left.
+
+Two details matter:
+
+- Bind the handler with `commands.handle(job, queue(...))` (or `m.handle` in a module), not as the second argument of `createJob`. Only a bound handler lets the job learn from the policy when a call really starts, so `pending` is sent at the start and not at the call.
+- A call that is still waiting in the queue when the signal aborts never starts, and the job sends no outcome for it. Count such calls yourself if you need the totals to add up.
+
+The [job-worker example](../examples/job-worker) has all of it: the counts, `GET /stats`, and a shutdown in three steps (stop taking jobs, wait, abort the rest).
+
+## Examples
+
+| Folder | What it shows |
+| ------ | ------------- |
+| [`api-server`](../examples/api-server) | A Fastify server over PokeAPI: `timeout`, `retry`, `allSettled`, and the abort when the client leaves |
+| [`ws-server`](../examples/ws-server) | A WebSocket server: one controller for each socket, `latest` with a `key`, an idle close |
+| [`job-worker`](../examples/job-worker) | A queue worker: `queue`, `retry`, `timeout`, counts from the outcomes, a three-step shutdown |

package/docs/starter.md

@@ -48,7 +48,7 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `react-ts` | The `react` app in TypeScript | You build a React app in TypeScript |
 | `domains-ts` | Commands, a job and modules, with the logic split into domain folders and React as a thin layer | You build an app with more than one feature and want the logic off the UI |
 | `vue-ts` | The `react-ts` app in Vue 3, with `watchEmitter` and `useEventRef` from `nanoeffects/vue` | You build a Vue 3 app |
-| `svelte-ts` | The `react-ts` app in Svelte 5, with a Svelte store made from an event | You build a Svelte app |
+| `svelte-ts` | The `react-ts` app in Svelte 5, with `eventStore` from `nanoeffects/svelte` | You build a Svelte app |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
@@ -74,7 +74,7 @@ npm create nanoeffects@latest my-app -- --template vue-ts
 
 ### Start with Svelte
 
-`svelte-ts` is the search app of `react-ts` in Svelte 5. It needs no part of nanoeffects for Svelte: a Svelte store is any object with `subscribe`, so a small helper of the project, `src/event-store.ts`, makes a store from an event with `readable` and `bus.on`. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. The query goes to the bus from the `oninput` handler, so nothing is emitted when the component mounts. The store listens only while something reads it, and is [not a store of the app](react.md#show-the-last-value-of-an-event-as-state): a value that several components share belongs in a store of your own.
+`svelte-ts` is the search app of `react-ts` in Svelte 5. Its bus uses `sveltePlugin` from `nanoeffects/svelte`: `eventStore` makes a Svelte store from an event. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. The query goes to the bus from the `oninput` handler, so nothing is emitted when the component mounts. The store listens only while something reads it, and is [not a store of the app](svelte.md#it-is-not-a-store-of-the-app): a value that several components share belongs in a store of your own.
 
 ```bash
 npm create nanoeffects@latest my-app -- --template svelte-ts
@@ -98,7 +98,7 @@ npm create nanoeffects@latest my-app -- --template domains-ts
 | `src/domains/checkout/` | Placing an order: `checkout.ts` (a job), `checkout-handlers.ts` (`leading` and `retry`), `checkout-store.ts` (state written from the job's outcomes), `checkout-module.ts`. |
 | `src/ui/` | The components. None of them calls the fake server in `src/api.ts`. |
 
-For a bigger example with the same layout, a chat with four domains and mocks, see [Build a chat with domains, modules and a small server](chat-example.md).
+For a bigger example, a chat in which parts react to each other, see [Build a chat with entities, features, modules and a small server](chat-example.md). It has more layers than `domains-ts`: when domains must react to each other, it keeps them from importing each other by splitting them into entities and features.
 
 The commands, jobs and modules themselves are explained in [Actions, commands, jobs and modules](actions.md). The template keeps found products in a Context provider with one `useEventState`, and the order state in a store of its own: `useEventState` is [not a store](react.md#show-the-last-value-of-an-event-as-state).
 

package/docs/stores.md

@@ -25,7 +25,7 @@ Redux’s `dispatch` → reducers updates **state**. It does not give you first-
 
 `createEffectsMiddleware(bus)` does the same job: after the reducer runs, the action also hits the nanoeffects bus you pass to it. Keep RTK for state; use policies and effects for async.
 
-Skip this section if you are not already on Redux. The recipe as a file, type-checked with the project: [`examples/redux.ts`](../examples/redux.ts).
+Skip this section if you are not already on Redux. The recipe as a file, type-checked with the project: [`examples/redux.ts`](../examples/redux.ts). To run it, open the [counter example](../examples/counter): `redux.html` is a counter with Redux Toolkit and this middleware.
 
 ```js
 // bus.js

package/docs/svelte.md

@@ -0,0 +1,81 @@
+# Use nanoeffects in a Svelte app
+
+Use this page when your app is in Svelte 5 and a component has to show the result of an event. `sveltePlugin` gives you one function for that, `eventStore`. To see it in a running project, start from the `svelte-ts` template in [Start a project from a template](starter.md#start-with-svelte).
+
+You need Svelte 5 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
+
+## 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.
+
+**When.** A component shows the payload of an event, such as the result of a search.
+
+`sveltePlugin()` adds `eventStore` to the bus. Take it out of the bus once, in the file that makes it, and import it where you need it:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { sveltePlugin } from "nanoeffects/svelte";
+
+// createBus — the event bus, created once outside Svelte
+// sveltePlugin — adds eventStore to the bus
+export const bus = createBus().use(sveltePlugin());
+export const { eventStore } = bus; // a free function: it does not read `this`
+```
+
+## Show the result of an event
+
+<!-- docs-check: continue -->
+
+`eventStore(event, initial)` returns a Svelte store. Its value is `initial` at first and the payload of every `event` after that. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. A payload that is a function is stored, not called.
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — an event with a name; calling it builds { type, payload }
+export const searchLoaded = createAction("search/loaded");
+```
+
+<!-- docs-check: skip - a .svelte file -->
+```svelte
+<script>
+  import { eventStore } from "./bus";
+  import { searchLoaded } from "./search";
+
+  // eventStore — like a store of [], but searchLoaded sets the value
+  const found = eventStore(searchLoaded, []);
+</script>
+
+<ul>
+  {#each $found as title (title)}
+    <li>{title}</li>
+  {/each}
+</ul>
+```
+
+In TypeScript the type of the store comes from the event: with `createAction<string[]>("search/loaded")` it is `Readable<string[]>`, and for an event with no payload type it comes from `initial`.
+
+To send a value to the bus, call `bus.emit` from the handler of the event, for example `oninput`. Nothing is emitted when the component mounts, so no plugin function is needed for that direction.
+
+### It is not a store of the app
+
+The bus listens only while something reads the store: the first `$found` starts it, and the last one stops it. The bus keeps no values, so an event that came while nothing read the store is lost, and a component that mounts later starts from `initial`. To keep a value for components that come later, keep it in a store of your own and write to it from a handler of the event:
+
+```js
+// found-store.js
+import { writable } from "svelte/store";
+import { bus } from "./bus";
+import { searchLoaded } from "./search";
+
+// writable — a Svelte store that you keep for the whole app
+export const foundTitles = writable([]);
+
+// bus.on — copy every searchLoaded into the store, whether or not a component is open
+bus.on(searchLoaded, (titles) => foundTitles.set(titles));
+```
+
+## Where to go next
+
+- The same job for React: [Build a sign-up form in React](react.md); for Vue: [Use nanoeffects in a Vue app](vue.md).
+- A policy in a component (a debounced save): in the script of a component make it once with [`withPolicy`](policies.md#use-a-policy-without-a-bus); Svelte runs the script once, so it needs no hook.