nanoeffects 0.28.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,9 +32,9 @@ 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`
@@ -42,12 +42,12 @@ Rules that generated code often gets wrong:
 - [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
 
@@ -60,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,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.28.0",
+	"version": "0.29.0",
 	"description": "Business logic and side effects outside UI components, as plain async functions. Tiny, no dependencies.",
 	"keywords": [
 		"event-bus",
@@ -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-DlpEluzd.js

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

@@ -1,14 +0,0 @@
-import { C as ContextOf, H as EventMap } from "./action-creator-CcAEvUnw.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 };