turbine-orm 0.78.0 → 0.79.0

package/dist/query-events.d.ts

@@ -0,0 +1,82 @@
+/**
+ * turbine-orm, `$on('query')` event metadata: the raw-statement model name
+ * and per-scope query tags for attribution.
+ *
+ * A tag is a caller-chosen label (`'checkout'`, `'nightly-report'`) that rides
+ * on every {@link QueryEvent} emitted while a `db.$tag(label, fn)` callback is
+ * running, including queries issued from inside awaited helpers, transactions
+ * and pipelines. It exists so telemetry can answer "which feature issued this
+ * query", which model + action alone cannot: `orders.findMany` is called from
+ * a dozen places.
+ *
+ * The tag is scoped by async context rather than threaded through every query
+ * argument type. A per-query option would have to be added to every args type,
+ * the runtime option surface, and the prisma-compat unknown-option check, and
+ * it would still miss raw SQL and pipelines. A scope reaches every emitter with
+ * one read at the single emit seam in client.ts, and it costs nothing when no
+ * `$on('query')` listener is registered, because the store is only read on the
+ * emit path.
+ *
+ * ONE scope per realm. The store hangs off `globalThis` under a
+ * `Symbol.for(...)` key for the same reason the warn-once registry does: the
+ * package ships ESM and CJS, and a mixed graph loading both copies must still
+ * see the tag a caller set through either copy.
+ *
+ * The tag never reaches SQL. It is metadata on the in-process event only; what
+ * a listener does with it (log it, forward it to a collector) is the
+ * listener's business.
+ */
+import type { QueryEvent } from './query/deferred.js';
+/**
+ * The `model` reported for statements that are not tied to one table: `raw`,
+ * `sql`, the transaction-scoped `raw` / `rawQuery`, and prisma-compat's
+ * `$queryRaw` / `$executeRaw` family. `action` names the entry point that ran
+ * it. The `$` prefix cannot collide with a generated table accessor.
+ */
+export declare const RAW_QUERY_MODEL = "$raw";
+/** Longest tag accepted. Keeps a tag a label, not a payload. */
+export declare const MAX_QUERY_TAG_LENGTH = 128;
+/** The tag in force for the code currently running, or `undefined`. */
+export declare function currentQueryTag(): string | undefined;
+/**
+ * Run `fn` with `tag` attached to every query event it causes. An inner scope
+ * replaces an outer one for its own duration. Throws {@link ValidationError}
+ * (E003) for a tag that is not a non-empty string of at most
+ * {@link MAX_QUERY_TAG_LENGTH} characters, before `fn` runs.
+ */
+export declare function runWithQueryTag<R>(tag: string, fn: () => R): R;
+/** A client's event sink, as QueryInterfaceOptions carries it. */
+type QueryEventSink = ((event: QueryEvent) => void) | undefined;
+/** Rows a driver result reports: the affected count, else the returned rows. */
+export declare function resultRowCount(result: {
+    rowCount?: number | null;
+    rows?: unknown[];
+} | undefined): number;
+/**
+ * Emit one query event for a statement that ran outside a QueryInterface (raw
+ * SQL, a pipeline slot, a transaction-batch slot). Never throws: a listener
+ * problem must not turn a successful statement into a failed one.
+ */
+export declare function emitStatementEvent(sink: QueryEventSink, event: Omit<QueryEvent, 'timestamp'>): void;
+/**
+ * Split a DeferredQuery tag (`'<table>.<action>'`) into the event's model and
+ * action. A tag without one is reported as a raw statement.
+ */
+export declare function deferredIdentity(tag: string): {
+    model: string;
+    action: string;
+};
+/**
+ * Run one statement and report it. `identity` is the event's model and action
+ * (plus `batch` for a batch slot); for raw SQL the model is
+ * {@link RAW_QUERY_MODEL} and the action names the entry point (`'raw'`,
+ * `'sql'`, `'rawQuery'`, `'$queryRaw'` ...). `wrap` turns a driver error into
+ * what the caller sees, and the event carries that same error.
+ */
+export declare function runReportedStatement<R extends {
+    rowCount?: number | null;
+    rows?: unknown[];
+}>(sink: QueryEventSink, identity: Pick<QueryEvent, 'model' | 'action' | 'batch'>, sql: string, params: unknown[], run: () => Promise<R>, wrap: (err: unknown) => unknown): Promise<R>;
+/** The identity of a raw statement run through `action`. */
+export declare const rawIdentity: (action: string) => Pick<QueryEvent, "model" | "action">;
+export {};

package/dist/query-events.js

@@ -0,0 +1,127 @@
+/**
+ * turbine-orm, `$on('query')` event metadata: the raw-statement model name
+ * and per-scope query tags for attribution.
+ *
+ * A tag is a caller-chosen label (`'checkout'`, `'nightly-report'`) that rides
+ * on every {@link QueryEvent} emitted while a `db.$tag(label, fn)` callback is
+ * running, including queries issued from inside awaited helpers, transactions
+ * and pipelines. It exists so telemetry can answer "which feature issued this
+ * query", which model + action alone cannot: `orders.findMany` is called from
+ * a dozen places.
+ *
+ * The tag is scoped by async context rather than threaded through every query
+ * argument type. A per-query option would have to be added to every args type,
+ * the runtime option surface, and the prisma-compat unknown-option check, and
+ * it would still miss raw SQL and pipelines. A scope reaches every emitter with
+ * one read at the single emit seam in client.ts, and it costs nothing when no
+ * `$on('query')` listener is registered, because the store is only read on the
+ * emit path.
+ *
+ * ONE scope per realm. The store hangs off `globalThis` under a
+ * `Symbol.for(...)` key for the same reason the warn-once registry does: the
+ * package ships ESM and CJS, and a mixed graph loading both copies must still
+ * see the tag a caller set through either copy.
+ *
+ * The tag never reaches SQL. It is metadata on the in-process event only; what
+ * a listener does with it (log it, forward it to a collector) is the
+ * listener's business.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ValidationError } from './errors.js';
+/**
+ * The `model` reported for statements that are not tied to one table: `raw`,
+ * `sql`, the transaction-scoped `raw` / `rawQuery`, and prisma-compat's
+ * `$queryRaw` / `$executeRaw` family. `action` names the entry point that ran
+ * it. The `$` prefix cannot collide with a generated table accessor.
+ */
+export const RAW_QUERY_MODEL = '$raw';
+/** Longest tag accepted. Keeps a tag a label, not a payload. */
+export const MAX_QUERY_TAG_LENGTH = 128;
+const SCOPE_KEY = Symbol.for('turbine.queryTag.scope');
+function scope() {
+    const g = globalThis;
+    let store = g[SCOPE_KEY];
+    if (!store) {
+        store = new AsyncLocalStorage();
+        g[SCOPE_KEY] = store;
+    }
+    return store;
+}
+/** The tag in force for the code currently running, or `undefined`. */
+export function currentQueryTag() {
+    return scope().getStore();
+}
+/**
+ * Run `fn` with `tag` attached to every query event it causes. An inner scope
+ * replaces an outer one for its own duration. Throws {@link ValidationError}
+ * (E003) for a tag that is not a non-empty string of at most
+ * {@link MAX_QUERY_TAG_LENGTH} characters, before `fn` runs.
+ */
+export function runWithQueryTag(tag, fn) {
+    if (typeof tag !== 'string' || !tag.trim() || tag.length > MAX_QUERY_TAG_LENGTH) {
+        throw new ValidationError(`$tag() needs a label of 1-${MAX_QUERY_TAG_LENGTH} characters.`);
+    }
+    return scope().run(tag, fn);
+}
+/** Rows a driver result reports: the affected count, else the returned rows. */
+export function resultRowCount(result) {
+    return typeof result?.rowCount === 'number' ? result.rowCount : (result?.rows?.length ?? 0);
+}
+/**
+ * Emit one query event for a statement that ran outside a QueryInterface (raw
+ * SQL, a pipeline slot, a transaction-batch slot). Never throws: a listener
+ * problem must not turn a successful statement into a failed one.
+ */
+export function emitStatementEvent(sink, event) {
+    try {
+        sink?.({ ...event, timestamp: new Date() });
+    }
+    catch {
+        // Listener errors must never crash a query.
+    }
+}
+/**
+ * Split a DeferredQuery tag (`'<table>.<action>'`) into the event's model and
+ * action. A tag without one is reported as a raw statement.
+ */
+export function deferredIdentity(tag) {
+    const at = tag.lastIndexOf('.');
+    return at > 0 ? { model: tag.slice(0, at), action: tag.slice(at + 1) } : { model: RAW_QUERY_MODEL, action: tag };
+}
+/**
+ * Run one statement and report it. `identity` is the event's model and action
+ * (plus `batch` for a batch slot); for raw SQL the model is
+ * {@link RAW_QUERY_MODEL} and the action names the entry point (`'raw'`,
+ * `'sql'`, `'rawQuery'`, `'$queryRaw'` ...). `wrap` turns a driver error into
+ * what the caller sees, and the event carries that same error.
+ */
+export async function runReportedStatement(sink, identity, sql, params, run, wrap) {
+    const start = performance.now();
+    let result;
+    let error;
+    try {
+        result = await run();
+        return result;
+    }
+    catch (err) {
+        error = wrap(err);
+        throw error;
+    }
+    finally {
+        if (sink) {
+            emitStatementEvent(sink, {
+                ...identity,
+                sql,
+                params,
+                duration: performance.now() - start,
+                rows: resultRowCount(result),
+                ...(error === undefined ? {} : { error: error instanceof Error ? error : new Error(String(error)) }),
+            });
+        }
+    }
+}
+/** The identity of a raw statement run through `action`. */
+export const rawIdentity = (action) => ({
+    model: RAW_QUERY_MODEL,
+    action,
+});

package/dist/typed-sql.d.ts

@@ -49,6 +49,7 @@
  */
 import type { PgCompatPool } from './client.js';
 import { type Dialect } from './dialect.js';
+import type { QueryEvent } from './query/deferred.js';
 /**
  * Build a `(sql, params)` pair from a tagged-template invocation.
  *
@@ -93,6 +94,12 @@ export declare class TypedSqlQuery<T extends Record<string, unknown>> implements
      * behaves exactly as before.
      */
     private readonly runScoped;
+    /**
+     * The owning client's `$on('query')` sink. Each execution emits one event
+     * with model `'$raw'` and action `'sql'`. Absent for a `TypedSqlQuery`
+     * built outside a client, which then emits nothing, as before.
+     */
+    private readonly onQuery?;
     constructor(pool: PgCompatPool, sql: string, params: unknown[], logging: boolean, 
     /**
      * Runs the execution under the owning client's `errorMessages` mode. Passed
@@ -107,7 +114,13 @@ export declare class TypedSqlQuery<T extends Record<string, unknown>> implements
      * Defaults to calling through, so a `TypedSqlQuery` built outside a client
      * behaves exactly as before.
      */
-    runScoped?: <R>(fn: () => R) => R);
+    runScoped?: <R>(fn: () => R) => R, 
+    /**
+     * The owning client's `$on('query')` sink. Each execution emits one event
+     * with model `'$raw'` and action `'sql'`. Absent for a `TypedSqlQuery`
+     * built outside a client, which then emits nothing, as before.
+     */
+    onQuery?: ((event: QueryEvent) => void) | undefined);
     /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
     private run;
     /**

package/dist/typed-sql.js

@@ -49,6 +49,7 @@
  */
 import { postgresDialect } from './dialect.js';
 import { ValidationError, wrapPgError } from './errors.js';
+import { rawIdentity, runReportedStatement } from './query-events.js';
 /**
  * Build a `(sql, params)` pair from a tagged-template invocation.
  *
@@ -93,6 +94,7 @@ export class TypedSqlQuery {
     params;
     logging;
     runScoped;
+    onQuery;
     constructor(pool, sql, params, logging, 
     /**
      * Runs the execution under the owning client's `errorMessages` mode. Passed
@@ -107,12 +109,19 @@ export class TypedSqlQuery {
      * Defaults to calling through, so a `TypedSqlQuery` built outside a client
      * behaves exactly as before.
      */
-    runScoped = (fn) => fn()) {
+    runScoped = (fn) => fn(), 
+    /**
+     * The owning client's `$on('query')` sink. Each execution emits one event
+     * with model `'$raw'` and action `'sql'`. Absent for a `TypedSqlQuery`
+     * built outside a client, which then emits nothing, as before.
+     */
+    onQuery) {
         this.pool = pool;
         this.sql = sql;
         this.params = params;
         this.logging = logging;
         this.runScoped = runScoped;
+        this.onQuery = onQuery;
     }
     /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
     run() {
@@ -120,13 +129,8 @@ export class TypedSqlQuery {
             if (this.logging) {
                 console.log(`[turbine] Typed SQL: ${this.sql.trim().substring(0, 120)}...`);
             }
-            try {
-                const result = await this.pool.query(this.sql, this.params);
-                return result.rows;
-            }
-            catch (err) {
-                throw wrapPgError(err);
-            }
+            const result = await runReportedStatement(this.onQuery, rawIdentity('sql'), this.sql, this.params, () => this.pool.query(this.sql, this.params), wrapPgError);
+            return result.rows;
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.78.0",
+  "version": "0.79.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": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",