turbine-orm 0.5.0 → 0.7.0

package/dist/cjs/cli/migrate.js

@@ -27,15 +27,19 @@ exports.createMigration = createMigration;
 exports.migrateUp = migrateUp;
 exports.migrateDown = migrateDown;
 exports.migrateStatus = migrateStatus;
+const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const pg_1 = __importDefault(require("pg"));
+const errors_js_1 = require("../errors.js");
+const query_js_1 = require("../query.js");
 // ---------------------------------------------------------------------------
 // Tracking table management
 // ---------------------------------------------------------------------------
 const TRACKING_TABLE = '_turbine_migrations';
+const QUOTED_TRACKING_TABLE = (0, query_js_1.quoteIdent)(TRACKING_TABLE);
 const CREATE_TRACKING_TABLE = `
-  CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
+  CREATE TABLE IF NOT EXISTS ${QUOTED_TRACKING_TABLE} (
     id SERIAL PRIMARY KEY,
     name TEXT NOT NULL UNIQUE,
     checksum TEXT NOT NULL,
@@ -47,7 +51,7 @@ async function ensureTrackingTable(client) {
 }
 async function getAppliedMigrations(client) {
     await ensureTrackingTable(client);
-    const result = await client.query(`SELECT id, name, applied_at, checksum FROM ${TRACKING_TABLE} ORDER BY id ASC`);
+    const result = await client.query(`SELECT id, name, applied_at, checksum FROM ${QUOTED_TRACKING_TABLE} ORDER BY id ASC`);
     return result.rows;
 }
 // ---------------------------------------------------------------------------
@@ -155,30 +159,45 @@ function parseMigrationSQL(filePath) {
     return parseMigrationContent(content);
 }
 /**
- * Simple checksum for a migration file (for drift detection).
+ * SHA-256 checksum for migration drift detection.
+ * Returns a hex-encoded hash of the file content.
  */
 function checksum(content) {
-    let hash = 0;
-    for (let i = 0; i < content.length; i++) {
-        const chr = content.charCodeAt(i);
-        hash = ((hash << 5) - hash + chr) | 0;
-    }
-    return Math.abs(hash).toString(36);
+    return (0, node_crypto_1.createHash)('sha256').update(content, 'utf-8').digest('hex');
+}
+/** Detect legacy djb2 checksums (short alphanumeric strings, pre-v0.6) */
+function isLegacyChecksum(hash) {
+    return hash.length < 64;
 }
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
 /**
  * Create a new migration file.
+ * If `autoContent` is provided, the UP/DOWN sections are pre-populated with the given SQL.
  */
-function createMigration(migrationsDir, name) {
+function createMigration(migrationsDir, name, autoContent) {
     (0, node_fs_1.mkdirSync)(migrationsDir, { recursive: true });
     const now = new Date();
     const ts = formatTimestamp(now);
     const safeName = sanitizeName(name);
     const filename = `${ts}_${safeName}.sql`;
     const filePath = (0, node_path_1.join)(migrationsDir, filename);
-    const template = `-- Migration: ${name}
+    let template;
+    if (autoContent) {
+        template = `-- Migration: ${name} (auto-generated from schema diff)
+-- Created: ${now.toISOString()}
+-- Review this file before running: npx turbine migrate up
+
+-- UP
+${autoContent.up}
+
+-- DOWN
+${autoContent.down}
+`;
+    }
+    else {
+        template = `-- Migration: ${name}
 -- Created: ${now.toISOString()}
 
 -- UP
@@ -187,6 +206,7 @@ function createMigration(migrationsDir, name) {
 -- DOWN
 -- Write your rollback SQL here
 `;
+    }
     (0, node_fs_1.writeFileSync)(filePath, template, 'utf-8');
     return {
         filename,
@@ -201,17 +221,16 @@ function createMigration(migrationsDir, name) {
 /** Fixed lock ID for Turbine migrations — prevents concurrent migrate runs */
 const MIGRATION_LOCK_ID = 8_347_291; // arbitrary but stable
 async function acquireLock(client) {
-    const result = await client.query(`SELECT pg_try_advisory_lock($1)`, [MIGRATION_LOCK_ID]);
+    const result = await client.query(`SELECT pg_try_advisory_lock($1)`, [
+        MIGRATION_LOCK_ID,
+    ]);
     return result.rows[0]?.pg_try_advisory_lock ?? false;
 }
 async function releaseLock(client) {
     await client.query(`SELECT pg_advisory_unlock($1)`, [MIGRATION_LOCK_ID]);
 }
-// ---------------------------------------------------------------------------
-// Checksum validation
-// ---------------------------------------------------------------------------
 /**
- * Validate that applied migration files have not been modified since they were run.
+ * Validate that applied migration files have not been modified or deleted since they were run.
  * Returns an array of mismatched migrations (empty if all are clean).
  */
 async function validateChecksums(client, migrationsDir) {
@@ -221,15 +240,31 @@ async function validateChecksums(client, migrationsDir) {
     const mismatches = [];
     for (const migration of applied) {
         const file = fileMap.get(migration.name);
-        if (!file)
-            continue; // file deleted — not a checksum issue
+        if (!file) {
+            mismatches.push({
+                name: migration.name,
+                expected: migration.checksum,
+                actual: '',
+                type: 'missing',
+            });
+            continue;
+        }
         const content = (0, node_fs_1.readFileSync)(file.path, 'utf-8');
         const currentHash = checksum(content);
         if (currentHash !== migration.checksum) {
+            // Auto-upgrade legacy djb2 checksums to SHA-256 without flagging as modified
+            if (isLegacyChecksum(migration.checksum)) {
+                await client.query(`UPDATE ${QUOTED_TRACKING_TABLE} SET checksum = $1 WHERE name = $2`, [
+                    currentHash,
+                    migration.name,
+                ]);
+                continue;
+            }
             mismatches.push({
                 name: migration.name,
                 expected: migration.checksum,
                 actual: currentHash,
+                type: 'modified',
             });
         }
     }
@@ -251,27 +286,23 @@ async function migrateUp(connectionString, migrationsDir, options) {
         // Acquire advisory lock to prevent concurrent migrations
         const gotLock = await acquireLock(client);
         if (!gotLock) {
-            return {
-                applied: [],
-                errors: [{
-                        file: { filename: '', path: '', name: '', timestamp: '' },
-                        error: 'Could not acquire migration lock — another migration is already running',
-                    }],
-            };
+            throw new errors_js_1.MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
         try {
             await ensureTrackingTable(client);
-            // Validate checksums of already-applied migrations
-            const mismatches = await validateChecksums(client, migrationsDir);
-            if (mismatches.length > 0) {
-                const names = mismatches.map((m) => m.name).join(', ');
-                return {
-                    applied: [],
-                    errors: [{
-                            file: { filename: '', path: '', name: '', timestamp: '' },
-                            error: `Checksum mismatch: migration file(s) modified after application: ${names}. This is dangerous — applied migrations should be immutable. Use --force to skip this check.`,
-                        }],
-                };
+            // Validate checksums of already-applied migrations (skip with --force)
+            if (!options?.force) {
+                const mismatches = await validateChecksums(client, migrationsDir);
+                if (mismatches.length > 0) {
+                    const modified = mismatches.filter((m) => m.type === 'modified');
+                    const missing = mismatches.filter((m) => m.type === 'missing');
+                    const parts = [];
+                    if (modified.length > 0)
+                        parts.push(`modified: ${modified.map((m) => m.name).join(', ')}`);
+                    if (missing.length > 0)
+                        parts.push(`deleted: ${missing.map((m) => m.name).join(', ')}`);
+                    throw new errors_js_1.MigrationError(`[turbine] Migration integrity check failed — ${parts.join('; ')}. Applied migrations should be immutable. Use --force to skip this check.`);
+                }
             }
             const applied = await getAppliedMigrations(client);
             const appliedNames = new Set(applied.map((m) => m.name));
@@ -293,7 +324,7 @@ async function migrateUp(connectionString, migrationsDir, options) {
                 try {
                     await client.query('BEGIN');
                     await client.query(up);
-                    await client.query(`INSERT INTO ${TRACKING_TABLE} (name, checksum) VALUES ($1, $2) ON CONFLICT (name) DO NOTHING`, [file.name, hash]);
+                    await client.query(`INSERT INTO ${QUOTED_TRACKING_TABLE} (name, checksum) VALUES ($1, $2) ON CONFLICT (name) DO NOTHING`, [file.name, hash]);
                     await client.query('COMMIT');
                     results.push(file);
                 }
@@ -329,13 +360,7 @@ async function migrateDown(connectionString, migrationsDir, options) {
     try {
         const gotLock = await acquireLock(client);
         if (!gotLock) {
-            return {
-                rolledBack: [],
-                errors: [{
-                        file: { filename: '', path: '', name: '', timestamp: '' },
-                        error: 'Could not acquire migration lock — another migration is already running',
-                    }],
-            };
+            throw new errors_js_1.MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
         try {
             await ensureTrackingTable(client);
@@ -353,7 +378,7 @@ async function migrateDown(connectionString, migrationsDir, options) {
                 const file = fileMap.get(migration.name);
                 if (!file) {
                     errors.push({
-                        file: { filename: migration.name + '.sql', path: '', name: migration.name, timestamp: '' },
+                        file: { filename: `${migration.name}.sql`, path: '', name: migration.name, timestamp: '' },
                         error: `Migration file not found for "${migration.name}"`,
                     });
                     continue;
@@ -366,7 +391,7 @@ async function migrateDown(connectionString, migrationsDir, options) {
                 try {
                     await client.query('BEGIN');
                     await client.query(down);
-                    await client.query(`DELETE FROM ${TRACKING_TABLE} WHERE name = $1`, [migration.name]);
+                    await client.query(`DELETE FROM ${QUOTED_TRACKING_TABLE} WHERE name = $1`, [migration.name]);
                     await client.query('COMMIT');
                     results.push(file);
                 }

package/dist/cjs/cli/ui.js

@@ -24,9 +24,7 @@ exports.redactUrl = redactUrl;
 // ---------------------------------------------------------------------------
 // ANSI escape codes
 // ---------------------------------------------------------------------------
-const isColorSupported = process.env['NO_COLOR'] == null &&
-    process.env['TERM'] !== 'dumb' &&
-    (process.stdout.isTTY ?? false);
+const isColorSupported = process.env.NO_COLOR == null && process.env.TERM !== 'dumb' && (process.stdout.isTTY ?? false);
 function code(open, close) {
     if (!isColorSupported)
         return (s) => s;
@@ -113,9 +111,7 @@ function table(headers, rows) {
         return ` ${(0, exports.bold)(h)}${' '.repeat(Math.max(0, w - stripAnsi(h).length))} `;
     })
         .join((0, exports.dim)(exports.symbols.vertLine));
-    const separator = colWidths
-        .map((w) => exports.symbols.line.repeat(w + 2))
-        .join((0, exports.dim)(exports.symbols.line));
+    const separator = colWidths.map((w) => exports.symbols.line.repeat(w + 2)).join((0, exports.dim)(exports.symbols.line));
     const bodyLines = rows.map((row) => row
         .map((cell, i) => {
         const w = colWidths[i];
@@ -195,7 +191,7 @@ function info(msg) {
     console.log(`  ${(0, exports.blue)(exports.symbols.info)} ${msg}`);
 }
 function label(key, value) {
-    console.log(`  ${(0, exports.dim)(key + ':')} ${value}`);
+    console.log(`  ${(0, exports.dim)(`${key}:`)} ${value}`);
 }
 function newline() {
     console.log('');
@@ -209,7 +205,7 @@ function divider() {
 // ---------------------------------------------------------------------------
 function banner() {
     console.log('');
-    console.log(`  ${(0, exports.bold)((0, exports.cyan)('turbine'))} ${(0, exports.dim)('by')} ${(0, exports.bold)('BataData')}`);
+    console.log(`  ${(0, exports.bold)((0, exports.cyan)('turbine-orm'))}`);
     console.log(`  ${(0, exports.dim)('TypeScript ORM with json_agg nested queries')}`);
     console.log('');
 }
@@ -226,7 +222,7 @@ function elapsed(startMs) {
 // Strip ANSI codes (for width calculation)
 // ---------------------------------------------------------------------------
 function stripAnsi(s) {
-    // eslint-disable-next-line no-control-regex
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape codes require control characters
     return s.replace(/\x1b\[[0-9;]*m/g, '');
 }
 // ---------------------------------------------------------------------------

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,81 @@ 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;
+        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`);
+            }
         }
         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;
-        }
-        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`);
+            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 +336,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)
@@ -375,7 +426,7 @@ class TurbineClient {
                 let timer;
                 const timeoutPromise = new Promise((_, reject) => {
                     timer = setTimeout(() => {
-                        reject(new Error(`[turbine] Transaction timed out after ${timeout}ms`));
+                        reject(new errors_js_1.TimeoutError(timeout, 'Transaction'));
                     }, timeout);
                 });
                 try {
@@ -426,8 +477,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 +497,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,
         };
     }
 }