nanoeffects 0.0.0-stage → 0.1.0

package/dist/notrace/actions.d.ts

@@ -0,0 +1,196 @@
+import { L as UnsubscribeCallback, N as Task, c as Command, j as PayloadOf, k as EventMap, m as Emittable, n as FreeActionCreator, o as Bus, r as createAction, t as ActionCreator, u as Context } from "./action-BM-UdmJr.js";
+//#region src/actions/command.d.ts
+/**
+ * Creates a command: a typed request for a result. `bus.emit(command, payload)`
+ * runs its handler as a task, with a context, and returns what the handler
+ * returns. Listeners of the command's type are told first, as for any event.
+ *
+ * The handler is optional. A command without one is only a contract, and the
+ * bus gets its implementation from the `commands` registry (see
+ * `createCommands` and `bindHandler`). A handler bound there wins over the one
+ * the command was created with, so a test can give a bus its own implementation.
+ *
+ * A handler can be wrapped in a policy, e.g. `latest(fn)`. Calling the command
+ * directly, `command(payload)`, runs its own handler outside of any bus.
+ *
+ * @example
+ * ```ts
+ * const getUser = createCommand("user/get", (id: string, { signal }) =>
+ *   fetchUser(id, { signal }),
+ * );
+ * const sendMail = createCommand<Mail, void>("mail/send"); // implemented elsewhere
+ *
+ * const commands = createCommands([bindHandler(sendMail, smtpSend)]);
+ * const bus = createBus({ commands });
+ * const user = await bus.emit(getUser, "1");
+ *
+ * commands.handle(getUser, async () => fakeUser); // in a test
+ * ```
+ */
+export declare const createCommand: <P = void, R = void, T extends string = string, E extends EventMap = EventMap>(type: T, handler?: Task<P, E, R>) => Command<P, R> & {
+  readonly type: T;
+};
+/** A command (or its type) with the handler to bind to it; `bindHandler` makes one. */
+type Binding<E extends EventMap = EventMap> = readonly [Command<never, unknown> | string, Task<never, E, unknown>];
+/**
+ * Pairs a command with the handler to bind to it, for `createCommands`. It
+ * checks that the handler fits the command.
+ *
+ * @example
+ * ```ts
+ * createCommands([bindHandler(sendMail, smtpSend)]);
+ * ```
+ */
+export declare const bindHandler: <P, R, E extends EventMap>(command: Command<P, R>, fn: Task<P, E, R>) => Binding<E>;
+/**
+ * The handlers bound to commands, for `createBus({ commands })`. Each bus gets
+ * its own, so each test can have its own implementation. `handle` binds more
+ * later and returns the function that unbinds.
+ *
+ * What the bus runs for a command: the handler bound last, else the one the
+ * command was created with, else it throws `No handler for command "..."`.
+ *
+ * @example
+ * ```ts
+ * const commands = createCommands([bindHandler(sendMail, smtpSend)]);
+ * const bus = createBus<Events>({ commands });
+ *
+ * const unbind = commands.handle(getUser, async () => fakeUser);
+ * unbind(); // the command's own handler is back
+ * ```
+ */
+export declare const createCommands: <E extends EventMap = EventMap>(bindings?: readonly Binding<E>[]) => {
+  run: (command: Command, payload: unknown, ctx: unknown) => unknown;
+  handle: {
+    <P, R>(command: Command<P, R>, fn: Task<P, E, R>): UnsubscribeCallback;
+    (type: string, fn: Task<never, E, unknown>): UnsubscribeCallback;
+    (bindings: readonly Binding<E>[]): UnsubscribeCallback;
+  };
+};
+//#endregion
+//#region src/actions/job.d.ts
+/**
+ * Creates a command whose outcome is sent on: when the handler succeeds, its
+ * result goes to `done`, and when it fails, the error goes to `fail`. Each is
+ * anything `emit` takes as its first argument, and receives the result (or the
+ * error) as the payload: an event type, an action creator, a command, or a
+ * plain action. It is made for the case where nobody waits for the result and
+ * the bus carries it on, like `createAsyncThunk` or an effector effect.
+ *
+ * `bus.emit(job, payload)` returns a promise of the result. When `fail` is set
+ * the error counts as handled: it goes to `fail` and the promise resolves with
+ * `undefined`; without `fail` the promise rejects. The outcome is routed by the
+ * bus, also for a handler bound with `commands.handle`, and is skipped once the
+ * task is aborted. Calling the job directly runs only its handler.
+ *
+ * @example
+ * ```ts
+ * const loaded = createAction<User>("user/loaded");
+ * const failed = createAction<Error>("user/failed");
+ *
+ * const loadUser = createJob("user/load", fetchUser, { done: loaded, fail: failed });
+ *
+ * bus.on(loaded, (user) => render(user));
+ * bus.emit(loadUser, "1"); // loaded(user) or failed(error) comes later
+ * ```
+ */
+export declare const createJob: <P = void, R = void, T extends string = string, E extends EventMap = EventMap>(type: T, handler?: Task<P, E, R>, outcomes?: {
+  /** Gets the result when the handler succeeds. */
+  done?: Emittable<E>;
+  /** Gets the error when the handler fails. */
+  fail?: Emittable<E>;
+}) => Command<P, Promise<Awaited<R> | undefined>> & {
+  readonly type: T;
+};
+//#endregion
+//#region src/actions/module.d.ts
+/**
+ * What a module's `setup` gets: the context of the module's task, so `on`,
+ * `emit` and `run` work as in a handler, plus `handle` to bind commands, `use`
+ * to mount sub-modules and `spawn` to start a background task. Everything the
+ * module does is undone when it is unmounted.
+ */
+type ModuleContext<E extends EventMap = EventMap> = Context<E> & {
+  /** Binds the handler of a command, or a list of them; undone on unmount. */
+  handle<P, R>(command: Command<P, R>, fn: Task<P, E, R>): UnsubscribeCallback;
+  handle(type: string, fn: Task<never, E, unknown>): UnsubscribeCallback;
+  handle(bindings: readonly Binding<E>[]): UnsubscribeCallback;
+  /**
+   * Mounts sub-modules; they are unmounted with this one. The returned function
+   * unmounts just these, e.g. when they were added later from a listener.
+   */
+  use(...modules: Module<E>[]): UnsubscribeCallback;
+  /**
+   * Starts a background task that lives as long as the module: it is aborted
+   * on unmount, and an error of it is left unhandled, as in any handler.
+   */
+  spawn<P>(fn: Task<P, E, unknown>, ...payload: PayloadOf<P>): void;
+};
+type Module<E extends EventMap = EventMap> = {
+  readonly name: string;
+  readonly setup: (m: ModuleContext<E>) => void;
+};
+/**
+ * Describes one domain of an app: the commands it handles, the events it
+ * listens to, its sub-modules and its background tasks. The `name` shows up as
+ * the type of the module's tasks in the trace.
+ *
+ * @example
+ * ```ts
+ * export const userModule = createModule<Events>("user", (m) => {
+ *   m.handle(getUser, fetchUser);
+ *   m.handle([bindHandler(sendMail, smtpSend)]);
+ *   m.use(authModule);
+ *
+ *   m.on(loginRequested, (user, ctx) => ctx.emit(userLoaded(user)));
+ *   m.spawn(async (_, ctx) => {
+ *     for (;;) await handleNext(await take(ctx, "job"));
+ *   });
+ * });
+ * ```
+ */
+export declare const createModule: <E extends EventMap = EventMap>(name: string, setup: (m: ModuleContext<E>) => void) => Module<E>;
+type Registry<E extends EventMap> = ReturnType<typeof createCommands<E>>;
+/** What `registerModules` returns. */
+type ModuleApi<E extends EventMap = EventMap> = {
+  /** The registry of command handlers of the bus: the one it was made with, or the app's own. */
+  commands: Registry<E>;
+  /** Mounts a module and returns the function that unmounts it; a module that is mounted already is not run again. */
+  mount(module: Module<E>): UnsubscribeCallback;
+  unmount(module: Module<E>): void;
+  isMounted(module: Module<E>): boolean;
+  /** Unmounts every module; a disposed app cannot mount modules. */
+  dispose(): void;
+};
+/**
+ * Assembles an app from modules on `bus`: mounts `modules` at once, in the
+ * order given, and returns `mount`, `unmount`, `isMounted` and `dispose` for
+ * the modules that come and go later. The bus runs the commands that the
+ * modules bind: if it was made with `commands: createCommands()` that registry
+ * is used, otherwise the app brings its own, as `app.commands`.
+ *
+ * A module is known by its `name`: mounting a module whose name is taken
+ * replaces the mounted one, which is unmounted first. That is what hot reload
+ * needs (see `docs/hmr.md`): the new version of a module file mounts again and
+ * the old version goes away with its subscriptions, commands and tasks.
+ *
+ * Unmounting undoes everything the module did: its subscriptions, its bound
+ * commands, its sub-modules and its background tasks. `dispose` unmounts them
+ * all, and a disposed app cannot mount modules.
+ *
+ * @example
+ * ```ts
+ * const bus = createBus<Events>();
+ * const app = registerModules(bus, [userModule]);
+ *
+ * const unmount = app.mount(orderModule); // later, e.g. after a lazy import
+ * unmount(); // or app.unmount(orderModule)
+ *
+ * bus.emit(getUser, "1");
+ * app.commands.handle(getUser, fakeUser); // in a test
+ * app.dispose();
+ * ```
+ */
+export declare const registerModules: <E extends EventMap>(bus: Bus<E>, modules?: readonly Module<E>[]) => ModuleApi<E>;
+//#endregion
+export { type ActionCreator, type Binding, type FreeActionCreator, type Module, type ModuleApi, type ModuleContext, createAction };

package/dist/notrace/actions.js

@@ -0,0 +1 @@
+import{i as e,n as t,s as n}from"./context-DGPIFXxI.js";import{t as r}from"./event-0RIBGYqS.js";function i(e,t){return Object.assign((...n)=>({type:e,payload:t?t(...n).payload:n[0]}),{type:e,match:t=>t.type===e,toString:()=>e})}var a=class extends Error{};const o=(e,n)=>Object.assign((r,i)=>{if(!n)throw new a(`No handler for command "${e}"`);return n(r,i??t({type:e,payload:r}).ctx)},{type:e}),s=(e,t)=>[e,t],c=(e=[])=>{let t=/* @__PURE__ */ new Map,n=(e,n)=>{let r={fn:n};return t.set(e,[...t.get(e)??[],r]),()=>{let n=(t.get(e)??[]).filter(e=>e!==r);n.length>0?t.set(e,n):t.delete(e)}};function i(e,t){if(t)return n(r(e),t);let i=e.map(([e,t])=>n(r(e),t));return()=>{for(let e of i)e()}}return i(e),{run:(e,n,r)=>{let i=(t.get(e.type)??[]).at(-1)?.fn,a=i&&e.wrap?e.wrap(i):i??e;return Reflect.apply(a,null,[n,r])},handle:i}},l=(e,t,n)=>{let r=e.emit;typeof t==`string`?r(t,n):typeof t==`function`?r(`match`in t?t.type:t,n):r({type:t.type,payload:n})},u=e=>{try{return Promise.resolve(e())}catch(e){if(e instanceof a)throw e;return Promise.reject(e)}},d=(e,t,n={})=>{let r=o(e,t),i=(e,t,r)=>{let i=r;return u(()=>Reflect.apply(e,null,[t,r])).then(e=>(n.done&&l(i,n.done,e),e),e=>{if(!n.fail)throw e;l(i,n.fail,e)})};return Object.assign((e,t)=>t?i(r,e,t):u(()=>r(e)),{type:e,wrap:e=>(t,n)=>i(e,t,n)})},f=(e,t)=>({name:e,setup:t}),p=(r,i=[])=>{let a=r.commands??c();r.commands??=a;let o={handle:(...e)=>{if(!a.handle)throw Error("registerModules: the `commands` of the bus is not a registry from `createCommands()`");return Reflect.apply(a.handle,null,e)}},s=t({type:`app`,payload:void 0},r,r.trace),l=t=>{let r=/* @__PURE__ */ new Map,i=/* @__PURE__ */ new Map;return{mount:a=>{let s=r.get(a);if(s)return s;let c=i.get(a.name);c&&r.get(c)?.();let u=e(t,a.name),d=u.ctx,f=l(d),p=()=>{r.delete(a),i.get(a.name)===a&&i.delete(a.name),d.abort(),u.unlink()};r.set(a,p),i.set(a.name,a);let m=(e,t)=>{let r=Reflect.apply(o.handle,null,[e,t]);return n(d,r),r},h=(...e)=>{let t=e.map(f.mount);return()=>{for(let e of t)e()}},g=(e,...t)=>{d.run(e,...t).catch(e=>{if(!d.signal.aborted)throw e})};try{a.setup(Object.assign(d,{handle:m,use:h,spawn:g}))}catch(e){throw p(),e}return p},unmount:e=>r.get(e)?.(),isMounted:e=>r.has(e)}},u=l(s.ctx);for(let e of i)u.mount(e);return{commands:a,mount:e=>(s.ctx.signal.throwIfAborted(),u.mount(e)),unmount:u.unmount,isMounted:u.isMounted,dispose:()=>s.ctx.abort()}};export{s as bindHandler,i as createAction,o as createCommand,c as createCommands,d as createJob,f as createModule,p as registerModules};

package/dist/notrace/bus-CFxgpsRL.js

@@ -0,0 +1 @@
+import{a as e,c as t,n,r}from"./context-DGPIFXxI.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(a,m,s.trace,{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(f,m,s.trace,{ref:r()}),a=m.commands?.run??l;return e(i,`command`,()=>a(t,d,i))}},commands:s.commands,context:s.context,trace:s.trace};return m};export{s as n,u as t};

package/dist/notrace/context-DGPIFXxI.js

@@ -0,0 +1 @@
+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))}};let o;const s=()=>o,c=()=>{},l=(e,t,n,r)=>{},u=(e,t)=>c,d=(e,t,n)=>n(),f=(e,t)=>typeof e==`function`?e(t):e,p=e=>e,m=(e,t,n,r)=>{let{controller:s,unlink:l}=a(r?.signal),{signal:u}=s,h=(...e)=>{if(u.aborted)return;let n=t?.emit,r=o;o=void 0;try{return n?.(...e)}finally{o=r}},g=(...e)=>{if(u.aborted)return c;let n=t?.on,r=n?.(...e);if(!r)return c;let a=i({signal:u},r);return()=>{a(),r()}},_=async(r,...i)=>{u.throwIfAborted();let a=i[0],o=m({type:e.type,payload:a},t,n,{signal:u,ref:void 0});try{return await d(o.ctx,`run`,()=>r(a,o.ctx))}finally{o.unlink()}};return{ctx:p({...f(t?.context,e),type:e.type,payload:e.payload,signal:u,abort:e=>s.abort(e),emit:h,on:g,off:t?.off??c,run:_}),unlink:l}},h=(e,t)=>m({type:t??e.type??``,payload:e.payload},{emit:e.emit,on:e.on,off:e.off,context:e},void 0,{signal:e.signal,ref:void 0});export{d as a,e as c,h as i,m as n,l as o,s as r,i as s,u as t};

package/dist/notrace/delay-Cko_Q9hl.js

@@ -0,0 +1 @@
+import{s as e}from"./context-DGPIFXxI.js";const t=2**31-1,n=(e,n)=>{let r={id:null};if(n===1/0)return r;let i=n=>{r.id=setTimeout(()=>{n>t?i(n-t):(r.id=null,e())},Math.min(n,t))};return i(n>0?n:0),r},r=e=>{e.id!==null&&(clearTimeout(e.id),e.id=null)},i=(t,i)=>new Promise((a,o)=>{let s=n(()=>{c(),a()},typeof i==`function`?i():i),c=e(t,e=>{r(s),o(e)})});export{r as n,n as r,i as t};

package/dist/notrace/effects.d.ts

@@ -0,0 +1,244 @@
+import { A as Keys, k as EventMap, u as Context } from "./action-BM-UdmJr.js";
+//#region src/utils/delay.d.ts
+/**
+ * Resolves after `ms`, or rejects early if `ctx.signal` aborts. `ms` can be a
+ * function that returns the number of ms, called once when the delay starts:
+ * handy for a random pause (jitter).
+ *
+ * @example
+ * ```ts
+ * await delay({}, 500);
+ *
+ * // 200 to 400 ms
+ * await delay({}, () => 200 + Math.random() * 200);
+ *
+ * // inside a task: stops waiting when the task is aborted
+ * bus.on("retry", async (_, ctx) => {
+ *   await delay(ctx, 1000);
+ *   await load();
+ * });
+ * ```
+ */
+export declare const delay: (ctx: {
+  signal?: AbortSignal | undefined;
+}, ms: number | (() => number)) => Promise<void>;
+//#endregion
+//#region src/utils/onAbort.d.ts
+export declare const onAbort: (ctx: {
+  signal?: AbortSignal | undefined;
+}, fn: (reason: unknown) => void) => (() => void);
+//#endregion
+//#region src/effects/run.d.ts
+/** Context passed into `race` / `all` effect starters. */
+type EffectContext = {
+  signal: AbortSignal;
+  abort: (reason?: unknown) => void;
+};
+type Starter<T> = (ctx: EffectContext) => T | PromiseLike<T>;
+//#endregion
+//#region src/effects/all.d.ts
+/**
+ * Runs all starters; waits for every result. On failure or parent abort, cancels the rest.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const { user, posts } = await all(ctx, {
+ *     user: ({ signal }) => fetchUser(id, { signal }),
+ *     posts: ({ signal }) => fetchPosts(id, { signal }),
+ *   });
+ *
+ *   // arrays work too: const [user, posts] = await all(ctx, [getUser, getPosts]);
+ * });
+ * ```
+ */
+export declare function all<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+export declare function all<const T extends readonly Starter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]: Awaited<ReturnType<T[K]>>; }>;
+//#endregion
+//#region src/effects/allSettled.d.ts
+/**
+ * Runs all starters and waits for every one to settle, whether it succeeds or
+ * fails: nothing is cancelled when a starter fails. The result has, for each
+ * starter, `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`.
+ * Only an abort of `ctx` rejects it, with the abort reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const { user, posts } = await allSettled(ctx, {
+ *     user: ({ signal }) => fetchUser(id, { signal }),
+ *     posts: ({ signal }) => fetchPosts(id, { signal }),
+ *   });
+ *
+ *   if (user.status === "fulfilled") render(user.value);
+ * });
+ * ```
+ */
+export declare function allSettled<T extends Record<string, Starter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+export declare function allSettled<const T extends readonly Starter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>>; }>;
+//#endregion
+//#region src/effects/cancellable.d.ts
+type CancellableHandle<T> = {
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+  /** Registers a cleanup that runs if the promise is cancelled before it settles. */
+  onCancel: (cleanup: () => void) => void;
+};
+type CancellableExecutor<T> = (handle: CancellableHandle<T>) => void;
+/**
+ * A promise tied to `ctx.signal`. It works like `new Promise`, but the
+ * executor gets one object, `{ resolve, reject, onCancel }`. If the signal
+ * aborts before the promise settles, the cleanups run (last registered first)
+ * and the promise rejects with the abort reason. If the signal is already
+ * aborted, the executor does not run. After the promise settles, the abort
+ * listener is removed and the cleanups are dropped.
+ *
+ * @example
+ * ```ts
+ * bus.on(
+ *   "wait",
+ *   latest((_, ctx) =>
+ *     cancellable(ctx, ({ resolve, onCancel }) => {
+ *       const timer = setTimeout(resolve, 5000);
+ *       onCancel(() => clearTimeout(timer));
+ *     }),
+ *   ),
+ * );
+ * ```
+ */
+export declare const cancellable: <T = void>(ctx: {
+  signal: AbortSignal;
+}, executor: CancellableExecutor<T>) => Promise<T>;
+//#endregion
+//#region src/effects/poll.d.ts
+type PollOptions = {
+  /** Also call `fn` at once, not only after the first `ms`. Default `false`. */
+  leading?: boolean;
+  /**
+   * Start the pause after a call finishes, so calls never overlap. By default
+   * the calls come every `ms` whatever the duration of `fn`.
+   */
+  waitForFn?: boolean;
+};
+/**
+ * Calls `fn` every `ms`, like patronum `interval`: the first call comes after
+ * `ms` (with `leading` also at once), and the next ticks keep a steady rate
+ * whatever the duration of `fn`, so a slow `fn` may overlap with the next call
+ * (`waitForFn` starts each pause when the call ends instead). `fn` gets the
+ * number of the call, starting at 0.
+ *
+ * `ms` can be a function of the number of the call that the pause leads to, for
+ * a growing or random pause: `(call) => Math.min(1000 * 2 ** call, 60_000)`.
+ *
+ * It stops when `ctx` aborts: the result then resolves, it does not reject, and
+ * the pending timer is cleared. If a call throws, polling stops and the result
+ * rejects.
+ *
+ * @example
+ * ```ts
+ * bus.on("watch", async (_, ctx) => {
+ *   await poll(ctx, () => refresh(), 5000);
+ *   cleanup(); // the task was aborted
+ * });
+ * ```
+ */
+export declare const poll: (ctx: {
+  signal: AbortSignal;
+}, fn: (tick: number) => unknown, ms: number | ((call: number) => number), options?: PollOptions) => Promise<void>;
+//#endregion
+//#region src/effects/race.d.ts
+type RaceStarter<T> = Starter<T>;
+/**
+ * Runs all starters; first to settle wins, losers are cancelled via `ctx.abort`.
+ * The result holds only the winner's value, under its key or index.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const result = await race(ctx, {
+ *     data: ({ signal }) => fetchData(id, { signal }),
+ *     timeout: ({ signal }) => delay({ signal }, 5000),
+ *   });
+ *
+ *   if ("timeout" in result) throw new Error("timed out");
+ *   render(result.data);
+ * });
+ * ```
+ */
+export declare function race<T extends Record<string, RaceStarter<unknown>>>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+export declare function race<const T extends readonly RaceStarter<unknown>[]>(ctx: {
+  signal?: AbortSignal;
+}, effects: T): Promise<{ -readonly [K in keyof T]?: Awaited<ReturnType<T[K]>>; }>;
+//#endregion
+//#region src/effects/retry.d.ts
+type RetryOptions = {
+  /** Total number of attempts, the first one included. Default 3. */
+  times?: number;
+  /**
+   * Pause before the next attempt, in ms: a number, or a function of the
+   * number of the attempt that just failed and its error. Default 0.
+   */
+  delay?: number | ((attempt: number, error: unknown) => number);
+  /** Return `false` to stop retrying and throw `error`. Default: always retry. */
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+export declare const retry: <T>(ctx: {
+  signal?: AbortSignal;
+}, fn: (attempt: number) => T | PromiseLike<T>, options?: RetryOptions) => Promise<T>;
+//#endregion
+//#region src/effects/take.d.ts
+type TakeOptions<P> = {
+  /** Wait for the first payload this accepts; others are skipped. */
+  predicate?: (payload: P) => boolean;
+  /** Stop waiting when this aborts, e.g. the signal of a `race` starter. */
+  signal?: AbortSignal | undefined;
+};
+/**
+ * Waits for the next `event` on the bus and resolves with its payload. It sees
+ * only events emitted after the call, takes only one, and unsubscribes when it
+ * is done. If `ctx` (or `options.signal`) aborts first, it unsubscribes and
+ * rejects with the abort reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("login", async (user, ctx) => {
+ *   const reason = await take(ctx, "logout");
+ *   cleanup(user, reason);
+ * });
+ *
+ * // wait for a matching event, but not longer than 5 s
+ * const done = await timeout(ctx, 5000, ({ signal }) =>
+ *   take(ctx, "saved", { signal, predicate: (id) => id === draftId }),
+ * );
+ * ```
+ */
+export declare const take: <E extends EventMap, K extends Keys<E>>(ctx: Context<E>, event: K, options?: TakeOptions<E[K]>) => Promise<E[K]>;
+//#endregion
+//#region src/effects/timeout.d.ts
+/**
+ * Runs `starter`; if it takes longer than `ms`, aborts its signal and rejects
+ * with a `TimeoutError` (a `DOMException`, like `AbortSignal.timeout`), even
+ * if the starter ignores the signal. If `ctx` aborts, rejects with its reason.
+ *
+ * @example
+ * ```ts
+ * bus.on("load", async (id, ctx) => {
+ *   const data = await timeout(ctx, 5000, ({ signal }) => fetchData(id, { signal }));
+ * });
+ * ```
+ */
+export declare const timeout: <T>(ctx: {
+  signal?: AbortSignal;
+}, ms: number, starter: Starter<T>) => Promise<T>;
+//#endregion
+export type { CancellableExecutor, CancellableHandle, EffectContext, PollOptions, RaceStarter, RetryOptions, TakeOptions };

package/dist/notrace/effects.js

@@ -0,0 +1 @@
+import{a as e,c as t,i as n,o as r,s as i,t as a}from"./context-DGPIFXxI.js";import{n as o,r as s,t as c}from"./delay-Cko_Q9hl.js";const l=(e,t)=>t?.signal?new Promise((n,r)=>{let a=i(t,r);e.then(n,r).finally(a)}):e,u=e=>Array.isArray(e)?Array(e.length):{},d=(t,o,s)=>{s?.signal?.throwIfAborted();let c=n(s??{}),u=a(c.ctx,o);return r(c.ctx,o,`start`),i(c.ctx,()=>u(`cancel`)),{tasks:Object.entries(t).map(([t,r])=>{let i=n(c.ctx),a={signal:i.ctx.signal,abort:i.ctx.abort};return[t,new Promise(t=>t(e(i.ctx,`run`,()=>r(a)))).finally(i.unlink)]}),cancelAll:()=>c.ctx.abort(),unfollowParent:c.unlink,settle:u,until:e=>l(e,s)}};async function f(e,t){let n=d(t,`all`,e);try{let e=await n.until(Promise.all(n.tasks.map(([,e])=>e))),r=u(t);for(let[t,[i]]of n.tasks.entries())r[i]=e[t];return n.settle(`done`),r}catch(e){throw n.settle(`error`,e),n.cancelAll(),e}finally{n.unfollowParent()}}const p=e=>e.then(e=>({status:`fulfilled`,value:e}),e=>({status:`rejected`,reason:e}));async function m(e,t){let n=d(t,`allSettled`,e);try{let e=await n.until(Promise.all(n.tasks.map(([,e])=>p(e)))),r=u(t);for(let[t,[i]]of n.tasks.entries())r[i]=e[t];return n.settle(`done`),r}catch(e){throw n.settle(`error`,e),n.cancelAll(),e}finally{n.unfollowParent()}}const h=(e,n)=>e.signal.aborted?Promise.reject(e.signal.reason):new Promise((r,a)=>{let o=[],s=`pending`,c=e=>{try{e()}catch(e){t(`cancel cleanup failed`,e)}},l=i(e,e=>{s=`cancelled`;for(let e of o.reverse())c(e);a(e)}),u=e=>(...t)=>{s===`pending`&&(s=`settled`,l(),o.length=0,e(...t))},d=e=>{s===`pending`?o.push(e):s===`cancelled`&&c(e)};try{n({resolve:u(r),reject:u(a),onCancel:d})}catch(e){u(a)(e)}}),g=async(e,t,o)=>{t?.signal?.throwIfAborted();let{ctx:s,unlink:c}=n(t??{}),u=a(s,e);r(s,e,`start`),i(s,()=>u(`cancel`));try{let e=await l(o(s),t);return u(`done`),e}catch(e){throw u(`error`,e),e}finally{c()}},_=async(t,r)=>{let{ctx:i,unlink:a}=n(t);try{return await e(i,`run`,r)}finally{a()}},v=(e,t,n,r={})=>{if(e.signal.aborted)return Promise.resolve();let a=r.leading??!1,c=r.waitForFn??!1;return g(`poll`,e,e=>new Promise((r,l)=>{let u=0,d=null,f=()=>{d!==null&&(o(d),d=null)},p=e=>{try{d=s(m,typeof n==`function`?n(e):n)}catch(e){f(),l(e)}},m=()=>{d=null,c||p(u+1),h()},h=()=>{let n=u++;_(e,()=>t(n)).then(()=>{c&&!e.signal.aborted&&p(u)},e=>{f(),l(e)})};i(e,f),a?(h(),c||p(u)):p(0)})).catch(t=>{if(!e.signal.aborted)throw t})};async function y(e,t){let n=u(t);if(Object.keys(t).length===0)return n;let r=d(t,`race`,e);try{let[e,t]=await r.until(Promise.race(r.tasks.map(([e,t])=>t.then(t=>[e,t]))));return n[e]=t,r.settle(`done`),n}catch(e){throw r.settle(`error`,e),e}finally{r.unfollowParent(),r.cancelAll()}}const b=(e,t,n)=>typeof e==`function`?e(t,n):e,x=e=>({times:e.times??3,delay:e.delay??0,shouldRetry:e.shouldRetry??(()=>!0)}),S=(e,t,n={})=>g(`retry`,e,async e=>{let{times:r,delay:i,shouldRetry:a}=x(n);for(let n=1;;n++)try{return await _(e,()=>t(n))}catch(t){if(e.signal.throwIfAborted(),n>=r||!a(t,n))throw t;let o=b(i,n,t);o>0&&await c(e,o)}}),C=(e,t,n={})=>g(`take`,e,r=>new Promise((a,o)=>{let{predicate:s}=n,c=[],l=()=>{for(let e of c)e()},u=e=>{l(),o(e)};c.push(e.on(t,e=>{(!s||s(e))&&(l(),a(e))})),c.push(i(r,u)),c.push(i({signal:n.signal},u))})),w=(t,r,i)=>g(`timeout`,t,async t=>{let a=n(t),c=s(()=>a.ctx.abort(new DOMException(`Timed out after ${r}ms`,`TimeoutError`)),r);try{return await l(Promise.resolve(e(a.ctx,`run`,()=>i({signal:a.ctx.signal,abort:a.ctx.abort}))),a.ctx)}finally{o(c),a.unlink()}});export{f as all,m as allSettled,h as cancellable,c as delay,i as onAbort,v as poll,y as race,S as retry,C as take,w as timeout};

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

@@ -0,0 +1 @@
+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/index-CaxrMD1A.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/notrace/index.d.ts

@@ -0,0 +1,3 @@
+import { A as Keys, C as WithPayload, D as anyEventType, E as Tracer, F as TraceEvent, I as TraceLogger, L as UnsubscribeCallback, M as Phase, N as Task, O as EffectName, P as Trace, S as WithContext, T as createBus, _ as EventPayload, a as AnyEvent, b as Off, c as Command, d as ContextOf, f as ContextOption, g as EventLike, h as EventKey, i as Action, j as PayloadOf, k as EventMap, l as Commands, m as Emittable, o as Bus, p as Emit, s as BusOptions, u as Context, v as Handler, w as WithType, x as On, y as HandlerRef } from "./action-BM-UdmJr.js";
+import "./index-CaxrMD1A.js";
+export { type Action, type AnyEvent, type Bus, type BusOptions, type Command, type Commands, type Context, type ContextOf, type ContextOption, type EffectName, type Emit, type Emittable, type EventKey, type EventLike, type EventMap, type EventPayload, type Handler, type HandlerRef, type Keys, type Off, type On, type PayloadOf, type Phase, type Task, type Trace, type TraceEvent, type TraceLogger, type Tracer, type UnsubscribeCallback, type WithContext, type WithPayload, type WithType, anyEventType, createBus };

package/dist/notrace/index.js

@@ -0,0 +1 @@
+export{n as anyEventType,t as createBus}from"./bus-CFxgpsRL.js";

package/dist/notrace/policies.d.ts

@@ -0,0 +1,171 @@
+import { N as Task, k as EventMap } from "./action-BM-UdmJr.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/notrace/policies.js

@@ -0,0 +1 @@
+import{a as e,i as t,o as n,s as r,t as i}from"./context-DGPIFXxI.js";import{n as a,r as o,t as s}from"./delay-Cko_Q9hl.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={})=>{let n=t=>p(`latest`,(t,n,r)=>(r(),e(t,n)),t);return t.key?d(t.key,n):n(u)},p=(e,a,o=u)=>{let s=null;return(l,u)=>{if(s?.abort(),u.signal.aborted)return;let{ctx:d,unlink:f}=t(u);s=d;let p=i(d,e),m=!1,h=()=>{d.signal.aborted||(m=!0,n(d,e,`start`))};r(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}}},m=(e,t,n={})=>{let r=r=>g(e,t,n,r);return n.key?d(n.key,r):r(u)},h=(t,r,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>=t||p-l<0;return l=p,d!==null&&a(d),d=c?o(s,t):null,i&&m?Promise.resolve(e(f,`debounce`,()=>r(u,f))):(n(f,`debounce`,`drop`),Promise.resolve(void 0))}},g=(t,n,i,a)=>{let o=i.leading??!1,c=i.trailing??!0;if(!c)return h(t,n,o,a);let l=!1,u=0,d=p(`debounce`,([e,i],a,o)=>{let d=u;return r(a,()=>{u===d&&(l=!1)}),s(a,t).then(()=>{if(l=!1,c&&!i)return o(),n(e,a)})},a);return(t,r)=>{if(r.signal.aborted)return;let i=o&&!l;l=!0,u++;let a=d([t,i],r);return i?Promise.resolve(e(r,`debounce`,()=>n(t,r))):a}},_=(t,i={})=>{let a=i=>{let a=null;return(o,s)=>{if(s.signal.aborted)return;if(a){n(s,`leading`,`drop`);return}let c={};a=c;let u=()=>{d(),a===c&&(a=null,i())},d=r(s,u);try{return l(e(s,`leading`,()=>t(o,s)),u)}catch(e){throw u(),e}}};return i.key?d(i.key,a):a(u)},v=(e,t={})=>{let n=n=>y(e,t,n);return t.key?d(t.key,n):n(u)},y=(t,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(),n(p,`queue`,`drop`),m(void 0)},v=()=>{if(g(),p.signal.aborted){_();return}l++;let n=!0,i=()=>{n&&(n=!1,l--,d(),l===0&&c.length===0&&a())},o=r(p,()=>{i(),m(void 0)}),s;try{s=Promise.resolve(e(p,`queue`,()=>t(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=r(p,()=>{let e=c.indexOf(y);e>=0&&c.splice(e,1),_()})})},b=(e,t,n={})=>{let r=r=>x(e,t,n,r);return n.key?d(n.key,r):r(u)},x=(t,r,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=e=>f===null||e-f>=t||e-f<0||e-p>=t,y=e=>n(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=(t,n,i)=>{b(),p=i,_=!0;try{return e(n,`throttle`,()=>r(t,n))}finally{_=!1}},C=()=>{d&&(h=o(w,t))},w=()=>{if(h=null,!d||m!==null||g)return;let e=Date.now(),n=Math.max(t-(e-(f??-1/0)),t-(e-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 e=Date.now();v(e)?T(e):m=o(E,Math.min(t-(e-(f??e)),t-(e-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=(e,n,r,i)=>i&&m!==null?(a(m),m=o(E,t),S(e,n,r)):m===null&&(m=o(E,t),i&&(p=r,c))?S(e,n,r):O(e,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{m as debounce,f as latest,_ as leading,v as queue,b as throttle};