@ayepi/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @ayepi/core
+
+zod-first, painfully-typed HTTP + WebSocket API library with OpenAPI 3.1 +
+AsyncAPI 3.0 generation. Define endpoints and events once with zod schemas and
+get a typed server, a typed client, wire docs, and a zod-free runtime manifest.
+
+```sh
+pnpm add @ayepi/core zod
+```
+
+```ts
+import { spec, endpoint, server, client } from '@ayepi/core'
+import { client } from '@ayepi/core/client' // zod-free browser entry
+```
+
+`zod` is a **peer dependency** (`^4`). The `@ayepi/core/client` entry contains
+zero zod runtime code.
+
+Runtime adapters: [`@ayepi/node`](https://www.npmjs.com/package/@ayepi/node),
+[`@ayepi/bun`](https://www.npmjs.com/package/@ayepi/bun),
+[`@ayepi/deno`](https://www.npmjs.com/package/@ayepi/deno). The core is
+fetch-native, so it also runs directly on Cloudflare Workers and edge runtimes by
+passing `app.fetch`.
+
+See the [full documentation and feature tour](https://github.com/pdiffenderfer/ayepi#readme).
+
+## `@ayepi/core/doer`
+
+A small, runtime-agnostic **concurrency + scheduling** primitive (`available()` /
+`do(task, opts)` / `done()`) with bundled policies — `unlimitedDoer`, `balancedDoer`,
+`priorityDoer`, `ageDoer`. It has no dependency on the rest of core; [`@ayepi/work`](https://www.npmjs.com/package/@ayepi/work)
+drives one to govern job execution, and [`@ayepi/rate`](https://www.npmjs.com/package/@ayepi/rate)
+adds a `rateLimitedDoer`.
+
+```ts
+import { priorityDoer } from '@ayepi/core/doer'
+```
+
+## `@ayepi/core/retry`
+
+A general retry helper — run an operation with exponential backoff + jitter, hooks
+(`onSuccess`/`onRetry`/`onError`), an `errorResult` escape hatch, and a live
+`RetryState`. Set fleet-wide defaults with `setDefaultRetryOptions`. `@ayepi/work` uses
+its `RetryOptions` for every work type's retry policy.
+
+```ts
+import { retry, setDefaultRetryOptions } from '@ayepi/core'
+
+setDefaultRetryOptions({ attempts: 5 })
+const data = await retry((state) => fetchJson(url), { base: 200 })
+```
+
+## `@ayepi/core/stats`
+
+A tiny, dependency-free metrics primitive — typed, **labelled** measurements you hand to
+whatever you already run (a periodic log, StatsD, Prometheus). Three kinds: **counter**
+(`inc`), **gauge** (`set`/`add`/`max`), and **summary** (`observe` → count/total/min/max/avg,
+plus histogram buckets + approximate quantiles when configured). `createMetrics()` is the
+registry: `list()`/`get()` snapshots, a **coalesced** `subscribe()` for change notifications,
+and `formatPrometheus()` to render the text exposition. `@ayepi/work` records its per-type job
+stats into one of these.
+
+```ts
+import { createMetrics, formatPrometheus } from '@ayepi/core'
+
+const m = createMetrics({ quantiles: [0.5, 0.95, 0.99] })
+m.counter('jobs_done', { type: 'email' }).inc()
+m.summary('job_ms', { type: 'email' }, { unit: 'ms' }).observe(42)
+
+setInterval(() => console.log(formatPrometheus(m.list())), 15_000) // scrape/log loop
+m.subscribe((changed) => pushToStatsd(changed))                    // or push on change (batched)
+```
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-core-client.md`](./ayepi-core-client.md)
+- [`ayepi-core-endpoints.md`](./ayepi-core-endpoints.md)
+- [`ayepi-core-middleware.md`](./ayepi-core-middleware.md)
+- [`ayepi-core-types.md`](./ayepi-core-types.md)
+- [`ayepi-core.md`](./ayepi-core.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/core) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/client/index.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_ws_transport = require("../ws-transport.cjs");
+exports.ApiError = require_ws_transport.ApiError;
+exports.client = require_ws_transport.client;
+exports.wsTransport = require_ws_transport.wsTransport;

package/dist/client/index.d.cts

@@ -0,0 +1,2 @@
+import { F as AnySpec, Ft as CallArgs, It as CallOpts, Rt as CallReturn, a as WebSocketCtor, an as HttpMethod, c as WsState, cn as ManifestEvent, d as wsTransport, f as ApiClient, g as client, h as GetUrlKeys, i as HeartbeatOptions, l as WsTransport, m as ClientWs, o as WebSocketLike, on as Manifest, p as ClientOptions, r as BackoffOptions, s as WsMessageEvent, sn as ManifestEndpoint, t as ApiError, u as WsTransportOptions, zt as ClientData } from "../errors.cjs";
+export { type AnySpec, type ApiClient, ApiError, type BackoffOptions, type CallArgs, type CallOpts, type CallReturn, type ClientData, type ClientOptions, type ClientWs, type GetUrlKeys, type HeartbeatOptions, type HttpMethod, type Manifest, type ManifestEndpoint, type ManifestEvent, type WebSocketCtor, type WebSocketLike, type WsMessageEvent, type WsState, type WsTransport, type WsTransportOptions, client, wsTransport };

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+import { F as AnySpec, Ft as CallArgs, It as CallOpts, Rt as CallReturn, a as WebSocketCtor, an as HttpMethod, c as WsState, cn as ManifestEvent, d as wsTransport, f as ApiClient, g as client, h as GetUrlKeys, i as HeartbeatOptions, l as WsTransport, m as ClientWs, o as WebSocketLike, on as Manifest, p as ClientOptions, r as BackoffOptions, s as WsMessageEvent, sn as ManifestEndpoint, t as ApiError, u as WsTransportOptions, zt as ClientData } from "../errors.js";
+export { type AnySpec, type ApiClient, ApiError, type BackoffOptions, type CallArgs, type CallOpts, type CallReturn, type ClientData, type ClientOptions, type ClientWs, type GetUrlKeys, type HeartbeatOptions, type HttpMethod, type Manifest, type ManifestEndpoint, type ManifestEvent, type WebSocketCtor, type WebSocketLike, type WsMessageEvent, type WsState, type WsTransport, type WsTransportOptions, client, wsTransport };

package/dist/client/index.js

@@ -0,0 +1,2 @@
+import { n as client, s as ApiError, t as wsTransport } from "../ws-transport.js";
+export { ApiError, client, wsTransport };

package/dist/doer.cjs

@@ -0,0 +1,110 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/doer.ts
+/** Default pull batch for {@link unlimitedDoer} — bounds how much one tick admits. */
+const DEFAULT_UNLIMITED_AVAILABLE = 256;
+/**
+* Run every task immediately with **no concurrency cap**. `available()` reports a fixed
+* batch so one tick doesn't admit an unbounded burst at once.
+*/
+function unlimitedDoer(opts = {}) {
+	const available = opts.available ?? DEFAULT_UNLIMITED_AVAILABLE;
+	let running = 0;
+	const idle = [];
+	const settle = () => {
+		if (running === 0) for (const r of idle.splice(0)) r();
+	};
+	return {
+		available: () => available,
+		do(task) {
+			running++;
+			Promise.resolve().then(task).catch(() => {}).finally(() => {
+				running--;
+				settle();
+			});
+		},
+		done: () => running === 0 ? Promise.resolve() : new Promise((r) => idle.push(r))
+	};
+}
+function boundedDoer(pick, opts) {
+	const max = opts.max;
+	const buffer = opts.buffer ?? opts.max;
+	const now = opts.now ?? Date.now;
+	const pending = [];
+	const runningByGroup = /* @__PURE__ */ new Map();
+	const idle = [];
+	let running = 0;
+	let seq = 0;
+	const held = () => running + pending.length;
+	const bump = (group, by) => void runningByGroup.set(group, (runningByGroup.get(group) ?? 0) + by);
+	const drain = () => {
+		while (running < max && pending.length > 0) {
+			const idx = pick(pending, runningByGroup);
+			const [task] = pending.splice(idx, 1);
+			running++;
+			bump(task.group, 1);
+			Promise.resolve().then(task.run).catch(() => {}).finally(() => {
+				running--;
+				bump(task.group, -1);
+				drain();
+				if (held() === 0) for (const r of idle.splice(0)) r();
+			});
+		}
+	};
+	return {
+		available: () => Math.max(0, max + buffer - held()),
+		do(task, o) {
+			pending.push({
+				run: task,
+				group: o?.group ?? "",
+				priority: o?.priority ?? 0,
+				createdAt: o?.createdAt ?? now(),
+				seq: seq++
+			});
+			drain();
+		},
+		done: () => held() === 0 ? Promise.resolve() : new Promise((r) => idle.push(r))
+	};
+}
+/** Pick the lowest pending task per a comparator (`better(a, b)` ⇒ `a` runs before `b`). */
+const argmin = (pending, better) => {
+	let best = 0;
+	for (let i = 1; i < pending.length; i++) if (better(pending[i], pending[best])) best = i;
+	return best;
+};
+/**
+* Cap `max`; when a slot frees, give it to the group with the fewest currently-running
+* tasks (fair share), breaking ties by higher priority, then older `createdAt`.
+*/
+function balancedDoer(opts) {
+	const pick = (pending, rbg) => argmin(pending, (a, b) => {
+		const ga = rbg.get(a.group) ?? 0;
+		const gb = rbg.get(b.group) ?? 0;
+		if (ga !== gb) return ga < gb;
+		if (a.priority !== b.priority) return a.priority > b.priority;
+		if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt;
+		return a.seq < b.seq;
+	});
+	return boundedDoer(pick, opts);
+}
+/** Cap `max`; run the highest-priority pending task next, breaking ties by older `createdAt`. */
+function priorityDoer(opts) {
+	const pick = (pending) => argmin(pending, (a, b) => {
+		if (a.priority !== b.priority) return a.priority > b.priority;
+		if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt;
+		return a.seq < b.seq;
+	});
+	return boundedDoer(pick, opts);
+}
+/** Cap `max`; run the oldest pending task next (by `createdAt`). */
+function ageDoer(opts) {
+	const pick = (pending) => argmin(pending, (a, b) => {
+		if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt;
+		return a.seq < b.seq;
+	});
+	return boundedDoer(pick, opts);
+}
+//#endregion
+exports.ageDoer = ageDoer;
+exports.balancedDoer = balancedDoer;
+exports.priorityDoer = priorityDoer;
+exports.unlimitedDoer = unlimitedDoer;

package/dist/doer.d.cts

@@ -0,0 +1,75 @@
+//#region src/doer.d.ts
+/**
+ * # Doers — concurrency + scheduling policy
+ *
+ * A **doer** decides *how many* tasks to admit and *which* to run next. A caller asks
+ * {@link Doer.available} how many tasks it may submit right now, then hands each to
+ * {@link Doer.do}; the doer runs up to its policy's cap and, when a slot frees, picks
+ * the next pending task. {@link Doer.done} resolves when everything it holds has
+ * settled. This is a runtime-agnostic primitive — `@ayepi/work` drives one to govern
+ * job execution, but it has no dependency on work and can throttle anything.
+ *
+ * Bundled policies:
+ * - {@link unlimitedDoer} — run everything immediately, no cap.
+ * - {@link balancedDoer} — cap N; share slots fairly across groups, then priority, then age.
+ * - {@link priorityDoer} — cap N; highest priority first, then age.
+ * - {@link ageDoer} — cap N; oldest (by `createdAt`) first.
+ *
+ * A rate-limiting doer (start-rate cap), `rateLimitedDoer`, lives in `@ayepi/rate`,
+ * built on this interface and that package's limiter primitives.
+ *
+ * @module
+ */
+/** Per-task hints used by a {@link Doer} to order pending work. */
+interface DoerTaskOptions {
+  /** Fairness group — `balancedDoer` spreads slots evenly across distinct groups. */
+  readonly group?: string;
+  /** Higher runs first (default 0). */
+  readonly priority?: number;
+  /** Creation time (epoch ms) — older runs first on ties (default: now). */
+  readonly createdAt?: number;
+}
+/**
+ * Runs tasks under a concurrency + ordering policy.
+ *
+ * A driver loop uses it like: `available()` → how many to submit now; `do(task, opts)`
+ * → accept a task; `done()` → resolve when all accepted tasks have settled.
+ */
+interface Doer {
+  /** How many more tasks this doer will accept right now (a driver submits up to this many). */
+  available(): number;
+  /** Accept a task to run (now or when a slot frees, per policy). Never rejects. */
+  do(task: () => Promise<void>, opts?: DoerTaskOptions): void;
+  /** Resolve once every accepted task (running + pending) has settled. */
+  done(): Promise<void>;
+}
+/** Options for {@link unlimitedDoer}. */
+interface UnlimitedDoerOptions {
+  /** Max tasks to admit per tick (default 256). Concurrency itself is unbounded. */
+  readonly available?: number;
+}
+/**
+ * Run every task immediately with **no concurrency cap**. `available()` reports a fixed
+ * batch so one tick doesn't admit an unbounded burst at once.
+ */
+declare function unlimitedDoer(opts?: UnlimitedDoerOptions): Doer;
+/** Options shared by the bounded doers. */
+interface BoundedDoerOptions {
+  /** Max concurrently running. */
+  readonly max: number;
+  /** Extra pending tasks to buffer for selection (default `max`). Total held ≤ `max + buffer`. */
+  readonly buffer?: number;
+  /** Clock for the default `createdAt` (default `Date.now`). */
+  readonly now?: () => number;
+}
+/**
+ * Cap `max`; when a slot frees, give it to the group with the fewest currently-running
+ * tasks (fair share), breaking ties by higher priority, then older `createdAt`.
+ */
+declare function balancedDoer(opts: BoundedDoerOptions): Doer;
+/** Cap `max`; run the highest-priority pending task next, breaking ties by older `createdAt`. */
+declare function priorityDoer(opts: BoundedDoerOptions): Doer;
+/** Cap `max`; run the oldest pending task next (by `createdAt`). */
+declare function ageDoer(opts: BoundedDoerOptions): Doer;
+//#endregion
+export { BoundedDoerOptions, Doer, DoerTaskOptions, UnlimitedDoerOptions, ageDoer, balancedDoer, priorityDoer, unlimitedDoer };

package/dist/doer.d.ts

@@ -0,0 +1,75 @@
+//#region src/doer.d.ts
+/**
+ * # Doers — concurrency + scheduling policy
+ *
+ * A **doer** decides *how many* tasks to admit and *which* to run next. A caller asks
+ * {@link Doer.available} how many tasks it may submit right now, then hands each to
+ * {@link Doer.do}; the doer runs up to its policy's cap and, when a slot frees, picks
+ * the next pending task. {@link Doer.done} resolves when everything it holds has
+ * settled. This is a runtime-agnostic primitive — `@ayepi/work` drives one to govern
+ * job execution, but it has no dependency on work and can throttle anything.
+ *
+ * Bundled policies:
+ * - {@link unlimitedDoer} — run everything immediately, no cap.
+ * - {@link balancedDoer} — cap N; share slots fairly across groups, then priority, then age.
+ * - {@link priorityDoer} — cap N; highest priority first, then age.
+ * - {@link ageDoer} — cap N; oldest (by `createdAt`) first.
+ *
+ * A rate-limiting doer (start-rate cap), `rateLimitedDoer`, lives in `@ayepi/rate`,
+ * built on this interface and that package's limiter primitives.
+ *
+ * @module
+ */
+/** Per-task hints used by a {@link Doer} to order pending work. */
+interface DoerTaskOptions {
+  /** Fairness group — `balancedDoer` spreads slots evenly across distinct groups. */
+  readonly group?: string;
+  /** Higher runs first (default 0). */
+  readonly priority?: number;
+  /** Creation time (epoch ms) — older runs first on ties (default: now). */
+  readonly createdAt?: number;
+}
+/**
+ * Runs tasks under a concurrency + ordering policy.
+ *
+ * A driver loop uses it like: `available()` → how many to submit now; `do(task, opts)`
+ * → accept a task; `done()` → resolve when all accepted tasks have settled.
+ */
+interface Doer {
+  /** How many more tasks this doer will accept right now (a driver submits up to this many). */
+  available(): number;
+  /** Accept a task to run (now or when a slot frees, per policy). Never rejects. */
+  do(task: () => Promise<void>, opts?: DoerTaskOptions): void;
+  /** Resolve once every accepted task (running + pending) has settled. */
+  done(): Promise<void>;
+}
+/** Options for {@link unlimitedDoer}. */
+interface UnlimitedDoerOptions {
+  /** Max tasks to admit per tick (default 256). Concurrency itself is unbounded. */
+  readonly available?: number;
+}
+/**
+ * Run every task immediately with **no concurrency cap**. `available()` reports a fixed
+ * batch so one tick doesn't admit an unbounded burst at once.
+ */
+declare function unlimitedDoer(opts?: UnlimitedDoerOptions): Doer;
+/** Options shared by the bounded doers. */
+interface BoundedDoerOptions {
+  /** Max concurrently running. */
+  readonly max: number;
+  /** Extra pending tasks to buffer for selection (default `max`). Total held ≤ `max + buffer`. */
+  readonly buffer?: number;
+  /** Clock for the default `createdAt` (default `Date.now`). */
+  readonly now?: () => number;
+}
+/**
+ * Cap `max`; when a slot frees, give it to the group with the fewest currently-running
+ * tasks (fair share), breaking ties by higher priority, then older `createdAt`.
+ */
+declare function balancedDoer(opts: BoundedDoerOptions): Doer;
+/** Cap `max`; run the highest-priority pending task next, breaking ties by older `createdAt`. */
+declare function priorityDoer(opts: BoundedDoerOptions): Doer;
+/** Cap `max`; run the oldest pending task next (by `createdAt`). */
+declare function ageDoer(opts: BoundedDoerOptions): Doer;
+//#endregion
+export { BoundedDoerOptions, Doer, DoerTaskOptions, UnlimitedDoerOptions, ageDoer, balancedDoer, priorityDoer, unlimitedDoer };

package/dist/doer.js

@@ -0,0 +1,106 @@
+//#region src/doer.ts
+/** Default pull batch for {@link unlimitedDoer} — bounds how much one tick admits. */
+const DEFAULT_UNLIMITED_AVAILABLE = 256;
+/**
+* Run every task immediately with **no concurrency cap**. `available()` reports a fixed
+* batch so one tick doesn't admit an unbounded burst at once.
+*/
+function unlimitedDoer(opts = {}) {
+	const available = opts.available ?? DEFAULT_UNLIMITED_AVAILABLE;
+	let running = 0;
+	const idle = [];
+	const settle = () => {
+		if (running === 0) for (const r of idle.splice(0)) r();
+	};
+	return {
+		available: () => available,
+		do(task) {
+			running++;
+			Promise.resolve().then(task).catch(() => {}).finally(() => {
+				running--;
+				settle();
+			});
+		},
+		done: () => running === 0 ? Promise.resolve() : new Promise((r) => idle.push(r))
+	};
+}
+function boundedDoer(pick, opts) {
+	const max = opts.max;
+	const buffer = opts.buffer ?? opts.max;
+	const now = opts.now ?? Date.now;
+	const pending = [];
+	const runningByGroup = /* @__PURE__ */ new Map();
+	const idle = [];
+	let running = 0;
+	let seq = 0;
+	const held = () => running + pending.length;
+	const bump = (group, by) => void runningByGroup.set(group, (runningByGroup.get(group) ?? 0) + by);
+	const drain = () => {
+		while (running < max && pending.length > 0) {
+			const idx = pick(pending, runningByGroup);
+			const [task] = pending.splice(idx, 1);
+			running++;
+			bump(task.group, 1);
+			Promise.resolve().then(task.run).catch(() => {}).finally(() => {
+				running--;
+				bump(task.group, -1);
+				drain();
+				if (held() === 0) for (const r of idle.splice(0)) r();
+			});
+		}
+	};
+	return {
+		available: () => Math.max(0, max + buffer - held()),
+		do(task, o) {
+			pending.push({
+				run: task,
+				group: o?.group ?? "",
+				priority: o?.priority ?? 0,
+				createdAt: o?.createdAt ?? now(),
+				seq: seq++
+			});
+			drain();
+		},
+		done: () => held() === 0 ? Promise.resolve() : new Promise((r) => idle.push(r))
+	};
+}
+/** Pick the lowest pending task per a comparator (`better(a, b)` ⇒ `a` runs before `b`). */
+const argmin = (pending, better) => {
+	let best = 0;
+	for (let i = 1; i < pending.length; i++) if (better(pending[i], pending[best])) best = i;
+	return best;
+};
+/**
+* Cap `max`; when a slot frees, give it to the group with the fewest currently-running
+* tasks (fair share), breaking ties by higher priority, then older `createdAt`.
+*/
+function balancedDoer(opts) {
+	const pick = (pending, rbg) => argmin(pending, (a, b) => {
+		const ga = rbg.get(a.group) ?? 0;
+		const gb = rbg.get(b.group) ?? 0;
+		if (ga !== gb) return ga < gb;
+		if (a.priority !== b.priority) return a.priority > b.priority;
+		if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt;
+		return a.seq < b.seq;
+	});
+	return boundedDoer(pick, opts);
+}
+/** Cap `max`; run the highest-priority pending task next, breaking ties by older `createdAt`. */
+function priorityDoer(opts) {
+	const pick = (pending) => argmin(pending, (a, b) => {
+		if (a.priority !== b.priority) return a.priority > b.priority;
+		if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt;
+		return a.seq < b.seq;
+	});
+	return boundedDoer(pick, opts);
+}
+/** Cap `max`; run the oldest pending task next (by `createdAt`). */
+function ageDoer(opts) {
+	const pick = (pending) => argmin(pending, (a, b) => {
+		if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt;
+		return a.seq < b.seq;
+	});
+	return boundedDoer(pick, opts);
+}
+//#endregion
+export { ageDoer, balancedDoer, priorityDoer, unlimitedDoer };