nanoeffects 0.4.0 → 0.6.0

package/llms.txt

@@ -0,0 +1,49 @@
+# nanoeffects
+
+> A small typed event bus for JavaScript and TypeScript apps. Each handler runs as a task with an `AbortSignal`, so in-flight work can be cancelled. Policies (`latest`, `debounce`, ...) and effects (`retry`, `timeout`, ...) are plain functions.
+
+Rules that generated code often gets wrong:
+
+- The package is ESM only. There is no default export and no `require`.
+- `const unbind = bus.on("event", handler)` subscribes and returns the unsubscribe function. There is no `subscribe` or `addListener`.
+- 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`; needs React), `nanoeffects/trace`, `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
+- [Package entries](docs/package.md): which import holds what
+
+## Async UI and unreliable networks
+
+- [Policies](docs/policies.md): `latest`, `leading`, `debounce`, `throttle`, `queue`, and `key`
+- [Effects and cancellation](docs/effects.md): `retry`, `timeout`, `poll`, `take`, `all`, `race`, `backoff`
+- [Errors and unheard events](docs/errors.md): `onError`, `onUnhandled`
+
+## Domain logic and stores
+
+- [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
+- [Build a sign-up form in React](docs/react.md): a form with a username check, a submit that cannot fire twice, and retry
+- [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
+
+## TypeScript
+
+- [TypeScript in many files](docs/typescript.md): keep the types of the bus in commands and modules
+
+## Coming from another library
+
+- [Coming from redux-saga](docs/migrating-from-saga.md)
+- [Coming from Effector](docs/migrating-from-effector.md)
+- [Use nanoeffects next to RxJS](docs/migrating-from-rxjs.md)
+
+## Reference
+
+- [Semantics](docs/semantics.md): exact rules of emit, abort and ordering
+- [Trace tasks](docs/tracing.md): loggers, Redux DevTools, the `notrace` build
+- [Turn events into Observables](docs/observable.md): `createObserve`
+- [Hot reload and development diagnostics](docs/hmr.md): `devPlugin`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"description": "Typed event bus where every handler is a task with an AbortSignal, plus policies (latest, debounce, throttle, queue), effects (retry, timeout, poll) and tracing. About 1.3 kB gzip.",
 	"keywords": [
 		"event-bus",
@@ -33,6 +33,8 @@
 	"sideEffects": false,
 	"files": [
 		"dist",
+		"llms.txt",
+		"llms-full.txt",
 		"README.md",
 		"LICENSE",
 		"docs"
@@ -72,6 +74,10 @@
 			"types": "./dist/actions.d.ts",
 			"import": "./dist/actions.js"
 		},
+		"./scope": {
+			"types": "./dist/scope.d.ts",
+			"import": "./dist/scope.js"
+		},
 		"./trace": {
 			"types": "./dist/trace.d.ts",
 			"import": "./dist/trace.js"
@@ -88,6 +94,10 @@
 			"types": "./dist/observable.d.ts",
 			"import": "./dist/observable.js"
 		},
+		"./react": {
+			"types": "./dist/react.d.ts",
+			"import": "./dist/react.js"
+		},
 		"./dev": {
 			"production": {
 				"types": "./dist/dev.d.ts",
@@ -98,7 +108,7 @@
 		}
 	},
 	"scripts": {
-		"build": "tsdown && node scripts/notrace-types.mjs",
+		"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",
@@ -108,8 +118,10 @@
 		"prepare": "lefthook install",
 		"lint:package": "publint && attw --pack . --profile esm-only",
 		"size": "size-limit",
-		"verify": "pnpm tsgo && pnpm 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 test && pnpm build && pnpm test:integration && pnpm smoke && pnpm lint:package && pnpm size",
 		"test:integration": "vitest run --config vitest.integration.config.ts",
+		"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",
 		"consumer-check": "node scripts/consumer-check.mjs"
 	},
@@ -121,12 +133,17 @@
 		"@reduxjs/toolkit": "^2.13.0",
 		"@size-limit/esbuild": "^14.2.0",
 		"@size-limit/file": "^14.2.0",
+		"@types/react": "^19.3.0",
+		"@types/react-dom": "^19.3.0",
 		"archunit": "^2.5.4",
+		"happy-dom": "^21.0.4",
 		"jotai": "^3.0.1",
 		"lefthook": "2.2.1",
 		"lodash": "4.17.21",
 		"mobx": "^7.0.6",
 		"publint": "^0.3.25",
+		"react": "^19.3.1",
+		"react-dom": "^19.3.1",
 		"redux": "^5.0.1",
 		"size-limit": "^14.2.0",
 		"tsdown": "0.23.1",
@@ -155,12 +172,17 @@
 		{
 			"name": "effects (all)",
 			"path": "dist/effects.js",
-			"limit": "2.3 kB"
+			"limit": "2.45 kB"
 		},
 		{
 			"name": "actions (all)",
 			"path": "dist/actions.js",
-			"limit": "1.8 kB"
+			"limit": "2.1 kB"
+		},
+		{
+			"name": "scope (plugin and effect)",
+			"path": "dist/scope.js",
+			"limit": "0.75 kB"
 		},
 		{
 			"name": "redux",
@@ -172,6 +194,14 @@
 			"path": "dist/observable.js",
 			"limit": "0.5 kB"
 		},
+		{
+			"name": "react",
+			"path": "dist/react.js",
+			"ignore": [
+				"react"
+			],
+			"limit": "320 B"
+		},
 		{
 			"name": "dev",
 			"path": "dist/dev.js",
@@ -182,5 +212,13 @@
 			"path": "dist/production/dev.js",
 			"limit": "100 B"
 		}
-	]
+	],
+	"peerDependencies": {
+		"react": ">=18"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
+	}
 }