nanoeffects 0.20.0 → 0.22.0

package/docs/README.md

@@ -19,6 +19,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 | Already on Redux / Zustand / MobX / Pinia | [Stores](stores.md) |
 | A React form with async checks | [Build a sign-up form in React](react.md) |
 | A Vue app | [Use nanoeffects in a Vue app](vue.md) |
+| A Svelte app | [Use nanoeffects in a Svelte app](svelte.md) |
 | Old responses overwrite new ones | [Cancel stale requests](cancel-stale-requests.md) |
 | Debounced input that must also cancel the old request | [Debounce and abort](debounce-and-abort.md) |
 | A second click sends a second request | [Prevent a double submit](prevent-double-submit.md) |
@@ -34,6 +35,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 - [Actions, commands, jobs and modules](actions.md)
 - [Sign-up form in React](react.md) — one form: races, double submit, retry
 - [nanoeffects in a Vue app](vue.md) — `watchEmitter` and `useEventRef`
+- [nanoeffects in a Svelte app](svelte.md) — `eventStore`
 - [Context fields](context.md) — store or client on every task
 - [Use the bus from a class](oop.md) — `extendBus`, `@WithBus`, `@On`, and `dispose()` for the subscriptions of an instance
 - [TypeScript in many files](typescript.md) — keep the types of the bus in commands and modules

package/docs/chat-example.md

@@ -44,7 +44,7 @@ Each domain is a folder. The components only emit events and read values; they n
 | `src/domains/incoming/` | New messages, asked for at an interval. |
 | `src/ui/` | The components. |
 
-A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store.
+A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store. Events and commands both live in the events file. An event (`createAction`) says that something happened, and any domain may listen: `rooms/selected` is heard by three. A command (`createCommand`) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createCommand`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
 
 ## Load a history that must not race
 
@@ -173,19 +173,24 @@ export const runSearch = debounce(
 `take` waits for the next event of a name. Start it before the emit that causes the event, so nothing is missed:
 
 ```js
+import { createCommand } from "nanoeffects/actions";
 import { take } from "nanoeffects/effects";
 
+// createCommand — an order for the messages domain, with the handler that does it
+const markMessage = createCommand("messages/mark", (messageId) => console.log("mark", messageId));
+
 // the room that is open, kept from the rooms/selected event
 let selectedRoom = "general";
 
-export const openResult = async (hit, ctx) => {
+export const goToResult = async (hit, ctx) => {
   if (hit.roomId !== selectedRoom) {
     // take — wait for the next event of that name; started before the emit so nothing is missed
     const loaded = take(ctx, "messages/loadHistory/success");
     ctx.emit("rooms/selected", hit.roomId);
     await loaded;
   }
-  ctx.emit("messages/marked", hit.id);
+  // ctx.emit with a command — the messages domain marks the message
+  ctx.emit(markMessage(hit.id));
 };
 ```
 

package/docs/effects.md

@@ -244,18 +244,24 @@ bus.on("watch", (_, ctx) => {
 - Under `latest`, subscriptions of a superseded run end with that run.
 - `ctx.off(event)` clears every handler of the event on the bus, not only the task’s.
 
-`take(ctx, event, options?)` waits for the next `event` and resolves with its payload:
+`take(ctx, event, options?)` waits for the next `event` and resolves with its payload. `event` is the name of an event or an action creator, as for `bus.on`:
 
 ```js
 import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
 import { take, timeout } from "nanoeffects/effects";
 
 const bus = createBus();
+const stopRequested = createAction("stop"); // an event with a name; calling it builds the action
 
 bus.on("login", async (user, ctx) => {
   const reason = await take(ctx, "logout"); // resolves on the next logout
   cleanup(user, reason);
 
+  // an action creator works the same, and its payload type is the type of the result
+  const stopped = await take(ctx, stopRequested);
+  console.log(stopped);
+
   // wait for a matching event, but not longer than 5 s
   const id = await timeout(ctx, 5000, ({ signal }) =>
     take(ctx, "saved", { signal, predicate: (savedId) => savedId === draft.id }),
@@ -264,6 +270,7 @@ bus.on("login", async (user, ctx) => {
 ```
 
 - Sees only events emitted after the call, takes one, and unsubscribes.
+- With an action creator the result has the payload type of the creator. A creator made without a payload type (`createAction("saved")`) takes it from the event map of the bus.
 - `options.predicate` skips payloads it rejects. In TypeScript, a type guard (`(payload): payload is Admin`) narrows the type of the result.
 - `options.signal` stops the wait (how a `race` or `timeout` starter cancels it).
 - On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.

package/docs/migrating-from-saga.md

@@ -14,7 +14,7 @@ Read this page if you know redux-saga and want to find the same job in nanoeffec
 | `fork(fn, x)` | `ctx.run(task, x)` without `await` |
 | `spawn(fn, x)` | `ctx.emit(event, x)` or `bus.emit(event, x)` |
 | `put(action)` | `ctx.emit(action)` |
-| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md) |
+| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md), where `event` is a name or an action creator |
 | `select` | a [context field](context.md), such as `store` |
 | `all`, `race` | [`all`, `race`](effects.md) |
 | `retry`, `delay` | [`retry`, `delay`](effects.md) |
@@ -62,6 +62,8 @@ bus.on(
 
 Tasks are plain `async` functions. `ctx.signal` replaces `cancel`: pass it to `fetch` or to your client, and the request stops.
 
+To see the counter, `takeLatest` with `delay`, a cancel and a failing call running, open the [counter example](../examples/counter): it has a page without a store and a page with Redux Toolkit.
+
 ## Start a task without waiting
 
 `fork` and `spawn` differ in what happens when the caller is aborted. Pick by that.

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/policies.md

@@ -36,6 +36,33 @@ Every policy accepts `key` in its options (see [Isolate state by key](#isolate-s
 | `throttle(ms, fn, options?)` | at most one run per `ms` |
 | `queue(fn, options?)` | one after another, in order |
 
+## Call a policy without its function
+
+**Problem.** Some code builds the function for you and only asks which policy to use, as [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) does. If you must pass your own function there, it is easy to pass the wrong one.
+
+**When.** You pass a policy to `usePolicy`. With a bus, `withPolicy` or your own code, call the policy with its function as above.
+
+Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+
+```js
+import { debounce } from "nanoeffects/policies";
+
+const runSearch = async (query) => {
+  await api.search(query);
+};
+
+// debounce(300) — no function yet: returns a wrapper
+const wrap = debounce(300);
+
+// the wrapper takes the function; same as debounce(300, runSearch)
+const search = wrap(runSearch);
+```
+
+- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
+- Each time you apply a wrapper to a function, you get a new policy with its own state.
+- To combine policies, nest them as before: `throttle(100, latest(fn))`.
+- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
+
 ## Configure debounce and throttle
 
 `debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.

package/docs/query-libraries.md

@@ -122,3 +122,5 @@ Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the c
 - **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Commands that fetch are async, so this only matters for a sync handler that sets up a callback.
 - **Give each request its own signal for an event.** For a command or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
 - **The signal reaches the tasks that this `emit` starts**, with the listeners of the command's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.
+
+A whole small app, with a search, a filter, pages and a detail panel, is in the [Rick and Morty example](../examples/rickandmorty).

package/docs/react.md

@@ -248,8 +248,8 @@ export const Search = ({ wait }) => {
       const found = await api.search(query, { signal });
       setItems(found);
     },
-    // the second argument builds the policy once; task runs the callback above
-    (task) => debounce(wait, task),
+    // debounce(wait) — the second argument builds the policy once around the callback above
+    debounce(wait),
     // deps — list what the second argument reads; a new wait makes a new policy
     [wait],
   );
@@ -265,7 +265,9 @@ export const Search = ({ wait }) => {
 
 - `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
 - A pending call is cancelled on unmount and when `deps` change.
-- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Write the policy without its callback: `debounce(300)`, not `debounce(300, callback)`. `usePolicy` puts the callback in itself, always the one of the latest render.
+- To combine policies, write a function of the task: `(task) => throttle(100, latest(task))`. Here `task` is the callback that `usePolicy` keeps current; pass it, not your own function.
+- `deps` stay your job: `debounce(wait)` is made again on every render, but only the first one (and the one after `deps` change) is used.
 - Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
 
 ## Where to go next

package/docs/starter.md

@@ -48,6 +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 `eventStore` from `nanoeffects/svelte` | You build a Svelte app |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
@@ -71,6 +72,16 @@ npm create nanoeffects@latest my-app -- --template vue-ts
 
 `npm run build` type-checks the `.vue` files with `vue-tsc`, which needs TypeScript 5: the template depends on it.
 
+### Start with Svelte
+
+`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
+```
+
+`npm run build` type-checks the `.svelte` files with `svelte-check`, which needs TypeScript 5: the template depends on it.
+
 ### Start with domains
 
 `domains-ts` is not the search box of the other templates grown in TypeScript: it shows where logic goes when an app has several features. Each domain is a folder under `src/domains/`. It has the events of the domain, the work that handles them, and a module that mounts the work. The React components only emit events and read values.
@@ -93,7 +104,7 @@ The commands, jobs and modules themselves are explained in [Actions, commands, j
 
 ## Read the files
 
-Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components).
+Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components, `.svelte` for Svelte components).
 
 | File | Job |
 | ---- | --- |

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.

package/llms-full.txt

@@ -9,7 +9,7 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ---
@@ -553,6 +553,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 `eventStore` from `nanoeffects/svelte` | You build a Svelte app |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
@@ -576,6 +577,16 @@ npm create nanoeffects@latest my-app -- --template vue-ts
 
 `npm run build` type-checks the `.vue` files with `vue-tsc`, which needs TypeScript 5: the template depends on it.
 
+### Start with Svelte
+
+`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
+```
+
+`npm run build` type-checks the `.svelte` files with `svelte-check`, which needs TypeScript 5: the template depends on it.
+
 ### Start with domains
 
 `domains-ts` is not the search box of the other templates grown in TypeScript: it shows where logic goes when an app has several features. Each domain is a folder under `src/domains/`. It has the events of the domain, the work that handles them, and a module that mounts the work. The React components only emit events and read values.
@@ -598,7 +609,7 @@ The commands, jobs and modules themselves are explained in [Actions, commands, j
 
 ## Read the files
 
-Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components).
+Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components, `.svelte` for Svelte components).
 
 | File | Job |
 | ---- | --- |
@@ -681,6 +692,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) |
@@ -1069,6 +1081,33 @@ Every policy accepts `key` in its options (see [Isolate state by key](#isolate-s
 | `throttle(ms, fn, options?)` | at most one run per `ms` |
 | `queue(fn, options?)` | one after another, in order |
 
+## Call a policy without its function
+
+**Problem.** Some code builds the function for you and only asks which policy to use, as [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) does. If you must pass your own function there, it is easy to pass the wrong one.
+
+**When.** You pass a policy to `usePolicy`. With a bus, `withPolicy` or your own code, call the policy with its function as above.
+
+Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+
+```js
+import { debounce } from "nanoeffects/policies";
+
+const runSearch = async (query) => {
+  await api.search(query);
+};
+
+// debounce(300) — no function yet: returns a wrapper
+const wrap = debounce(300);
+
+// the wrapper takes the function; same as debounce(300, runSearch)
+const search = wrap(runSearch);
+```
+
+- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
+- Each time you apply a wrapper to a function, you get a new policy with its own state.
+- To combine policies, nest them as before: `throttle(100, latest(fn))`.
+- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
+
 ## Configure debounce and throttle
 
 `debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.
@@ -1789,18 +1828,24 @@ bus.on("watch", (_, ctx) => {
 - Under `latest`, subscriptions of a superseded run end with that run.
 - `ctx.off(event)` clears every handler of the event on the bus, not only the task’s.
 
-`take(ctx, event, options?)` waits for the next `event` and resolves with its payload:
+`take(ctx, event, options?)` waits for the next `event` and resolves with its payload. `event` is the name of an event or an action creator, as for `bus.on`:
 
 ```js
 import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
 import { take, timeout } from "nanoeffects/effects";
 
 const bus = createBus();
+const stopRequested = createAction("stop"); // an event with a name; calling it builds the action
 
 bus.on("login", async (user, ctx) => {
   const reason = await take(ctx, "logout"); // resolves on the next logout
   cleanup(user, reason);
 
+  // an action creator works the same, and its payload type is the type of the result
+  const stopped = await take(ctx, stopRequested);
+  console.log(stopped);
+
   // wait for a matching event, but not longer than 5 s
   const id = await timeout(ctx, 5000, ({ signal }) =>
     take(ctx, "saved", { signal, predicate: (savedId) => savedId === draft.id }),
@@ -1809,6 +1854,7 @@ bus.on("login", async (user, ctx) => {
 ```
 
 - Sees only events emitted after the call, takes one, and unsubscribes.
+- With an action creator the result has the payload type of the creator. A creator made without a payload type (`createAction("saved")`) takes it from the event map of the bus.
 - `options.predicate` skips payloads it rejects. In TypeScript, a type guard (`(payload): payload is Admin`) narrows the type of the result.
 - `options.signal` stops the wait (how a `race` or `timeout` starter cancels it).
 - On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.
@@ -2249,7 +2295,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
@@ -3022,6 +3068,8 @@ Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the c
 - **Give each request its own signal for an event.** For a command or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
 - **The signal reaches the tasks that this `emit` starts**, with the listeners of the command's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.
 
+A whole small app, with a search, a filter, pages and a detail panel, is in the [Rick and Morty example](../examples/rickandmorty).
+
 ---
 Source: docs/react.md
 
@@ -3275,8 +3323,8 @@ export const Search = ({ wait }) => {
       const found = await api.search(query, { signal });
       setItems(found);
     },
-    // the second argument builds the policy once; task runs the callback above
-    (task) => debounce(wait, task),
+    // debounce(wait) — the second argument builds the policy once around the callback above
+    debounce(wait),
     // deps — list what the second argument reads; a new wait makes a new policy
     [wait],
   );
@@ -3292,7 +3340,9 @@ export const Search = ({ wait }) => {
 
 - `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
 - A pending call is cancelled on unmount and when `deps` change.
-- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Write the policy without its callback: `debounce(300)`, not `debounce(300, callback)`. `usePolicy` puts the callback in itself, always the one of the latest render.
+- To combine policies, write a function of the task: `(task) => throttle(100, latest(task))`. Here `task` is the callback that `usePolicy` keeps current; pass it, not your own function.
+- `deps` stay your job: `debounce(wait)` is made again on every render, but only the first one (and the one after `deps` change) is used.
 - Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
 
 ## Where to go next
@@ -3352,7 +3402,7 @@ Each domain is a folder. The components only emit events and read values; they n
 | `src/domains/incoming/` | New messages, asked for at an interval. |
 | `src/ui/` | The components. |
 
-A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store.
+A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store. Events and commands both live in the events file. An event (`createAction`) says that something happened, and any domain may listen: `rooms/selected` is heard by three. A command (`createCommand`) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createCommand`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
 
 ## Load a history that must not race
 
@@ -3481,19 +3531,24 @@ export const runSearch = debounce(
 `take` waits for the next event of a name. Start it before the emit that causes the event, so nothing is missed:
 
 ```js
+import { createCommand } from "nanoeffects/actions";
 import { take } from "nanoeffects/effects";
 
+// createCommand — an order for the messages domain, with the handler that does it
+const markMessage = createCommand("messages/mark", (messageId) => console.log("mark", messageId));
+
 // the room that is open, kept from the rooms/selected event
 let selectedRoom = "general";
 
-export const openResult = async (hit, ctx) => {
+export const goToResult = async (hit, ctx) => {
   if (hit.roomId !== selectedRoom) {
     // take — wait for the next event of that name; started before the emit so nothing is missed
     const loaded = take(ctx, "messages/loadHistory/success");
     ctx.emit("rooms/selected", hit.roomId);
     await loaded;
   }
-  ctx.emit("messages/marked", hit.id);
+  // ctx.emit with a command — the messages domain marks the message
+  ctx.emit(markMessage(hit.id));
 };
 ```
 
@@ -3648,6 +3703,91 @@ In TypeScript the type of the `ref` comes from the event: with `createAction<str
 - A policy in a component (a debounced save): in `<script setup>` make it once with [`withPolicy`](policies.md#use-a-policy-without-a-bus); Vue runs the setup once, so it needs no hook.
 - Keep values in Pinia: [Connect Redux, Zustand, MobX, or Pinia](stores.md).
 
+---
+Source: docs/svelte.md
+
+# 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.
+
 ---
 Source: docs/context.md
 
@@ -4586,7 +4726,7 @@ Read this page if you know redux-saga and want to find the same job in nanoeffec
 | `fork(fn, x)` | `ctx.run(task, x)` without `await` |
 | `spawn(fn, x)` | `ctx.emit(event, x)` or `bus.emit(event, x)` |
 | `put(action)` | `ctx.emit(action)` |
-| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md) |
+| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md), where `event` is a name or an action creator |
 | `select` | a [context field](context.md), such as `store` |
 | `all`, `race` | [`all`, `race`](effects.md) |
 | `retry`, `delay` | [`retry`, `delay`](effects.md) |
@@ -4634,6 +4774,8 @@ bus.on(
 
 Tasks are plain `async` functions. `ctx.signal` replaces `cancel`: pass it to `fetch` or to your client, and the request stops.
 
+To see the counter, `takeLatest` with `delay`, a cancel and a failing call running, open the [counter example](../examples/counter): it has a page without a store and a page with Redux Toolkit.
+
 ## Start a task without waiting
 
 `fork` and `spawn` differ in what happens when the caller is aborted. Pick by that.

package/llms.txt

@@ -9,13 +9,13 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ## Start here
 
 - [Guide](docs/guide.md): bus, handler context, policies, effects, commands and modules, step by step
-- [Start a project from a template](docs/starter.md): `npm create nanoeffects` makes a Vite project (`vanilla`, `react`, `vue-ts` and others, in JavaScript or TypeScript) with a bus, `debounce` and `latest`
+- [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
 - [Plugins](docs/plugins.md): every plugin of a bus, what `bus.use` returns, and the order to use them in
@@ -37,6 +37,7 @@ Rules that generated code often gets wrong:
 - [Build a sign-up form in React](docs/react.md): a form with a username check, a submit that cannot fire twice, and retry; `useEventState` shows an event as state, `usePolicy` keeps a debounced handler between renders
 - [Build a chat with domains, modules and a small server](docs/chat-example.md): rooms, a history under `latest`, a send under `queue` and `retry`, a search with `allSettled` and `timeout`, new messages polled with `poll`
 - [Use nanoeffects in a Vue app](docs/vue.md): `vuePlugin` adds `watchEmitter` (a value of a component to the bus) and `useEventRef` (an event as a ref)
+- [Use nanoeffects in a Svelte app](docs/svelte.md): `sveltePlugin` adds `eventStore` (an event as a Svelte store)
 - [Context fields](docs/context.md): put a store or client on every task
 - [Scopes](docs/scope.md): fields for one command, action, job, module or `emit`, and a way to replace them in a test
 - [Use the bus from a class](docs/oop.md): `Emitter`, `extendBus`, `@WithBus`, `@On`, `@Once`, and `dispose()` for the subscriptions of an instance