actor-ts 0.9.0

package/dist/metrics/Metrics.js

@@ -0,0 +1,231 @@
+/**
+ * In-process metrics primitives for the actor framework (#11).
+ *
+ * Three classic types:
+ *
+ *   - **Counter** — monotonic, only goes up.  Page views, messages
+ *     delivered, restart counts.
+ *   - **Gauge** — settable / inc/dec.  Mailbox depth, members up,
+ *     active connections.
+ *   - **Histogram** — fixed buckets + sum + count.  Persist latency,
+ *     handler duration.  Bucket boundaries are upper-inclusive
+ *     (`le="0.005"` matches the Prometheus convention).
+ *
+ * Metrics carry **labels** — key/value tag pairs that turn one metric
+ * into many time series.  A `MetricsRegistry.counter('foo')` with no
+ * labels has one series; with `{node: 'n-1'}` you get one series per
+ * distinct value of `node`.
+ *
+ * Cardinality discipline is the user's responsibility — high-cardinality
+ * labels (request id, user id, …) will OOM your monitoring system.  The
+ * registry doesn't enforce limits; it'll happily create one series per
+ * combo you ask for.
+ *
+ * Exposition format is decoupled — see {@link PrometheusExporter} for
+ * the Prometheus 0.0.4 text format implementation.
+ */
+class CounterImpl {
+    _v = 0;
+    inc(delta = 1) {
+        if (delta < 0)
+            throw new Error('Counter.inc requires delta >= 0');
+        if (!Number.isFinite(delta))
+            throw new Error('Counter.inc requires a finite delta');
+        this._v += delta;
+    }
+    get value() { return this._v; }
+}
+class GaugeImpl {
+    _v = 0;
+    set(v) {
+        if (!Number.isFinite(v))
+            throw new Error('Gauge.set requires a finite value');
+        this._v = v;
+    }
+    inc(delta = 1) {
+        if (!Number.isFinite(delta))
+            throw new Error('Gauge.inc requires a finite delta');
+        this._v += delta;
+    }
+    dec(delta = 1) {
+        if (!Number.isFinite(delta))
+            throw new Error('Gauge.dec requires a finite delta');
+        this._v -= delta;
+    }
+    get value() { return this._v; }
+}
+/* ----------------------------- Histogram ----------------------------- */
+/**
+ * Default bucket boundaries — the Prometheus client-library defaults,
+ * which work well for short-tail latencies in the 5ms..10s range.
+ * Provide your own via `MetricsRegistry.histogram(..., { buckets })`
+ * for histograms that don't fit this shape (e.g. payload sizes).
+ */
+export const DEFAULT_HISTOGRAM_BUCKETS = Object.freeze([
+    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
+]);
+class HistogramImpl {
+    _buckets;
+    _counts;
+    _sum = 0;
+    _count = 0;
+    constructor(buckets) {
+        if (buckets.length === 0)
+            throw new Error('Histogram: at least one bucket boundary required');
+        // Defensive copy + sorted ascending; we add a +Inf bucket internally.
+        const sorted = [...buckets].sort((a, b) => a - b);
+        if (sorted.some((b) => !Number.isFinite(b))) {
+            throw new Error('Histogram: bucket boundaries must be finite');
+        }
+        this._buckets = Object.freeze([...sorted, Number.POSITIVE_INFINITY]);
+        this._counts = new Array(this._buckets.length).fill(0);
+    }
+    observe(v) {
+        if (!Number.isFinite(v)) {
+            // Prometheus convention — only record if finite.  +Inf observations
+            // are dropped; NaN throws so the bug is visible.
+            if (Number.isNaN(v))
+                throw new Error('Histogram.observe: NaN');
+            return;
+        }
+        this._sum += v;
+        this._count += 1;
+        for (let i = 0; i < this._buckets.length; i++) {
+            if (v <= this._buckets[i]) {
+                this._counts[i] += 1;
+            }
+        }
+    }
+    get buckets() { return this._buckets; }
+    get counts() { return this._counts; }
+    get sum() { return this._sum; }
+    get count() { return this._count; }
+}
+/**
+ * Default in-memory implementation.  Thread-safe by virtue of being
+ * single-threaded (Bun + Node both run JS on a single thread per
+ * Worker; metrics live on the main thread of an ActorSystem).
+ */
+export class DefaultMetricsRegistry {
+    families = new Map();
+    counter(name, labels = {}, opts = {}) {
+        const family = this.familyOf(name, 'counter', opts.help);
+        return this.childOf(family, labels, () => new CounterImpl());
+    }
+    gauge(name, labels = {}, opts = {}) {
+        const family = this.familyOf(name, 'gauge', opts.help);
+        return this.childOf(family, labels, () => new GaugeImpl());
+    }
+    histogram(name, labels = {}, opts = {}) {
+        const family = this.familyOf(name, 'histogram', opts.help, opts.buckets);
+        return this.childOf(family, labels, () => new HistogramImpl(family.buckets));
+    }
+    collect() {
+        const out = [];
+        for (const [name, family] of this.families) {
+            for (const child of family.children.values()) {
+                if (family.kind === 'counter') {
+                    out.push({
+                        name, help: family.help, kind: 'counter',
+                        labels: child.labels, value: child.metric.value,
+                    });
+                }
+                else if (family.kind === 'gauge') {
+                    out.push({
+                        name, help: family.help, kind: 'gauge',
+                        labels: child.labels, value: child.metric.value,
+                    });
+                }
+                else {
+                    // Histogram: emit cumulative bucket samples + sum + count.
+                    const h = child.metric;
+                    let cumulative = 0;
+                    for (let i = 0; i < h.buckets.length; i++) {
+                        cumulative = h.counts[i]; // counts are already cumulative inside observe()
+                        out.push({
+                            name, help: family.help, kind: 'histogram',
+                            labels: child.labels, value: cumulative,
+                            bucket: h.buckets[i],
+                        });
+                    }
+                    out.push({
+                        name, help: family.help, kind: 'histogram',
+                        labels: child.labels, value: 0, // unused for sum/count rows
+                        sum: h.sum, count: h.count,
+                    });
+                }
+            }
+        }
+        return out;
+    }
+    clear() {
+        this.families.clear();
+    }
+    /* ----------------------------- internals ---------------------------- */
+    familyOf(name, kind, help, buckets) {
+        const existing = this.families.get(name);
+        if (existing) {
+            if (existing.kind !== kind) {
+                throw new Error(`Metric '${name}' already registered as ${existing.kind}, can't reuse as ${kind}`);
+            }
+            return existing;
+        }
+        let family;
+        if (kind === 'counter') {
+            family = { kind: 'counter', help: help ?? '', children: new Map() };
+        }
+        else if (kind === 'gauge') {
+            family = { kind: 'gauge', help: help ?? '', children: new Map() };
+        }
+        else {
+            family = {
+                kind: 'histogram',
+                help: help ?? '',
+                buckets: buckets ?? DEFAULT_HISTOGRAM_BUCKETS,
+                children: new Map(),
+            };
+        }
+        this.families.set(name, family);
+        return family;
+    }
+    childOf(family, labels, factory) {
+        const key = labelKey(labels);
+        const existing = family.children.get(key);
+        if (existing)
+            return existing.metric;
+        const metric = factory();
+        family.children.set(key, { labels: { ...labels }, metric: metric });
+        return metric;
+    }
+}
+/** Stable string key for a label set — used as the inner-map key. */
+function labelKey(labels) {
+    const keys = Object.keys(labels).sort();
+    if (keys.length === 0)
+        return '';
+    return keys.map((k) => `${k}=${String(labels[k])}`).join('\x1f');
+}
+/* ------------------------------ Noop ------------------------------- */
+const NOOP_COUNTER = { inc: () => { }, get value() { return 0; } };
+const NOOP_GAUGE = { set: () => { }, inc: () => { }, dec: () => { }, get value() { return 0; } };
+const NOOP_HIST = {
+    observe: () => { },
+    buckets: [],
+    counts: [],
+    sum: 0,
+    count: 0,
+};
+/**
+ * Zero-cost registry that throws nothing away but records nothing.
+ * Used as the default on `ActorSystem.metrics` so instrumentation
+ * sprinkled through the codebase pays nothing when metrics aren't
+ * enabled.
+ */
+export class NoopMetricsRegistry {
+    counter() { return NOOP_COUNTER; }
+    gauge() { return NOOP_GAUGE; }
+    histogram() { return NOOP_HIST; }
+    collect() { return []; }
+    clear() { }
+}
+//# sourceMappingURL=Metrics.js.map

package/dist/metrics/Metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Metrics.js","sourceRoot":"","sources":["../../src/metrics/Metrics.ts"],"names":[],"mappings":"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"}

package/dist/metrics/MetricsExtension.d.ts

@@ -0,0 +1,51 @@
+import type { ActorSystem } from '../ActorSystem.js';
+import { type Extension, type ExtensionId } from '../Extension.js';
+import { type MetricsRegistry } from './Metrics.js';
+/**
+ * `MetricsExtension` — the `system.extension(MetricsExtensionId)`
+ * accessor that hands back a {@link MetricsRegistry}.  By default the
+ * extension creates a `NoopMetricsRegistry` (zero-cost) so framework
+ * instrumentation pays nothing when the user doesn't enable metrics.
+ *
+ * Opt in:
+ *
+ *   const metrics = system.extension(MetricsExtensionId).enable();
+ *   // ... or pre-register a custom registry:
+ *   system.extension(MetricsExtensionId).useRegistry(myCustomRegistry);
+ *
+ * After `enable()`, the same `system.extension(MetricsExtensionId)`
+ * accessor returns the live {@link DefaultMetricsRegistry}; calls
+ * before that return the noop.
+ */
+export declare class MetricsExtension implements Extension {
+    private readonly _system;
+    private registry;
+    constructor(_system: ActorSystem);
+    /** Current registry — noop until `enable()` has been called. */
+    get(): MetricsRegistry;
+    /**
+     * Replace the noop registry with a real one.  Returns the live
+     * registry so callers can wire counters / gauges immediately.
+     * Idempotent — repeated calls return the same instance once a real
+     * registry is in place.
+     */
+    enable(): MetricsRegistry;
+    /**
+     * Plug in a custom registry — useful when you want to share a
+     * single registry across multiple `ActorSystem`s (rare) or to
+     * instrument with a third-party Prom client library directly.
+     */
+    useRegistry(registry: MetricsRegistry): void;
+    /** True if a real (non-noop) registry is installed. */
+    isEnabled(): boolean;
+}
+export declare const MetricsExtensionId: ExtensionId<MetricsExtension>;
+/**
+ * Convenience accessor — `metricsOf(system)` returns the live registry
+ * (or noop) without going through the extension chain at every call
+ * site.  Used by ActorCell / Cluster instrumentation hooks where the
+ * `MetricsExtensionId.get(...)` boilerplate would dwarf the actual
+ * `counter.inc()` call.
+ */
+export declare function metricsOf(system: ActorSystem): MetricsRegistry;
+//# sourceMappingURL=MetricsExtension.d.ts.map

package/dist/metrics/MetricsExtension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetricsExtension.d.ts","sourceRoot":"","sources":["../../src/metrics/MetricsExtension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAGpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAA8C;gBAEjC,OAAO,EAAE,WAAW;IAEjD,gEAAgE;IAChE,GAAG,IAAI,eAAe;IAEtB;;;;;OAKG;IACH,MAAM,IAAI,eAAe;IAOzB;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI5C,uDAAuD;IACvD,SAAS,IAAI,OAAO;CAGrB;AAED,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,gBAAgB,CAI1D,CAAC;AAEJ;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAE9D"}

package/dist/metrics/MetricsExtension.js

@@ -0,0 +1,63 @@
+import { extensionId } from '../Extension.js';
+import { DefaultMetricsRegistry, NoopMetricsRegistry, } from './Metrics.js';
+/**
+ * `MetricsExtension` — the `system.extension(MetricsExtensionId)`
+ * accessor that hands back a {@link MetricsRegistry}.  By default the
+ * extension creates a `NoopMetricsRegistry` (zero-cost) so framework
+ * instrumentation pays nothing when the user doesn't enable metrics.
+ *
+ * Opt in:
+ *
+ *   const metrics = system.extension(MetricsExtensionId).enable();
+ *   // ... or pre-register a custom registry:
+ *   system.extension(MetricsExtensionId).useRegistry(myCustomRegistry);
+ *
+ * After `enable()`, the same `system.extension(MetricsExtensionId)`
+ * accessor returns the live {@link DefaultMetricsRegistry}; calls
+ * before that return the noop.
+ */
+export class MetricsExtension {
+    _system;
+    registry = new NoopMetricsRegistry();
+    constructor(_system) {
+        this._system = _system;
+    }
+    /** Current registry — noop until `enable()` has been called. */
+    get() { return this.registry; }
+    /**
+     * Replace the noop registry with a real one.  Returns the live
+     * registry so callers can wire counters / gauges immediately.
+     * Idempotent — repeated calls return the same instance once a real
+     * registry is in place.
+     */
+    enable() {
+        if (this.registry instanceof NoopMetricsRegistry) {
+            this.registry = new DefaultMetricsRegistry();
+        }
+        return this.registry;
+    }
+    /**
+     * Plug in a custom registry — useful when you want to share a
+     * single registry across multiple `ActorSystem`s (rare) or to
+     * instrument with a third-party Prom client library directly.
+     */
+    useRegistry(registry) {
+        this.registry = registry;
+    }
+    /** True if a real (non-noop) registry is installed. */
+    isEnabled() {
+        return !(this.registry instanceof NoopMetricsRegistry);
+    }
+}
+export const MetricsExtensionId = extensionId('actor-ts/metrics', (system) => new MetricsExtension(system));
+/**
+ * Convenience accessor — `metricsOf(system)` returns the live registry
+ * (or noop) without going through the extension chain at every call
+ * site.  Used by ActorCell / Cluster instrumentation hooks where the
+ * `MetricsExtensionId.get(...)` boilerplate would dwarf the actual
+ * `counter.inc()` call.
+ */
+export function metricsOf(system) {
+    return system.extension(MetricsExtensionId).get();
+}
+//# sourceMappingURL=MetricsExtension.js.map

package/dist/metrics/MetricsExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetricsExtension.js","sourceRoot":"","sources":["../../src/metrics/MetricsExtension.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAoC,MAAM,iBAAiB,CAAC;AAChF,OAAO,EACL,sBAAsB,EACtB,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,gBAAgB;IAGE;IAFrB,QAAQ,GAAoB,IAAI,mBAAmB,EAAE,CAAC;IAE9D,YAA6B,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAAG,CAAC;IAErD,gEAAgE;IAChE,GAAG,KAAsB,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,MAAM;QACJ,IAAI,IAAI,CAAC,QAAQ,YAAY,mBAAmB,EAAE,CAAC;YACjD,IAAI,CAAC,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,QAAyB;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,uDAAuD;IACvD,SAAS;QACP,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,YAAY,mBAAmB,CAAC,CAAC;IACzD,CAAC;CACF;AAED,MAAM,CAAC,MAAM,kBAAkB,GAC7B,WAAW,CACT,kBAAkB,EAClB,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CACzC,CAAC;AAEJ;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAmB;IAC3C,OAAO,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC,GAAG,EAAE,CAAC;AACpD,CAAC"}

package/dist/metrics/PromClientAdapter.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Bridge from the framework's {@link MetricsRegistry} to a
+ * `prom-client` registry (#64).
+ *
+ * Most users that already run a Node service have `prom-client` wired
+ * to their own `/metrics` route.  Without an adapter, framework
+ * metrics live in our own `MetricsRegistry` and the user has to scrape
+ * them on a separate path or merge two text exports — both irritating.
+ * `promClientRegistry(...)` returns a `MetricsRegistry` whose every
+ * mutation lands in the user's `prom-client` registry directly, so
+ * the framework's counters / gauges / histograms appear under the
+ * user's existing exposition route alongside their app metrics.
+ *
+ * Why this isn't an `import 'prom-client'`:
+ * - Optional peer dep, not a hard dependency — only users who wire
+ *   the bridge pull it in.
+ * - The user already has `import client from 'prom-client'` in their
+ *   app; passing the namespace in (instead of us loading it) avoids
+ *   loading the module twice and keeps version pinning under the
+ *   user's control.
+ *
+ * Structural typing: the {@link PromClientLike} interface below
+ * captures only the surface we actually use.  `prom-client`'s real
+ * types are a superset; passing `import * as client from 'prom-client'`
+ * in works at runtime and TypeScript narrows down to our shape.
+ */
+import type { MetricsRegistry } from './Metrics.js';
+export interface PromClientLabelValues {
+    [k: string]: string | number;
+}
+export interface PromClientCounter {
+    inc(value?: number): void;
+    inc(labels: PromClientLabelValues, value?: number): void;
+    labels(values: PromClientLabelValues): {
+        inc(value?: number): void;
+    };
+}
+export interface PromClientGauge {
+    set(value: number): void;
+    set(labels: PromClientLabelValues, value: number): void;
+    inc(value?: number): void;
+    inc(labels: PromClientLabelValues, value?: number): void;
+    dec(value?: number): void;
+    dec(labels: PromClientLabelValues, value?: number): void;
+    labels(values: PromClientLabelValues): {
+        set(v: number): void;
+        inc(v?: number): void;
+        dec(v?: number): void;
+    };
+}
+export interface PromClientHistogram {
+    observe(value: number): void;
+    observe(labels: PromClientLabelValues, value: number): void;
+    labels(values: PromClientLabelValues): {
+        observe(v: number): void;
+    };
+}
+export interface PromClientRegistryLike {
+    registerMetric(metric: unknown): void;
+    removeSingleMetric?(name: string): void;
+    getSingleMetric(name: string): unknown;
+    resetMetrics?(): void;
+}
+export interface PromClientLike {
+    Counter: new (opts: PromConstructorOpts) => PromClientCounter;
+    Gauge: new (opts: PromConstructorOpts) => PromClientGauge;
+    Histogram: new (opts: PromConstructorOpts & {
+        buckets?: number[];
+    }) => PromClientHistogram;
+}
+interface PromConstructorOpts {
+    name: string;
+    help: string;
+    labelNames?: string[];
+    registers?: PromClientRegistryLike[];
+    buckets?: number[];
+}
+export interface PromClientAdapterOptions {
+    /** The prom-client API namespace (`import client from 'prom-client'`). */
+    readonly client: PromClientLike;
+    /** The prom-client `Registry` to publish into.  Typically `client.register`. */
+    readonly registry: PromClientRegistryLike;
+    /**
+     * Optional name prefix, e.g. `'actor_ts_'`.  Applied to every metric
+     * name registered through the adapter.  Default: empty.
+     */
+    readonly namePrefix?: string;
+}
+/**
+ * Build a {@link MetricsRegistry} backed by the supplied `prom-client`
+ * registry.  Plug it into `ActorSystem.create({ metrics })` (or the
+ * framework's metrics extension) and your /metrics endpoint will
+ * include the framework's counters / gauges / histograms next to
+ * your existing app metrics — same registry, same exposition.
+ *
+ * `collect()` returns a snapshot translated from the prom-client side
+ * for parity; in practice users read via `prom-client.register.metrics()`
+ * directly and only call `collect()` from tests.
+ */
+export declare function promClientRegistry(opts: PromClientAdapterOptions): MetricsRegistry;
+export {};
+//# sourceMappingURL=PromClientAdapter.d.ts.map

package/dist/metrics/PromClientAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromClientAdapter.d.ts","sourceRoot":"","sources":["../../src/metrics/PromClientAdapter.ts"],"names":[],"mappings":"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"}