nanoeffects 0.5.0 → 0.7.0

package/docs/plugins.md

@@ -0,0 +1,108 @@
+# Choose the plugins of a bus
+
+Optional. A plugin adds one thing to a bus: fields on `ctx`, a method, a registry of handlers, diagnostics. Read this page when you want to know which plugins exist, what each one returns, and in what order to use them. Skip it for a small bus: `createBus()` alone is enough.
+
+## Use a plugin
+
+A plugin is a function of the bus. `bus.use(plugin)` calls it with the bus and returns whatever the plugin returns.
+
+```js
+import { createBus } from "nanoeffects";
+
+// your own plugin: a function of the bus that returns what you want back
+const countPlugin = (bus) => {
+  let count = 0;
+  const unbind = bus.on("*", () => {
+    count += 1;
+  });
+  return { count: () => count, stop: unbind };
+};
+
+const bus = createBus();
+// use — calls countPlugin(bus) and returns its result
+const counter = bus.use(countPlugin);
+
+bus.emit("greet", "Ada");
+console.log(counter.count()); // 1
+counter.stop();
+```
+
+The bus keeps no list of plugins. A plugin that was used cannot be taken out by the bus; it returns its own `stop` or `disconnect` when it needs one.
+
+## See every plugin
+
+| Plugin | Import | It adds | `bus.use` returns | Page |
+| ------ | ------ | ------- | ----------------- | ---- |
+| `contextPlugin` | `nanoeffects` | Fields on `ctx` of every task | The same bus, typed with the fields | [Context fields](context.md) |
+| `effectsPlugin` | `nanoeffects/effects` | `race`, `all`, `take`, `delay` and your own effects on `ctx`, bound to the task | The same bus, typed with the effects | [Effects](effects.md#put-selected-effects-on-ctx) |
+| `scopePlugin` | `nanoeffects/scope` | Fields and effects for one command, action, job, module or `emit` | The same bus | [Scopes](scope.md) |
+| `commandsPlugin` | `nanoeffects/actions` | The registry of command handlers, `bus.commands` | The registry `{ run, handle }` | [Actions](actions.md#describe-events-commands-and-jobs) |
+| `modulePlugin` | `nanoeffects/actions` | Modules that mount and unmount as one unit | The app `{ mount, unmount, isMounted, dispose, commands, createModule }` | [Modules](actions.md#mount-domains-with-modules) |
+| `emitterPlugin` | `nanoeffects/actions` | `bus.emitter(creator)`, a callback that emits an action | The same bus, with `emitter` | [Stores](stores.md#emit-from-a-state-manager) |
+| `reactPlugin` | `nanoeffects/react` | `bus.useEmitter(event, value)`, a React hook | The same bus, with `useEmitter` | [React and stores](stores.md#react-sharing-a-value-across-components) |
+| `devPlugin` | `nanoeffects/dev` | Warnings about listeners that pile up, and messages about modules | A function that disconnects it | [Hot reload](hmr.md#report-leaks-with-devplugin) |
+
+"The same bus" means you can keep writing `bus` and ignore the result. Keep the result of `contextPlugin` and `effectsPlugin` in TypeScript, though: the type of the bus with its new fields is the type they return (`const bus = createBus().use(contextPlugin({ store }))`).
+
+## Put them together
+
+One bus with every plugin that does not need React. The order is explained in the next section.
+
+```js
+import { contextPlugin, createBus } from "nanoeffects";
+import {
+  commandsPlugin,
+  emitterPlugin,
+  modulePlugin,
+} from "nanoeffects/actions";
+import { devPlugin } from "nanoeffects/dev";
+import { all, effectsPlugin, race } from "nanoeffects/effects";
+import { scopePlugin } from "nanoeffects/scope";
+
+const bus = createBus()
+  .use(contextPlugin({ store })) // ctx.store on every task
+  .use(effectsPlugin({ race, all })) // ctx.race and ctx.all, bound to the task
+  .use(scopePlugin()) // scopes for commands, actions, jobs, modules and emit
+  .use(emitterPlugin()); // bus.emitter(creator)
+
+// commandsPlugin — the registry of command handlers; keep it to bind handlers later
+const commands = bus.use(commandsPlugin());
+
+// modulePlugin — mounts userModule now; keep app to mount and unmount later
+const app = bus.use(modulePlugin([userModule]));
+
+// devPlugin — reports leaks and modules while you develop; keep disconnect to remove it
+const disconnect = bus.use(devPlugin({ app }));
+```
+
+## Follow the order
+
+Most plugins do not care about each other. These pairs do:
+
+| Rule | Why |
+| ---- | --- |
+| `scopePlugin` after `effectsPlugin` | `effectsPlugin` assigns its effects on `ctx`, so one used later would replace an effect with the same name that a scope put there. |
+| `scopePlugin` before `modulePlugin` | `modulePlugin` mounts the modules when it is used, and a module with a scope needs the plugin by then. |
+| `commandsPlugin` before `modulePlugin`, if you bind handlers yourself | `modulePlugin` uses the registry that exists. Without one it makes its own, which is `app.commands`. |
+| `modulePlugin` before `devPlugin({ app })` | `devPlugin` reports the modules of the `app` that `modulePlugin` returned. |
+| `emitterPlugin` and `reactPlugin` anywhere | They only call `bus.emit`, which is read when you call them. |
+
+Two more things the checker enforces. A name that is already a context field of the bus is a type error when `contextPlugin` or `effectsPlugin` adds it again. `contextPlugin` does not replace a field that is on `ctx` already, so a scope wins over it in any order.
+
+## Choose by need
+
+- **A store, a client or a logger on every handler.** `contextPlugin`. Or `createBus({ context })` when you do not need the types from the value.
+- **`race`, `all` or your own effect without passing `ctx`.** `effectsPlugin`.
+- **Fields for one command, or a fake for one test call.** `scopePlugin`.
+- **A request with a result, or handlers that a test can replace.** `commandsPlugin`. Add `modulePlugin` when the domain needs a mount and an unmount.
+- **A callback for a state manager, such as `$name.listen(...)`.** `emitterPlugin`.
+- **Tell the bus when a value of a React component changes.** `reactPlugin`.
+- **Find listeners that were never unbound, or see modules reload.** `devPlugin`. In a production build `nanoeffects/dev` is empty, so the call can stay.
+
+## See what is not a plugin
+
+These connect the bus to something, but are not used with `bus.use`:
+
+- `createEffectsMiddleware(bus, { filter })` from `nanoeffects/redux` is a Redux middleware for a bus that exists. See [Stores](stores.md#wire-redux-toolkit-to-a-bus).
+- `createBus({ trace })` takes a tracer from `nanoeffects/trace`. See [Tracing](tracing.md).
+- `createObserve(bus)` from `nanoeffects/observable` turns an event into an Observable. See [Observable](observable.md).

package/docs/scope.md

@@ -0,0 +1,228 @@
+# Pin context fields to a command, an action, a module or a call
+
+Optional, for domain logic. Use it when one command needs its own client, one module its own logger, or one test its own fake, and a field on the whole bus ([context fields](context.md)) is too wide.
+
+A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`, `logger`), except one: `$effects`. Its functions take `{ signal }` as the first parameter, like `retry(ctx, fn)`, and go on `ctx` bound to the task, so you call `ctx.fetchJson(url)` instead of `fetchJson(ctx, url)`.
+
+You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
+
+## Turn scopes on
+
+Scopes are a plugin, so a bus that does not use them pays nothing.
+
+```js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+// scopePlugin — makes the scopes below work on this bus; returns the same bus
+const bus = createBus().use(scopePlugin());
+```
+
+- Without `scopePlugin` a scope is **ignored**: no error and no warning. If a field is missing from `ctx`, check this first.
+- Use it **after** `effectsPlugin` (an effect it adds later would be assigned over an effect of a scope with the same name) and **before** `modulePlugin` (it mounts the modules when it is used). `contextPlugin` and `createBus({ context })` can come in any order: a scope wins over them.
+
+## Give a command its own fields
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { scopePlugin } from "nanoeffects/scope";
+
+const bus = createBus().use(scopePlugin());
+
+// createCommand — third argument is the scope of this command
+const getUser = createCommand(
+  "user/get",
+  (id, { api, cache }) => {
+    // api and cache are on ctx for this command only
+    return cache.get(id) ?? api.getUser(id);
+  },
+  { api, cache: new Map() },
+);
+
+const user = await bus.emit(getUser("1")); // the handler has api and cache
+```
+
+The listeners of `"user/get"` get the same fields when the command is emitted, because the fields belong to the call.
+
+## Bind an effect to the task
+
+An effect is a function with `{ signal }` as its first parameter. In `$effects` it is bound to the task, so it stops with the task.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { delay, race } from "nanoeffects/effects";
+import { scopePlugin } from "nanoeffects/scope";
+
+const bus = createBus().use(scopePlugin());
+
+// your own effect: first parameter is the task (only its signal is used)
+const fetchJson = (ctx, url) =>
+  fetch(url, { signal: ctx.signal }).then((response) => response.json());
+
+const loadFeed = createCommand(
+  "feed/load",
+  (url, { fetchJson, race, delay }) =>
+    // race, delay, fetchJson — bound to this task: no ctx argument
+    race({
+      feed: () => fetchJson(url),
+      timeout: () => delay(5000),
+    }),
+  // $effects — built-in and your own functions share one object
+  { $effects: { fetchJson, race, delay } },
+);
+
+const result = await bus.emit(loadFeed("/feed"));
+```
+
+- Put in `$effects` only functions that take `ctx` first. A plain function (a formatter, a logger) belongs in `context`.
+- A function under any other key is copied as it is; a function in `$effects` is bound.
+- `$effects` is the one name with a meaning. A field called `effects` is an ordinary field: `{ effects: { retries: 3 } }` puts that object on `ctx`, and nothing in it is bound.
+
+## Replace a field for one call
+
+The second argument of `emit` is a scope for the tasks of **that** call. It is the usual way to give a test a fake.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { scopePlugin } from "nanoeffects/scope";
+
+const bus = createBus().use(scopePlugin());
+const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
+  api,
+});
+
+// the real api for this call
+await bus.emit(getUser("1"));
+
+// the second argument — a fake api, for this call only
+const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
+await bus.emit(getUser("1"), { api: fakeApi });
+```
+
+Rules for the second argument:
+
+- It works with an action or a command call (`emit(getUser("1"), scope)`, `ctx.emit(loaded(user), scope)`).
+- It does not work with the string form: in `emit("user/get", payload)` the second argument is the payload.
+- It can replace `$effects` too: `{ $effects: { delay: instantDelay } }`.
+- Fields of the library (`signal`, `emit`, …) in it are ignored.
+
+## Give an action, a job or a module its own fields
+
+```js
+import { createAction, createJob, createModule } from "nanoeffects/actions";
+
+// createAction — the listeners of this action's calls get the fields
+const userLoaded = createAction("user/loaded", { store });
+
+// createJob — the scope is the fourth argument, after the outcomes;
+// the handler and the listeners of the outcome get its fields
+const loadUser = createJob(
+  "user/load",
+  fetchUser,
+  { success: userLoaded, fail: "user/failed" },
+  { logger },
+);
+
+// createModule — third argument; everything the module owns gets the fields:
+// m.on listeners, m.handle handlers, m.spawn tasks
+const auditModule = createModule(
+  "audit",
+  (m) => {
+    m.on(userLoaded, (user, { logger }) => logger.info(user.id));
+  },
+  { logger },
+);
+```
+
+If the outcome action (`success` or `fail`) has a scope of its own, its listeners see the job's fields with the action's own fields over them; the handler of the job sees only the job's.
+
+A module scope does not leak: a listener registered outside the module does not see it.
+
+## Which value wins
+
+When several places set the same field, the strongest one wins:
+
+| Strength | Where it is set |
+| -------- | --------------- |
+| 1 (strongest) | the second argument of `emit` |
+| 2 | the scope of the action, command or job |
+| 3 | the scope of the module that owns the handler |
+| 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
+
+The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`, `payload`) are never replaced. A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
+
+## Keep a generic effect generic
+
+In `$effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
+
+`effect(fn)`: mark the function where you declare it, then put it in the scope like any other value. No annotation, so a JavaScript editor shows the exact hint too.
+
+```js
+import { createCommand } from "nanoeffects/actions";
+import { effect } from "nanoeffects/scope";
+
+// effect — marks the function, so a scope binds it to the task; the editor keeps its generic
+const first = effect((ctx, items) => items[0]);
+
+const pick = createCommand("pick", (items, { first }) => first(items), {
+  first, // a plain key of the scope, not an entry of `$effects`
+});
+```
+
+Call `effect` where you declare the function, as above, and not inline in the scope: TypeScript does not infer the scope from a generic call written there.
+
+`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `$effects`.
+
+```ts
+import { createCommand } from "nanoeffects/actions";
+import type { Effect } from "nanoeffects/effects";
+
+// First — checker-only: how a handler calls the effect (no ctx)
+type First = <T>(items: T[]) => T;
+
+// Effect<First> — the function takes the task first and is typed as First once bound
+const first: Effect<First> = (ctx, items) => items[0];
+
+const pick = createCommand(
+  "pick",
+  (id: string, { first }) => first([id]), // string
+  { $effects: { first } },
+);
+```
+
+`Effect<F>` and `effect` change what the checker sees. At run time the function is the same.
+
+## Type the fields (optional)
+
+A handler of a command, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
+
+```ts
+import { createCommand } from "nanoeffects/actions";
+
+type User = { id: string; name: string };
+
+const getUser = createCommand(
+  "user/get",
+  async (id: string, ctx) => {
+    ctx.cache; // Map<string, User>, from the scope below
+    return ctx.cache.get(id);
+  },
+  { cache: new Map<string, User>() },
+);
+```
+
+- A field of a scope replaces a field of the same name from the bus in the type too.
+- An override in `emit` must match the type of the field it replaces: `emit(getUser("1"), { cache: 1 })` is an error.
+- A field that no scope and no bus declares has no type to check against, so `emit(call, { unknown: 1 })` is an error in TypeScript.
+- `bus.on(creator, fn)` for an action with a scope types `ctx` with its fields.
+
+## Limits
+
+- No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
+- The fields of the bus are not in the handler of a command made with `createCommand(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
+- The string form of `emit` takes no scope.
+- `effect(fn)` works only as a value of a scope, not as an entry of `$effects`.
+- A scope on a command, action, job or module is typed without the events of a bus, so `take` in its `$effects` takes any event name.