nanoeffects 0.16.0 → 0.17.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/docs/starter.md

@@ -0,0 +1,69 @@
+# 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 `usePolicy` for a debounced save in a component | You build a React app |
+
+```bash
+npm create nanoeffects@latest my-app -- --template react
+```
+
+## Read the files
+
+Both templates split the code the way [the guide](guide.md) does: one job per file.
+
+| 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

@@ -500,6 +500,79 @@ 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 `usePolicy` for a debounced save in a component | You build a React app |
+
+```bash
+npm create nanoeffects@latest my-app -- --template react
+```
+
+## Read the files
+
+Both templates split the code the way [the guide](guide.md) does: one job per file.
+
+| 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
 

package/llms.txt

@@ -15,6 +15,7 @@ Rules that generated code often gets wrong:
 ## 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.16.0",
+	"version": "0.17.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,13 +138,13 @@
 	"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",
 		"test:integration": "vitest run --config vitest.integration.config.ts",
@@ -163,6 +163,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",