@ayepi/core 0.1.0

package/dist/stats.d.ts

@@ -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 };

package/dist/types.d.cts

@@ -0,0 +1,54 @@
+//#region src/types.d.ts
+/**
+ * # Type utilities
+ *
+ * Small, dependency-free type-level helpers used across the library. None of
+ * these emit runtime code — they exist purely to make the public generic
+ * surface infer precisely without leaking `any`/`unknown` to consumers.
+ *
+ * @module
+ */
+/**
+ * Flatten an intersection (`A & B & …`) into a single object literal so editor
+ * tooltips and `Equal<>` comparisons see one clean shape instead of a chain of
+ * intersections.
+ *
+ * @example
+ * ```ts
+ * type Messy = { a: 1 } & { b: 2 }
+ * type Clean = Simplify<Messy> // { a: 1; b: 2 }
+ * ```
+ */
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+/** A value that may be returned either synchronously or as a `Promise`. */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * The empty object type. Used as the identity element when merging contributed
+ * shapes (middleware context, path params, etc.) so an absent contribution adds
+ * nothing rather than widening the result.
+ */
+type EmptyObject = {};
+/**
+ * Convert a union `A | B | C` into the intersection `A & B & C`.
+ *
+ * Drives middleware-context merging: each middleware contributes a shape, and
+ * the handler sees the intersection of every contribution in its chain.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+/** Distribute `keyof` across a union, yielding the union of every member's keys. */
+
+/**
+ * Safe indexed access: resolves to `T[K]` when `K` is a key of `T`, otherwise
+ * `undefined`. Lets optional config properties be read without first proving
+ * they exist.
+ */
+type Get<T, K extends string> = K extends keyof T ? T[K] : undefined;
+/**
+ * A JSON-shaped value — the closed set of things the OpenAPI/AsyncAPI doc
+ * generators produce and accept in their patch callbacks.
+ */
+type Json = string | number | boolean | null | Json[] | {
+  [k: string]: Json;
+};
+//#endregion
+export { Simplify as a, MaybePromise as i, Get as n, UnionToIntersection as o, Json as r, EmptyObject as t };

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+//#region src/types.d.ts
+/**
+ * # Type utilities
+ *
+ * Small, dependency-free type-level helpers used across the library. None of
+ * these emit runtime code — they exist purely to make the public generic
+ * surface infer precisely without leaking `any`/`unknown` to consumers.
+ *
+ * @module
+ */
+/**
+ * Flatten an intersection (`A & B & …`) into a single object literal so editor
+ * tooltips and `Equal<>` comparisons see one clean shape instead of a chain of
+ * intersections.
+ *
+ * @example
+ * ```ts
+ * type Messy = { a: 1 } & { b: 2 }
+ * type Clean = Simplify<Messy> // { a: 1; b: 2 }
+ * ```
+ */
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+/** A value that may be returned either synchronously or as a `Promise`. */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * The empty object type. Used as the identity element when merging contributed
+ * shapes (middleware context, path params, etc.) so an absent contribution adds
+ * nothing rather than widening the result.
+ */
+type EmptyObject = {};
+/**
+ * Convert a union `A | B | C` into the intersection `A & B & C`.
+ *
+ * Drives middleware-context merging: each middleware contributes a shape, and
+ * the handler sees the intersection of every contribution in its chain.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+/** Distribute `keyof` across a union, yielding the union of every member's keys. */
+
+/**
+ * Safe indexed access: resolves to `T[K]` when `K` is a key of `T`, otherwise
+ * `undefined`. Lets optional config properties be read without first proving
+ * they exist.
+ */
+type Get<T, K extends string> = K extends keyof T ? T[K] : undefined;
+/**
+ * A JSON-shaped value — the closed set of things the OpenAPI/AsyncAPI doc
+ * generators produce and accept in their patch callbacks.
+ */
+type Json = string | number | boolean | null | Json[] | {
+  [k: string]: Json;
+};
+//#endregion
+export { Simplify as a, MaybePromise as i, Get as n, UnionToIntersection as o, Json as r, EmptyObject as t };