nanoeffects 0.3.0 → 0.5.0

package/llms.txt

@@ -0,0 +1,48 @@
+# 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
+
+## 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,7 +1,7 @@
 {
 	"name": "nanoeffects",
-	"version": "0.3.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.2 kB gzip.",
+	"version": "0.5.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",
 		"event-emitter",
@@ -33,6 +33,8 @@
 	"sideEffects": false,
 	"files": [
 		"dist",
+		"llms.txt",
+		"llms-full.txt",
 		"README.md",
 		"LICENSE",
 		"docs"
@@ -88,6 +90,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 +104,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 +114,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,11 +129,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",
@@ -144,7 +158,7 @@
 			"name": "createBus",
 			"path": "dist/index.js",
 			"import": "{ createBus }",
-			"limit": "1.2 kB"
+			"limit": "1.3 kB"
 		},
 		{
 			"name": "policies (all)",
@@ -154,23 +168,31 @@
 		{
 			"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": "1850 B"
 		},
 		{
 			"name": "redux",
 			"path": "dist/redux.js",
-			"limit": "1.5 kB"
+			"limit": "1.55 kB"
 		},
 		{
 			"name": "observable",
 			"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",
@@ -181,5 +203,13 @@
 			"path": "dist/production/dev.js",
 			"limit": "100 B"
 		}
-	]
+	],
+	"peerDependencies": {
+		"react": ">=18"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
+	}
 }

package/dist/bus-CRnlwmQ4.js

@@ -1 +0,0 @@
-import{n as e}from"./onAbort-BgMfspK4.js";import{a as t,n,r}from"./context-DlA80GOA.js";import{n as i}from"./promise-CSLpzwSR.js";import{n as a,t as o}from"./event-0RIBGYqS.js";const s=`*`,c=()=>{let e={},t=/* @__PURE__ */ new WeakSet,n=n=>{let r=e[n]??[];if(!t.has(r))return e[n]=r,r;let i=[...r];return e[n]=i,i},r=(t,r)=>{if(!r){e[t]=[];return}let i=(e[t]??[]).indexOf(r);i>=0&&n(t).splice(i,1)};return{get:n=>{let r=e[n]??[];return t.add(r),r},add:(e,t)=>(n(e).push(t),()=>{r(e,t)}),remove:r}},l=(e,t,n)=>Reflect.apply(e,null,[t,n]),u=(s={})=>{let u=c(),d=(e,t)=>u.add(o(e),t),f=(e,t)=>u.remove(o(e),t),p=(t,a)=>{let{onError:o}=s,{ctx:c}=n({event:a,bus:m,tracer:s.trace,parent:{ref:r()}});if(!o){t(a.payload,c);return}let l=t=>{try{o(t,a)}catch(t){e(`onError failed`,t)}};try{let e=t(a.payload,c);i(e)&&Promise.resolve(e).catch(l)}catch(e){l(e)}},m={on:d,off:f,emit:(e,i)=>{let c=o(e),d=a(e,i),f={type:c,payload:d},h=[...u.get(c),...u.get(`*`)];h.length===0&&typeof e!=`function`&&s.onUnhandled?.(f);for(let e of h)p(e,f);if(typeof e==`function`){let{ctx:i}=n({event:f,bus:m,tracer:s.trace,parent:{ref:r()}}),a=m.commands?.run??l;return t(i,`command`,()=>a(e,d,i))}},use:e=>e(m),context:s.context,trace:s.trace};return m};export{s as n,u as t};

package/dist/notrace/bus-Dx0l9X6h.js

@@ -1 +0,0 @@
-import{a as e,c as t,n,r}from"./context-yAWj0BFZ.js";import{n as i}from"./promise-CSLpzwSR.js";import{n as a,t as o}from"./event-0RIBGYqS.js";const s=`*`,c=()=>{let e={},t=/* @__PURE__ */ new WeakSet,n=n=>{let r=e[n]??[];if(!t.has(r))return e[n]=r,r;let i=[...r];return e[n]=i,i},r=(t,r)=>{if(!r){e[t]=[];return}let i=(e[t]??[]).indexOf(r);i>=0&&n(t).splice(i,1)};return{get:n=>{let r=e[n]??[];return t.add(r),r},add:(e,t)=>(n(e).push(t),()=>{r(e,t)}),remove:r}},l=(e,t,n)=>Reflect.apply(e,null,[t,n]),u=(s={})=>{let u=c(),d=(e,t)=>u.add(o(e),t),f=(e,t)=>u.remove(o(e),t),p=(e,a)=>{let{onError:o}=s,{ctx:c}=n({event:a,bus:m,tracer:s.trace,parent:{ref:r()}});if(!o){e(a.payload,c);return}let l=e=>{try{o(e,a)}catch(e){t(`onError failed`,e)}};try{let t=e(a.payload,c);i(t)&&Promise.resolve(t).catch(l)}catch(e){l(e)}},m={on:d,off:f,emit:(t,i)=>{let c=o(t),d=a(t,i),f={type:c,payload:d},h=[...u.get(c),...u.get(`*`)];h.length===0&&typeof t!=`function`&&s.onUnhandled?.(f);for(let e of h)p(e,f);if(typeof t==`function`){let{ctx:i}=n({event:f,bus:m,tracer:s.trace,parent:{ref:r()}}),a=m.commands?.run??l;return e(i,`command`,()=>a(t,d,i))}},use:e=>e(m),context:s.context,trace:s.trace};return m};export{s as n,u as t};

package/dist/notrace/event-0RIBGYqS.js

@@ -1 +0,0 @@
-const e=e=>typeof e==`string`?e:e.type,t=(e,t)=>typeof e==`object`?e.payload:t;export{t as n,e as t};