turbine-orm 0.78.0 → 0.79.0

package/dist/cjs/prisma-compat.js

@@ -2104,17 +2104,17 @@ function makeRawSurface(exec, ph) {
     return {
         $queryRaw: async (strings, ...values) => {
             const { text, params } = flattenTemplate(strings, values, ph);
-            return (await exec(text, params)).rows;
+            return (await exec(text, params, '$queryRaw')).rows;
         },
         $queryRawUnsafe: async (sql, ...params) => {
-            return (await exec(sql, params)).rows;
+            return (await exec(sql, params, '$queryRawUnsafe')).rows;
         },
         $executeRaw: async (strings, ...values) => {
             const { text, params } = flattenTemplate(strings, values, ph);
-            return (await exec(text, params)).rowCount ?? 0;
+            return (await exec(text, params, '$executeRaw')).rowCount ?? 0;
         },
         $executeRawUnsafe: async (sql, ...params) => {
-            return (await exec(sql, params)).rowCount ?? 0;
+            return (await exec(sql, params, '$executeRawUnsafe')).rowCount ?? 0;
         },
     };
 }
@@ -2371,8 +2371,12 @@ function createPrismaCompatClient(client, map, options = {}) {
         baseDelegates.set(prismaModel, makeDelegate(ctx, mm, () => db.table(mm.table), (fn) => db.$transaction((tx) => fn((n) => tx.table(n)))));
     }
     const ph = placeholderOf(db);
-    const runRaw = async (text, params) => {
+    // Prefer the client's own raw seam, which emits a `$on('query')` event; a
+    // client without one (an older core, a test stub) runs on the pool as before.
+    const runRaw = async (text, params, action) => {
         try {
+            if (typeof db.rawQuery === 'function')
+                return await db.rawQuery(text, params, action);
             return await poolOf(db).query(text, params);
         }
         catch (err) {
@@ -2387,14 +2391,14 @@ function createPrismaCompatClient(client, map, options = {}) {
      * `wrapPgError` is idempotent (it returns an already-typed TurbineError
      * untouched), so the error shape matches the pool path exactly.
      */
-    const txRunRaw = (tx) => async (text, params) => {
+    const txRunRaw = (tx) => async (text, params, action) => {
         if (typeof tx.rawQuery !== 'function') {
             throw decorate(new errors_js_1.ValidationError('prisma-compat: raw SQL inside $transaction needs a transaction client that can execute it ' +
                 '(core TransactionClient.rawQuery). Refusing to run the statement on a pool connection, which would ' +
                 'silently place it outside the transaction.'), ctx.options.prismaErrorCodes);
         }
         try {
-            return await tx.rawQuery(text, params);
+            return await tx.rawQuery(text, params, action);
         }
         catch (err) {
             throw decorate((0, errors_js_1.wrapPgError)(err), ctx.options.prismaErrorCodes);

package/dist/cjs/query/deferred.d.ts

@@ -93,6 +93,21 @@ export interface QueryEvent {
      * observability can see exactly which queries the auto default re-planned.
      */
     strategy?: 'auto-batched';
+    /**
+     * The label of the innermost `db.$tag(label, fn)` scope the query ran in.
+     * Absent outside any scope. Lets a listener attribute a query to the feature
+     * or code path that issued it, which `model` + `action` cannot.
+     */
+    tag?: string;
+    /**
+     * Set on statements that ran as part of a batch rather than on their own:
+     * `'pipeline'` for `db.pipeline(...)`, `'transaction'` for the array form
+     * `$transaction([...])`. A pipeline sends every statement in one round trip,
+     * so its per-statement `duration` is the batch's wall time divided evenly
+     * across the statements (the sum is exact, the split is not). Transaction
+     * batch statements are timed individually. Absent for everything else.
+     */
+    batch?: 'pipeline' | 'transaction';
 }
 export type QueryEventListener = (event: QueryEvent) => void;
 /** Options passed from TurbineClient to QueryInterface */

package/dist/cjs/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/cjs/query-events.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rawIdentity = exports.MAX_QUERY_TAG_LENGTH = exports.RAW_QUERY_MODEL = void 0;
+exports.currentQueryTag = currentQueryTag;
+exports.runWithQueryTag = runWithQueryTag;
+exports.resultRowCount = resultRowCount;
+exports.emitStatementEvent = emitStatementEvent;
+exports.deferredIdentity = deferredIdentity;
+exports.runReportedStatement = runReportedStatement;
+const node_async_hooks_1 = require("node:async_hooks");
+const errors_js_1 = require("./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.
+ */
+exports.RAW_QUERY_MODEL = '$raw';
+/** Longest tag accepted. Keeps a tag a label, not a payload. */
+exports.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 node_async_hooks_1.AsyncLocalStorage();
+        g[SCOPE_KEY] = store;
+    }
+    return store;
+}
+/** The tag in force for the code currently running, or `undefined`. */
+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.
+ */
+function runWithQueryTag(tag, fn) {
+    if (typeof tag !== 'string' || !tag.trim() || tag.length > exports.MAX_QUERY_TAG_LENGTH) {
+        throw new errors_js_1.ValidationError(`$tag() needs a label of 1-${exports.MAX_QUERY_TAG_LENGTH} characters.`);
+    }
+    return scope().run(tag, fn);
+}
+/** Rows a driver result reports: the affected count, else the returned rows. */
+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.
+ */
+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.
+ */
+function deferredIdentity(tag) {
+    const at = tag.lastIndexOf('.');
+    return at > 0 ? { model: tag.slice(0, at), action: tag.slice(at + 1) } : { model: exports.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.
+ */
+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`. */
+const rawIdentity = (action) => ({
+    model: exports.RAW_QUERY_MODEL,
+    action,
+});
+exports.rawIdentity = rawIdentity;

package/dist/cjs/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/cjs/typed-sql.js

@@ -53,6 +53,7 @@ exports.TypedSqlQuery = void 0;
 exports.buildTypedSql = buildTypedSql;
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
+const query_events_js_1 = require("./query-events.js");
 /**
  * Build a `(sql, params)` pair from a tagged-template invocation.
  *
@@ -97,6 +98,7 @@ class TypedSqlQuery {
     params;
     logging;
     runScoped;
+    onQuery;
     constructor(pool, sql, params, logging, 
     /**
      * Runs the execution under the owning client's `errorMessages` mode. Passed
@@ -111,12 +113,19 @@ 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() {
@@ -124,13 +133,8 @@ 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 (0, errors_js_1.wrapPgError)(err);
-            }
+            const result = await (0, query_events_js_1.runReportedStatement)(this.onQuery, (0, query_events_js_1.rawIdentity)('sql'), this.sql, this.params, () => this.pool.query(this.sql, this.params), errors_js_1.wrapPgError);
+            return result.rows;
         });
     }
     /**

package/dist/client.d.ts

@@ -648,9 +648,11 @@ export declare class TransactionClient {
      * inside the same BEGIN/COMMIT (and any active SAVEPOINT) as every other
      * statement in the callback. Driver errors are translated by `wrapPgError`,
      * exactly as pool-scoped and table-scoped queries are. Like {@link raw}, it
-     * emits no `$on('query')` event and runs no middleware.
+     * runs no middleware, and it emits one `$on('query')` event with model
+     * `'$raw'` and `action` set to the optional `action` label (the adapter
+     * passes `'$queryRaw'` / `'$executeRaw'` ...; default `'rawQuery'`).
      */
-    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[]): Promise<{
+    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[], action?: string): Promise<{
         rows: T[];
         rowCount: number | null;
     }>;
@@ -986,6 +988,16 @@ export declare class TurbineClient {
      * On HTTP-based drivers it falls back to sequential execution.
      */
     pipeline<T extends readonly DeferredQuery<unknown>[]>(...args: T | [T, PipelineOptions?]): Promise<PipelineResults<T>>;
+    /**
+     * {@link pipeline} with one `$on('query')` event per statement. Only taken
+     * when a listener is registered, so an unobserved pipeline runs exactly as
+     * before. Each statement's `transform` is wrapped to capture the driver's
+     * row count on the way through (the pipeline returns transformed values, not
+     * driver results). The statements share one round trip, so the batch's wall
+     * time is split evenly across them and each event carries
+     * `batch: 'pipeline'`.
+     */
+    private reportedPipeline;
     /**
      * Check whether the underlying pool supports the real pipeline protocol.
      * Returns `true` for standard pg.Pool TCP connections, `false` for HTTP
@@ -1005,6 +1017,39 @@ export declare class TurbineClient {
      * ```
      */
     raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * @internal The `turbine-orm/prisma-compat` adapter's pool-level raw seam,
+     * the twin of {@link TransactionClient.rawQuery}. NOT application API: use
+     * {@link raw} or {@link sql}, whose tagged templates make concatenating a
+     * value into the SQL text impossible. It exists so the adapter's
+     * `$queryRaw` / `$executeRaw` statements emit a `$on('query')` event (model
+     * `'$raw'`, `action` the adapter's label) instead of running unobserved on
+     * the pool. Errors are translated by `wrapPgError`, like {@link raw}.
+     */
+    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[], action?: string): Promise<{
+        rows: T[];
+        rowCount: number | null;
+    }>;
+    /**
+     * Run `fn` with `tag` attached to every `$on('query')` event it causes, so a
+     * listener can attribute queries to the feature or code path that issued
+     * them. The scope follows async context: queries in awaited helpers,
+     * transactions, pipelines and raw SQL inside `fn` are all tagged. An inner
+     * `$tag` replaces an outer one for its own duration. The tag is event
+     * metadata only and never reaches SQL.
+     *
+     * Throws {@link ValidationError} (E003) for an empty tag or one longer than
+     * {@link MAX_QUERY_TAG_LENGTH} (128) characters.
+     *
+     * @example
+     * ```ts
+     * const order = await db.$tag('checkout', async () => {
+     *   const cart = await db.carts.findUnique({ where: { id } });
+     *   return db.orders.create({ data: { cartId: cart.id } });
+     * });
+     * ```
+     */
+    $tag<R>(tag: string, fn: () => R): R;
     /**
      * Execute a **typed** raw SQL query, Turbine's answer to Prisma's TypedSQL.
      *