turbine-orm 0.19.1 → 0.21.0

package/dist/cli/studio.d.ts

@@ -79,14 +79,4 @@ export declare function apiBuilder(req: IncomingMessage, res: ServerResponse, ct
 export declare function apiListSavedQueries(res: ServerResponse, ctx: StudioContext, params: URLSearchParams): void;
 export declare function apiCreateSavedQuery(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
 export declare function apiDeleteSavedQuery(res: ServerResponse, ctx: StudioContext, id: string): void;
-/**
- * Accept only SELECT or WITH (CTE) statements. Reject any statement that
- * contains a semicolon followed by non-whitespace (prevents statement
- * stacking), and require the first non-comment keyword to be SELECT or WITH.
- *
- * This is a first-line filter — the transaction's READ ONLY mode is the
- * second line of defense. Both must fail before a destructive statement
- * could run.
- */
-export declare function isReadOnlyStatement(sql: string): boolean;
 //# sourceMappingURL=studio.d.ts.map

package/dist/cli/studio.js

@@ -21,7 +21,7 @@
  * Studio is for inspection. Use the CLI, migrate, or raw SQL for writes.
  */
 import { spawn } from 'node:child_process';
-import { randomBytes, randomUUID } from 'node:crypto';
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { platform } from 'node:os';
@@ -223,13 +223,12 @@ function checkRateLimit(limiter, token) {
     return { allowed: true, resetAt: entry.resetAt };
 }
 function constantTimeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
+    // Hash both inputs to fixed-length 32-byte SHA-256 digests before comparing.
+    // This makes the comparison constant-length (timingSafeEqual never throws on a
+    // length mismatch) and leaks neither length nor content via timing.
+    const ah = createHash('sha256').update(a).digest();
+    const bh = createHash('sha256').update(b).digest();
+    return timingSafeEqual(ah, bh);
 }
 /**
  * Build a helpful "unknown table" error that lists the available tables so the
@@ -535,35 +534,6 @@ function clampInt(value, fallback, min, max) {
         return fallback;
     return Math.min(Math.max(n, min), max);
 }
-/**
- * Accept only SELECT or WITH (CTE) statements. Reject any statement that
- * contains a semicolon followed by non-whitespace (prevents statement
- * stacking), and require the first non-comment keyword to be SELECT or WITH.
- *
- * This is a first-line filter — the transaction's READ ONLY mode is the
- * second line of defense. Both must fail before a destructive statement
- * could run.
- */
-export function isReadOnlyStatement(sql) {
-    const stripped = stripSqlComments(sql).trim();
-    if (!stripped)
-        return false;
-    // Disallow statement stacking. A single trailing `;` is fine.
-    const withoutTrailingSemi = stripped.replace(/;+\s*$/, '');
-    if (withoutTrailingSemi.includes(';'))
-        return false;
-    const firstWord = withoutTrailingSemi.slice(0, 6).toUpperCase();
-    if (firstWord.startsWith('SELECT'))
-        return true;
-    if (firstWord.startsWith('WITH'))
-        return true;
-    return false;
-}
-function stripSqlComments(sql) {
-    // Strip -- line comments and /* block comments */. Not a full SQL parser,
-    // but sufficient to catch the common bypass attempts.
-    return sql.replace(/--[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
-}
 function serializeRow(row) {
     const out = {};
     for (const [k, v] of Object.entries(row)) {

package/dist/client.d.ts

@@ -22,7 +22,7 @@
  * ```
  */
 import pg from 'pg';
-import type { Dialect } from './dialect.js';
+import { type Dialect } from './dialect.js';
 import { type ErrorMessageMode } from './errors.js';
 import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
@@ -83,6 +83,24 @@ export interface PgCompatPool {
     /** Optional — pg.Pool supports 'error' event; HTTP drivers typically do not */
     on?(event: 'error', listener: (err: Error) => void): this;
 }
+/**
+ * Driver-neutral seam. Bundles a pg-compatible connection pool with the SQL
+ * {@link Dialect} that owns every piece of SQL text varying across engines —
+ * parameter placeholders, transaction-control keywords (BEGIN/COMMIT/ROLLBACK/
+ * SAVEPOINT/isolation/set_config), streaming, and capability flags.
+ *
+ * This is the structural boundary that keeps hard-coded Postgres SQL out of
+ * `client.ts`: the pool provides connect/query/transaction/close, the dialect
+ * provides every literal keyword and the placeholder syntax. A future MySQL /
+ * SQLite engine ships a `{ pool, dialect }` pair instead of a raw `pg.Pool`,
+ * exactly as `turbineHttp` ships a serverless pool today.
+ */
+export interface TurbineDriver {
+    /** The underlying pg-compatible connection pool (connect/query/transaction/close). */
+    readonly pool: PgCompatPool;
+    /** SQL dialect: placeholders, transaction keywords, session-config, capability flags. */
+    readonly dialect: Dialect;
+}
 export interface TurbineConfig {
     /**
      * An external pg-compatible pool. Use this to plug in serverless drivers
@@ -211,6 +229,8 @@ export declare class TransactionClient {
     private readonly queryOptions?;
     private readonly tableCache;
     private savepointCounter;
+    /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
+    private readonly dialect;
     constructor(client: pg.PoolClient, schema: SchemaMetadata, middlewares: Middleware[], queryOptions?: QueryInterfaceOptions | undefined);
     /**
      * Get a QueryInterface for a table within this transaction.
@@ -244,6 +264,8 @@ export declare class TurbineClient {
     readonly schema: SchemaMetadata;
     private static int8ParserRegistered;
     private readonly logging;
+    /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
+    private readonly dialect;
     private readonly tableCache;
     private readonly middlewares;
     private readonly queryListeners;
@@ -255,12 +277,14 @@ export declare class TurbineClient {
     private readonly activeSubscriptions;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
-     * Register a middleware function that runs before/after every query.
+     * Register a middleware function that runs around every query.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      *
      * @example
      * ```ts
@@ -272,16 +296,13 @@ export declare class TurbineClient {
      *   return result;
      * });
      *
-     * // Soft-delete middleware
+     * // Result transformation middleware — redact a field on the way out
      * db.$use(async (params, next) => {
-     *   if (params.action === 'findMany' || params.action === 'findUnique') {
-     *     params.args.where = { ...params.args.where, deletedAt: null };
-     *   }
-     *   if (params.action === 'delete') {
-     *     params.action = 'update';
-     *     params.args = { where: params.args.where, data: { deletedAt: new Date() } };
+     *   const result = await next(params);
+     *   if (params.model === 'users' && Array.isArray(result)) {
+     *     for (const row of result as { email?: string }[]) row.email = '[redacted]';
      *   }
-     *   return next(params);
+     *   return result;
      * });
      * ```
      */

package/dist/client.js

@@ -22,7 +22,8 @@
  * ```
  */
 import pg from 'pg';
-import { setErrorMessageMode, TimeoutError, ValidationError, wrapPgError } from './errors.js';
+import { postgresDialect } from './dialect.js';
+import { setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
@@ -82,11 +83,14 @@ export class TransactionClient {
     queryOptions;
     tableCache = new Map();
     savepointCounter = 0;
+    /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
+    dialect;
     constructor(client, schema, middlewares, queryOptions) {
         this.client = client;
         this.schema = schema;
         this.middlewares = middlewares;
         this.queryOptions = queryOptions;
+        this.dialect = queryOptions?.dialect ?? postgresDialect;
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
             const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
@@ -120,14 +124,14 @@ export class TransactionClient {
      */
     async $transaction(fn) {
         const savepointName = `sp_${++this.savepointCounter}`;
-        await this.client.query(`SAVEPOINT ${savepointName}`);
+        await this.client.query(this.dialect.savepointStatement(savepointName));
         try {
             const result = await fn(this);
-            await this.client.query(`RELEASE SAVEPOINT ${savepointName}`);
+            await this.client.query(this.dialect.releaseSavepointStatement(savepointName));
             return result;
         }
         catch (err) {
-            await this.client.query(`ROLLBACK TO SAVEPOINT ${savepointName}`);
+            await this.client.query(this.dialect.rollbackToSavepointStatement(savepointName));
             throw err;
         }
     }
@@ -139,7 +143,7 @@ export class TransactionClient {
         strings.forEach((str, i) => {
             sql += str;
             if (i < values.length) {
-                sql += `$${i + 1}`;
+                sql += this.dialect.paramPlaceholder(i + 1);
             }
         });
         try {
@@ -192,6 +196,8 @@ export class TurbineClient {
     schema;
     static int8ParserRegistered = false;
     logging;
+    /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
+    dialect;
     tableCache = new Map();
     middlewares = [];
     queryListeners = new Set();
@@ -237,6 +243,7 @@ export class TurbineClient {
             TurbineClient.int8ParserRegistered = true;
         }
         this.logging = config.logging ?? false;
+        this.dialect = config.dialect ?? postgresDialect;
         this.schema = schema;
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
@@ -323,12 +330,14 @@ export class TurbineClient {
     // Middleware — intercept all queries
     // -------------------------------------------------------------------------
     /**
-     * Register a middleware function that runs before/after every query.
+     * Register a middleware function that runs around every query.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      *
      * @example
      * ```ts
@@ -340,16 +349,13 @@ export class TurbineClient {
      *   return result;
      * });
      *
-     * // Soft-delete middleware
+     * // Result transformation middleware — redact a field on the way out
      * db.$use(async (params, next) => {
-     *   if (params.action === 'findMany' || params.action === 'findUnique') {
-     *     params.args.where = { ...params.args.where, deletedAt: null };
-     *   }
-     *   if (params.action === 'delete') {
-     *     params.action = 'update';
-     *     params.args = { where: params.args.where, data: { deletedAt: new Date() } };
+     *   const result = await next(params);
+     *   if (params.model === 'users' && Array.isArray(result)) {
+     *     for (const row of result as { email?: string }[]) row.email = '[redacted]';
      *   }
-     *   return next(params);
+     *   return result;
      * });
      * ```
      */
@@ -466,7 +472,7 @@ export class TurbineClient {
         strings.forEach((str, i) => {
             sql += str;
             if (i < values.length) {
-                sql += `$${i + 1}`;
+                sql += this.dialect.paramPlaceholder(i + 1);
             }
         });
         if (this.logging) {
@@ -511,7 +517,7 @@ export class TurbineClient {
      * ```
      */
     sql(strings, ...values) {
-        const { sql, params } = buildTypedSql(strings, values);
+        const { sql, params } = buildTypedSql(strings, values, this.dialect);
         return new TypedSqlQuery(this.pool, sql, params, this.logging);
     }
     // -------------------------------------------------------------------------
@@ -531,13 +537,13 @@ export class TurbineClient {
     async transaction(fn) {
         const client = await this.pool.connect();
         try {
-            await client.query('BEGIN');
+            await client.query(this.dialect.beginStatement());
             const result = await fn(client);
-            await client.query('COMMIT');
+            await client.query(this.dialect.commitStatement());
             return result;
         }
         catch (err) {
-            await client.query('ROLLBACK');
+            await client.query(this.dialect.rollbackStatement());
             throw err;
         }
         finally {
@@ -588,14 +594,10 @@ export class TurbineClient {
         };
         let timedOut = false;
         try {
-            // BEGIN with optional isolation level
-            let beginSQL = 'BEGIN';
-            if (options?.isolationLevel) {
-                const level = ISOLATION_LEVELS[options.isolationLevel];
-                if (level)
-                    beginSQL += ` ISOLATION LEVEL ${level}`;
-            }
-            await client.query(beginSQL);
+            // BEGIN with optional isolation level — the dialect owns the keyword and
+            // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
+            const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
+            await client.query(this.dialect.beginStatement(isolationSql));
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
             // user fn. Any error here propagates to the catch below and rolls back
@@ -603,12 +605,16 @@ export class TurbineClient {
             // is_local=true) — the parameterizable, transaction-scoped equivalent of
             // SET LOCAL — so both name and value are BOUND params, never interpolated.
             if (options?.sessionContext) {
+                if (!this.dialect.supportsRLS) {
+                    throw new UnsupportedFeatureError('sessionContext (RLS session GUCs)', this.dialect.name, 'set_config-based row-level-security context requires PostgreSQL.');
+                }
                 for (const [name, value] of Object.entries(options.sessionContext)) {
                     if (!GUC_NAME_REGEX.test(name)) {
                         throw new ValidationError(`[turbine] Invalid session-context GUC name "${name}" — must match ` +
                             '/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)?$/ (optionally namespaced, e.g. "app.current_tenant")');
                     }
-                    await client.query('SELECT set_config($1, $2, true)', [name, String(value)]);
+                    const cfg = this.dialect.buildSetSessionConfig(name, String(value));
+                    await client.query(cfg.sql, cfg.params);
                 }
             }
             // Create the transaction client with typed table accessors
@@ -654,7 +660,7 @@ export class TurbineClient {
             else {
                 result = await fn(tx);
             }
-            await client.query('COMMIT');
+            await client.query(this.dialect.commitStatement());
             if (this.logging) {
                 console.log('[turbine] Transaction committed');
             }
@@ -667,7 +673,7 @@ export class TurbineClient {
             // when its socket was closed).
             if (!timedOut && !released) {
                 try {
-                    await client.query('ROLLBACK');
+                    await client.query(this.dialect.rollbackStatement());
                 }
                 catch {
                     // Best-effort rollback — the connection may have died mid-query.
@@ -734,6 +740,9 @@ export class TurbineClient {
      * ```
      */
     async $listen(channel, handler) {
+        if (!this.dialect.supportsListenNotify) {
+            throw new UnsupportedFeatureError('$listen (LISTEN/NOTIFY realtime)', this.dialect.name, 'Realtime pub/sub requires PostgreSQL.');
+        }
         validateChannel(channel);
         const quoted = quoteIdent(channel);
         if (this.logging) {
@@ -759,6 +768,9 @@ export class TurbineClient {
      * ```
      */
     async $notify(channel, payload) {
+        if (!this.dialect.supportsListenNotify) {
+            throw new UnsupportedFeatureError('$notify (LISTEN/NOTIFY realtime)', this.dialect.name, 'Realtime pub/sub requires PostgreSQL.');
+        }
         validateChannel(channel);
         if (this.logging) {
             console.log(`[turbine] NOTIFY ${channel}`);