turbine-orm 0.46.0 → 0.47.0

package/dist/observe.js

@@ -1,10 +1,16 @@
 /**
- * turbine-orm — Observability module
+ * turbine-orm: Observability module
  *
  * Buffers query metrics in memory (keyed by model:action per minute bucket),
- * then periodically flushes aggregates (count, avg, p50, p95, p99, errors)
- * to a dedicated _turbine_metrics table. Uses a separate 1-connection pool
- * so metrics writes never contend with the application pool.
+ * then periodically flushes aggregates (count, avg, p50, p95, p99, errors) to a
+ * pluggable {@link ObserveSink}. The default sink writes to a dedicated
+ * `_turbine_metrics` Postgres table over its own 1-connection pool, so metrics
+ * writes never contend with the application pool; alternative sinks (for example
+ * {@link HttpJsonSink}) can forward the same aggregates elsewhere.
+ *
+ * The aggregation privacy posture is deliberate: a batch carries only the
+ * model/action identity, the counts, and the latency percentiles. It never
+ * carries SQL text or bound parameter values.
  */
 import pg from 'pg';
 function floorToMinute(date) {
@@ -19,7 +25,7 @@ function percentile(sorted, p) {
     return sorted[Math.max(0, idx)];
 }
 // ---------------------------------------------------------------------------
-// Schema DDL
+// Schema DDL + statements (default Postgres sink)
 // ---------------------------------------------------------------------------
 const SCHEMA_DDL = `
 CREATE TABLE IF NOT EXISTS _turbine_metrics (
@@ -50,22 +56,102 @@ ON CONFLICT (bucket, model, action) DO UPDATE SET
   error_count = _turbine_metrics.error_count + EXCLUDED.error_count
 `;
 const RETENTION_SQL = `DELETE FROM _turbine_metrics WHERE bucket < NOW() - INTERVAL '1 day' * $1`;
+/**
+ * The default flush target: upserts each aggregate row into `_turbine_metrics`
+ * and prunes rows older than `retentionDays`. The SQL and per-row/retention
+ * ordering are byte-identical to the pre-sink `ObserveEngine.flush` writer.
+ */
+export class PgMetricsSink {
+    pool;
+    retentionDays;
+    constructor(options) {
+        this.pool = new pg.Pool({ connectionString: options.connectionString, max: 1 });
+        this.retentionDays = options.retentionDays ?? 30;
+    }
+    async init() {
+        await this.pool.query(SCHEMA_DDL);
+    }
+    async flush(batch) {
+        if (batch.rows.length === 0)
+            return;
+        for (const row of batch.rows) {
+            try {
+                await this.pool.query(UPSERT_SQL, [
+                    row.bucket,
+                    row.model,
+                    row.action,
+                    row.count,
+                    row.avg,
+                    row.p50,
+                    row.p95,
+                    row.p99,
+                    row.errors,
+                ]);
+            }
+            catch {
+                // Fire-and-forget: never throw from flush
+            }
+        }
+        try {
+            await this.pool.query(RETENTION_SQL, [this.retentionDays]);
+        }
+        catch {
+            // Best effort
+        }
+    }
+    async stop() {
+        await this.pool.end();
+    }
+}
+/**
+ * Forwards each aggregate batch to an HTTP endpoint as a JSON POST. Fire-and-
+ * forget: a failed request is swallowed and never throws, and there are no
+ * retries beyond the engine's next scheduled flush. Aggregates only: the body
+ * carries no SQL text and no parameter values.
+ */
+export class HttpJsonSink {
+    url;
+    headers;
+    fetchFn;
+    constructor(options) {
+        this.url = options.url;
+        this.headers = options.headers ?? {};
+        this.fetchFn = options.fetchFunction ?? fetch;
+    }
+    async flush(batch) {
+        if (batch.rows.length === 0)
+            return;
+        try {
+            await this.fetchFn(this.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...this.headers },
+                body: JSON.stringify(batch),
+            });
+        }
+        catch {
+            // Fire-and-forget: a failing collector never affects the application.
+        }
+    }
+}
 // ---------------------------------------------------------------------------
 // Observe engine
 // ---------------------------------------------------------------------------
 export class ObserveEngine {
-    pool;
+    sink;
     buffer = new Map();
     currentBucket;
     flushIntervalMs;
-    retentionDays;
     timer;
     listener;
     stopped = false;
     constructor(config) {
-        this.pool = new pg.Pool({ connectionString: config.connectionString, max: 1 });
+        if (!config.sink && !config.connectionString) {
+            throw new Error('ObserveEngine requires either a connectionString or a sink');
+        }
+        this.sink =
+            config.sink ??
+                new PgMetricsSink({ connectionString: config.connectionString, retentionDays: config.retentionDays ?? 30 });
         this.flushIntervalMs = config.flushIntervalMs ?? 60_000;
-        this.retentionDays = config.retentionDays ?? 30;
         this.currentBucket = floorToMinute(new Date());
         this.listener = (event) => {
             if (this.stopped)
@@ -89,7 +175,7 @@ export class ObserveEngine {
         return this.listener;
     }
     async init() {
-        await this.pool.query(SCHEMA_DDL);
+        await this.sink.init?.();
         this.timer = setInterval(() => {
             this.flush().catch(() => { });
         }, this.flushIntervalMs);
@@ -104,34 +190,32 @@ export class ObserveEngine {
         const bucket = this.currentBucket;
         const entries = new Map(this.buffer);
         this.buffer.clear();
+        const rows = [];
         for (const [key, entry] of entries) {
             const [model, action] = key.split(':');
             const sorted = entry.durations.slice().sort((a, b) => a - b);
             const count = sorted.length;
             const avg = sorted.reduce((s, v) => s + v, 0) / count;
-            const p50 = percentile(sorted, 0.5);
-            const p95 = percentile(sorted, 0.95);
-            const p99 = percentile(sorted, 0.99);
-            try {
-                await this.pool.query(UPSERT_SQL, [bucket, model, action, count, avg, p50, p95, p99, entry.errors]);
-            }
-            catch {
-                // Fire-and-forget — never throw from flush
-            }
-        }
-        try {
-            await this.pool.query(RETENTION_SQL, [this.retentionDays]);
-        }
-        catch {
-            // Best effort
+            rows.push({
+                bucket,
+                model: model ?? '',
+                action: action ?? '',
+                count,
+                avg,
+                p50: percentile(sorted, 0.5),
+                p95: percentile(sorted, 0.95),
+                p99: percentile(sorted, 0.99),
+                errors: entry.errors,
+            });
         }
+        await this.sink.flush({ rows });
     }
     async stop() {
         this.stopped = true;
         if (this.timer)
             clearInterval(this.timer);
         await this.flush();
-        await this.pool.end();
+        await this.sink.stop?.();
     }
 }
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {