nanoeffects 0.18.0 → 0.19.0

package/docs/actions.md

@@ -6,6 +6,8 @@ If you only need `on` / `emit` or policies, stay in the [Guide](guide.md) until
 
 Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
 
+A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
+
 ## Return a value from `emit` with a command
 
 The bus lives in one file and its events in another, so any module can import both without a cycle.

package/docs/react.md

@@ -220,6 +220,8 @@ export function Found() {
 
 `setFound` is the setter of React. It changes the state of this component only and emits nothing.
 
+`useEventState` is not a store. Each component that calls it keeps its own copy of the last payload, and a component that mounts later does not see earlier events. To share a value between components, or to keep it for components that mount later, keep it in a state manager (Redux, Zustand, Jotai or another) and write to it from a handler of the event. See [Stores](stores.md). Without a state manager, one `useEventState` in a Context provider at the root shares the value with every component below it: [Plain React: Context, `useEmitter` and `useEventState`](stores.md#plain-react-context-useemitter-and-useeventstate).
+
 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`.

package/docs/starter.md

@@ -46,20 +46,41 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `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 |
+| `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 |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
 ```
 
+In the `react` templates, `useEventState` keeps the found items in the component. It is not a global store: another component gets its own copy. To share a value between components, use a state manager and see [Stores](stores.md).
+
 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
 ```
 
+### 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.
+
+```bash
+npm create nanoeffects@latest my-app -- --template domains-ts
+```
+
+| Path | Job |
+| ---- | --- |
+| `src/bus.ts` | Creates the bus. It imports no events and no domain. |
+| `src/app.ts` | Mounts the domains with `modulePlugin`. |
+| `src/domains/catalog/` | Searching products: `catalog.ts` (events and a command), `catalog-handlers.ts` (`debounce` and `latest`), `catalog-module.ts`. |
+| `src/domains/checkout/` | Placing an order: `checkout.ts` (a job), `checkout-handlers.ts` (`leading` and `retry`), `checkout-store.ts` (state written from the job's outcomes), `checkout-module.ts`. |
+| `src/ui/` | The components. None of them calls the fake server in `src/api.ts`. |
+
+The commands, jobs and modules themselves are explained in [Actions, commands, jobs and modules](actions.md). The template keeps found products in a Context provider with one `useEventState`, and the order state in a store of its own: `useEventState` is [not a store](react.md#show-the-last-value-of-an-event-as-state).
+
 ## 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).
+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 components).
 
 | File | Job |
 | ---- | --- |

package/docs/stores.md

@@ -365,23 +365,23 @@ A value of your UI (a query, a filter, a name) often has two jobs. Several compo
 
 | The value lives in | Use when |
 | --- | --- |
-| A Context provider with `useState` | Only components read it. Plain React, one `useEmitter` call. |
+| A Context provider with `useState` and `useEventState` | Only components read it. Plain React, one `useEmitter` and one `useEventState` call. |
 | A small store on `useSyncExternalStore` | A bus handler, a test or a timer must read it too. |
 | An atom of a store library | You already use Nanostores, Jotai and the like. |
 
-#### Plain React: Context and `useEmitter`
+#### Plain React: Context, `useEmitter` and `useEventState`
 
 Writing `useEffect(() => bus.emit(...), [value])` looks enough, but it emits on mount, emits twice on mount under StrictMode, and re-runs when the emit function is new on every render. `useEmitter` from `nanoeffects/react` avoids all three. It emits after a render commits with a changed value, never on mount, and compares with `Object.is`. You need React 18 or newer; no other entry of the package uses React.
 
-First the bus, the events and the handlers, each in its own file. `reactPlugin()` adds `bus.useEmitter`, and destructuring it gives a plain hook that you export from the bus file:
+First the bus, the events and the handlers, each in its own file. `reactPlugin()` adds `bus.useEmitter` and `bus.useEventState`, and destructuring them gives plain hooks that you export from the bus file:
 
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
 import { reactPlugin } from "nanoeffects/react";
 
-export const bus = createBus().use(reactPlugin()); // the bus; reactPlugin adds bus.useEmitter
-export const { useEmitter } = bus; // a free hook: it does not read `this`
+export const bus = createBus().use(reactPlugin()); // the bus; reactPlugin adds the React hooks
+export const { useEmitter, useEventState } = bus; // free hooks: they do not read `this`
 ```
 
 ```js
@@ -411,25 +411,24 @@ bus.on(
 );
 ```
 
-Then the provider. It holds the state, calls `useEmitter` once, and listens for the result. Every component below it only reads the context:
+Then the provider. It holds the state, calls `useEmitter` once to send the query to the bus, and `useEventState` once to receive the result. Every component below it only reads the context:
 
 ```jsx
 // SearchProvider.jsx
-import { createContext, useContext, useEffect, useState } from "react";
-import { bus, useEmitter } from "./bus";
+import { createContext, useContext, useState } from "react";
+import { useEmitter, useEventState } from "./bus";
 import { queryChanged, searchLoaded } from "./search";
 
 const SearchContext = createContext(null);
 
 export function SearchProvider({ children }) {
   const [query, setQuery] = useState("");
-  const [items, setItems] = useState([]);
 
   // React → bus: emits queryChanged(query) after every change of query, not on mount
   useEmitter(queryChanged, query);
 
-  // bus → React: bus.on returns the unsubscribe function, which the effect returns
-  useEffect(() => bus.on(searchLoaded, setItems), []);
+  // bus → React: like useState([]), but searchLoaded sets the value; one subscription for the whole app
+  const [items] = useEventState(searchLoaded, []);
 
   return (
     <SearchContext.Provider value={{ query, setQuery, items }}>
@@ -463,8 +462,9 @@ export function Results() {
 }
 ```
 
-Two limits to know:
+Three limits to know:
 
+- **The provider must be mounted first.** `useEventState` is not a store: the bus keeps no values, so a result that arrives before the provider mounts, or after it unmounts, is lost. Put the provider at the root. If a value must survive that, keep it in a store below and write to it from a handler.
 - **All consumers re-render** on any change of the context value. Split it into two contexts (`query` and `items`) if that is slow.
 - **A new object counts as a change.** For a value that is rebuilt with the same content, pass `equals` in the options, the third argument, to say when two values are the same: `useEmitter(profileChanged, profile, { equals: (previous, next) => previous.id === next.id })`. The same object takes `traceId` and `traceGroupId`, which name the subscription and the flow in the [trace](tracing.md#show-which-subscription-began-a-chain).
 

package/llms-full.txt

@@ -551,20 +551,41 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `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 |
+| `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 |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
 ```
 
+In the `react` templates, `useEventState` keeps the found items in the component. It is not a global store: another component gets its own copy. To share a value between components, use a state manager and see [Stores](stores.md).
+
 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
 ```
 
+### 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.
+
+```bash
+npm create nanoeffects@latest my-app -- --template domains-ts
+```
+
+| Path | Job |
+| ---- | --- |
+| `src/bus.ts` | Creates the bus. It imports no events and no domain. |
+| `src/app.ts` | Mounts the domains with `modulePlugin`. |
+| `src/domains/catalog/` | Searching products: `catalog.ts` (events and a command), `catalog-handlers.ts` (`debounce` and `latest`), `catalog-module.ts`. |
+| `src/domains/checkout/` | Placing an order: `checkout.ts` (a job), `checkout-handlers.ts` (`leading` and `retry`), `checkout-store.ts` (state written from the job's outcomes), `checkout-module.ts`. |
+| `src/ui/` | The components. None of them calls the fake server in `src/api.ts`. |
+
+The commands, jobs and modules themselves are explained in [Actions, commands, jobs and modules](actions.md). The template keeps found products in a Context provider with one `useEventState`, and the order state in a store of its own: `useEventState` is [not a store](react.md#show-the-last-value-of-an-event-as-state).
+
 ## 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).
+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 components).
 
 | File | Job |
 | ---- | --- |
@@ -1861,6 +1882,8 @@ If you only need `on` / `emit` or policies, stay in the [Guide](guide.md) until
 
 Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
 
+A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
+
 ## Return a value from `emit` with a command
 
 The bus lives in one file and its events in another, so any module can import both without a cycle.
@@ -2522,23 +2545,23 @@ A value of your UI (a query, a filter, a name) often has two jobs. Several compo
 
 | The value lives in | Use when |
 | --- | --- |
-| A Context provider with `useState` | Only components read it. Plain React, one `useEmitter` call. |
+| A Context provider with `useState` and `useEventState` | Only components read it. Plain React, one `useEmitter` and one `useEventState` call. |
 | A small store on `useSyncExternalStore` | A bus handler, a test or a timer must read it too. |
 | An atom of a store library | You already use Nanostores, Jotai and the like. |
 
-#### Plain React: Context and `useEmitter`
+#### Plain React: Context, `useEmitter` and `useEventState`
 
 Writing `useEffect(() => bus.emit(...), [value])` looks enough, but it emits on mount, emits twice on mount under StrictMode, and re-runs when the emit function is new on every render. `useEmitter` from `nanoeffects/react` avoids all three. It emits after a render commits with a changed value, never on mount, and compares with `Object.is`. You need React 18 or newer; no other entry of the package uses React.
 
-First the bus, the events and the handlers, each in its own file. `reactPlugin()` adds `bus.useEmitter`, and destructuring it gives a plain hook that you export from the bus file:
+First the bus, the events and the handlers, each in its own file. `reactPlugin()` adds `bus.useEmitter` and `bus.useEventState`, and destructuring them gives plain hooks that you export from the bus file:
 
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
 import { reactPlugin } from "nanoeffects/react";
 
-export const bus = createBus().use(reactPlugin()); // the bus; reactPlugin adds bus.useEmitter
-export const { useEmitter } = bus; // a free hook: it does not read `this`
+export const bus = createBus().use(reactPlugin()); // the bus; reactPlugin adds the React hooks
+export const { useEmitter, useEventState } = bus; // free hooks: they do not read `this`
 ```
 
 ```js
@@ -2568,25 +2591,24 @@ bus.on(
 );
 ```
 
-Then the provider. It holds the state, calls `useEmitter` once, and listens for the result. Every component below it only reads the context:
+Then the provider. It holds the state, calls `useEmitter` once to send the query to the bus, and `useEventState` once to receive the result. Every component below it only reads the context:
 
 ```jsx
 // SearchProvider.jsx
-import { createContext, useContext, useEffect, useState } from "react";
-import { bus, useEmitter } from "./bus";
+import { createContext, useContext, useState } from "react";
+import { useEmitter, useEventState } from "./bus";
 import { queryChanged, searchLoaded } from "./search";
 
 const SearchContext = createContext(null);
 
 export function SearchProvider({ children }) {
   const [query, setQuery] = useState("");
-  const [items, setItems] = useState([]);
 
   // React → bus: emits queryChanged(query) after every change of query, not on mount
   useEmitter(queryChanged, query);
 
-  // bus → React: bus.on returns the unsubscribe function, which the effect returns
-  useEffect(() => bus.on(searchLoaded, setItems), []);
+  // bus → React: like useState([]), but searchLoaded sets the value; one subscription for the whole app
+  const [items] = useEventState(searchLoaded, []);
 
   return (
     <SearchContext.Provider value={{ query, setQuery, items }}>
@@ -2620,8 +2642,9 @@ export function Results() {
 }
 ```
 
-Two limits to know:
+Three limits to know:
 
+- **The provider must be mounted first.** `useEventState` is not a store: the bus keeps no values, so a result that arrives before the provider mounts, or after it unmounts, is lost. Put the provider at the root. If a value must survive that, keep it in a store below and write to it from a handler.
 - **All consumers re-render** on any change of the context value. Split it into two contexts (`query` and `items`) if that is slow.
 - **A new object counts as a change.** For a value that is rebuilt with the same content, pass `equals` in the options, the third argument, to say when two values are the same: `useEmitter(profileChanged, profile, { equals: (previous, next) => previous.id === next.id })`. The same object takes `traceId` and `traceGroupId`, which name the subscription and the flow in the [trace](tracing.md#show-which-subscription-began-a-chain).
 
@@ -3180,6 +3203,8 @@ export function Found() {
 
 `setFound` is the setter of React. It changes the state of this component only and emits nothing.
 
+`useEventState` is not a store. Each component that calls it keeps its own copy of the last payload, and a component that mounts later does not see earlier events. To share a value between components, or to keep it for components that mount later, keep it in a state manager (Redux, Zustand, Jotai or another) and write to it from a handler of the event. See [Stores](stores.md). Without a state manager, one `useEventState` in a Context provider at the root shares the value with every component below it: [Plain React: Context, `useEmitter` and `useEventState`](stores.md#plain-react-context-useemitter-and-useeventstate).
+
 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.18.0",
+	"version": "0.19.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",