nanoeffects 0.17.0 → 0.18.0

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

@@ -43,15 +43,23 @@ 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 `usePolicy` for a debounced save in a component | You build a React app |
+| `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
 
-Both templates split the code the way [the guide](guide.md) does: one job per file.
+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 |
 | ---- | --- |

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.
 
 ---
@@ -548,15 +548,23 @@ 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 `usePolicy` for a debounced save in a component | You build a React app |
+| `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
 
-Both templates split the code the way [the guide](guide.md) does: one job per file.
+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 |
 | ---- | --- |
@@ -3114,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,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.
 
 ## Start here
@@ -34,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.17.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",
@@ -146,8 +146,9 @@
 		"prepare": "lefthook install",
 		"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",
@@ -250,7 +251,7 @@
 			"ignore": [
 				"react"
 			],
-			"limit": "1.18 kB"
+			"limit": "1.24 kB"
 		},
 		{
 			"name": "dev",