nanoeffects 0.16.0 → 0.18.0

package/README.md

@@ -15,6 +15,8 @@ npm install nanoeffects
 
 ESM only, no dependencies, types included.
 
+Starting a new project? `npm create nanoeffects@latest my-app` makes a Vite app with a bus ([Docs](docs/starter.md)).
+
 Want to try it first? [Open the playground](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/playground): a search box with `debounce` and `latest`, running in your browser, no install. More playgrounds (React) and recipes: [Examples](examples/README.md).
 
 ## Create a bus

package/dist/react.d.ts

@@ -24,7 +24,30 @@ type ReactApi<E extends EventMap> = {
     <K extends EventKey<E>>(creator: FreeActionCreator<K>, value: E[K], options?: UseEmitterOptions<E[K]>): void;
     <P, T extends string>(creator: ActionCreator<P, T>, value: P, options?: UseEmitterOptions<P>): void;
   };
+  /**
+   * A React hook with the signature of `useState`: returns `[state, setState]`, and
+   * every emit of `event` sets the state to its payload while the component is
+   * mounted. `initial` may be a function, as in `useState`. The bus keeps no values,
+   * so an event emitted before the first commit is not seen: read a current value
+   * into `initial` when that matters. The method does not read `this`, so
+   * `export const { useEventState } = bus` gives a free hook.
+   *
+   * @example
+   * ```tsx
+   * const [found, setFound] = useEventState(searchLoaded, []); // [] until the first searchLoaded
+   * ```
+   */
+  useEventState: {
+    <K extends EventKey<E>, S>(event: K, initial: StateOf<E[K], S> | (() => StateOf<E[K], S>)): EventState<StateOf<E[K], S>>;
+    /** A creator without a payload type: the payload comes from the event map. */
+    <K extends EventKey<E>, S>(creator: FreeActionCreator<K>, initial: StateOf<E[K], S> | (() => StateOf<E[K], S>)): EventState<StateOf<E[K], S>>;
+    <P, T extends string>(creator: ActionCreator<P, T>, initial: P | (() => P)): EventState<P>;
+  };
 };
+/** What `useEventState` returns: the pair of `useState`, with the payload of the event as state. */
+type EventState<P> = [P, (next: P | ((previous: P) => P)) => void];
+type Widen<S> = [S] extends [never[]] ? unknown[] : S;
+type StateOf<P, S> = unknown extends P ? Widen<S> : P;
 /**
  * Adds `bus.useEmitter(event, value)`: a hook that tells the bus when a value of
  * a component changes, without the traps of `useEffect(() => emit(value), [value])`

package/dist/react.js

@@ -1 +1 @@
-import{t as e}from"./with-policy-CW50Edgk.js";import{t}from"./origin-key-BbWN3gmN.js";import{useEffect as n,useMemo as r,useRef as i}from"react";const a=()=>e=>{function r(r,a,o){let s=i(a),c=i({event:r,options:o});n(()=>{c.current={event:r,options:o}}),n(()=>{let{event:n,options:r}=c.current,i=r?.equals??Object.is,o=s.current;if(i(o,a))return;s.current=a;let l=typeof n==`function`?n(a):{type:n,payload:a},u=Reflect.get(e,t);u?u(l,r??{}):e.emit(l)},[a])}return Object.assign(e,{useEmitter:r})},o=(t,a,o=[])=>{let s=i(t);n(()=>{s.current=t});let c=r(()=>e(a((e,t)=>s.current(e,t))),o);return n(()=>()=>c.cancel(),[c]),c};export{a as reactPlugin,o as usePolicy};
+import{t as e}from"./with-policy-CW50Edgk.js";import{t}from"./origin-key-BbWN3gmN.js";import{useEffect as n,useMemo as r,useRef as i,useState as a}from"react";const o=()=>e=>{function r(r,a,o){let s=i(a),c=i({event:r,options:o});n(()=>{c.current={event:r,options:o}}),n(()=>{let{event:n,options:r}=c.current,i=r?.equals??Object.is,o=s.current;if(i(o,a))return;s.current=a;let l=typeof n==`function`?n(a):{type:n,payload:a},u=Reflect.get(e,t);u?u(l,r??{}):e.emit(l)},[a])}function o(t,r){let[i,o]=a(r);return n(()=>{let n=t;return e.on(n,e=>{let t=e;o(()=>t)})},[t]),[i,o]}return Object.assign(e,{useEmitter:r,useEventState:o})},s=(t,a,o=[])=>{let s=i(t);n(()=>{s.current=t});let c=r(()=>e(a((e,t)=>s.current(e,t))),o);return n(()=>()=>c.cancel(),[c]),c};export{o as reactPlugin,s as usePolicy};

package/docs/react.md

@@ -162,6 +162,68 @@ const checkName = latest(async (name, ctx) => {
 
 In the component, add `bus.emit("form/closed")` to the cleanup function of the effect. This is optional: skip it when finishing a request after unmount does no harm, as for a cheap check.
 
+## Show the last value of an event as state
+
+**Problem.** A component often needs the latest result of an event, such as the found items of a search. The hand-written form is easy to get slightly wrong:
+
+<!-- docs-check: skip - the hand-written form that this section replaces -->
+```jsx
+useEffect(() => bus.on(searchLoaded, setFound), []);
+```
+
+It needs a `useState` next to it, the empty `[]` hides the dependency on the event, and it breaks if the payload is a function, because React calls `setFound(payload)` as an updater.
+
+**When.** The value you show comes from the bus, not from the component. For the opposite direction, a value of the component that the bus must hear, use `useEmitter`.
+
+`useEventState(event, initial)` has the signature of `useState`: it returns `[state, setState]`. `initial` is the state before the first event and may be a function, as in `useState`. After that, every emit of `event` sets the state to its payload. The hook unsubscribes when the component unmounts.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { reactPlugin } from "nanoeffects/react";
+
+// createBus — the event bus, created once outside React
+// reactPlugin — adds the hooks bus.useEmitter and bus.useEventState
+export const bus = createBus().use(reactPlugin());
+export const { useEventState } = bus; // a free hook: components import it without the bus
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — the event name; the handlers emit it with the found titles
+export const searchLoaded = createAction("search/loaded");
+```
+
+```jsx
+// Found.jsx
+import { useEventState } from "./bus";
+import { searchLoaded } from "./search";
+
+export function Found() {
+  // useEventState — like useState([]), but searchLoaded sets the value
+  const [found, setFound] = useEventState(searchLoaded, []);
+
+  return (
+    <>
+      <ul>
+        {found.map((title) => (
+          <li key={title}>{title}</li>
+        ))}
+      </ul>
+      <button onClick={() => setFound([])}>Clear</button>
+    </>
+  );
+}
+```
+
+`setFound` is the setter of React. It changes the state of this component only and emits nothing.
+
+In TypeScript, the state type comes from the event: from `createAction<string[]>("search/loaded")` or from the event map of the bus. When the event has no payload type, as in the example above, it comes from `initial`: `["a"]` is `string[]`, and an empty `[]` is `unknown[]`. Give the event a type, or pass a typed `initial`, when you need more.
+
+The bus keeps no values, so the hook cannot replay an event. An event emitted before the component mounts is not seen: if that matters, read the current value into `initial`.
+
 ## Keep a debounced handler between renders
 
 **Problem.** A component runs again on every render. A policy made in its body, such as `debounce(300, search)`, is made again each time and loses its timer. A policy made once keeps the callback of the first render, which reads old props and state.

package/docs/starter.md

@@ -0,0 +1,77 @@
+# Start a project from a template
+
+Use this page when you want a running project in one command instead of wiring Vite and the bus by hand. It makes a small app with a search box that waits for you to stop typing (`debounce`) and aborts the older request when a newer one starts (`latest`).
+
+You need Node 18 or newer.
+
+## Create the project
+
+Run the command for your package manager. Replace `my-app` with the name of the new directory.
+
+```bash
+npm create nanoeffects@latest my-app
+```
+
+```bash
+pnpm create nanoeffects my-app
+```
+
+```bash
+yarn create nanoeffects my-app
+```
+
+```bash
+bun create nanoeffects my-app
+```
+
+The command asks for the template when you do not give one. The directory must be new or empty: the command stops instead of overwriting files.
+
+Then follow the steps it prints:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+Open the address that Vite prints and type in the box. The fake server answers after 800 ms, so you can see the older request being aborted.
+
+## Choose a template
+
+Pass `--template` to skip the question. With npm, put `--` before the option.
+
+| Template | What it shows | Use it when |
+| -------- | ------------- | ----------- |
+| `vanilla` | A bus, one event and a `debounce` plus `latest` handler, with plain DOM code | You use no framework, or want to see the bus alone |
+| `react` | The same handler with `useEmitter` and `useEventState`, and `usePolicy` for a debounced save in a component | You build a React app |
+| `vanilla-ts` | The `vanilla` app in TypeScript | You want the compiler to check events and handlers |
+| `react-ts` | The `react` app in TypeScript | You build a React app in TypeScript |
+
+```bash
+npm create nanoeffects@latest my-app -- --template react
+```
+
+The TypeScript templates are the same apps with the same files, written in `.ts` and `.tsx`. Events are made with `createAction<Payload>`, so handlers and `useEventState` get their types from the events, with no annotation in the component. `npm run build` type-checks the project (`tsc --noEmit`) before bundling it.
+
+```bash
+npm create nanoeffects@latest my-app -- --template react-ts
+```
+
+## Read the files
+
+Every template 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 components).
+
+| File | Job |
+| ---- | --- |
+| `src/bus.js` | Creates the bus. It imports no events. |
+| `src/search.js` | Names the events with `createAction`. It imports no bus. |
+| `src/search-handlers.js` | Handles the events with `debounce` and `latest`. It knows the bus and the events. |
+| `src/api.js` | A fake server. Replace it with your own requests. |
+
+Every call of nanoeffects in these files has a comment that says what it does. To make it your own, replace `src/api.js`, then rename the events and the handler.
+
+## Next steps
+
+- [Policies](policies.md): `leading`, `throttle` and `queue` next to `latest`.
+- [Build a sign-up form in React](react.md): the same ideas in a bigger React example.
+- [Package entries](package.md): which import holds what.

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`; `usePolicy`; needs React), `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/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ---
@@ -500,6 +500,87 @@ More in [Errors](errors.md).
 | Guarantees | [Semantics](semantics.md) |
 | Which import | [Package entries](package.md) |
 
+---
+Source: docs/starter.md
+
+# Start a project from a template
+
+Use this page when you want a running project in one command instead of wiring Vite and the bus by hand. It makes a small app with a search box that waits for you to stop typing (`debounce`) and aborts the older request when a newer one starts (`latest`).
+
+You need Node 18 or newer.
+
+## Create the project
+
+Run the command for your package manager. Replace `my-app` with the name of the new directory.
+
+```bash
+npm create nanoeffects@latest my-app
+```
+
+```bash
+pnpm create nanoeffects my-app
+```
+
+```bash
+yarn create nanoeffects my-app
+```
+
+```bash
+bun create nanoeffects my-app
+```
+
+The command asks for the template when you do not give one. The directory must be new or empty: the command stops instead of overwriting files.
+
+Then follow the steps it prints:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+Open the address that Vite prints and type in the box. The fake server answers after 800 ms, so you can see the older request being aborted.
+
+## Choose a template
+
+Pass `--template` to skip the question. With npm, put `--` before the option.
+
+| Template | What it shows | Use it when |
+| -------- | ------------- | ----------- |
+| `vanilla` | A bus, one event and a `debounce` plus `latest` handler, with plain DOM code | You use no framework, or want to see the bus alone |
+| `react` | The same handler with `useEmitter` and `useEventState`, and `usePolicy` for a debounced save in a component | You build a React app |
+| `vanilla-ts` | The `vanilla` app in TypeScript | You want the compiler to check events and handlers |
+| `react-ts` | The `react` app in TypeScript | You build a React app in TypeScript |
+
+```bash
+npm create nanoeffects@latest my-app -- --template react
+```
+
+The TypeScript templates are the same apps with the same files, written in `.ts` and `.tsx`. Events are made with `createAction<Payload>`, so handlers and `useEventState` get their types from the events, with no annotation in the component. `npm run build` type-checks the project (`tsc --noEmit`) before bundling it.
+
+```bash
+npm create nanoeffects@latest my-app -- --template react-ts
+```
+
+## Read the files
+
+Every template 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 components).
+
+| File | Job |
+| ---- | --- |
+| `src/bus.js` | Creates the bus. It imports no events. |
+| `src/search.js` | Names the events with `createAction`. It imports no bus. |
+| `src/search-handlers.js` | Handles the events with `debounce` and `latest`. It knows the bus and the events. |
+| `src/api.js` | A fake server. Replace it with your own requests. |
+
+Every call of nanoeffects in these files has a comment that says what it does. To make it your own, replace `src/api.js`, then rename the events and the handler.
+
+## Next steps
+
+- [Policies](policies.md): `leading`, `throttle` and `queue` next to `latest`.
+- [Build a sign-up form in React](react.md): the same ideas in a bigger React example.
+- [Package entries](package.md): which import holds what.
+
 ---
 Source: docs/motivation.md
 
@@ -3041,6 +3122,68 @@ const checkName = latest(async (name, ctx) => {
 
 In the component, add `bus.emit("form/closed")` to the cleanup function of the effect. This is optional: skip it when finishing a request after unmount does no harm, as for a cheap check.
 
+## Show the last value of an event as state
+
+**Problem.** A component often needs the latest result of an event, such as the found items of a search. The hand-written form is easy to get slightly wrong:
+
+<!-- docs-check: skip - the hand-written form that this section replaces -->
+```jsx
+useEffect(() => bus.on(searchLoaded, setFound), []);
+```
+
+It needs a `useState` next to it, the empty `[]` hides the dependency on the event, and it breaks if the payload is a function, because React calls `setFound(payload)` as an updater.
+
+**When.** The value you show comes from the bus, not from the component. For the opposite direction, a value of the component that the bus must hear, use `useEmitter`.
+
+`useEventState(event, initial)` has the signature of `useState`: it returns `[state, setState]`. `initial` is the state before the first event and may be a function, as in `useState`. After that, every emit of `event` sets the state to its payload. The hook unsubscribes when the component unmounts.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { reactPlugin } from "nanoeffects/react";
+
+// createBus — the event bus, created once outside React
+// reactPlugin — adds the hooks bus.useEmitter and bus.useEventState
+export const bus = createBus().use(reactPlugin());
+export const { useEventState } = bus; // a free hook: components import it without the bus
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — the event name; the handlers emit it with the found titles
+export const searchLoaded = createAction("search/loaded");
+```
+
+```jsx
+// Found.jsx
+import { useEventState } from "./bus";
+import { searchLoaded } from "./search";
+
+export function Found() {
+  // useEventState — like useState([]), but searchLoaded sets the value
+  const [found, setFound] = useEventState(searchLoaded, []);
+
+  return (
+    <>
+      <ul>
+        {found.map((title) => (
+          <li key={title}>{title}</li>
+        ))}
+      </ul>
+      <button onClick={() => setFound([])}>Clear</button>
+    </>
+  );
+}
+```
+
+`setFound` is the setter of React. It changes the state of this component only and emits nothing.
+
+In TypeScript, the state type comes from the event: from `createAction<string[]>("search/loaded")` or from the event map of the bus. When the event has no payload type, as in the example above, it comes from `initial`: `["a"]` is `string[]`, and an empty `[]` is `unknown[]`. Give the event a type, or pass a typed `initial`, when you need more.
+
+The bus keeps no values, so the hook cannot replay an event. An event emitted before the component mounts is not seen: if that matters, read the current value into `initial`.
+
 ## Keep a debounced handler between renders
 
 **Problem.** A component runs again on every render. A policy made in its body, such as `debounce(300, search)`, is made again each time and loses its timer. A policy made once keeps the callback of the first render, which reads old props and state.

package/llms.txt

@@ -9,12 +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`; `usePolicy`; needs React), `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/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` or `react`) 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
@@ -33,7 +34,7 @@ Rules that generated code often gets wrong:
 - [Actions, commands, jobs and modules](docs/actions.md): `createAction`, `createCommand`, `createJob`, `createModule`
 - [Connect Redux, Zustand, MobX, or Pinia](docs/stores.md): the Redux middleware and callbacks of other stores
 - [Use nanoeffects with React Query and SWR](docs/query-libraries.md): call a command from `queryFn` or the SWR fetcher; `signalPlugin` passes the abort of the library to the task
-- [Build a sign-up form in React](docs/react.md): a form with a username check, a submit that cannot fire twice, and retry; `usePolicy` keeps a debounced handler between renders
+- [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
 - [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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.16.0",
+	"version": "0.18.0",
 	"description": "Cancel stale async work and fix race conditions in event handlers: a typed event bus where every handler is a task with an AbortSignal, plus latest, debounce, throttle, queue, retry, timeout and poll. About 1.4 kB gzip.",
 	"keywords": [
 		"event-bus",
@@ -138,16 +138,17 @@
 	"scripts": {
 		"build": "tsdown && node scripts/notrace-types.mjs && node scripts/llms-full.mjs",
 		"prepublishOnly": "pnpm build",
-		"check": "biome check ./src ./examples ./integration ./scripts",
-		"format": "npx @biomejs/biome check --write --unsafe ./src ./examples ./integration ./scripts",
+		"check": "biome check ./src ./examples ./integration ./scripts ./packages",
+		"format": "npx @biomejs/biome check --write --unsafe ./src ./examples ./integration ./scripts ./packages",
 		"tsgo": "tsc --noEmit",
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"prepare": "lefthook install",
-		"lint:package": "publint && attw --pack . --profile esm-only",
+		"lint:package": "publint && attw --pack . --profile esm-only && publint packages/create-nanoeffects",
 		"size": "size-limit",
-		"verify": "pnpm tsgo && pnpm check && pnpm docs:check && pnpm llms:check && pnpm test && pnpm build && pnpm test:integration && pnpm smoke && pnpm lint:package && pnpm size",
+		"verify": "pnpm tsgo && pnpm check && pnpm docs:check && pnpm llms:check && pnpm templates:check && pnpm test && pnpm build && pnpm test:integration && pnpm smoke && pnpm lint:package && pnpm size",
 		"test:integration": "vitest run --config vitest.integration.config.ts",
+		"templates:check": "node scripts/templates-check.mjs",
 		"docs:check": "node scripts/docs-check.mjs",
 		"llms:check": "node scripts/llms-full.mjs --check",
 		"smoke": "node scripts/smoke.mjs && node scripts/smoke.mjs --notrace",
@@ -163,6 +164,7 @@
 		"@size-limit/file": "^14.2.0",
 		"@types/react": "^19.3.0",
 		"@types/react-dom": "^19.3.0",
+		"@vitejs/plugin-react": "^6.1.2",
 		"archunit": "^2.5.4",
 		"happy-dom": "^21.0.4",
 		"jotai": "^3.0.1",
@@ -249,7 +251,7 @@
 			"ignore": [
 				"react"
 			],
-			"limit": "1.18 kB"
+			"limit": "1.24 kB"
 		},
 		{
 			"name": "dev",