nanoeffects 0.3.0 → 0.5.0

package/docs/migrating-from-effector.md

@@ -0,0 +1,293 @@
+# Coming from Effector
+
+Read this page if your project uses Effector and you want to know where nanoeffects fits. They overlap in one place: events that start effects. Effector also holds state; nanoeffects does not. It maps the names, shows one effect both ways, and lists what has no equivalent.
+
+## Split the work
+
+| Job | Use |
+| --- | --- |
+| Hold state (`createStore`, `combine`, `restore`) | Effector, or any store: [Stores](stores.md) |
+| Derive state from events (`.on`, `sample` into a store) | Effector, or any store |
+| Run a request when an event happens, cancel, retry, time out, trace | nanoeffects |
+
+nanoeffects has no store. `createStore` can be replaced by any store you like, for example Zustand: a store and its `set` do the job of `createStore` and `.on`. [Stores](stores.md) shows how each of Zustand, Redux, MobX, Jotai and others calls the bus. If you keep Effector, use nanoeffects only for the effects that `createEffect` runs with little control over overlapping calls.
+
+## Find the equivalent
+
+| Effector | nanoeffects |
+| -------- | ----------- |
+| `createEvent()` | an event name on the bus, or [`createAction`](actions.md) |
+| event call `loaded(user)` | `bus.emit("loaded", user)` |
+| `createEffect(handler)` | a handler: `bus.on(event, handler)` |
+| effect with `done` and `fail` | [`createJob`](actions.md): emits the success and fail actions |
+| `effect.pending` | not provided: keep a flag in your store, or read it from [Tracing](tracing.md) |
+| `sample({ clock, fn, target })` | `bus.on(clock, handler)` and `ctx.emit(target, …)` |
+| `sample({ source: $store, clock })` | read the store from a [context field](context.md) in the handler |
+| `sample({ filter })` | an `if` in the handler |
+| `debounce`, `throttle` from patronum | [`debounce`, `throttle`](policies.md) (same rules as lodash, checked in tests) |
+| take only the last effect call | [`latest`](policies.md) |
+| `attach` | a [context field](context.md): the handler reads it from `ctx` |
+| `fork()` and scope | one `createBus()` per scope |
+| `createStore`, `combine`, `restore` | any store, such as Zustand, Redux, MobX or Jotai: see [Stores](stores.md) |
+| `watch`, `createWatch` | `bus.on(event, handler)` |
+| `event.prepend(fn)` | a function that you write, `(event) => ({ key, value })`; the bus needs nothing |
+| `useStoreMap({ store, keys, fn })` | a selector of your store; with `useState` the component keeps the value |
+| `event.watch((e) => e.preventDefault())` | call `event.preventDefault()` in the `onSubmit` handler |
+
+## Rewrite an effect
+
+A search that runs on every query, and reacts to the result:
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+// Effector
+import { createEffect, createEvent, createStore, sample } from "effector";
+
+const queryChanged = createEvent();
+const searchFx = createEffect((query) => api.search(query));
+const $items = createStore([]).on(searchFx.doneData, (_, items) => items);
+
+sample({ clock: queryChanged, target: searchFx });
+```
+
+If the user types fast, several `searchFx` calls overlap, and the old ones are not cancelled. The same job in nanoeffects, with the old request cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer query aborts the request in flight
+const search = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("found", items);
+});
+
+bus.on("query-changed", debounce(300, search)); // debounce: run after 300 ms of quiet
+```
+
+The store (`$items`) is not here. Keep it in Effector and update it from the `found` event, or replace it with a store of your choice. The next example does that with Zustand.
+
+### Keep the state in Zustand
+
+Without Effector, something must hold `$items`. A Zustand store does it: `create` replaces `createStore`, and `setState` replaces `.on(searchFx.doneData, …)`. The handler writes the result to the store directly, so the `found` event is not needed. A component reads the store with a selector, as `useUnit($items)` did.
+
+```jsx
+// search-zustand.jsx
+import { create } from "zustand";
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+// create — Zustand: the store replaces $items
+const useSearchStore = create(() => ({ items: [] }));
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest — a newer query aborts the request in flight; debounce — wait 300 ms of quiet
+const search = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  useSearchStore.setState({ items }); // Zustand: replaces .on(searchFx.doneData, …)
+});
+
+bus.on("query-changed", debounce(300, search));
+
+export function Search() {
+  const items = useSearchStore((state) => state.items); // Zustand: a selector reads items
+
+  return (
+    <div>
+      <input onChange={(event) => bus.emit("query-changed", event.target.value)} />
+      <ul>
+        {items.map((item) => (
+          <li key={item.id}>{item.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+`bus.emit("query-changed", …)` in `onChange` does the work of calling the `queryChanged` event. To also start a task when the store changes, see [Zustand in Stores](stores.md#zustand).
+
+## Rewrite a form
+
+The form from the [Forms recipe of the Effector docs](https://effector.dev/en/recipes/react/forms/) has five parts: an event for a change of a field (`fieldUpdate`), a store for the values (`$form`), an event for the submit (`formSubmitted`), an effect that sends them (`sendFormFx`), and a `sample` that reads the store when the form is submitted. Four of them keep state or wire units together. Only the effect has a counterpart in nanoeffects.
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```jsx
+// Effector (adapted from the Effector docs)
+import { createEffect, createEvent, createStore, sample } from "effector";
+import { useStoreMap } from "effector-react";
+
+const formSubmitted = createEvent();
+const fieldUpdate = createEvent();
+
+const sendFormFx = createEffect((params) => {
+  console.log(params);
+});
+
+const $form = createStore({});
+$form.on(fieldUpdate, (form, { key, value }) => ({ ...form, [key]: value }));
+
+// sample: when the form is submitted, read $form and run the effect with it
+sample({ clock: formSubmitted, source: $form, target: sendFormFx });
+
+// prepend: turn a DOM event into the { key, value } that fieldUpdate takes
+const handleChange = fieldUpdate.prepend((event) => ({
+  key: event.target.name,
+  value: event.target.value,
+}));
+
+const Field = ({ name, type, label }) => {
+  const value = useStoreMap({
+    store: $form,
+    keys: [name],
+    fn: (values) => values[name] ?? "",
+  });
+
+  return (
+    <div>
+      {label} <input name={name} type={type} value={value} onChange={handleChange} />
+    </div>
+  );
+};
+
+const App = () => (
+  <form onSubmit={formSubmitted}>
+    <Field name="login" label="Login" />
+    <Field name="password" type="password" label="Password" />
+    <button type="submit">Submit!</button>
+  </form>
+);
+
+formSubmitted.watch((event) => {
+  event.preventDefault();
+});
+```
+
+The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus, in its own file:
+
+```js
+// form-bus.js
+import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: events and their handlers
+
+// bus.on — the job of sendFormFx: runs when the form is submitted
+bus.on("form/submitted", (values) => {
+  console.log(values);
+});
+```
+
+Then the form. `useState` does the work of `$form`, `fieldUpdate` and `prepend`; the event handler does the work of the `watch` that called `preventDefault`:
+
+```jsx
+// App.jsx
+import { useState } from "react";
+import { bus } from "./form-bus"; // the bus of the previous snippet
+
+function Field({ name, type, label, value, onChange }) {
+  return (
+    <div>
+      {label} <input name={name} type={type} value={value} onChange={onChange} />
+    </div>
+  );
+}
+
+export function App() {
+  const [form, setForm] = useState({}); // the values of the form, as $form held them
+
+  // one handler for every field, as handleChange was
+  function handleChange(event) {
+    const { name, value } = event.target;
+    setForm((current) => ({ ...current, [name]: value }));
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault(); // the page must not reload; no separate watcher is needed
+    bus.emit("form/submitted", form); // bus.emit — the values go in the event
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Field name="login" label="Login" value={form.login ?? ""} onChange={handleChange} />
+      <Field
+        name="password"
+        type="password"
+        label="Password"
+        value={form.password ?? ""}
+        onChange={handleChange}
+      />
+      <button type="submit">Submit!</button>
+    </form>
+  );
+}
+```
+
+`useStoreMap` re-renders only the field whose value changed. Here every field re-renders with the form, which is fine for a small form. If it matters, use the selector of your store (Zustand and Jotai have one).
+
+If the values live in a store outside React, give the store to the handlers with `createBus({ context: { store } })` ([Context fields](context.md)) and read it in the handler, as `sample` read `$form`.
+
+### Replace the log with a request
+
+`sendFormFx` only logs. A real sign-up sends a request, and then the double click and the network matter. `leading` drops a second submit while the first one runs, and `ctx.signal` lets the request be cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and their handlers
+
+// leading — a second submit is ignored while the request is running
+bus.on(
+  "form/submitted",
+  leading(async (values, ctx) => {
+    // api — your client; ctx.signal lets the request be cancelled
+    await api.signUp(values, { signal: ctx.signal });
+  }),
+);
+```
+
+Retrying a failed network request, and cancelling when the form closes, are in [Build a sign-up form in React](react.md).
+
+## Use both in one app
+
+Keep the Effector stores, and run the effects on the bus. A store calls the bus through `bus.emitter`, and the handler sends the result back as an event that the store listens to.
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+import { createEvent, createStore } from "effector";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+
+const queryChanged = createAction("query/changed"); // a plain action creator
+
+const found = createEvent(); // Effector: the result comes back as an event
+const $items = createStore([]).on(found, (_, items) => items);
+const $query = createStore("");
+
+// watch calls back on every change of the store; bus.emitter turns it into an emit
+$query.watch(bus.emitter(queryChanged));
+
+bus.on(
+  queryChanged,
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal });
+    found(items); // back to Effector
+  }),
+);
+```
+
+## What is different
+
+- **No state.** There is no `createStore`, `combine`, `restore`, `$store.map`. The bus holds listeners only. Take a store such as Zustand for state ([Stores](stores.md)).
+- **No `pending`.** A running task is visible through [Tracing](tracing.md), not through a store. A flag in your store set at the start and the end of the handler does the job.
+- **Cancellation is the default tool.** An Effector effect runs every call to the end. Here `latest` and `ctx.signal` stop what is no longer needed.
+- **Events are matched by name, not by identity.** An event is a string or a `createAction` creator, not a unit that you import and call. Two modules agree on the name.
+- **No graph.** `sample` and `forward` build a static graph. A bus subscribes handlers at runtime and the call order is the order of `on`.
+- **The event carries the data.** `sample({ source })` reads a store at the moment of the clock. Here the sender puts the values in the event (`bus.emit("form/submitted", form)`), or the handler reads a store from a [context field](context.md).
+- **Scopes are buses.** `fork()` becomes a `createBus()` per scope (a test, a request on the server).

package/docs/migrating-from-rxjs.md

@@ -0,0 +1,127 @@
+# Use nanoeffects next to RxJS
+
+Read this page if your project uses RxJS and you wonder what nanoeffects takes over. It does not replace RxJS. The two split the work: RxJS shapes streams of values, nanoeffects runs the side effects that events start. It maps the operators, shows one search box both ways, and lists what stays in RxJS.
+
+## Split the work
+
+| Job | Use |
+| --- | --- |
+| Start a request when something happens, cancel it when a newer one arrives, retry it, time it out | nanoeffects |
+| Know which task started which, log and trace it | nanoeffects ([Tracing](tracing.md)) |
+| Combine several streams, keep a running value, buffer, window, merge over time | RxJS |
+| Work with a stream as a value (`map`, `scan`, `combineLatest`) | RxJS |
+
+A handler in nanoeffects is one function per event. A pipeline in RxJS is a chain of operators over a stream. If your pipeline is a few operators that end in `switchMap` and a request, it fits a handler with a policy and is shorter. If it combines streams, it stays.
+
+## Find the equivalent
+
+| RxJS | nanoeffects |
+| ---- | ----------- |
+| `mergeMap` | `bus.on(event, handler)`: every event starts a task |
+| `switchMap` | [`latest`](policies.md) |
+| `exhaustMap` | [`leading`](policies.md) |
+| `concatMap` | [`queue`](policies.md) |
+| `debounceTime` | [`debounce`](policies.md) |
+| `throttleTime` | [`throttle`](policies.md) |
+| `groupBy` + `switchMap` | `latest(handler, { key })` |
+| `retry`, `retryWhen` | [`retry`, `backoff`](effects.md) |
+| `timeout` | [`timeout`](effects.md) |
+| `interval` + `switchMap` | [`poll`](effects.md) |
+| `takeUntil(stop$)` | `ctx.signal`, and [`take`](effects.md) to wait for the stop event |
+| `forkJoin` | [`all`](effects.md) |
+| `race` | [`race`](effects.md) |
+| `firstValueFrom(fromEvent(…))` | [`take(ctx, event)`](effects.md) |
+| `Subject` | `bus.emit` and `bus.on` |
+| `map`, `filter`, `scan`, `combineLatest`, `buffer`, `window`, `share` | stay in RxJS |
+| `distinctUntilChanged` | a check in the handler, or in the store subscription (see [Stores](stores.md)) |
+
+A policy and an operator differ in one thing. `switchMap` drops the old inner stream. `latest` aborts the old task through its `signal`, so a `fetch` that got the signal stops. Pass the signal on, or the work goes on in the background.
+
+## Rewrite a search box
+
+The same job in RxJS: wait for a pause, skip repeats, cancel the old request.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+// RxJS
+import { fromEvent } from "rxjs";
+import { debounceTime, distinctUntilChanged, map, switchMap } from "rxjs/operators";
+
+fromEvent(input, "input")
+  .pipe(
+    map((event) => event.target.value),
+    debounceTime(300),
+    distinctUntilChanged(),
+    switchMap((query) => api.searchStream(query)),
+  )
+  .subscribe((items) => render(items));
+```
+
+The same job in nanoeffects:
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer search aborts the request in flight
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce: run after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+
+bus.on("results", (items) => render(items));
+
+const input = document.querySelector("#search"); // the search box
+input.addEventListener("input", (event) => bus.emit("typed", event.target.value));
+```
+
+The skip of repeated values is not here. Add `if (query === lastQuery) return;` to the handler, or keep that one step in RxJS (next section).
+
+## Use both in one app
+
+Keep RxJS where a stream is how you think, and let events cross to the bus in either direction.
+
+**Bus to RxJS.** `createObserve(bus)` gives an Observable of an event ([Observables](observable.md)).
+
+**RxJS to bus.** `bus.emitter(action)` returns a callback that emits the action, so it is the argument of `subscribe` ([Stores](stores.md) has the plugin).
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { combineLatest } from "rxjs";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+
+const filtersChanged = createAction("filters/changed"); // a plain action creator
+
+// RxJS: combine two streams into one value; nanoeffects does not do that
+const subscription = combineLatest([query$, category$]).subscribe(
+  bus.emitter(filtersChanged), // calls bus.emit(filtersChanged(value))
+);
+
+// nanoeffects: one cancellable request per change of the filters
+bus.on(
+  filtersChanged,
+  latest(async ([query, category], { signal }) => {
+    const items = await api.search(query, category, { signal });
+    bus.emit("results", items);
+  }),
+);
+```
+
+The subscription is not tied to a task. Call `subscription.unsubscribe()` when the screen goes away.
+
+## What is different
+
+- **No streams of values.** A handler gets one payload and runs a task. There is no `pipe`, no operator for the values that follow.
+- **Abort replaces unsubscribe for work in flight.** A stopped task is stopped through its `signal`. Pass it to `fetch` or to the client.
+- **Errors are not part of the stream.** A failed task rejects its own promise. Without `onError` on the bus nobody else hears it ([Errors](errors.md)).
+- **No completion.** An event bus does not end. A task ends when its work ends or its signal aborts.
+- **No marble tests.** Test with the real handler and fake timers.

package/docs/migrating-from-saga.md

@@ -0,0 +1,93 @@
+# Coming from redux-saga
+
+Read this page if you know redux-saga and want to find the same job in nanoeffects. It maps the names, shows one saga rewritten, and lists what has no equivalent. It does not teach the library: start with the [Guide](guide.md).
+
+## Find the equivalent
+
+| redux-saga | nanoeffects |
+| ---------- | ----------- |
+| `takeEvery` | `bus.on(event, handler)` |
+| `takeLatest` | [`latest`](policies.md) |
+| `takeLeading` | [`leading`](policies.md) |
+| `debounce`, `throttle` | [`debounce`, `throttle`](policies.md) (same rules as lodash) |
+| `call(fn, x)` | `await ctx.run(task, x)` |
+| `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) |
+| `select` | a [context field](context.md), such as `store` |
+| `all`, `race` | [`all`, `race`](effects.md) |
+| `retry`, `delay` | [`retry`, `delay`](effects.md) |
+| `cancel(task)` | `ctx.abort()` on the context, or a newer call under `latest` |
+| `eventChannel` | `bus.emitter(action)` as the callback of the subscription |
+| `actionChannel` | [`queue`](policies.md) and the other policies |
+
+## Rewrite a saga
+
+A saga that searches on every new query, cancels the older request, and retries a failed one:
+
+<!-- docs-check: skip - redux-saga code, not nanoeffects -->
+```js
+// redux-saga
+function* search({ payload }) {
+  const items = yield retry(3, 1000, api.search, payload);
+  yield put(found(items));
+}
+function* watchSearch() {
+  yield takeLatest("search", search);
+}
+```
+
+The same job in nanoeffects:
+
+```js
+import { createBus } from "nanoeffects";
+import { retry } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const search = (query, { signal }) => api.search(query, { signal });
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // latest: a newer "search" aborts this run; ctx.signal is aborted
+    const load = retry(search, { times: 3, delay: 1000 }); // retry: up to 3 attempts, 1 s apart
+    const items = await ctx.run(load, query); // child task, aborted with this handler
+    ctx.emit("found", items); // like put
+  }),
+);
+```
+
+Tasks are plain `async` functions. `ctx.signal` replaces `cancel`: pass it to `fetch` or to your client, and the request stops.
+
+## Start a task without waiting
+
+`fork` and `spawn` differ in what happens when the caller is aborted. Pick by that.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+const loadSidebar = (_, { signal }) => api.sidebar({ signal });
+
+bus.on("page-opened", async (_, ctx) => {
+  // like fork: a child of this task, aborted with it
+  const warmUp = ctx.run(loadSidebar);
+  warmUp.catch(console.error); // nobody awaits it, so handle the error here
+
+  // like spawn: a new task, not stopped when this one is aborted
+  ctx.emit("analytics", { page: "home" });
+});
+```
+
+## What is different
+
+- **Errors go up only through `await`.** `await ctx.run(task)` and `all(ctx, …)` throw the error of a child to the caller. A child that nobody awaits does not abort its parent, as a forked child does in redux-saga: handle it yourself, as above. See [Errors](errors.md).
+- **Abort goes down.** Aborting a task aborts its children. A child does not abort its siblings.
+- **Effects are not data.** `yield call(fn)` returns a description that a test can compare. Here `await` calls the function. Test with the real handler and fake timers, as the tests of this library do.
+- **No generators.** Sequential flows are `async` functions with `await take(ctx, event)`.
+- **No `END` of a channel.** A task stops when its signal aborts.
+- **One payload.** A task has one argument, so pass an object where a saga passes several.

package/docs/observable.md

@@ -1,22 +1,24 @@
-# Observable: events as streams
+# Turn events into Observables
 
-`createObserve(bus)` from `nanoeffects/observable` turns an event of the bus into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is, and nothing here depends on them.
+Use this page only when you already work in Observables / RxJS. Prefer `bus.on` with policies for cancellation and tracing.
 
-```ts
+`createObserve(bus)` from `nanoeffects/observable` turns a bus event into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is. Nothing here depends on them.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
 import { from } from "rxjs";
 import { debounceTime, distinctUntilChanged, switchMap } from "rxjs/operators";
 import { createObserve } from "nanoeffects/observable";
 
-const observe = createObserve(bus);
+const observe = createObserve(bus); // Observable per event name
 
-// events of the bus as a stream
 from(observe("typed"))
   .pipe(debounceTime(300), distinctUntilChanged(), switchMap(searchRequest))
   .subscribe((items) => bus.emit("results", items));
 ```
 
-- `observe(event)` returns an Observable of the payloads of that event. Each `subscribe` is a `bus.on` of its own, and `unsubscribe()` removes it.
+- `observe(event)` returns an Observable of the payloads of that event. Each `subscribe` is a `bus.on` of its own; `unsubscribe()` removes it.
 - `subscribe` takes a function or an object with `next`.
-- The stream never completes and never fails: events are the only thing that arrives. Errors of the handler of the subscriber belong to the subscriber.
-- A subscription made this way is not tied to a task, so end it yourself: `onAbort(ctx, subscription.unsubscribe)` inside a task, or with the signal of a module.
-- For cancellation, policies and tracing keep to `bus.on` with `latest`, `debounce`, `queue`: they know about tasks. The Observable is for the places where a stream is already the way you work.
+- The stream never completes and never fails: events are the only thing that arrives. Errors of the subscriber’s handler belong to the subscriber.
+- A subscription made this way is not tied to a task. End it yourself: `onAbort(ctx, subscription.unsubscribe)` inside a task, or with the signal of a module.
+- For cancellation, policies, and tracing, keep to `bus.on` with `latest`, `debounce`, `queue` — they know about tasks. The Observable is for places where a stream is already how you work.

package/docs/package.md

@@ -0,0 +1,24 @@
+# Choose a package entry
+
+Imports are split so you only load what you use. `createBus` stays small; the rest is another entry.
+
+| Import | What is in it |
+| ------ | ------------- |
+| `nanoeffects` | `createBus`, the types |
+| `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
+| `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
+| `nanoeffects/actions` | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin`, `commandsPlugin` |
+| `nanoeffects/redux` | `createEffectsMiddleware` |
+| `nanoeffects/observable` | `createObserve` |
+| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
+| `nanoeffects/dev` | `devPlugin` (no-op in production) |
+| `nanoeffects/trace` | `createTracer` and the loggers |
+
+## Give the docs to an AI assistant
+
+The package ships two plain-text files for assistants that write code with it:
+
+- `llms.txt`: a short index. It states the rules that generated code often gets wrong and links to every page of these docs.
+- `llms-full.txt`: the same summary followed by the text of every linked page, in one file.
+
+Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. Both match the installed version.