turbine-orm 0.5.0 → 0.7.1

package/dist/cjs/client.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * @batadata/turbine — TurbineClient
+ * turbine-orm — TurbineClient
  *
  * The main entry point for the Turbine TypeScript SDK.
  * Manages connection pooling and provides typed table accessors.
@@ -17,7 +17,7 @@
  * const user = await db.users.findUnique({ where: { id: 1 } });
  *
  * // With base client (dynamic):
- * import { TurbineClient } from '@batadata/turbine';
+ * import { TurbineClient } from 'turbine-orm';
  * const db = new TurbineClient({ connectionString: '...' }, schema);
  * const users = db.table<User>('users');
  * ```
@@ -28,22 +28,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TurbineClient = exports.TransactionClient = void 0;
 const pg_1 = __importDefault(require("pg"));
-const query_js_1 = require("./query.js");
+const errors_js_1 = require("./errors.js");
 const pipeline_js_1 = require("./pipeline.js");
-/**
- * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
- * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
- *
- * NOTE: For values exceeding Number.MAX_SAFE_INTEGER, the parser falls back
- * to returning the raw string to avoid precision loss. The generated TypeScript
- * type maps int8/bigint to `number`, which is correct for the vast majority of
- * use cases (IDs, counts, timestamps). If you store values > 2^53 - 1 in a
- * bigint column, the runtime return type will be `string` for those rows.
- */
-pg_1.default.types.setTypeParser(20, (val) => {
-    const n = Number(val);
-    return Number.isSafeInteger(n) ? n : val; // fall back to string for huge values
-});
+const query_js_1 = require("./query.js");
 /** Maps isolation level names to SQL */
 const ISOLATION_LEVELS = {
     ReadUncommitted: 'READ UNCOMMITTED',
@@ -125,20 +112,36 @@ class TransactionClient {
                 sql += `$${i + 1}`;
             }
         });
-        const result = await this.client.query(sql, values);
-        return result.rows;
+        try {
+            const result = await this.client.query(sql, values);
+            return result.rows;
+        }
+        catch (err) {
+            throw (0, errors_js_1.wrapPgError)(err);
+        }
     }
     /**
      * Create a pool-like wrapper around the transaction client.
      * This allows QueryInterface to work with the transaction connection
      * without knowing it's in a transaction.
+     *
+     * pg driver errors thrown by queries are translated into typed Turbine
+     * errors via wrapPgError so transaction-scoped queries surface the same
+     * typed errors as pool-scoped queries.
      */
     createTxPool() {
         const client = this.client;
         // Return a minimal pool-compatible object that routes queries
         // through the transaction client
         return {
-            query: (text, values) => client.query(text, values),
+            query: async (text, values) => {
+                try {
+                    return await client.query(text, values);
+                }
+                catch (err) {
+                    throw (0, errors_js_1.wrapPgError)(err);
+                }
+            },
             connect: () => Promise.resolve(client),
         };
     }
@@ -152,38 +155,86 @@ class TurbineClient {
     pool;
     /** The schema metadata this client was built from */
     schema;
+    static int8ParserRegistered = false;
     logging;
     tableCache = new Map();
     middlewares = [];
     queryOptions;
+    /** True when Turbine created the pool and is responsible for tearing it down */
+    ownsPool = true;
     constructor(config = {}, schema) {
+        /**
+         * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
+         * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
+         *
+         * NOTE: For values exceeding Number.MAX_SAFE_INTEGER, the parser falls back
+         * to returning the raw string to avoid precision loss. The generated TypeScript
+         * type maps int8/bigint to `number`, which is correct for the vast majority of
+         * use cases (IDs, counts, timestamps). If you store values > 2^53 - 1 in a
+         * bigint column, the runtime return type will be `string` for those rows.
+         *
+         * NOTE: We intentionally do NOT register a parser for numeric (OID 1700).
+         * Postgres numeric is arbitrary-precision, so the default pg driver behavior
+         * of returning a string is correct and matches the generated TypeScript type
+         * (numeric → string). Users who want number can cast explicitly in SQL.
+         */
+        // Only register the int8 parser when we own the pg driver. External
+        // pools (Neon HTTP, Vercel Postgres) may ship their own pg-types fork
+        // and rely on their own parser configuration — don't mutate global state
+        // we don't own.
+        if (!config.pool && !TurbineClient.int8ParserRegistered) {
+            pg_1.default.types.setTypeParser(20, (val) => {
+                const n = Number(val);
+                return Number.isSafeInteger(n) ? n : val;
+            });
+            TurbineClient.int8ParserRegistered = true;
+        }
         this.logging = config.logging ?? false;
         this.schema = schema;
         this.queryOptions = {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
         };
-        const poolConfig = {
-            max: config.poolSize ?? 10,
-            idleTimeoutMillis: config.idleTimeoutMs ?? 30_000,
-            connectionTimeoutMillis: config.connectionTimeoutMs ?? 5_000,
-        };
-        if (config.connectionString) {
-            poolConfig.connectionString = config.connectionString;
+        // Apply NotFoundError message redaction mode (default: safe — values are
+        // stripped from messages to avoid leaking PII into error logs).
+        if (config.errorMessages) {
+            (0, errors_js_1.setErrorMessageMode)(config.errorMessages);
         }
-        else {
-            poolConfig.host = config.host ?? 'localhost';
-            poolConfig.port = config.port ?? 5432;
-            poolConfig.database = config.database ?? 'postgres';
-            poolConfig.user = config.user ?? 'postgres';
-            poolConfig.password = config.password;
+        if (config.pool) {
+            // External pool — use directly. Turbine doesn't manage its lifecycle.
+            this.pool = config.pool;
+            this.ownsPool = false;
+            if (this.logging) {
+                console.log(`[turbine] Using external pool — ${Object.keys(schema.tables).length} tables`);
+            }
         }
-        this.pool = new pg_1.default.Pool(poolConfig);
-        this.pool.on('error', (err) => {
-            console.error('[turbine] Unexpected pool error:', err.message);
-        });
-        if (this.logging) {
-            console.log(`[turbine] Pool created — max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
+        else {
+            const poolConfig = {
+                max: config.poolSize ?? 10,
+                idleTimeoutMillis: config.idleTimeoutMs ?? 30_000,
+                connectionTimeoutMillis: config.connectionTimeoutMs ?? 5_000,
+            };
+            if (config.connectionString) {
+                poolConfig.connectionString = config.connectionString;
+            }
+            else {
+                poolConfig.host = config.host ?? 'localhost';
+                poolConfig.port = config.port ?? 5432;
+                poolConfig.database = config.database ?? 'postgres';
+                poolConfig.user = config.user ?? 'postgres';
+                poolConfig.password = config.password;
+            }
+            if (config.ssl !== undefined) {
+                poolConfig.ssl = config.ssl;
+            }
+            this.pool = new pg_1.default.Pool(poolConfig);
+            this.ownsPool = true;
+            this.pool.on('error', (err) => {
+                console.error('[turbine] Unexpected pool error:', err.message);
+            });
+            if (this.logging) {
+                console.log(`[turbine] Pool created — max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
+            }
         }
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
@@ -290,8 +341,13 @@ class TurbineClient {
         if (this.logging) {
             console.log(`[turbine] Raw SQL: ${sql.trim().substring(0, 120)}...`);
         }
-        const result = await this.pool.query(sql, values);
-        return result.rows;
+        try {
+            const result = await this.pool.query(sql, values);
+            return result.rows;
+        }
+        catch (err) {
+            throw (0, errors_js_1.wrapPgError)(err);
+        }
     }
     // -------------------------------------------------------------------------
     // Transaction support (raw — legacy)
@@ -348,6 +404,24 @@ class TurbineClient {
     async $transaction(fn, options) {
         const client = await this.pool.connect();
         const timeout = options?.timeout;
+        /**
+         * Track whether the connection has already been released so the finally
+         * block doesn't double-release. When a timeout fires we destroy the
+         * connection eagerly to abort the in-flight backend query.
+         */
+        let released = false;
+        const releaseOnce = (err) => {
+            if (released)
+                return;
+            released = true;
+            try {
+                client.release(err);
+            }
+            catch {
+                // pg may throw if the client is already released — swallow.
+            }
+        };
+        let timedOut = false;
         try {
             // BEGIN with optional isolation level
             let beginSQL = 'BEGIN';
@@ -371,11 +445,23 @@ class TurbineClient {
             }
             let result;
             if (timeout) {
-                // Race between the function and a timeout
+                // Race between the function and a timeout. If the timeout fires we
+                // need to actually abort the in-flight query — otherwise the backend
+                // keeps running until pg's own timeout, holding a pool slot the whole
+                // time. The simplest reliable cancellation is to destroy the
+                // connection: passing a truthy argument to client.release() tells the
+                // pg pool to discard the client (its socket is closed, which causes
+                // Postgres to abort the active query and roll back the transaction).
+                // The pool will spin up a fresh connection on the next checkout.
                 let timer;
                 const timeoutPromise = new Promise((_, reject) => {
                     timer = setTimeout(() => {
-                        reject(new Error(`[turbine] Transaction timed out after ${timeout}ms`));
+                        timedOut = true;
+                        // Destroy the connection to abort the in-flight backend query.
+                        // We do this BEFORE rejecting so the socket is gone by the time
+                        // the caller's catch block runs.
+                        releaseOnce(new Error('[turbine] Transaction timeout — connection destroyed'));
+                        reject(new errors_js_1.TimeoutError(timeout, 'Transaction'));
                     }, timeout);
                 });
                 try {
@@ -395,14 +481,25 @@ class TurbineClient {
             return result;
         }
         catch (err) {
-            await client.query('ROLLBACK');
+            // If the timeout fired we already destroyed the connection — issuing a
+            // ROLLBACK on a released client would throw "Client has already been
+            // released". Skip the rollback in that case (the backend rolled back
+            // when its socket was closed).
+            if (!timedOut && !released) {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch {
+                    // Best-effort rollback — the connection may have died mid-query.
+                }
+            }
             if (this.logging) {
                 console.log('[turbine] Transaction rolled back');
             }
             throw err;
         }
         finally {
-            client.release();
+            releaseOnce();
         }
     }
     // -------------------------------------------------------------------------
@@ -426,8 +523,17 @@ class TurbineClient {
     }
     /**
      * Gracefully shut down the connection pool.
+     *
+     * If Turbine was given an external pool via `TurbineConfig.pool`, this
+     * method is a no-op — the caller is responsible for the pool's lifecycle.
      */
     async disconnect() {
+        if (!this.ownsPool) {
+            if (this.logging) {
+                console.log('[turbine] disconnect() skipped — external pool is not owned by Turbine');
+            }
+            return;
+        }
         await this.pool.end();
         if (this.logging) {
             console.log('[turbine] Pool disconnected');
@@ -437,12 +543,15 @@ class TurbineClient {
     async end() {
         return this.disconnect();
     }
-    /** Pool statistics for monitoring. */
+    /**
+     * Pool statistics for monitoring. Returns zeros for pools that don't
+     * expose connection counts (e.g., stateless HTTP drivers like Neon).
+     */
     get stats() {
         return {
-            totalCount: this.pool.totalCount,
-            idleCount: this.pool.idleCount,
-            waitingCount: this.pool.waitingCount,
+            totalCount: this.pool.totalCount ?? 0,
+            idleCount: this.pool.idleCount ?? 0,
+            waitingCount: this.pool.waitingCount ?? 0,
         };
     }
 }