nanoeffects 0.27.0 → 0.29.0

package/llms.txt

@@ -10,11 +10,11 @@ Rules that generated code often gets wrong:
 - 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` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
-- `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
+- `bus.emit(action(payload))` runs the action'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
+- [Guide](docs/guide.md): bus, handler context, policies, effects, actions and modules, step by step
 - [Start a project from a template](docs/starter.md): `npm create nanoeffects` makes a Vite project (`vanilla`, `react`, `vue-ts`, `svelte-ts` and others, in JavaScript or TypeScript) with a bus, `debounce` and `latest`
 - [Why nanoeffects exists](docs/motivation.md): logic and side effects outside UI components as plain async functions, no dependencies and no global state for SDKs and Module Federation, and why not redux-saga, RxJS, Redux or Effector
 - [Package entries](docs/package.md): which import holds what
@@ -32,21 +32,22 @@ Rules that generated code often gets wrong:
 
 ## Domain logic and stores
 
-- [Actions, jobs and modules](docs/actions.md): `createAction`, `createAction`, `createJob`, `createModule`
+- [Actions, jobs and modules](docs/actions.md): `createAction` (with or without a handler), `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
+- [Use nanoeffects with React Query, SWR and RTK Query](docs/query-libraries.md): call an action from `queryFn` or the SWR fetcher; `signalPlugin` passes the abort of the library to the task; `fromSignal` clients, a live stream into the cache with `events`, refetch on a bus event
 - [Stop work on a server when the client leaves](docs/server.md): one `AbortController` for each request or socket, `signalPlugin`, a clean shutdown, and a queue worker; Fastify examples
 - [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
 - [Build a chat with entities, features, modules and a small server](docs/chat-example.md): rooms, a history under `latest`, a send under `queue` and `retry`, a search with `allSettled` and `timeout`, new messages polled with `poll`
+- [Build a chat widget that listens only while it is open](docs/chat-widget.md): a bot widget for a site; opening mounts a module (handlers, polling, Escape), closing unmounts it and aborts running requests
 - [Use nanoeffects in a Vue app](docs/vue.md): `vuePlugin` adds `watchEmitter` (a value of a component to the bus) and `useEventRef` (an event as a ref)
 - [Use nanoeffects in a Svelte app](docs/svelte.md): `sveltePlugin` adds `eventStore` (an event as a Svelte store)
 - [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
+- [Scopes](docs/scope.md): fields for one 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
 
 ## TypeScript
 
-- [TypeScript in many files](docs/typescript.md): keep the types of the bus in commands and modules
+- [TypeScript in many files](docs/typescript.md): keep the types of the bus in actions and modules
 
 ## Coming from another library
 
@@ -59,5 +60,5 @@ Rules that generated code often gets wrong:
 
 - [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`, `Subject`
+- [Turn events into Observables](docs/observable.md): `createObserve`, `Subject`, `events` (an event as a `for await` loop)
 - [Hot reload and development diagnostics](docs/hmr.md): `devPlugin`

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "nanoeffects",
-	"version": "0.27.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.",
+	"version": "0.29.0",
+	"description": "Business logic and side effects outside UI components, as plain async functions. Tiny, no dependencies.",
 	"keywords": [
 		"event-bus",
 		"event-emitter",
@@ -226,7 +226,7 @@
 		{
 			"name": "actions (all)",
 			"path": "dist/actions.js",
-			"limit": "3.3 kB"
+			"limit": "3.31 kB"
 		},
 		{
 			"name": "match (plugin)",
@@ -236,12 +236,12 @@
 		{
 			"name": "signal (plugin)",
 			"path": "dist/signal.js",
-			"limit": "0.6 kB"
+			"limit": "0.7 kB"
 		},
 		{
 			"name": "context (plugin)",
 			"path": "dist/context.js",
-			"limit": "0.2 kB"
+			"limit": "0.4 kB"
 		},
 		{
 			"name": "oop (class entry)",
@@ -261,7 +261,7 @@
 		{
 			"name": "observable",
 			"path": "dist/observable.js",
-			"limit": "0.5 kB"
+			"limit": "0.85 kB"
 		},
 		{
 			"name": "react",

package/skills/nanoeffects/SKILL.md

@@ -26,7 +26,7 @@ Do not write the setup by hand. `npm create nanoeffects@latest my-app -- --templ
 
 - `vanilla`, `react`: JavaScript, one search handler with `debounce` and `latest`.
 - `vanilla-ts`, `react-ts`: the same apps in TypeScript.
-- `domains-ts`: React and TypeScript with the logic split by domain (commands, a job, modules). Pick it for an app with several features.
+- `domains-ts`: React and TypeScript with the logic split by domain (actions, a job, modules). Pick it for an app with several features.
 
 In an existing project, start from `docs/cancel-stale-requests.md` (races) or `docs/guide.md`.
 
@@ -38,7 +38,7 @@ In an existing project, start from `docs/cancel-stale-requests.md` (races) or `d
 - Effects take `ctx` first: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`. The wrapper form is `retry(fn, options)`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
 - Import each part from its path: `nanoeffects`, `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/react`.
-- `bus.emit(command(payload))` returns the command's result. Plain events return nothing.
+- `bus.emit(action(payload))` returns the action's result. Plain events return nothing.
 - The bus keeps no values: an event emitted before a listener exists is lost. `useEventState(event, initial)` (`nanoeffects/react`) is state of one component, not a store. Share a value through a Context provider at the root or a state manager.
 
 ## Where to read more

package/dist/bus-DQDHUN5e.js

@@ -1 +0,0 @@
-import{d as e,n as t,o as n,r}from"./context-UcmrAIhP.js";import{n as i}from"./promise-CSLpzwSR.js";import{n as a,t as o}from"./event-0RIBGYqS.js";const s=()=>{let e={},t={},n=n=>(t[n]=void 0,e[n]??=/* @__PURE__ */ new Map,e[n]),r=(e,t)=>{let r=n(e),i=r.get(t)??0;i>1?r.set(t,i-1):t?r.delete(t):r.clear()};return{get:n=>(t[n]??=[...e[n]??[]].flatMap(([e,t])=>Array(t).fill(e)),t[n]),add:(e,t)=>{let i=n(e);return i.set(t,(i.get(t)??0)+1),()=>{r(e,t)}},remove:r,clear:()=>{e={},t={}}}},c=Symbol(),l=(e,t,n)=>{let r={type:t,payload:n};return Object.defineProperty(r,c,{value:e,enumerable:!1}),r},u=e=>{if(typeof e==`function`)return e;if(typeof e==`object`&&e&&c in e)return e[c]},d=(e,t,n)=>Reflect.apply(e,null,[t,n]),f=(c={})=>{let l=s(),f=(e,t)=>l.add(o(e),t),p=(e,t)=>{let n=f(e,(e,r)=>(n(),t(e,r)));return n},m=(e,t)=>{e===void 0?l.clear():l.remove(o(e),t)},h=(n,a)=>{let{onError:o}=c,{ctx:s}=t({event:a,bus:g,tracer:c.trace,parent:{ref:r()}});if(!o){n(a.payload,s);return}let l=t=>{try{o(t,a)}catch(t){e(`onError failed`,t)}};try{let e=n(a.payload,s);i(e)&&Promise.resolve(e).catch(l)}catch(e){l(e)}},g={on:f,once:p,off:m,emit:(e,i)=>{let s=o(e),f=a(e,i),p={type:s,payload:f},m=u(e);m||=g.actions?.bound?.(s);let _=[...l.get(s),...l.get(`*`)];_.length===0&&!m&&c.onUnhandled?.(p);for(let e of _)h(e,p);if(m){let{ctx:e}=t({event:p,bus:g,tracer:c.trace,parent:{ref:r()}}),i=g.actions?.run??d;return n(e,`command`,()=>i(m,f,e))}},use:e=>e(g),ctx:c.context,trace:c.trace};return g};export{f as n,l as r,u as t};

package/dist/context-UcmrAIhP.js

@@ -1 +0,0 @@
-const e=(e,t)=>{globalThis.console?.error(`[nanoeffects] ${e}`,t)},t=()=>{},n=/* @__PURE__ */ new WeakMap,r=t=>{let r=n.get(t);if(r)return r;let i=/* @__PURE__ */ new Set;return n.set(t,i),t.addEventListener(`abort`,()=>{let n=[...i];i.clear();for(let{fn:r}of n)try{r(t.reason)}catch(t){e(`abort callback failed`,t)}},{once:!0}),i},i=(e,n)=>{let{signal:i}=e;if(!i)return t;if(i.aborted)return n(i.reason),t;let a=r(i),o={fn:n};return a.add(o),()=>{a.delete(o)}},a=e=>{let t=new AbortController;return{controller:t,unlink:i({signal:e},e=>t.abort(e))}},o=Symbol(),s=typeof __NANOEFFECTS_TRACE__>`u`||__NANOEFFECTS_TRACE__,c=/* @__PURE__ */ new WeakMap;let l;const u=()=>l,d=()=>{},f=(e,t,n,r)=>{let i=s&&c.get(e);i&&i.tracer.report(i.ref,t,n,r)},p=(e,t)=>{let n=s&&c.get(e);n&&n.tracer.rename?.(n.ref,t)},m=(e,t)=>{let n=s&&c.get(e);return n?n.tracer.settler(n.ref,t):d},h=(e,t,n)=>{let r=s&&c.get(e);return r?r.tracer.run(r.ref,t,e.signal,n):n()},g=Symbol(`nanoeffects.addContext`),_=(e,t)=>typeof e==`function`?e(t):e,v=({event:e,bus:t,tracer:n,parent:r})=>{let{controller:u,unlink:f}=a(r?.signal),{signal:p}=u,m=s&&n?{tracer:n,ref:n.task(e,r?.ref)}:void 0,y=(...e)=>{if(p.aborted&&!S[o])return;let n=t?.emit,r=l;l=m?.ref;try{return n?.(...e)}finally{l=r}},b=(...e)=>{if(p.aborted)return d;let n=t?.on,r=n?.(...e);if(!r)return d;let a=i({signal:p},r);return()=>{a(),r()}},x=async(r,...i)=>{p.throwIfAborted();let a=i[0],o=v({event:{type:e.type,payload:a},bus:t,tracer:n,parent:{signal:p,ref:m?.ref}});try{return await h(o.ctx,`run`,()=>r(a,o.ctx))}finally{o.unlink()}},S={..._(t?.ctx,e),type:e.type,payload:e.payload,signal:p,abort:e=>u.abort(e),emit:y,on:b,off:t?.off??d,run:x,[g]:t?.addContext};return t?.addContext?.(S),m&&c.set(S,m),{ctx:S,unlink:f}},y=(e,t)=>{let n=s?c.get(e):void 0;return v({event:{type:t??e.type??``,payload:e.payload},bus:{emit:e.emit,on:e.on,off:e.off,ctx:e,addContext:Reflect.get(e,g)},tracer:n?.tracer,parent:{signal:e.signal,ref:n?.ref}})};export{p as a,s as c,e as d,y as i,o as l,v as n,h as o,u as r,f as s,m as t,i as u};

package/dist/context-types-nGtzhjxD.d.ts

@@ -1,14 +0,0 @@
-import { C as ContextOf, H as EventMap } from "./action-creator-D_c223C7.js";
-//#region src/core/context-types.d.ts
-/** What a function that makes the fields of a task gets to see. */
-type ContextTask = {
-  type: string;
-  payload?: unknown;
-};
-/**
- * `unknown` when none of the `fields` is already a context field of the bus,
- * else `never`: the call does not compile. Used as `bus: Bus<E> & NoClash<…>`.
- */
-type NoClash<Fields extends object, E extends EventMap> = [keyof Fields & keyof ContextOf<E>] extends [never] ? unknown : never;
-//#endregion
-export { NoClash as n, ContextTask as t };

package/dist/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};

package/dist/notrace/bus-CGi2lrd5.js

@@ -1 +0,0 @@
-import{a as e,l as t,n,r}from"./context-_HWcdjZf.js";import{n as i}from"./promise-CSLpzwSR.js";const a=e=>typeof e==`string`?e:e.type,o=(e,t)=>typeof e==`object`?e.payload:t,s=()=>{let e={},t={},n=n=>(t[n]=void 0,e[n]??=/* @__PURE__ */ new Map,e[n]),r=(e,t)=>{let r=n(e),i=r.get(t)??0;i>1?r.set(t,i-1):t?r.delete(t):r.clear()};return{get:n=>(t[n]??=[...e[n]??[]].flatMap(([e,t])=>Array(t).fill(e)),t[n]),add:(e,t)=>{let i=n(e);return i.set(t,(i.get(t)??0)+1),()=>{r(e,t)}},remove:r,clear:()=>{e={},t={}}}},c=Symbol(),l=(e,t,n)=>{let r={type:t,payload:n};return Object.defineProperty(r,c,{value:e,enumerable:!1}),r},u=e=>{if(typeof e==`function`)return e;if(typeof e==`object`&&e&&c in e)return e[c]},d=(e,t,n)=>Reflect.apply(e,null,[t,n]),f=(c={})=>{let l=s(),f=(e,t)=>l.add(a(e),t),p=(e,t)=>{let n=f(e,(e,r)=>(n(),t(e,r)));return n},m=(e,t)=>{e===void 0?l.clear():l.remove(a(e),t)},h=(e,a)=>{let{onError:o}=c,{ctx:s}=n({event:a,bus:g,tracer:c.trace,parent:{ref:r()}});if(!o){e(a.payload,s);return}let l=e=>{try{o(e,a)}catch(e){t(`onError failed`,e)}};try{let t=e(a.payload,s);i(t)&&Promise.resolve(t).catch(l)}catch(e){l(e)}},g={on:f,once:p,off:m,emit:(t,i)=>{let s=a(t),f=o(t,i),p={type:s,payload:f},m=u(t);m||=g.actions?.bound?.(s);let _=[...l.get(s),...l.get(`*`)];_.length===0&&!m&&c.onUnhandled?.(p);for(let e of _)h(e,p);if(m){let{ctx:t}=n({event:p,bus:g,tracer:c.trace,parent:{ref:r()}}),i=g.actions?.run??d;return e(t,`command`,()=>i(m,f,t))}},use:e=>e(g),ctx:c.context,trace:c.trace};return g};export{l as n,a as r,f as t};

package/dist/notrace/promise-CSLpzwSR.js

@@ -1 +0,0 @@
-const e=e=>typeof e!=`object`||!e?!1:`then`in e&&typeof e.then==`function`,t=(t,n)=>e(t)?Promise.resolve(t).finally(n):(n(),t);export{e as n,t};