nanoeffects 0.0.0-stage → 0.2.0

package/dist/policies.d.ts

@@ -0,0 +1,171 @@
+import { N as Task, k as EventMap } from "./action-rqZEnRIp.js";
+//#region src/policies/keyed.d.ts
+/** Options shared by every policy that can keep its state per key. */
+type KeyOption<P> = {
+  /**
+   * Gives each key its own state: calls with different keys do not affect
+   * each other. The state of a key is dropped when that key goes idle, so
+   * keys can be unbounded (ids, urls).
+   */
+  key?: (payload: P) => unknown;
+};
+//#endregion
+//#region src/policies/debounce.d.ts
+type DebounceResult<R> = Promise<R | undefined> | Promise<Awaited<R> | undefined> | undefined;
+type DebounceOptions<P = never> = KeyOption<P> & {
+  /** Run the first call of a burst at once. Default `false`. */
+  leading?: boolean;
+  /** Run the last call of a burst after `ms` of quiet. Default `true`. */
+  trailing?: boolean;
+};
+/**
+ * Waits for `ms` of quiet, then runs; a new call restarts the wait and drops
+ * the previous. With `leading` the first call of a burst runs at once, and the
+ * trailing run happens only if more calls follow it. With `trailing: false`
+ * only the leading call runs. With `options.key` each key has its own wait.
+ *
+ * @example
+ * ```ts
+ * bus.on(
+ *   "input",
+ *   debounce(300, async (text, { signal }) => {
+ *     const res = await fetch(`/api?q=${text}`, { signal });
+ *     showResults(await res.json());
+ *   }),
+ * );
+ *
+ * bus.emit("input", "r");
+ * bus.emit("input", "re"); // only the last call runs, 300 ms after it
+ * ```
+ */
+export declare const debounce: <P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: DebounceOptions<P>) => Task<P, E, DebounceResult<R>>;
+//#endregion
+//#region src/policies/latest.d.ts
+type LatestOptions<P = never> = KeyOption<P>;
+/**
+ * Aborts the previous run when a new call arrives; stale results are dropped.
+ * With `options.key` each key has its own latest run.
+ *
+ * @example
+ * ```ts
+ * bus.on(
+ *   "search",
+ *   latest(async (query, { signal }) => {
+ *     const res = await fetch(`/api?q=${query}`, { signal });
+ *     showResults(await res.json());
+ *   }),
+ * );
+ *
+ * bus.emit("search", "re"); // aborted by the next call
+ * bus.emit("search", "redux"); // only this one finishes
+ *
+ * // one latest run per user instead of one for all
+ * bus.on("load", latest(loadUser, { key: (user) => user.id }));
+ * ```
+ */
+export declare const latest: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LatestOptions<P>) => Task<P, E, R | Promise<Awaited<R> | undefined> | undefined>;
+//#endregion
+//#region src/policies/leading.d.ts
+type LeadingOptions<P = never> = KeyOption<P>;
+/**
+ * Drops new calls while the task is still running. The lock is released when
+ * the run settles or when its task is aborted, whichever comes first, so a
+ * `fn` that ignores the abort signal may overlap with the next run. With
+ * `options.key` each key has its own lock.
+ *
+ * @example
+ * ```ts
+ * bus.on(
+ *   "save",
+ *   leading(async (draft) => {
+ *     await api.save(draft);
+ *   }),
+ * );
+ *
+ * bus.emit("save", draft); // runs
+ * bus.emit("save", draft); // dropped while the first save is in flight
+ * ```
+ */
+export declare const leading: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: LeadingOptions<P>) => Task<P, E, R | Promise<Awaited<R>> | undefined>;
+//#endregion
+//#region src/policies/queue.d.ts
+type QueueOptions<P = never> = KeyOption<P> & {
+  /** How many calls may run at the same time. Default 1. */
+  concurrency?: number;
+  /** How many calls may wait for a free slot. Default: no limit. */
+  limit?: number;
+  /**
+   * What to drop when a call arrives and `limit` calls already wait: the new
+   * call (`"drop-new"`, the default) or the oldest waiting one (`"drop-old"`,
+   * which keeps the most recent calls). A dropped call resolves with `undefined`.
+   */
+  overflow?: "drop-new" | "drop-old";
+};
+/**
+ * Runs calls one after another, in the order they arrived: a call starts when
+ * fewer than `concurrency` calls are running. Every call returns a promise with
+ * the result of its own run; an error rejects only that call, and the queue
+ * goes on. The first call on an idle queue starts synchronously.
+ *
+ * With `limit` the number of waiting calls is capped. `limit: 1` with
+ * `overflow: "drop-old"` keeps only the latest call while one is running, and
+ * runs it when the current one is done.
+ *
+ * With `options.key` each key has its own line.
+ *
+ * A call whose task aborts while it waits is skipped and resolves with
+ * `undefined`. When the task of a running call aborts, its slot is freed at
+ * once and its result is dropped; a `fn` that ignores the abort signal can
+ * then overlap with the next run.
+ *
+ * @example
+ * ```ts
+ * bus.on(
+ *   "save",
+ *   queue(async (draft, { signal }) => {
+ *     await api.save(draft, { signal });
+ *   }),
+ * );
+ *
+ * bus.emit("save", a); // runs
+ * bus.emit("save", b); // waits for a, then runs
+ * ```
+ */
+export declare const queue: <P, E extends EventMap, R>(fn: Task<P, E, R>, options?: QueueOptions<P>) => Task<P, E, Promise<Awaited<R> | undefined>>;
+//#endregion
+//#region src/policies/throttle.d.ts
+type ThrottleOptions<P = never> = KeyOption<P> & {
+  /** Run the first call at once, when the throttle is idle. Default `true`. */
+  leading?: boolean;
+  /** Run the latest call made while waiting, at the end of the window. Default `true`. */
+  trailing?: boolean;
+};
+/**
+ * At most one run per `ms`, with the semantics of lodash `throttle` (and
+ * patronum): a call made when the throttle is idle, that is, at least `ms`
+ * after the previous call and the previous run, runs at once (`leading`); calls
+ * made while it waits are held, and the latest of them runs when the window
+ * closes (`trailing`). Under a steady stream of calls it runs every `ms`.
+ *
+ * A held call returns a promise that settles with its result; calls superseded
+ * by a newer one, or not allowed to wait (`trailing: false`), resolve with
+ * `undefined`. With `leading: false` even the first call waits for the end of
+ * its window. With `options.key` each key has its own throttle.
+ *
+ * @example
+ * ```ts
+ * bus.on(
+ *   "scroll",
+ *   throttle(200, (position) => {
+ *     saveScrollPosition(position);
+ *   }),
+ * );
+ *
+ * bus.emit("scroll", 10); // runs now
+ * bus.emit("scroll", 20); // superseded
+ * bus.emit("scroll", 30); // runs once the 200 ms window closes
+ * ```
+ */
+export declare const throttle: <P, E extends EventMap, R>(ms: number, fn: Task<P, E, R>, options?: ThrottleOptions<P>) => Task<P, E, R | Promise<R | undefined> | undefined>;
+//#endregion
+export type { DebounceOptions, LatestOptions, LeadingOptions, QueueOptions, ThrottleOptions };

package/dist/policies.js

@@ -0,0 +1 @@
+import{t as e}from"./onAbort-BgMfspK4.js";import{a as t,i as n,o as r,t as i}from"./context-DlA80GOA.js";import{n as a,r as o,t as s}from"./delay-CIHnOh_L.js";import{n as c,t as l}from"./promise-CSLpzwSR.js";const u=()=>{},d=(e,t)=>{let n=/* @__PURE__ */ new Map;return(r,i)=>{let a=e(r),o=n.get(a);if(!o){let e=t(()=>{n.get(a)===e&&n.delete(a)});o=e,n.set(a,e)}return o(r,i)}},f=(e,t)=>e?d(e,t):t(u),p=(e,t={})=>f(t.key,t=>m(`latest`,(t,n,r)=>(r(),e(t,n)),t)),m=(t,a,o=u)=>{let s=null;return(l,u)=>{if(s?.abort(),u.signal.aborted)return;let{ctx:d,unlink:f}=n(u);s=d;let p=i(d,t),m=!1,h=()=>{d.signal.aborted||(m=!0,r(d,t,`start`))};e(d,()=>p(m?`cancel`:`drop`));let g=()=>{f(),s===d&&(s=null,o())},_=e=>{if(!d.signal.aborted)return p(m?`done`:`drop`),e};try{let e=a(l,d,h);return c(e)?Promise.resolve(e).then(_,e=>{if(!d.signal.aborted)throw p(`error`,e),e}).finally(g):(g(),_(e))}catch(e){if(g(),d.signal.aborted)return;throw p(`error`,e),e}}},h=(e,t,n={})=>f(n.key,r=>_(e,t,n,r)),g=(e,n,i,s)=>{let c=s!==u,l=null,d=null;return(u,f)=>{if(f.signal.aborted)return;let p=Date.now(),m=l===null||p-l>=e||p-l<0;return l=p,d!==null&&a(d),d=c?o(s,e):null,i&&m?Promise.resolve(t(f,`debounce`,()=>n(u,f))):(r(f,`debounce`,`drop`),Promise.resolve(void 0))}},_=(n,r,i,a)=>{let o=i.leading??!1,c=i.trailing??!0;if(!c)return g(n,r,o,a);let l=!1,u=0,d=m(`debounce`,([t,i],a,o)=>{let d=u;return e(a,()=>{u===d&&(l=!1)}),s(a,n).then(()=>{if(l=!1,c&&!i)return o(),r(t,a)})},a);return(e,n)=>{if(n.signal.aborted)return;let i=o&&!l;l=!0,u++;let a=d([e,i],n);return i?Promise.resolve(t(n,`debounce`,()=>r(e,n))):a}},v=(n,i={})=>f(i.key,i=>{let a=null;return(o,s)=>{if(s.signal.aborted)return;if(a){r(s,`leading`,`drop`);return}let c={};a=c;let u=()=>{d(),a===c&&(a=null,i())},d=e(s,u);try{return l(t(s,`leading`,()=>n(o,s)),u)}catch(e){throw u(),e}}}),y=(e,t={})=>f(t.key,n=>b(e,t,n)),b=(n,i,a)=>{let o=i.concurrency??1,s=i.limit??1/0,c=[],l=0,d=()=>{for(;l<o;){let e=c.shift();if(!e)return;e.start()}};return(f,p)=>new Promise((m,h)=>{if(p.signal.aborted){m(void 0);return}let g=u,_=()=>{g(),r(p,`queue`,`drop`),m(void 0)},v=()=>{if(g(),p.signal.aborted){_();return}l++;let r=!0,i=()=>{r&&(r=!1,l--,d(),l===0&&c.length===0&&a())},o=e(p,()=>{i(),m(void 0)}),s;try{s=Promise.resolve(t(p,`queue`,()=>n(f,p)))}catch(e){s=Promise.reject(e)}let u=()=>{o(),i()};s.then(e=>{u(),m(p.signal.aborted?void 0:e)},e=>{u(),p.signal.aborted?m(void 0):h(e)})};if(l<o){v();return}if(c.length>=s){if(i.overflow!==`drop-old`||s<=0){_();return}c.shift()?.drop()}let y={start:v,drop:_};c.push(y),g=e(p,()=>{let e=c.indexOf(y);e>=0&&c.splice(e,1),_()})})},x=(e,t,n={})=>f(n.key,r=>S(e,t,n,r)),S=(e,n,i,s)=>{let c=i.leading??!0,l=i.trailing??!0,d=s!==u,f=null,p=0,m=null,h=null,g=null,_=!1,v=t=>f===null||t-f>=e||t-f<0||t-p>=e,y=e=>r(e,`throttle`,`drop`),b=()=>{let e=g;g=null,e&&(y(e.ctx),e.resolve())},x=(e,t)=>(b(),new Promise((n,r)=>{g={payload:e,ctx:t,resolve:n,reject:r}})),S=(e,r,i)=>{b(),p=i,_=!0;try{return t(r,`throttle`,()=>n(e,r))}finally{_=!1}},C=()=>{d&&(h=o(w,e))},w=()=>{if(h=null,!d||m!==null||g)return;let t=Date.now(),n=Math.max(e-(t-(f??-1/0)),e-(t-p));n<=0?s():h=o(w,n)},T=e=>{m=null;let t=g;if(l&&t&&!t.ctx.signal.aborted){g=null;try{t.resolve(S(t.payload,t.ctx,e))}catch(e){t.reject(e)}}else b();w()},E=()=>{let t=Date.now();v(t)?T(t):m=o(E,Math.min(e-(t-(f??t)),e-(t-p)))},D=()=>{h!==null&&(a(h),h=null)},O=(e,t)=>{if(!l)y(t);else return x(e,t)},k=(e,t,n,r)=>{if(!r)y(t);else if(p=n,C(),!c)y(t);else return S(e,t,n)},A=(t,n,r,i)=>i&&m!==null?(a(m),m=o(E,e),S(t,n,r)):m===null&&(m=o(E,e),i&&(p=r,c))?S(t,n,r):O(t,n);return(e,t)=>{if(t.signal.aborted)return;let n=Date.now(),r=!_&&v(n);return f=n,D(),l?A(e,t,n,r):k(e,t,n,r)}};export{h as debounce,p as latest,v as leading,y as queue,x as throttle};

package/dist/production/dev.js

@@ -0,0 +1 @@
+const e=()=>{},t=()=>e,n=()=>t;export{n as devPlugin};

package/dist/promise-CSLpzwSR.js

@@ -0,0 +1 @@
+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};

package/dist/redux.d.ts

@@ -0,0 +1,92 @@
+import { k as EventMap, o as Bus, s as BusOptions } from "./action-rqZEnRIp.js";
+//#region src/store/redux/middleware.d.ts
+/** What Redux passes through a middleware: an action is a plain object with a `type`. */
+type ReduxAction = {
+  type: string;
+  payload?: unknown;
+};
+type NanoeffectsMiddlewareOptions = {
+  /** Return `false` for the actions that the bus should not get. Default: all of them. */
+  filter?: (action: ReduxAction) => boolean;
+};
+/**
+ * A Redux middleware that sends every action to the bus, after the reducers
+ * have handled it, so a handler that reads the store sees the new state. It
+ * does not depend on Redux: it only has the shape of a middleware. Values that
+ * are not plain actions (the functions of redux-thunk) go through untouched.
+ *
+ * The other way needs no adapter: give the store to the tasks with
+ * `createBus({ context: { store } })` and dispatch from a handler.
+ *
+ * Take care of loops: a handler must not dispatch the action it handles.
+ * Errors of handlers reach the caller of `dispatch`, as for `bus.emit`; set
+ * `onError` on the bus to isolate them.
+ *
+ * @example
+ * ```ts
+ * const store = configureStore({
+ *   reducer,
+ *   middleware: (getDefault) => getDefault().concat(nanoeffectsMiddleware(bus)),
+ * });
+ *
+ * bus.on(userRequested, latest(async (id, { store, signal }) => {
+ *   store.dispatch(userLoaded(await fetchUser(id, { signal })));
+ * }));
+ * ```
+ */
+export declare const nanoeffectsMiddleware: <E extends EventMap>(bus: Bus<E>, options?: NanoeffectsMiddlewareOptions) => () => (next: (action: unknown) => unknown) => (action: unknown) => unknown;
+//#endregion
+//#region src/store/redux/effects.d.ts
+/** What Redux gives a middleware: the parts of the store that it may use. */
+type ReduxStoreApi<State = unknown> = {
+  dispatch: (action: {
+    type: string;
+    payload?: unknown;
+  }) => unknown;
+  getState: () => State;
+};
+type EffectsMiddlewareOptions<E extends EventMap> = Omit<BusOptions<E>, "context"> & NanoeffectsMiddlewareOptions & {
+  /** More fields for the context of every task, next to `store`. */
+  context?: object;
+};
+/**
+ * Creates a bus and the Redux middleware that feeds it: the effects of an app
+ * in one place, without sagas. Every task gets `ctx.store`, the `dispatch` and
+ * `getState` of the store, as soon as the middleware is added to it. Type it
+ * in the event map:
+ *
+ * ```ts
+ * type Events = { userRequested: string } & WithContext<{ store: ReduxStoreApi<RootState> }>;
+ * ```
+ *
+ * Two things are looked after for you:
+ *
+ * - **A handler does not loop on its own action.** An action that a handler
+ *   dispatches through `ctx.store` and that has the type the handler works on
+ *   does not go back to the bus (a handler of `a` that dispatches `a`). Other
+ *   handlers of that type do not get it either. Longer cycles, `a` to `b` to
+ *   `a`, are yours to avoid.
+ * - **A failing handler does not break `dispatch`.** Errors go to `onError`,
+ *   by default to `console.error`, as in Redux Toolkit listeners; reducers
+ *   still throw to the caller.
+ *
+ * @example
+ * ```ts
+ * const effects = createEffectsMiddleware<Events>();
+ *
+ * const store = configureStore({
+ *   reducer,
+ *   middleware: (getDefault) => getDefault().concat(effects.middleware),
+ * });
+ *
+ * effects.bus.on(userRequested, latest(async (id, { store, signal }) => {
+ *   store.dispatch(userLoaded(await fetchUser(id, { signal })));
+ * }));
+ * ```
+ */
+export declare const createEffectsMiddleware: <E extends EventMap = EventMap>(options?: EffectsMiddlewareOptions<E>) => {
+  bus: Bus<E>;
+  middleware: (storeApi: ReduxStoreApi) => (next: (action: unknown) => unknown) => (action: unknown) => unknown;
+};
+//#endregion
+export type { EffectsMiddlewareOptions, NanoeffectsMiddlewareOptions, ReduxStoreApi };

package/dist/redux.js

@@ -0,0 +1 @@
+import{n as e}from"./onAbort-BgMfspK4.js";import{t}from"./bus-CRnlwmQ4.js";const n=e=>typeof e==`object`&&!!e&&`type`in e,r=(e,t={})=>{let r=e.emit;return()=>e=>i=>{let a=e(i);return n(i)&&(t.filter?.(i)??!0)&&r(i),a}},i=(n={})=>{let{filter:i,context:a,onError:o,...s}=n,c,l=/* @__PURE__ */ new WeakMap,u=e=>({...a,store:c&&{getState:c.getState,dispatch:t=>{typeof t==`object`&&t&&l.set(t,e.type);let n=t;return c?.dispatch(n)}}}),d=t({...s,onError:o??((t,{type:n})=>{e(`handler of "${n}" failed`,t)}),context:u}),f=r(d,{filter:e=>l.get(e)!==e.type&&(i?.(e)??!0)});return{bus:d,middleware:e=>(c=e,f())}};export{i as createEffectsMiddleware,r as nanoeffectsMiddleware};

package/dist/trace.d.ts

@@ -0,0 +1,162 @@
+import { E as Tracer, F as TraceEvent, I as TraceLogger, P as Trace } from "./action-rqZEnRIp.js";
+//#region src/trace/console.d.ts
+type ConsoleLoggerOptions = {
+  /** Defaults to `globalThis.console`. */
+  console?: Pick<Console, "debug" | "error">;
+  /** Prepended to every line. */
+  prefix?: string;
+};
+/**
+ * Trace logger that prints one line per phase, indented by task depth.
+ * Failures go to `console.error`, everything else to `console.debug`.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus<Events>({ trace: createTracer(consoleLogger()) });
+ * // search · latest start
+ * // search · latest cancel
+ * ```
+ */
+export declare const consoleLogger: (options?: ConsoleLoggerOptions) => TraceLogger;
+//#endregion
+//#region src/trace/performance.d.ts
+/** The part of the User Timing API the logger uses. */
+type PerformanceLike = {
+  now: () => number;
+  mark: (name: string, options?: {
+    detail?: unknown;
+  }) => unknown;
+  measure: (name: string, options: {
+    start: number;
+    end: number;
+    detail?: unknown;
+  }) => unknown;
+};
+type PerformanceLoggerOptions = {
+  /** Defaults to `globalThis.performance`. */
+  performance?: PerformanceLike;
+};
+/**
+ * Trace logger that records User Timing entries, so tasks show up on the
+ * Timings track of the browser Performance panel. A task that started is a
+ * measure from `start` to its end; a dropped call is a single mark.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus<Events>({ trace: createTracer(performanceLogger()) });
+ * ```
+ */
+export declare const performanceLogger: (options?: PerformanceLoggerOptions) => TraceLogger;
+//#endregion
+//#region src/trace/recorder.d.ts
+type Recorder<E = Record<string, unknown>> = TraceLogger<E> & {
+  /** Every event received so far, in order. */
+  readonly events: TraceEvent<E>[];
+  clear: () => void;
+};
+/**
+ * Trace logger that keeps events in memory; meant for tests.
+ *
+ * @example
+ * ```ts
+ * const recorder = createTraceRecorder<Events>();
+ * const bus = createBus<Events>({ trace: createTracer(recorder) });
+ *
+ * bus.emit("search", "re");
+ * bus.emit("search", "redux");
+ * recorder.events.map((e) => e.phase); // ["start", "cancel", "start", "done"]
+ * ```
+ */
+export declare const createTraceRecorder: <E = Record<string, unknown>>() => Recorder<E>;
+//#endregion
+//#region src/trace/redux.d.ts
+type ReduxConnection = {
+  init: (state: unknown) => void;
+  send: (action: unknown, state: unknown) => void;
+};
+type ReduxExtension = {
+  connect: (options?: {
+    name?: string;
+    maxAge?: number;
+  }) => ReduxConnection;
+};
+type ReduxDevtoolsOptions = {
+  /** Instance name in the Redux DevTools picker. */
+  name?: string;
+  /** Defaults to `globalThis.__REDUX_DEVTOOLS_EXTENSION__`. */
+  extension?: ReduxExtension;
+  /**
+   * Also send the start of every task as an action. Default `false`: a task
+   * is one action, sent when it ends, and the tasks that are running are in
+   * the state.
+   */
+  starts?: boolean;
+  /**
+   * How deep in the tree of tasks to show: `0` is the handler tasks only, `1`
+   * also the effects they start (`retry`, `timeout`, ...), and so on. The
+   * attempts and the starters under them are hidden at the default, `1`.
+   */
+  depth?: number;
+  /** The number of actions that DevTools keeps; its own default is 50. */
+  maxAge?: number;
+};
+type ReduxDevtoolsState = {
+  /** Tasks that started and have not settled yet, by trace id. */
+  running: Record<number, {
+    type: string;
+    effect: string;
+  }>;
+};
+/**
+ * Trace logger that sends the tasks to Redux DevTools as actions
+ * `type/effect/phase`, with the running tasks as state. By default it is quiet:
+ * a task is one action, when it ends, and only the handler tasks and the
+ * effects they start are shown (see `starts` and `depth` to show more).
+ * Read-only: there is no time travel. Does nothing when the extension is not
+ * installed.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus<Events>({
+ *   trace: createTracer(reduxDevtools({ name: "app" })),
+ * });
+ * ```
+ */
+export declare const reduxDevtools: (options?: ReduxDevtoolsOptions) => TraceLogger;
+//#endregion
+//#region src/trace/tracer.d.ts
+type TracerOptions = {
+  /** Drops the events it returns `false` for, before any logger sees them. */
+  filter?: (event: TraceEvent) => boolean;
+  /**
+   * Which root tasks to trace: a share between 0 and 1, or a function of the
+   * event. It is decided once per root task (a handler call) and every task
+   * below it follows, so a trace is never cut in the middle. Default: all.
+   */
+  sample?: number | ((event: {
+    type: string;
+    payload: unknown;
+  }) => boolean);
+};
+/**
+ * Makes the tracer for `createBus({ trace })` from one logger or several.
+ * A tracer numbers the tasks it sees, so share one across buses only if the
+ * ids should be unique across them. `options.filter` and `options.sample`
+ * cut the volume, e.g. for production.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus<Events>({
+ *   trace: createTracer([reduxDevtools({ name: "app" }), consoleLogger()]),
+ * });
+ *
+ * // production: trace 5% of the handler calls, and only their failures
+ * createTracer(logger, {
+ *   sample: 0.05,
+ *   filter: (event) => event.phase === "error",
+ * });
+ * ```
+ */
+export declare const createTracer: <E = Record<string, unknown>>(trace: Trace<E>, options?: TracerOptions) => Tracer;
+//#endregion
+export type { ConsoleLoggerOptions, PerformanceLoggerOptions, Recorder, ReduxDevtoolsOptions, ReduxDevtoolsState, ReduxExtension, TracerOptions };

package/dist/trace.js

@@ -0,0 +1 @@
+import{n as e,t}from"./onAbort-BgMfspK4.js";import{n}from"./promise-CSLpzwSR.js";const r=(e={})=>{let t=e.console??globalThis.console,n=e.prefix??`[nanoeffects]`,r=/* @__PURE__ */ new Map;return({id:e,parent:i,type:a,effect:o,phase:s,payload:c,error:l})=>{r.has(e)||r.set(e,typeof i==`number`?(r.get(i)??0)+1:0);let u=`  `.repeat(r.get(e)??0);s!==`start`&&r.delete(e);let d=`${n} ${u}${a} · ${o} ${s}`;s===`error`?t?.error(d,l):t?.debug(d,c)}},i=(e={})=>{let t=e.performance??globalThis.performance,n=/* @__PURE__ */ new Map;return({id:e,parent:r,type:i,effect:a,phase:o,error:s})=>{if(!t)return;if(o===`start`){n.set(e,t.now());return}let c=`${i} · ${a} (${o})`,l={id:e,parent:r,phase:o,...o===`error`&&{error:String(s)}},u=n.get(e);n.delete(e),typeof u==`number`?t.measure(c,{start:u,end:t.now(),detail:l}):t.mark(c,{detail:l})}},a=()=>{let e=[];return Object.assign(t=>{e.push(t)},{events:e,clear:()=>{e.length=0}})},o=()=>{},s=(e={})=>{let t=e.extension??globalThis.__REDUX_DEVTOOLS_EXTENSION__;if(!t)return o;let{starts:n=!1,depth:r=1,maxAge:i}=e,a=t.connect({name:e.name??`nanoeffects`,...i!==void 0&&{maxAge:i}}),s=/* @__PURE__ */ new Map,c=/* @__PURE__ */ new Map,l=()=>({running:Object.fromEntries(s)});return a.init(l()),({error:e,...t})=>{let i=(t.parent===void 0?-1:c.get(t.parent)??-1)+1,o=i<=r;t.phase===`start`?(c.set(t.id,i),o&&s.set(t.id,{type:t.type,effect:t.effect})):(c.delete(t.id),s.delete(t.id)),o&&(t.phase!==`start`||n)&&a.send({...t,type:`${t.type}/${t.effect}/${t.phase}`,event:t.type,...t.phase===`error`&&{error:e instanceof Error?e.message:e}},l())}},c=t=>{let n=typeof t==`function`?[t]:[...t??[]];return n.length===0?null:t=>{for(let r of n)try{r(t)}catch(t){e(`trace logger failed`,t)}}},l=()=>{},u=(e,r={})=>{let i=c(e),{filter:a,sample:o=1}=r,s=0,u=e=>typeof o==`function`?o({type:e.type,payload:e.payload}):Math.random()<o,d={task:(e,t)=>({id:++s,parent:t?.id,type:e.type,payload:e.payload,sampled:t?.sampled??u(e)}),report:(e,t,n,r)=>{if(!e.sampled)return;let o={id:e.id,type:e.type,effect:t,phase:n,payload:e.payload};typeof e.parent==`number`&&(o.parent=e.parent),n===`error`&&(o.error=r),(!a||a(o))&&i?.(o)},settler:(e,t)=>{if(!e.sampled)return l;let n=!1;return(r,i)=>{n||(n=!0,d.report(e,t,r,i))}},run:(e,r,i,a)=>{if(!e.sampled)return a();let o=d.settler(e,r);d.report(e,r,`start`),t({signal:i},()=>o(`cancel`));let s;try{s=a()}catch(e){throw o(`error`,e),e}return n(s)?Promise.resolve(s).then(e=>(o(`done`),e),e=>{throw o(`error`,e),e}):(o(`done`),s)}};return d};export{r as consoleLogger,a as createTraceRecorder,u as createTracer,i as performanceLogger,s as reduxDevtools};

package/docs/README.md

@@ -0,0 +1,15 @@
+# Documentation
+
+Start with the [Guide](guide.md): from a bare bus to modules, one step at a time. The pages below are the reference.
+
+- [Guide](guide.md)
+- [Policies](policies.md): `latest`, `leading`, `debounce`, `throttle`, `queue`, `key`
+- [Effects and cancellation](effects.md): `retry`, `timeout`, `poll`, `take`, `all`, `allSettled`, `race`, `ctx.on`
+- [Actions, commands, jobs and modules](actions.md)
+- [Your own fields in the context](context.md)
+- [Errors and unheard events](errors.md)
+- [Tracing](tracing.md): loggers, Redux DevTools, sampling, the `notrace` build
+- [Redux, Zustand, MobX](stores.md)
+- [Observable: events as streams](observable.md): `createObserve` for RxJS and friends
+- [Hot reload and dev diagnostics](hmr.md): modules replaced by name, `devPlugin`
+- [Semantics](semantics.md)

package/docs/actions.md

@@ -0,0 +1,78 @@
+# Actions, commands, jobs and modules
+
+## Actions, commands and jobs
+
+`nanoeffects/actions` has the pieces to describe what a bus does, apart from the code that does it.
+
+```ts
+import { createAction, createCommand, createJob } from "nanoeffects/actions";
+
+// an event with a payload, as in Redux Toolkit
+// the payload types come from the event map of the bus: type Events = { "user/loaded": User; "user/failed": Error }
+const userLoaded = createAction("user/loaded");
+const loadFailed = createAction("user/failed");
+
+// a request for a result: emit it and get what its handler returns
+const getUser = createCommand("user/get", (id: string, { signal }) => fetchUser(id, { signal }));
+
+// a contract without a handler: the code that sends mail is elsewhere
+const sendMail = createCommand<Mail, void>("mail/send");
+
+// a command whose outcome is sent on as actions: the command and its two actions together
+const { command: loadUser, successAction, failAction } = createJob("user/load", fetchUser, {
+  success: userLoaded, // an action creator that exists: used and returned as it is
+  fail: "user/failed", // a string: the job makes the action creator
+});
+```
+
+**Actions.** `createAction(type)` returns a creator, with no generics: it keeps the literal type, and the bus checks the payload against its event map (`bus.emit(userLoaded(5))` is an error when `"user/loaded"` is a `User`). Without an event map give the payload type, `createAction<User>("user/loaded")`. The creator: `userLoaded(user)` is `{ type, payload }`, `userLoaded.type` is the type, `userLoaded.match(action)` narrows an action. `createAction(type, prepare)` builds the payload from several arguments. A creator works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`.
+
+**Commands.** `bus.emit(command, payload)` tells the listeners of the command's type, then runs its handler as a task, with a context, and returns the result. The handler can be wrapped in a policy, `createCommand("search", latest(fn))`. Calling `command(payload)` runs its own handler without a bus.
+
+**Where handlers are registered.** The command may carry a handler. The bus gets the handlers bound to commands from a registry, `createCommands`, and a handler bound there wins over the command's own. The registry belongs to one bus, as an effector scope does with `fork({ handlers })`, so each bus (each test) can have its own.
+
+```ts
+import { createCommands, bindHandler } from "nanoeffects/actions";
+
+const bus = createBus<Events>();
+const commands = createCommands(bus, [bindHandler(sendMail, smtpSend)]); // attached to the bus
+
+const unbind = commands.handle(getUser, async () => fakeUser); // later, e.g. in a test
+unbind(); // the command's own handler is back; the latest binding wins
+```
+
+A command with no handler anywhere throws `No handler for command "..."` from `emit`. The registry lives in `nanoeffects/actions`, so a bus without one carries none of this code; without it `emit(command, payload)` simply runs the command's own handler. `createCommands(bus)` sets the registry as `bus.commands`, and a second call on the same bus replaces it. There is no `commands` option in `createBus`; a custom runner is assigned, `bus.commands = { run }`.
+
+**Jobs.** `createJob(type, handler, { success, fail })` makes a command that sends its outcome on as actions, for when nobody waits for the result, and returns `{ command, successAction, failAction }`. When the handler succeeds, `successAction(result)` is emitted on the bus, and when it fails, `failAction(error)`.
+
+- `success` and `fail` are a string, from which the job makes an action creator with `createAction` (the payload is the result, or the error), or an action creator that exists already, which is used and returned as it is. A missing one is made with the type `<type>/success` or `<type>/fail`.
+- `bus.emit(command, payload)` returns a promise of the result. An error of the handler always counts as handled: it goes to `failAction` and the promise resolves with `undefined`. For a result that must reject, use a command.
+- The actions are emitted as the task that ran the job, also for a handler bound with `commands.handle`, and are not sent once the task is aborted. A missing handler is not an outcome: `emit` throws `No handler for command "..."`.
+- Calling `command(payload)` directly runs only the handler.
+
+## Modules
+
+`bus.use(modulePlugin(modules))`, with `modulePlugin` from `nanoeffects/actions`, assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose` and `commands`, the registry of command handlers. A module is what a domain of the app needs: the commands it handles, the events it listens to, its sub-modules and its background tasks.
+
+```ts
+const userModule = createModule<Events>("user", (m) => {
+  m.handle(getUser, fetchUser); // a contract gets its handler here
+  m.use(saveUser, authModule); // a command that carries a handler, and a sub-module
+  m.on("login", (user, ctx) => ctx.emit("loaded", user));
+  m.spawn(async (_, ctx) => { /* background work, ends with the module */ });
+});
+
+const bus = createBus<Events>();
+const app = bus.use(modulePlugin([userModule]));
+
+const unmount = app.mount(orderModule); // later, e.g. after a lazy import
+app.commands.handle(getUser, fakeUser); // in a test
+app.dispose(); // unmounts every module
+```
+
+- **Unmounting undoes everything** the module did: its subscriptions, its bound commands, its sub-modules and its background tasks, which are aborted.
+- **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one. That is what hot reload needs: see [hmr.md](hmr.md).
+- **The registry.** If `createCommands(bus)` was called, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`, so the commands that modules bind are the ones the bus runs.
+- A disposed app cannot mount modules.
+- A module context is a task context plus `handle` (give a command a handler: for a contract, or to override), `use` (bring sub-modules and commands that carry a handler: `m.use(getUser, saveUser, subModule)`, in any order; the returned function undoes just that call) and `spawn` (a background task, aborted on unmount).
+- A command that carries a handler keeps answering after its module is unmounted: the handler is its own, and `use` only brings the command and tracks it in the registry. Use `handle` for a handler that should live only as long as the module.

package/docs/context.md

@@ -0,0 +1,15 @@
+# Your own fields in the context
+
+Add fields to the context of every task of a bus: a store, a client, a logger. Describe them in the event map with `WithContext`, and give the values in `createBus({ context })`:
+
+```ts
+type Events = { save: Draft } & WithContext<{ store: Store }>;
+
+const bus = createBus<Events>({ context: { store } });
+bus.on("save", (draft, { store }) => store.put(draft));
+```
+
+The fields are in the context of handlers, `ctx.run`, listeners added with `ctx.on`, commands, modules and the child tasks of effects and policies, and the compiler checks them: a handler of a bus without `WithContext` has no `store`, and `context` must have the fields that the map names. Two buses can have different fields.
+
+- The fields of the library (`signal`, `emit`, `run`, ...) win when the names are the same.
+- `context` can also be a function, `(task) => fields`, called with `{ type, payload }` of each task, for fields that depend on the task.