actor-ts 0.9.0

package/dist/metrics/PromClientAdapter.js

@@ -0,0 +1,244 @@
+/**
+ * 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 { DEFAULT_HISTOGRAM_BUCKETS } from './Metrics.js';
+/**
+ * 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 function promClientRegistry(opts) {
+    const { client, registry, namePrefix = '' } = opts;
+    const families = new Map();
+    function fullName(name) {
+        return namePrefix + name;
+    }
+    /**
+     * Stable string from a `Labels` object — sorted keys, JSON-encoded
+     * values.  Same shape as `Metrics.ts`'s internal series-key, used
+     * here only for our local cache (the prom-client side does its own
+     * label-tuple hashing).
+     */
+    function labelKey(labels) {
+        if (!labels)
+            return '';
+        const keys = Object.keys(labels).sort();
+        return keys.map((k) => `${k}=${JSON.stringify(labels[k])}`).join('|');
+    }
+    function asPromLabels(labels) {
+        if (!labels)
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(labels)) {
+            // prom-client's `LabelValues` only takes string | number.  Booleans
+            // and other primitives are coerced via `String(...)` so we don't
+            // silently drop them.  Cardinality discipline is the user's job.
+            if (typeof v === 'string' || typeof v === 'number')
+                out[k] = v;
+            else
+                out[k] = String(v);
+        }
+        return out;
+    }
+    function getOrCreateCounter(name, labels, opts2) {
+        const fullN = fullName(name);
+        const existing = families.get(fullN);
+        if (existing) {
+            if (existing.kind !== 'counter') {
+                throw new Error(`promClientRegistry: '${fullN}' is already registered as ${existing.kind}`);
+            }
+            return existing;
+        }
+        const labelNames = labels ? Object.keys(labels).sort() : [];
+        const impl = new client.Counter({
+            name: fullN,
+            help: opts2?.help ?? fullN,
+            labelNames: labelNames.length > 0 ? labelNames : undefined,
+            registers: [registry],
+        });
+        const entry = { kind: 'counter', help: opts2?.help ?? fullN, labelNames, impl };
+        families.set(fullN, entry);
+        return entry;
+    }
+    function getOrCreateGauge(name, labels, opts2) {
+        const fullN = fullName(name);
+        const existing = families.get(fullN);
+        if (existing) {
+            if (existing.kind !== 'gauge') {
+                throw new Error(`promClientRegistry: '${fullN}' is already registered as ${existing.kind}`);
+            }
+            return existing;
+        }
+        const labelNames = labels ? Object.keys(labels).sort() : [];
+        const impl = new client.Gauge({
+            name: fullN,
+            help: opts2?.help ?? fullN,
+            labelNames: labelNames.length > 0 ? labelNames : undefined,
+            registers: [registry],
+        });
+        const entry = { kind: 'gauge', help: opts2?.help ?? fullN, labelNames, impl };
+        families.set(fullN, entry);
+        return entry;
+    }
+    function getOrCreateHistogram(name, labels, opts2) {
+        const fullN = fullName(name);
+        const existing = families.get(fullN);
+        if (existing) {
+            if (existing.kind !== 'histogram') {
+                throw new Error(`promClientRegistry: '${fullN}' is already registered as ${existing.kind}`);
+            }
+            return existing;
+        }
+        const labelNames = labels ? Object.keys(labels).sort() : [];
+        const buckets = opts2?.buckets ?? DEFAULT_HISTOGRAM_BUCKETS;
+        const impl = new client.Histogram({
+            name: fullN,
+            help: opts2?.help ?? fullN,
+            labelNames: labelNames.length > 0 ? labelNames : undefined,
+            buckets: [...buckets],
+            registers: [registry],
+        });
+        const entry = {
+            kind: 'histogram', help: opts2?.help ?? fullN, labelNames,
+            buckets: [...buckets], impl,
+        };
+        families.set(fullN, entry);
+        return entry;
+    }
+    return {
+        counter(name, labels, opts2) {
+            const entry = getOrCreateCounter(name, labels, opts2);
+            const promLabels = asPromLabels(labels);
+            // Local mirror of the value so the framework's `Counter.value`
+            // contract (read for testing) keeps working without poking the
+            // prom-client side.
+            let mirror = 0;
+            // Prefix-bound inc on the prom-client side.
+            const child = entry.impl.labels(promLabels);
+            void labelKey(labels); // namespace-disambig debug — kept for symmetry with PrometheusExporter
+            return {
+                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');
+                    mirror += delta;
+                    child.inc(delta);
+                },
+                get value() { return mirror; },
+            };
+        },
+        gauge(name, labels, opts2) {
+            const entry = getOrCreateGauge(name, labels, opts2);
+            const promLabels = asPromLabels(labels);
+            let mirror = 0;
+            const child = entry.impl.labels(promLabels);
+            return {
+                set(v) {
+                    if (!Number.isFinite(v))
+                        throw new Error('Gauge.set requires a finite value');
+                    mirror = v;
+                    child.set(v);
+                },
+                inc(delta = 1) {
+                    if (!Number.isFinite(delta))
+                        throw new Error('Gauge.inc requires a finite delta');
+                    mirror += delta;
+                    child.inc(delta);
+                },
+                dec(delta = 1) {
+                    if (!Number.isFinite(delta))
+                        throw new Error('Gauge.dec requires a finite delta');
+                    mirror -= delta;
+                    child.dec(delta);
+                },
+                get value() { return mirror; },
+            };
+        },
+        histogram(name, labels, opts2) {
+            const entry = getOrCreateHistogram(name, labels, opts2);
+            const promLabels = asPromLabels(labels);
+            const child = entry.impl.labels(promLabels);
+            // Mirror the bucket counts + sum + count locally so the
+            // framework's `Histogram.{counts,sum,count}` contract keeps
+            // working for tests that read the values directly.
+            const bucketsWithInf = [...entry.buckets, Number.POSITIVE_INFINITY];
+            const counts = new Array(bucketsWithInf.length).fill(0);
+            let sum = 0;
+            let count = 0;
+            return {
+                observe(v) {
+                    if (!Number.isFinite(v)) {
+                        if (Number.isNaN(v))
+                            throw new Error('Histogram.observe: NaN');
+                        return;
+                    }
+                    sum += v;
+                    count += 1;
+                    for (let i = 0; i < bucketsWithInf.length; i++) {
+                        if (v <= bucketsWithInf[i])
+                            counts[i] += 1;
+                    }
+                    child.observe(v);
+                },
+                get buckets() { return bucketsWithInf; },
+                get counts() { return counts; },
+                get sum() { return sum; },
+                get count() { return count; },
+            };
+        },
+        /**
+         * Translate the prom-client side back into our `MetricSample` shape.
+         * Mostly useful in tests; production users will read via
+         * `register.metrics()` (or `register.getMetricsAsJSON()`) on the
+         * prom-client side directly and skip this round-trip.
+         */
+        collect() {
+            // This intentionally returns an empty array: the prom-client
+            // registry holds the canonical state, and exposing
+            // already-translated metrics here would compete with the
+            // user's own /metrics handler.  Tests that need read-back can
+            // call the prom-client registry directly.
+            return [];
+        },
+        clear() {
+            // We can't reach into the prom-client registry's internals to
+            // remove just our metrics in a back-compat way, so `clear()`
+            // is a no-op at the bridge level.  Tests that need a fresh
+            // registry should construct one explicitly.  (prom-client's
+            // own `Registry.clear()` works on its side — call that if you
+            // own the registry exclusively.)
+            families.clear();
+        },
+    };
+}
+//# sourceMappingURL=PromClientAdapter.js.map

package/dist/metrics/PromClientAdapter.js.map

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

package/dist/metrics/PrometheusExporter.d.ts

@@ -0,0 +1,31 @@
+import type { MetricsRegistry } from './Metrics.js';
+/**
+ * Prometheus 0.0.4 text-format exposition.
+ *
+ *   const text = exportPrometheus(registry);
+ *   // → "# HELP actor_messages_delivered_total ...
+ *   //    # TYPE actor_messages_delivered_total counter
+ *   //    actor_messages_delivered_total{node=\"n-1\"} 42
+ *   //    ..."
+ *
+ * Output is suitable for `Content-Type: text/plain; version=0.0.4`.
+ * The {@link prometheusHandler} convenience returns a request handler
+ * suitable for `Bun.serve` (and any framework that accepts the same
+ * `(req: Request) => Response` shape — Hono, vanilla `Deno.serve`, …).
+ */
+/**
+ * Render the registry's current state as Prometheus text format.
+ */
+export declare function exportPrometheus(registry: MetricsRegistry): string;
+/**
+ * Build a `(req: Request) => Response` handler that returns the
+ * current registry state in Prometheus text format.  Plug into your
+ * server:
+ *
+ *   Bun.serve({
+ *     port: 9090,
+ *     fetch: prometheusHandler(system.metrics),
+ *   });
+ */
+export declare function prometheusHandler(registry: MetricsRegistry): (req: Request) => Response;
+//# sourceMappingURL=PrometheusExporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PrometheusExporter.d.ts","sourceRoot":"","sources":["../../src/metrics/PrometheusExporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,eAAe,EAAE,MAAM,cAAc,CAAC;AAE1E;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAsDlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,GACxB,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,CAK5B"}

package/dist/metrics/PrometheusExporter.js

@@ -0,0 +1,128 @@
+/**
+ * Prometheus 0.0.4 text-format exposition.
+ *
+ *   const text = exportPrometheus(registry);
+ *   // → "# HELP actor_messages_delivered_total ...
+ *   //    # TYPE actor_messages_delivered_total counter
+ *   //    actor_messages_delivered_total{node=\"n-1\"} 42
+ *   //    ..."
+ *
+ * Output is suitable for `Content-Type: text/plain; version=0.0.4`.
+ * The {@link prometheusHandler} convenience returns a request handler
+ * suitable for `Bun.serve` (and any framework that accepts the same
+ * `(req: Request) => Response` shape — Hono, vanilla `Deno.serve`, …).
+ */
+/**
+ * Render the registry's current state as Prometheus text format.
+ */
+export function exportPrometheus(registry) {
+    const samples = registry.collect();
+    // Group by family name so we emit `# HELP` / `# TYPE` once per family.
+    const byName = new Map();
+    for (const s of samples) {
+        let arr = byName.get(s.name);
+        if (!arr) {
+            arr = [];
+            byName.set(s.name, arr);
+        }
+        arr.push(s);
+    }
+    const out = [];
+    for (const [name, group] of byName) {
+        if (group.length === 0)
+            continue;
+        const head = group[0];
+        if (head.help)
+            out.push(`# HELP ${name} ${escapeHelp(head.help)}`);
+        out.push(`# TYPE ${name} ${head.kind}`);
+        if (head.kind === 'histogram') {
+            // Histogram emission: bucket rows, then _sum and _count.
+            // Layout per series: all bucket rows for one label set, then _sum + _count
+            // for that label set.  We separate by labelKey first.
+            const byLabel = new Map();
+            for (const s of group) {
+                const k = labelKey(s.labels);
+                let arr = byLabel.get(k);
+                if (!arr) {
+                    arr = [];
+                    byLabel.set(k, arr);
+                }
+                arr.push(s);
+            }
+            for (const groupSamples of byLabel.values()) {
+                for (const s of groupSamples) {
+                    if (s.bucket !== undefined) {
+                        const le = s.bucket === Number.POSITIVE_INFINITY ? '+Inf' : String(s.bucket);
+                        const labels = renderLabels({ ...s.labels, le });
+                        out.push(`${name}_bucket${labels} ${formatNumber(s.value)}`);
+                    }
+                }
+                // sum + count come after the buckets.
+                for (const s of groupSamples) {
+                    if (s.sum !== undefined && s.count !== undefined) {
+                        const labels = renderLabels(s.labels);
+                        out.push(`${name}_sum${labels} ${formatNumber(s.sum)}`);
+                        out.push(`${name}_count${labels} ${formatNumber(s.count)}`);
+                    }
+                }
+            }
+        }
+        else {
+            // Counter / Gauge — one row per labeled series.  Counter family
+            // names traditionally end in `_total`; the user is responsible
+            // for that naming convention.
+            for (const s of group) {
+                out.push(`${name}${renderLabels(s.labels)} ${formatNumber(s.value)}`);
+            }
+        }
+    }
+    // Trailing newline per text-format spec.
+    return out.join('\n') + (out.length > 0 ? '\n' : '');
+}
+/**
+ * Build a `(req: Request) => Response` handler that returns the
+ * current registry state in Prometheus text format.  Plug into your
+ * server:
+ *
+ *   Bun.serve({
+ *     port: 9090,
+ *     fetch: prometheusHandler(system.metrics),
+ *   });
+ */
+export function prometheusHandler(registry) {
+    return (_req) => new Response(exportPrometheus(registry), {
+        status: 200,
+        headers: { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' },
+    });
+}
+/* ------------------------------ helpers --------------------------------- */
+function renderLabels(labels) {
+    const keys = Object.keys(labels).sort();
+    if (keys.length === 0)
+        return '';
+    const inner = keys
+        .map((k) => `${k}="${escapeLabelValue(String(labels[k]))}"`)
+        .join(',');
+    return `{${inner}}`;
+}
+function labelKey(labels) {
+    return Object.keys(labels).sort()
+        .map((k) => `${k}=${String(labels[k])}`).join('\x1f');
+}
+function escapeLabelValue(v) {
+    return v.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/"/g, '\\"');
+}
+function escapeHelp(v) {
+    return v.replace(/\\/g, '\\\\').replace(/\n/g, '\\n');
+}
+function formatNumber(n) {
+    if (Number.isNaN(n))
+        return 'NaN';
+    if (n === Number.POSITIVE_INFINITY)
+        return '+Inf';
+    if (n === Number.NEGATIVE_INFINITY)
+        return '-Inf';
+    // Integer-typed counters / counts should render without `.0`.
+    return Number.isInteger(n) ? n.toFixed(0) : String(n);
+}
+//# sourceMappingURL=PrometheusExporter.js.map

package/dist/metrics/PrometheusExporter.js.map

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

package/dist/metrics/index.d.ts

@@ -0,0 +1,7 @@
+export { DefaultMetricsRegistry, NoopMetricsRegistry, DEFAULT_HISTOGRAM_BUCKETS, } from './Metrics.js';
+export type { MetricsRegistry, Counter, Gauge, Histogram, MetricSample, Labels, LabelValue, CounterOptions, GaugeOptions, HistogramOptions, } from './Metrics.js';
+export { MetricsExtension, MetricsExtensionId, metricsOf, } from './MetricsExtension.js';
+export { exportPrometheus, prometheusHandler, } from './PrometheusExporter.js';
+export { promClientRegistry } from './PromClientAdapter.js';
+export type { PromClientLike, PromClientRegistryLike, PromClientCounter, PromClientGauge, PromClientHistogram, PromClientLabelValues, PromClientAdapterOptions, } from './PromClientAdapter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,OAAO,EACP,KAAK,EACL,SAAS,EACT,YAAY,EACZ,MAAM,EACN,UAAU,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,GACV,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC"}

package/dist/metrics/index.js

@@ -0,0 +1,5 @@
+export { DefaultMetricsRegistry, NoopMetricsRegistry, DEFAULT_HISTOGRAM_BUCKETS, } from './Metrics.js';
+export { MetricsExtension, MetricsExtensionId, metricsOf, } from './MetricsExtension.js';
+export { exportPrometheus, prometheusHandler, } from './PrometheusExporter.js';
+export { promClientRegistry } from './PromClientAdapter.js';
+//# sourceMappingURL=index.js.map

package/dist/metrics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AAatB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,GACV,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/pattern/BackoffPolicy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure backoff-policy primitives — stateless functions of `(restartCount)`
+ * to a delay in milliseconds.  Decoupled from {@link BackoffSupervisor}
+ * so callers can plug in their own policy without subclassing the
+ * supervisor, and so the policy itself is trivially unit-testable.
+ *
+ * Two built-ins:
+ *
+ *   - `exponentialBackoff` — `min × 2^n` clamped to `max`, with optional
+ *     ± jitter expressed as a fraction of the un-jittered delay.  This
+ *     is the policy you usually want — fast-then-slow, randomised so
+ *     a herd of clients doesn't synchronise their reconnect attempts.
+ *
+ *   - `linearBackoff` — `min + step × n` clamped to `max`.  Niche; use
+ *     when you specifically want bounded growth (e.g. polling cadence
+ *     that should plateau quickly).
+ *
+ * The randomness source defaults to `Math.random` but can be overridden
+ * — pass a seeded RNG to make the policy deterministic in tests.
+ */
+export interface BackoffPolicy {
+    /**
+     * Delay in milliseconds before the next restart attempt.  `restartCount`
+     * is 0-based: the **first** restart (after the very first failure)
+     * passes `0`, the second restart passes `1`, etc.
+     */
+    delayFor(restartCount: number): number;
+}
+export interface ExponentialBackoffOptions {
+    /** Floor for the delay, in ms. The first restart delay is at least this. */
+    readonly minMs: number;
+    /** Ceiling for the delay, in ms. */
+    readonly maxMs: number;
+    /**
+     * Jitter fraction in `[0, 1]`.  The actual delay is multiplied by
+     * `1 + random(-randomFactor, +randomFactor)` so two replicas don't
+     * synchronise.  Default `0.2`.
+     */
+    readonly randomFactor?: number;
+    /** Override `Math.random` for deterministic tests. */
+    readonly random?: () => number;
+}
+export interface LinearBackoffOptions {
+    readonly minMs: number;
+    readonly maxMs: number;
+    /** Linear step in ms — added once per restart. */
+    readonly stepMs: number;
+    readonly randomFactor?: number;
+    readonly random?: () => number;
+}
+/**
+ * `min × 2^n` clamped to `max`, multiplied by `1 ± randomFactor`.
+ *
+ *   exponentialBackoff({ minMs: 200, maxMs: 10_000, randomFactor: 0.2 })
+ *   //  n=0 → ~200 (160..240)
+ *   //  n=1 → ~400 (320..480)
+ *   //  n=2 → ~800
+ *   //  n=10 → 10_000 (clamped)
+ */
+export declare function exponentialBackoff(opts: ExponentialBackoffOptions): BackoffPolicy;
+/**
+ * `min + step × n` clamped to `max`.  Same jitter contract as
+ * {@link exponentialBackoff}.  Use when you want a bounded, predictable
+ * cadence rather than exponential growth.
+ */
+export declare function linearBackoff(opts: LinearBackoffOptions): BackoffPolicy;
+//# sourceMappingURL=BackoffPolicy.d.ts.map

package/dist/pattern/BackoffPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackoffPolicy.d.ts","sourceRoot":"","sources":["../../src/pattern/BackoffPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,aAAa,CAgBjF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAgBvE"}

package/dist/pattern/BackoffPolicy.js

@@ -0,0 +1,87 @@
+/**
+ * Pure backoff-policy primitives — stateless functions of `(restartCount)`
+ * to a delay in milliseconds.  Decoupled from {@link BackoffSupervisor}
+ * so callers can plug in their own policy without subclassing the
+ * supervisor, and so the policy itself is trivially unit-testable.
+ *
+ * Two built-ins:
+ *
+ *   - `exponentialBackoff` — `min × 2^n` clamped to `max`, with optional
+ *     ± jitter expressed as a fraction of the un-jittered delay.  This
+ *     is the policy you usually want — fast-then-slow, randomised so
+ *     a herd of clients doesn't synchronise their reconnect attempts.
+ *
+ *   - `linearBackoff` — `min + step × n` clamped to `max`.  Niche; use
+ *     when you specifically want bounded growth (e.g. polling cadence
+ *     that should plateau quickly).
+ *
+ * The randomness source defaults to `Math.random` but can be overridden
+ * — pass a seeded RNG to make the policy deterministic in tests.
+ */
+/**
+ * `min × 2^n` clamped to `max`, multiplied by `1 ± randomFactor`.
+ *
+ *   exponentialBackoff({ minMs: 200, maxMs: 10_000, randomFactor: 0.2 })
+ *   //  n=0 → ~200 (160..240)
+ *   //  n=1 → ~400 (320..480)
+ *   //  n=2 → ~800
+ *   //  n=10 → 10_000 (clamped)
+ */
+export function exponentialBackoff(opts) {
+    validateBaseOpts(opts);
+    const randomFactor = opts.randomFactor ?? 0.2;
+    if (randomFactor < 0 || randomFactor > 1) {
+        throw new Error(`exponentialBackoff: randomFactor must be in [0, 1], got ${randomFactor}`);
+    }
+    const random = opts.random ?? Math.random;
+    return {
+        delayFor(restartCount) {
+            const n = Math.max(0, restartCount);
+            // Use a guarded power so we don't overflow to Infinity for huge n.
+            const raw = n >= 30 ? opts.maxMs : opts.minMs * Math.pow(2, n);
+            const clamped = Math.min(raw, opts.maxMs);
+            return applyJitter(clamped, randomFactor, random);
+        },
+    };
+}
+/**
+ * `min + step × n` clamped to `max`.  Same jitter contract as
+ * {@link exponentialBackoff}.  Use when you want a bounded, predictable
+ * cadence rather than exponential growth.
+ */
+export function linearBackoff(opts) {
+    validateBaseOpts(opts);
+    if (opts.stepMs < 0)
+        throw new Error(`linearBackoff: stepMs must be >= 0, got ${opts.stepMs}`);
+    const randomFactor = opts.randomFactor ?? 0.2;
+    if (randomFactor < 0 || randomFactor > 1) {
+        throw new Error(`linearBackoff: randomFactor must be in [0, 1], got ${randomFactor}`);
+    }
+    const random = opts.random ?? Math.random;
+    return {
+        delayFor(restartCount) {
+            const n = Math.max(0, restartCount);
+            const raw = opts.minMs + opts.stepMs * n;
+            const clamped = Math.min(raw, opts.maxMs);
+            return applyJitter(clamped, randomFactor, random);
+        },
+    };
+}
+/* ------------------------------ helpers --------------------------------- */
+function validateBaseOpts(opts) {
+    if (!Number.isFinite(opts.minMs) || opts.minMs < 0) {
+        throw new Error(`backoff: minMs must be a non-negative finite number, got ${opts.minMs}`);
+    }
+    if (!Number.isFinite(opts.maxMs) || opts.maxMs < opts.minMs) {
+        throw new Error(`backoff: maxMs must be a finite number >= minMs (${opts.minMs}), got ${opts.maxMs}`);
+    }
+}
+function applyJitter(base, randomFactor, random) {
+    if (randomFactor === 0)
+        return base;
+    // random() returns [0, 1); map to [-randomFactor, +randomFactor].
+    const sign = random() * 2 - 1;
+    // Floor at 0 — a sub-zero delay would be nonsensical.
+    return Math.max(0, base * (1 + sign * randomFactor));
+}
+//# sourceMappingURL=BackoffPolicy.js.map

package/dist/pattern/BackoffPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackoffPolicy.js","sourceRoot":"","sources":["../../src/pattern/BackoffPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAmCH;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA+B;IAChE,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC;IAC9C,IAAI,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,2DAA2D,YAAY,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC1C,OAAO;QACL,QAAQ,CAAC,YAAoB;YAC3B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YACpC,mEAAmE;YACnE,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1C,OAAO,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;QACpD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAA0B;IACtD,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/F,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC;IAC9C,IAAI,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,sDAAsD,YAAY,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC1C,OAAO;QACL,QAAQ,CAAC,YAAoB;YAC3B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YACpC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YACzC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1C,OAAO,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;QACpD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAE9E,SAAS,gBAAgB,CAAC,IAAsC;IAC9D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,4DAA4D,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,oDAAoD,IAAI,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACxG,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,YAAoB,EAAE,MAAoB;IAC3E,IAAI,YAAY,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,kEAAkE;IAClE,MAAM,IAAI,GAAG,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,sDAAsD;IACtD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC;AACvD,CAAC"}