@ayepi/core 0.1.0

package/dist/retry.cjs

@@ -0,0 +1,135 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/retry.ts
+/**
+* Throw this from a {@link retry} operation to **stop retrying immediately**: the remaining
+* attempts (and their backoff) are skipped, `onError` fires once, and `retry` then re-throws the
+* abort's `cause` (or returns `errorResult` if one was configured). Use it for a permanent failure
+* a retry can't fix — a 4xx, a validation error, a missing resource.
+*
+* ```ts
+* await retry(async () => {
+*   const res = await fetch(url);
+*   if (res.status === 404) throw new RetryAbort(new Error('not found')); // don't retry a 404
+*   if (!res.ok) throw new Error(`http ${res.status}`);                   // transient → retried
+*   return res.json();
+* });
+* ```
+*/
+var RetryAbort = class extends Error {
+	constructor(cause, message = "retry aborted") {
+		super(message, { cause });
+		this.name = "RetryAbort";
+	}
+};
+/** The default {@link RetryOptions.on}: a {@link RetryAbort} stops the loop, anything else retries with the normal backoff. */
+const defaultOn = (err) => err instanceof RetryAbort ? false : 0;
+/** The built-in defaults — the floor under {@link setDefaultRetryOptions} and per-call options. */
+const DEFAULT_RETRY_OPTIONS = {
+	attempts: 3,
+	base: 1e3,
+	factor: 2,
+	max: 3e4,
+	jitter: .5
+};
+/** Process-wide overrides, applied between {@link DEFAULT_RETRY_OPTIONS} and per-call options. */
+let globalDefaults = {};
+/** Set process-wide default {@link RetryOptions} (merged over previous overrides). Per-call options still win. */
+function setDefaultRetryOptions(options) {
+	globalDefaults = {
+		...globalDefaults,
+		...options
+	};
+}
+/** The effective global defaults ({@link DEFAULT_RETRY_OPTIONS} plus any {@link setDefaultRetryOptions} overrides). */
+function getDefaultRetryOptions() {
+	return {
+		...DEFAULT_RETRY_OPTIONS,
+		...globalDefaults
+	};
+}
+const defaultSleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms).unref?.();
+});
+/**
+* Backoff delay for retry `attempt` (1 = the first retry):
+* `min(base · factor^(attempt-1), max) · (1 − jitter · random())`.
+*/
+function backoff(attempt, opts = {}, random = Math.random) {
+	const base = opts.base ?? DEFAULT_RETRY_OPTIONS.base;
+	const factor = opts.factor ?? DEFAULT_RETRY_OPTIONS.factor;
+	const max = opts.max ?? DEFAULT_RETRY_OPTIONS.max;
+	const jitter = opts.jitter ?? DEFAULT_RETRY_OPTIONS.jitter;
+	const raw = base * Math.pow(factor, Math.max(0, attempt - 1));
+	return Math.round(Math.min(raw, max) * (1 - jitter * random()));
+}
+/**
+* Run `fn`, retrying on rejection with exponential backoff + jitter up to `attempts`
+* times. Resolves with the first success; on exhaustion it returns `errorResult` if one
+* was provided, otherwise re-throws the last error.
+*/
+async function retry(fn, options = {}) {
+	const o = {
+		...DEFAULT_RETRY_OPTIONS,
+		...globalDefaults,
+		...options
+	};
+	const now = o.now ?? Date.now;
+	const random = o.random ?? Math.random;
+	const sleep = o.sleep ?? defaultSleep;
+	const decide = o.on ?? defaultOn;
+	const hasErrorResult = "errorResult" in options;
+	const startAt = now();
+	let lastError;
+	for (let attempt = 1; attempt <= o.attempts; attempt++) {
+		const lastAttemptAt = now();
+		const state = {
+			startAt,
+			attempt,
+			attempts: o.attempts,
+			lastAttemptAt,
+			lastError
+		};
+		try {
+			const result = await fn(state);
+			o.onSuccess?.(result, state);
+			return result;
+		} catch (err) {
+			const decision = await decide(err);
+			if (decision === false) {
+				const cause = err instanceof RetryAbort ? err.cause ?? err : err;
+				lastError = cause;
+				o.onError?.(cause, {
+					startAt,
+					attempt,
+					attempts: o.attempts,
+					lastAttemptAt,
+					lastError: cause
+				});
+				break;
+			}
+			lastError = err;
+			const failed = {
+				startAt,
+				attempt,
+				attempts: o.attempts,
+				lastAttemptAt,
+				lastError: err
+			};
+			if (attempt < o.attempts) {
+				o.onRetry?.(err, failed);
+				await sleep(Math.max(decision, backoff(attempt, o, random)));
+				continue;
+			}
+			o.onError?.(err, failed);
+		}
+	}
+	if (hasErrorResult) return options.errorResult;
+	throw lastError;
+}
+//#endregion
+exports.DEFAULT_RETRY_OPTIONS = DEFAULT_RETRY_OPTIONS;
+exports.RetryAbort = RetryAbort;
+exports.backoff = backoff;
+exports.getDefaultRetryOptions = getDefaultRetryOptions;
+exports.retry = retry;
+exports.setDefaultRetryOptions = setDefaultRetryOptions;

package/dist/retry.d.cts

@@ -0,0 +1,90 @@
+import { i as MaybePromise } from "./types.cjs";
+
+//#region src/retry.d.ts
+
+/**
+ * Throw this from a {@link retry} operation to **stop retrying immediately**: the remaining
+ * attempts (and their backoff) are skipped, `onError` fires once, and `retry` then re-throws the
+ * abort's `cause` (or returns `errorResult` if one was configured). Use it for a permanent failure
+ * a retry can't fix — a 4xx, a validation error, a missing resource.
+ *
+ * ```ts
+ * await retry(async () => {
+ *   const res = await fetch(url);
+ *   if (res.status === 404) throw new RetryAbort(new Error('not found')); // don't retry a 404
+ *   if (!res.ok) throw new Error(`http ${res.status}`);                   // transient → retried
+ *   return res.json();
+ * });
+ * ```
+ */
+declare class RetryAbort extends Error {
+  constructor(cause?: unknown, message?: string);
+}
+/** Live state passed to the operation and to the {@link RetryOptions} hooks. */
+interface RetryState {
+  /** When the first attempt started (epoch ms). */
+  readonly startAt: number;
+  /** Current attempt number (1-based). */
+  readonly attempt: number;
+  /** Total attempts allowed. */
+  readonly attempts: number;
+  /** When the current attempt started (epoch ms). */
+  readonly lastAttemptAt: number;
+  /** The most recent error (undefined before any failure). */
+  readonly lastError?: unknown;
+}
+/** Options for {@link retry}. Every numeric field has a default (see {@link DEFAULT_RETRY_OPTIONS}). */
+interface RetryOptions<R = unknown> {
+  /** Total attempts including the first (default 3). */
+  attempts?: number;
+  /** First-retry delay in ms (default 1000). */
+  base?: number;
+  /** Multiplier applied per attempt (default 2). */
+  factor?: number;
+  /** Delay cap in ms (default 30000). */
+  max?: number;
+  /** Jitter fraction in `[0,1]`: each delay is scaled down by up to this much (default 0.5). */
+  jitter?: number;
+  /** If every attempt fails, resolve with this value instead of throwing. */
+  errorResult?: R;
+  /**
+   * Decide what to do with a thrown error: return `false` to **stop** retrying (abort), or a number
+   * of **milliseconds to wait at least** before the next attempt — a floor under the normal backoff
+   * (e.g. honor a `Retry-After`; `0` = just use the backoff). May be async. Default:
+   * `(err) => (err instanceof RetryAbort ? false : 0)` — overriding it **replaces** that check
+   * (e.g. `on: (e) => (e.status === 404 ? false : 0)` aborts on a 404 with no `RetryAbort` wrapper).
+   * To keep retrying through a `RetryAbort`, override it (e.g. `on: () => 0`).
+   */
+  on?: (err: unknown) => MaybePromise<number | false>;
+  /** Called after a successful attempt. */
+  onSuccess?: (result: R, state: RetryState) => void;
+  /** Called after a failed attempt that will be retried, before backing off. */
+  onRetry?: (error: unknown, state: RetryState) => void;
+  /** Called when all attempts are exhausted, before throwing or returning `errorResult`. */
+  onError?: (error: unknown, state: RetryState) => void;
+  /** Sleep implementation (ms) — injectable for tests (default an unref'd timer). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Randomness for jitter (default `Math.random`). */
+  random?: () => number;
+  /** Clock (default `Date.now`). */
+  now?: () => number;
+}
+/** The built-in defaults — the floor under {@link setDefaultRetryOptions} and per-call options. */
+declare const DEFAULT_RETRY_OPTIONS: Required<Pick<RetryOptions, 'attempts' | 'base' | 'factor' | 'max' | 'jitter'>>;
+/** Set process-wide default {@link RetryOptions} (merged over previous overrides). Per-call options still win. */
+declare function setDefaultRetryOptions(options: RetryOptions): void;
+/** The effective global defaults ({@link DEFAULT_RETRY_OPTIONS} plus any {@link setDefaultRetryOptions} overrides). */
+declare function getDefaultRetryOptions(): RetryOptions;
+/**
+ * Backoff delay for retry `attempt` (1 = the first retry):
+ * `min(base · factor^(attempt-1), max) · (1 − jitter · random())`.
+ */
+declare function backoff(attempt: number, opts?: Pick<RetryOptions, 'base' | 'factor' | 'max' | 'jitter'>, random?: () => number): number;
+/**
+ * Run `fn`, retrying on rejection with exponential backoff + jitter up to `attempts`
+ * times. Resolves with the first success; on exhaustion it returns `errorResult` if one
+ * was provided, otherwise re-throws the last error.
+ */
+declare function retry<R>(fn: (state: RetryState) => Promise<R>, options?: RetryOptions<R>): Promise<R>;
+//#endregion
+export { DEFAULT_RETRY_OPTIONS, RetryAbort, RetryOptions, RetryState, backoff, getDefaultRetryOptions, retry, setDefaultRetryOptions };

package/dist/retry.d.ts

@@ -0,0 +1,90 @@
+import { i as MaybePromise } from "./types.js";
+
+//#region src/retry.d.ts
+
+/**
+ * Throw this from a {@link retry} operation to **stop retrying immediately**: the remaining
+ * attempts (and their backoff) are skipped, `onError` fires once, and `retry` then re-throws the
+ * abort's `cause` (or returns `errorResult` if one was configured). Use it for a permanent failure
+ * a retry can't fix — a 4xx, a validation error, a missing resource.
+ *
+ * ```ts
+ * await retry(async () => {
+ *   const res = await fetch(url);
+ *   if (res.status === 404) throw new RetryAbort(new Error('not found')); // don't retry a 404
+ *   if (!res.ok) throw new Error(`http ${res.status}`);                   // transient → retried
+ *   return res.json();
+ * });
+ * ```
+ */
+declare class RetryAbort extends Error {
+  constructor(cause?: unknown, message?: string);
+}
+/** Live state passed to the operation and to the {@link RetryOptions} hooks. */
+interface RetryState {
+  /** When the first attempt started (epoch ms). */
+  readonly startAt: number;
+  /** Current attempt number (1-based). */
+  readonly attempt: number;
+  /** Total attempts allowed. */
+  readonly attempts: number;
+  /** When the current attempt started (epoch ms). */
+  readonly lastAttemptAt: number;
+  /** The most recent error (undefined before any failure). */
+  readonly lastError?: unknown;
+}
+/** Options for {@link retry}. Every numeric field has a default (see {@link DEFAULT_RETRY_OPTIONS}). */
+interface RetryOptions<R = unknown> {
+  /** Total attempts including the first (default 3). */
+  attempts?: number;
+  /** First-retry delay in ms (default 1000). */
+  base?: number;
+  /** Multiplier applied per attempt (default 2). */
+  factor?: number;
+  /** Delay cap in ms (default 30000). */
+  max?: number;
+  /** Jitter fraction in `[0,1]`: each delay is scaled down by up to this much (default 0.5). */
+  jitter?: number;
+  /** If every attempt fails, resolve with this value instead of throwing. */
+  errorResult?: R;
+  /**
+   * Decide what to do with a thrown error: return `false` to **stop** retrying (abort), or a number
+   * of **milliseconds to wait at least** before the next attempt — a floor under the normal backoff
+   * (e.g. honor a `Retry-After`; `0` = just use the backoff). May be async. Default:
+   * `(err) => (err instanceof RetryAbort ? false : 0)` — overriding it **replaces** that check
+   * (e.g. `on: (e) => (e.status === 404 ? false : 0)` aborts on a 404 with no `RetryAbort` wrapper).
+   * To keep retrying through a `RetryAbort`, override it (e.g. `on: () => 0`).
+   */
+  on?: (err: unknown) => MaybePromise<number | false>;
+  /** Called after a successful attempt. */
+  onSuccess?: (result: R, state: RetryState) => void;
+  /** Called after a failed attempt that will be retried, before backing off. */
+  onRetry?: (error: unknown, state: RetryState) => void;
+  /** Called when all attempts are exhausted, before throwing or returning `errorResult`. */
+  onError?: (error: unknown, state: RetryState) => void;
+  /** Sleep implementation (ms) — injectable for tests (default an unref'd timer). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Randomness for jitter (default `Math.random`). */
+  random?: () => number;
+  /** Clock (default `Date.now`). */
+  now?: () => number;
+}
+/** The built-in defaults — the floor under {@link setDefaultRetryOptions} and per-call options. */
+declare const DEFAULT_RETRY_OPTIONS: Required<Pick<RetryOptions, 'attempts' | 'base' | 'factor' | 'max' | 'jitter'>>;
+/** Set process-wide default {@link RetryOptions} (merged over previous overrides). Per-call options still win. */
+declare function setDefaultRetryOptions(options: RetryOptions): void;
+/** The effective global defaults ({@link DEFAULT_RETRY_OPTIONS} plus any {@link setDefaultRetryOptions} overrides). */
+declare function getDefaultRetryOptions(): RetryOptions;
+/**
+ * Backoff delay for retry `attempt` (1 = the first retry):
+ * `min(base · factor^(attempt-1), max) · (1 − jitter · random())`.
+ */
+declare function backoff(attempt: number, opts?: Pick<RetryOptions, 'base' | 'factor' | 'max' | 'jitter'>, random?: () => number): number;
+/**
+ * Run `fn`, retrying on rejection with exponential backoff + jitter up to `attempts`
+ * times. Resolves with the first success; on exhaustion it returns `errorResult` if one
+ * was provided, otherwise re-throws the last error.
+ */
+declare function retry<R>(fn: (state: RetryState) => Promise<R>, options?: RetryOptions<R>): Promise<R>;
+//#endregion
+export { DEFAULT_RETRY_OPTIONS, RetryAbort, RetryOptions, RetryState, backoff, getDefaultRetryOptions, retry, setDefaultRetryOptions };

package/dist/retry.js

@@ -0,0 +1,129 @@
+//#region src/retry.ts
+/**
+* Throw this from a {@link retry} operation to **stop retrying immediately**: the remaining
+* attempts (and their backoff) are skipped, `onError` fires once, and `retry` then re-throws the
+* abort's `cause` (or returns `errorResult` if one was configured). Use it for a permanent failure
+* a retry can't fix — a 4xx, a validation error, a missing resource.
+*
+* ```ts
+* await retry(async () => {
+*   const res = await fetch(url);
+*   if (res.status === 404) throw new RetryAbort(new Error('not found')); // don't retry a 404
+*   if (!res.ok) throw new Error(`http ${res.status}`);                   // transient → retried
+*   return res.json();
+* });
+* ```
+*/
+var RetryAbort = class extends Error {
+	constructor(cause, message = "retry aborted") {
+		super(message, { cause });
+		this.name = "RetryAbort";
+	}
+};
+/** The default {@link RetryOptions.on}: a {@link RetryAbort} stops the loop, anything else retries with the normal backoff. */
+const defaultOn = (err) => err instanceof RetryAbort ? false : 0;
+/** The built-in defaults — the floor under {@link setDefaultRetryOptions} and per-call options. */
+const DEFAULT_RETRY_OPTIONS = {
+	attempts: 3,
+	base: 1e3,
+	factor: 2,
+	max: 3e4,
+	jitter: .5
+};
+/** Process-wide overrides, applied between {@link DEFAULT_RETRY_OPTIONS} and per-call options. */
+let globalDefaults = {};
+/** Set process-wide default {@link RetryOptions} (merged over previous overrides). Per-call options still win. */
+function setDefaultRetryOptions(options) {
+	globalDefaults = {
+		...globalDefaults,
+		...options
+	};
+}
+/** The effective global defaults ({@link DEFAULT_RETRY_OPTIONS} plus any {@link setDefaultRetryOptions} overrides). */
+function getDefaultRetryOptions() {
+	return {
+		...DEFAULT_RETRY_OPTIONS,
+		...globalDefaults
+	};
+}
+const defaultSleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms).unref?.();
+});
+/**
+* Backoff delay for retry `attempt` (1 = the first retry):
+* `min(base · factor^(attempt-1), max) · (1 − jitter · random())`.
+*/
+function backoff(attempt, opts = {}, random = Math.random) {
+	const base = opts.base ?? DEFAULT_RETRY_OPTIONS.base;
+	const factor = opts.factor ?? DEFAULT_RETRY_OPTIONS.factor;
+	const max = opts.max ?? DEFAULT_RETRY_OPTIONS.max;
+	const jitter = opts.jitter ?? DEFAULT_RETRY_OPTIONS.jitter;
+	const raw = base * Math.pow(factor, Math.max(0, attempt - 1));
+	return Math.round(Math.min(raw, max) * (1 - jitter * random()));
+}
+/**
+* Run `fn`, retrying on rejection with exponential backoff + jitter up to `attempts`
+* times. Resolves with the first success; on exhaustion it returns `errorResult` if one
+* was provided, otherwise re-throws the last error.
+*/
+async function retry(fn, options = {}) {
+	const o = {
+		...DEFAULT_RETRY_OPTIONS,
+		...globalDefaults,
+		...options
+	};
+	const now = o.now ?? Date.now;
+	const random = o.random ?? Math.random;
+	const sleep = o.sleep ?? defaultSleep;
+	const decide = o.on ?? defaultOn;
+	const hasErrorResult = "errorResult" in options;
+	const startAt = now();
+	let lastError;
+	for (let attempt = 1; attempt <= o.attempts; attempt++) {
+		const lastAttemptAt = now();
+		const state = {
+			startAt,
+			attempt,
+			attempts: o.attempts,
+			lastAttemptAt,
+			lastError
+		};
+		try {
+			const result = await fn(state);
+			o.onSuccess?.(result, state);
+			return result;
+		} catch (err) {
+			const decision = await decide(err);
+			if (decision === false) {
+				const cause = err instanceof RetryAbort ? err.cause ?? err : err;
+				lastError = cause;
+				o.onError?.(cause, {
+					startAt,
+					attempt,
+					attempts: o.attempts,
+					lastAttemptAt,
+					lastError: cause
+				});
+				break;
+			}
+			lastError = err;
+			const failed = {
+				startAt,
+				attempt,
+				attempts: o.attempts,
+				lastAttemptAt,
+				lastError: err
+			};
+			if (attempt < o.attempts) {
+				o.onRetry?.(err, failed);
+				await sleep(Math.max(decision, backoff(attempt, o, random)));
+				continue;
+			}
+			o.onError?.(err, failed);
+		}
+	}
+	if (hasErrorResult) return options.errorResult;
+	throw lastError;
+}
+//#endregion
+export { DEFAULT_RETRY_OPTIONS, RetryAbort, backoff, getDefaultRetryOptions, retry, setDefaultRetryOptions };

package/dist/stats.d.cts

@@ -0,0 +1,150 @@
+//#region src/stats.d.ts
+/**
+ * # Stats — a tiny, runtime-agnostic metrics primitive
+ *
+ * A dependency-free way to track named, typed measurements and hand them to whatever the
+ * end user already runs — a periodic log, StatsD, Prometheus. Three metric kinds cover
+ * the field:
+ *
+ * - **counter** — a monotonic tally (`inc`): requests served, jobs failed.
+ * - **gauge** — a value that moves both ways (`set`/`add`/`max`): in-flight count, a peak.
+ * - **summary** — a distribution of observations (`observe`): always count/total/min/max/avg,
+ *   and — when buckets/quantiles are configured — histogram buckets + approximate
+ *   percentiles (p50/p95/p99). Histogram-backed, so it's deterministic and bounded-memory.
+ *
+ * Every metric carries metadata (`name`, `kind`, `description`, `unit`) and is **labelled**
+ * (e.g. `{ type: 'email' }`), so one name spans many series. {@link createMetrics} is the
+ * registry: create handles, snapshot every series as a flat {@link StatValue} list, and
+ * {@link Metrics.subscribe} to **coalesced** change notifications (a burst of mutations
+ * yields one batched callback). {@link formatPrometheus} renders a snapshot as Prometheus
+ * text exposition.
+ *
+ * ```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
+ * ```
+ *
+ * @module
+ */
+/** The three metric shapes. */
+type StatKind = 'counter' | 'gauge' | 'summary';
+/** A metric's label set (a series within a metric family). Values are strings, order-insensitive. */
+type Labels = Readonly<Record<string, string>>;
+/** Static metadata describing a metric family (shared across its label series). */
+interface StatMeta {
+  /** The metric name (the family key). */
+  readonly name: string;
+  /** Which kind of metric this is. */
+  readonly kind: StatKind;
+  /** Human-readable description (exported as Prometheus `# HELP`). */
+  readonly description?: string;
+  /** Unit of measure, e.g. `'ms'`, `'bytes'`, `'count'` (informational). */
+  readonly unit?: string;
+}
+/** One histogram bucket: the cumulative count of observations `<= le` (`le` = upper bound, `Infinity` for the overflow). */
+interface StatBucket {
+  readonly le: number;
+  readonly count: number;
+}
+/** A summary's distribution snapshot. `quantiles`/`buckets` are present only when configured. */
+interface StatSummary {
+  /** Number of observations. */
+  readonly count: number;
+  /** Sum of all observations. */
+  readonly total: number;
+  /** Smallest observation (0 when none). */
+  readonly min: number;
+  /** Largest observation (0 when none). */
+  readonly max: number;
+  /** Mean (0 when none). */
+  readonly avg: number;
+  /** Approximate quantiles by probability key, e.g. `{ '0.95': 180 }` — when `quantiles` were configured. */
+  readonly quantiles?: Readonly<Record<string, number>>;
+  /** Cumulative histogram buckets — when buckets were configured. */
+  readonly buckets?: readonly StatBucket[];
+}
+/** A point-in-time snapshot of a single metric series (one name + label set). */
+interface StatValue {
+  /** The owning family's metadata. */
+  readonly meta: StatMeta;
+  /** This series' labels. */
+  readonly labels: Labels;
+  /** Counter/gauge value; for a summary, its observation `count` (full detail in {@link summary}). */
+  readonly value: number;
+  /** Present iff `meta.kind === 'summary'`. */
+  readonly summary?: StatSummary;
+}
+/** A monotonic tally. */
+interface Counter {
+  /** Add `by` (default 1). */
+  inc(by?: number): void;
+  /** Current total. */
+  value(): number;
+}
+/** A value that moves up and down. */
+interface Gauge {
+  /** Replace the value. */
+  set(v: number): void;
+  /** Add `by` (may be negative). */
+  add(by: number): void;
+  /** Raise to `v` if larger (a running high-water mark). */
+  max(v: number): void;
+  /** Current value. */
+  value(): number;
+}
+/** A distribution of observations. */
+interface Summary {
+  /** Record one observation. */
+  observe(v: number): void;
+  /** Current distribution snapshot. */
+  snapshot(): StatSummary;
+}
+/** Options for {@link createMetrics}. */
+interface MetricsOptions {
+  /**
+   * Probabilities (0–1) to estimate for every summary, e.g. `[0.5, 0.95, 0.99]`. Enables
+   * histogram bucketing (default {@link DEFAULT_BUCKETS} unless `buckets` is given) and fills
+   * {@link StatSummary.quantiles}. Omit for count/total/min/max/avg only (no per-observation cost).
+   */
+  readonly quantiles?: readonly number[];
+  /** Histogram bucket upper bounds for summaries (ascending). Defaults to {@link DEFAULT_BUCKETS} when `quantiles` is set. */
+  readonly buckets?: readonly number[];
+  /**
+   * Schedules the coalesced flush of change notifications. Default batches via `queueMicrotask`
+   * (one callback per synchronous burst). Inject `(fn) => fn()` for synchronous delivery, or a
+   * manual collector in tests.
+   */
+  readonly schedule?: (flush: () => void) => void;
+}
+/** The metrics registry returned by {@link createMetrics}. */
+interface Metrics {
+  /** Get-or-create a {@link Counter} series. */
+  counter(name: string, labels?: Labels, meta?: Omit<StatMeta, 'name' | 'kind'>): Counter;
+  /** Get-or-create a {@link Gauge} series. */
+  gauge(name: string, labels?: Labels, meta?: Omit<StatMeta, 'name' | 'kind'>): Gauge;
+  /** Get-or-create a {@link Summary} series. */
+  summary(name: string, labels?: Labels, meta?: Omit<StatMeta, 'name' | 'kind'>): Summary;
+  /** Snapshot every series as a flat list (one {@link StatValue} per name + label set). */
+  list(): StatValue[];
+  /** Snapshot one series, or `undefined` if it was never created. */
+  get(name: string, labels?: Labels): StatValue | undefined;
+  /** Subscribe to **coalesced** change notifications; the listener gets the batch of changed series. Returns an unsubscribe fn. */
+  subscribe(listener: (changed: readonly StatValue[]) => void): () => void;
+}
+/** Default histogram bucket upper bounds (ms-oriented), used when `quantiles` is set without explicit `buckets`. */
+declare const DEFAULT_BUCKETS: readonly number[];
+/** Create a metrics registry. */
+declare function createMetrics(opts?: MetricsOptions): Metrics;
+/**
+ * Render a {@link Metrics.list} snapshot as Prometheus text exposition format. Counters and gauges
+ * map directly; summaries are emitted as **histograms** (`_bucket`/`_count`/`_sum`) when buckets are
+ * present, else as bare `_count`/`_sum`. Names are sanitized to valid Prometheus identifiers.
+ */
+declare function formatPrometheus(stats: readonly StatValue[]): string;
+//#endregion
+export { Counter, DEFAULT_BUCKETS, Gauge, Labels, Metrics, MetricsOptions, StatBucket, StatKind, StatMeta, StatSummary, StatValue, Summary, createMetrics, formatPrometheus };