turbine-orm 0.14.0 → 0.16.0

package/dist/observe.js

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+import pg from 'pg';
+function floorToMinute(date) {
+    const d = new Date(date);
+    d.setSeconds(0, 0);
+    return d;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil(p * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+}
+// ---------------------------------------------------------------------------
+// Schema DDL
+// ---------------------------------------------------------------------------
+const SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS _turbine_metrics (
+  id          BIGSERIAL PRIMARY KEY,
+  bucket      TIMESTAMPTZ NOT NULL,
+  model       TEXT NOT NULL,
+  action      TEXT NOT NULL,
+  count       INTEGER NOT NULL DEFAULT 0,
+  avg_ms      REAL NOT NULL DEFAULT 0,
+  p50_ms      REAL NOT NULL DEFAULT 0,
+  p95_ms      REAL NOT NULL DEFAULT 0,
+  p99_ms      REAL NOT NULL DEFAULT 0,
+  error_count INTEGER NOT NULL DEFAULT 0,
+  UNIQUE(bucket, model, action)
+);
+CREATE INDEX IF NOT EXISTS idx_turbine_metrics_bucket ON _turbine_metrics(bucket);
+`;
+const UPSERT_SQL = `
+INSERT INTO _turbine_metrics (bucket, model, action, count, avg_ms, p50_ms, p95_ms, p99_ms, error_count)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+ON CONFLICT (bucket, model, action) DO UPDATE SET
+  count = _turbine_metrics.count + EXCLUDED.count,
+  avg_ms = (_turbine_metrics.avg_ms * _turbine_metrics.count + EXCLUDED.avg_ms * EXCLUDED.count)
+           / (_turbine_metrics.count + EXCLUDED.count),
+  p50_ms = EXCLUDED.p50_ms,
+  p95_ms = EXCLUDED.p95_ms,
+  p99_ms = EXCLUDED.p99_ms,
+  error_count = _turbine_metrics.error_count + EXCLUDED.error_count
+`;
+const RETENTION_SQL = `DELETE FROM _turbine_metrics WHERE bucket < NOW() - INTERVAL '1 day' * $1`;
+// ---------------------------------------------------------------------------
+// Observe engine
+// ---------------------------------------------------------------------------
+export class ObserveEngine {
+    pool;
+    buffer = new Map();
+    currentBucket;
+    flushIntervalMs;
+    retentionDays;
+    timer;
+    listener;
+    stopped = false;
+    constructor(config) {
+        this.pool = new pg.Pool({ connectionString: config.connectionString, max: 1 });
+        this.flushIntervalMs = config.flushIntervalMs ?? 60_000;
+        this.retentionDays = config.retentionDays ?? 30;
+        this.currentBucket = floorToMinute(new Date());
+        this.listener = (event) => {
+            if (this.stopped)
+                return;
+            const nowBucket = floorToMinute(new Date());
+            if (nowBucket.getTime() !== this.currentBucket.getTime()) {
+                this.currentBucket = nowBucket;
+            }
+            const key = `${event.model}:${event.action}`;
+            let entry = this.buffer.get(key);
+            if (!entry) {
+                entry = { durations: [], errors: 0 };
+                this.buffer.set(key, entry);
+            }
+            entry.durations.push(event.duration);
+            if (event.error)
+                entry.errors++;
+        };
+    }
+    getListener() {
+        return this.listener;
+    }
+    async init() {
+        await this.pool.query(SCHEMA_DDL);
+        this.timer = setInterval(() => {
+            this.flush().catch(() => { });
+        }, this.flushIntervalMs);
+        // Unref so it doesn't keep the process alive
+        if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+            this.timer.unref();
+        }
+    }
+    async flush() {
+        if (this.buffer.size === 0)
+            return;
+        const bucket = this.currentBucket;
+        const entries = new Map(this.buffer);
+        this.buffer.clear();
+        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
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.flush();
+        await this.pool.end();
+    }
+}
+// ---------------------------------------------------------------------------
+// Exported helpers for testing
+// ---------------------------------------------------------------------------
+export { floorToMinute, percentile };
+//# sourceMappingURL=observe.js.map

package/dist/query/builder.d.ts

@@ -13,7 +13,7 @@
 import type pg from 'pg';
 import type { Dialect } from '../dialect.js';
 import type { SchemaMetadata } from '../schema.js';
-import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause, WithResult } from './types.js';
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
 export interface DeferredQuery<T> {
     /** SQL text with $1, $2 placeholders */
     sql: string;
@@ -36,6 +36,18 @@ export type MiddlewareFn = (params: {
     action: string;
     args: Record<string, unknown>;
 }) => Promise<unknown>) => Promise<unknown>;
+/** Emitted after every query execution (success or failure). */
+export interface QueryEvent {
+    sql: string;
+    params: unknown[];
+    duration: number;
+    model: string;
+    action: string;
+    rows: number;
+    timestamp: Date;
+    error?: Error;
+}
+export type QueryEventListener = (event: QueryEvent) => void;
 /** Options passed from TurbineClient to QueryInterface */
 export interface QueryInterfaceOptions {
     /** Default LIMIT applied to findMany() when no limit is specified */
@@ -67,6 +79,10 @@ export interface QueryInterfaceOptions {
     sqlCache?: boolean;
     /** SQL dialect implementation. Defaults to PostgreSQL. */
     dialect?: Dialect;
+    /** @internal Set by TransactionClient — signals that this QI runs inside an active transaction. */
+    _txScoped?: boolean;
+    /** @internal Callback from TurbineClient for query event emission. */
+    _onQuery?: (event: QueryEvent) => void;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
@@ -98,6 +114,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly columnArrayTypeMap;
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     private readonly deepWithWarned;
+    /** True when this QI runs inside an active transaction (set via _txScoped option). */
+    private readonly txScoped;
+    /** Original options reference — forwarded to child QIs in nested writes. */
+    private readonly options?;
+    /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
+    private currentAction;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /** Quote an identifier through the active SQL dialect. */
     private q;
@@ -127,6 +149,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * exactly once per table without bleeding state between assertions.
      */
     resetUnlimitedWarnings(): void;
+    private emitQueryEvent;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
@@ -143,9 +166,9 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * To intercept queries before SQL generation, use the raw() method instead.
      */
     private executeWithMiddleware;
-    findUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
-    buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T | null>;
-    findMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>[]>;
+    findUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
+    buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
+    findMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>[]>;
     /**
      * Emit a one-time `console.warn` when {@link findMany} is called without an
      * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
@@ -162,7 +185,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Used by the dev-only deep-with warning guard.
      */
     private measureWithDepth;
-    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T[]>;
+    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T[]>;
     /**
      * Stream rows from a findMany query using PostgreSQL cursors.
      * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
@@ -190,19 +213,24 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * }
      * ```
      */
-    findManyStream<W extends TypedWithClause<R> = {}>(args?: FindManyStreamArgs<T, R, W>): AsyncGenerator<WithResult<T, R, W>, void, undefined>;
-    findFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
-    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T | null>;
-    findFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>>;
-    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T>;
-    findUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W>>;
-    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T>;
+    findManyStream<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyStreamArgs<T, R, W, S, O>): AsyncGenerator<QueryResult<T, R, W, S, O>, void, undefined>;
+    findFirst<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
+    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
+    findFirstOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
+    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
+    findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
+    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
     create(args: CreateArgs<T>): Promise<T>;
     buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
     buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
     update(args: UpdateArgs<T>): Promise<T>;
     buildUpdate(args: UpdateArgs<T>): DeferredQuery<T>;
+    private nestedCreate;
+    private nestedUpdate;
+    private runInImplicitTx;
+    private buildNestedCtx;
+    private makeTxProxy;
     delete(args: DeleteArgs<T>): Promise<T>;
     buildDelete(args: DeleteArgs<T>): DeferredQuery<T>;
     upsert(args: UpsertArgs<T>): Promise<T>;
@@ -502,6 +530,11 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Supports: has, hasEvery, hasSome, isEmpty.
      */
     private buildArrayFilterClauses;
+    /**
+     * Build SQL clause for full-text search using to_tsvector @@ to_tsquery.
+     * The config name is validated to prevent injection (only alphanumeric + underscore).
+     */
+    private buildTextSearchClause;
     /**
      * Get the Postgres array type for a column (used by UNNEST in createMany).
      * Uses pre-computed Map for O(1) lookup instead of linear scan.