turbine-orm 0.4.0 → 0.7.0

package/dist/cli/migrate.js

@@ -11,15 +11,19 @@
  *   -- DOWN
  *   DROP TABLE users;
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import pg from 'pg';
+import { MigrationError } from '../errors.js';
+import { quoteIdent } from '../query.js';
 // ---------------------------------------------------------------------------
 // Tracking table management
 // ---------------------------------------------------------------------------
 const TRACKING_TABLE = '_turbine_migrations';
+const QUOTED_TRACKING_TABLE = 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,
@@ -31,7 +35,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;
 }
 // ---------------------------------------------------------------------------
@@ -39,10 +43,10 @@ async function getAppliedMigrations(client) {
 // ---------------------------------------------------------------------------
 /**
  * Parse a migration filename into its components.
- * Expected format: YYYYMMDD_NNN_description.sql
+ * Expected format: YYYYMMDDHHMMSS_description.sql
  */
-function parseMigrationFilename(filename) {
-    const match = filename.match(/^(\d{8})_(\d{3})_(.+)\.sql$/);
+export function parseMigrationFilename(filename) {
+    const match = filename.match(/^(\d{14})_(.+)\.sql$/);
     if (!match)
         return null;
     return {
@@ -50,9 +54,39 @@ function parseMigrationFilename(filename) {
         path: '', // Set by caller
         name: filename.replace(/\.sql$/, ''),
         timestamp: match[1],
-        sequence: match[2],
     };
 }
+/**
+ * Sanitize a migration name: lowercase, replace non-alnum with _, collapse duplicates, trim.
+ */
+export function sanitizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+/**
+ * Generate a YYYYMMDDHHMMSS timestamp string from a Date.
+ */
+export function formatTimestamp(date) {
+    return [
+        date.getFullYear(),
+        String(date.getMonth() + 1).padStart(2, '0'),
+        String(date.getDate()).padStart(2, '0'),
+        String(date.getHours()).padStart(2, '0'),
+        String(date.getMinutes()).padStart(2, '0'),
+        String(date.getSeconds()).padStart(2, '0'),
+    ].join('');
+}
+/**
+ * Get pending migration files — those not yet applied.
+ * Returns files sorted by timestamp (ascending).
+ */
+export function getPendingMigrations(migrationsDir, applied) {
+    const appliedSet = new Set(applied);
+    return listMigrationFiles(migrationsDir).filter((f) => !appliedSet.has(f.name));
+}
 /**
  * List all migration files in the migrations directory, sorted by name.
  */
@@ -73,10 +107,10 @@ export function listMigrationFiles(migrationsDir) {
     return files;
 }
 /**
- * Parse a migration file into UP and DOWN sections.
+ * Parse migration content string into UP and DOWN sections.
+ * Exported for unit testing.
  */
-export function parseMigrationSQL(filePath) {
-    const content = readFileSync(filePath, 'utf-8');
+export function parseMigrationContent(content) {
     const lines = content.split('\n');
     let section = 'none';
     const upLines = [];
@@ -102,58 +136,67 @@ export function parseMigrationSQL(filePath) {
     };
 }
 /**
- * Simple checksum for a migration file (for drift detection).
+ * Parse a migration file into UP and DOWN sections.
+ */
+export function parseMigrationSQL(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    return parseMigrationContent(content);
+}
+/**
+ * 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 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.
  */
-export function createMigration(migrationsDir, name) {
+export function createMigration(migrationsDir, name, autoContent) {
     mkdirSync(migrationsDir, { recursive: true });
-    // Get today's date as YYYYMMDD
     const now = new Date();
-    const datePart = [
-        now.getFullYear(),
-        String(now.getMonth() + 1).padStart(2, '0'),
-        String(now.getDate()).padStart(2, '0'),
-    ].join('');
-    // Find the next sequence number for today
-    const existing = listMigrationFiles(migrationsDir);
-    const todayMigrations = existing.filter((f) => f.timestamp === datePart);
-    const nextSeq = String(todayMigrations.length + 1).padStart(3, '0');
-    // Sanitize name: lowercase, replace spaces/special chars with underscores
-    const safeName = name
-        .toLowerCase()
-        .replace(/[^a-z0-9_]/g, '_')
-        .replace(/_+/g, '_')
-        .replace(/^_|_$/g, '');
-    const filename = `${datePart}_${nextSeq}_${safeName}.sql`;
+    const ts = formatTimestamp(now);
+    const safeName = sanitizeName(name);
+    const filename = `${ts}_${safeName}.sql`;
     const filePath = join(migrationsDir, filename);
-    const template = `-- UP
--- Write your migration SQL here
+    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
--- Write the rollback SQL here
+${autoContent.down}
+`;
+    }
+    else {
+        template = `-- Migration: ${name}
+-- Created: ${now.toISOString()}
 
+-- UP
+-- Write your migration SQL here
+
+-- DOWN
+-- Write your rollback SQL here
 `;
+    }
     writeFileSync(filePath, template, 'utf-8');
     return {
         filename,
         path: filePath,
         name: filename.replace(/\.sql$/, ''),
-        timestamp: datePart,
-        sequence: nextSeq,
+        timestamp: ts,
     };
 }
 // ---------------------------------------------------------------------------
@@ -162,17 +205,16 @@ export 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) {
@@ -182,15 +224,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 = 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',
             });
         }
     }
@@ -212,27 +270,23 @@ export 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: '', sequence: '' },
-                        error: 'Could not acquire migration lock — another migration is already running',
-                    }],
-            };
+            throw new 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: '', sequence: '' },
-                            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 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));
@@ -254,7 +308,7 @@ export 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);
                 }
@@ -290,13 +344,7 @@ export async function migrateDown(connectionString, migrationsDir, options) {
     try {
         const gotLock = await acquireLock(client);
         if (!gotLock) {
-            return {
-                rolledBack: [],
-                errors: [{
-                        file: { filename: '', path: '', name: '', timestamp: '', sequence: '' },
-                        error: 'Could not acquire migration lock — another migration is already running',
-                    }],
-            };
+            throw new MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
         try {
             await ensureTrackingTable(client);
@@ -314,7 +362,7 @@ export 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: '', sequence: '' },
+                        file: { filename: `${migration.name}.sql`, path: '', name: migration.name, timestamp: '' },
                         error: `Migration file not found for "${migration.name}"`,
                     });
                     continue;
@@ -327,7 +375,7 @@ export 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/cli/ui.js

@@ -7,9 +7,7 @@
 // ---------------------------------------------------------------------------
 // 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;
@@ -96,9 +94,7 @@ export function table(headers, rows) {
         return ` ${bold(h)}${' '.repeat(Math.max(0, w - stripAnsi(h).length))} `;
     })
         .join(dim(symbols.vertLine));
-    const separator = colWidths
-        .map((w) => symbols.line.repeat(w + 2))
-        .join(dim(symbols.line));
+    const separator = colWidths.map((w) => symbols.line.repeat(w + 2)).join(dim(symbols.line));
     const bodyLines = rows.map((row) => row
         .map((cell, i) => {
         const w = colWidths[i];
@@ -177,7 +173,7 @@ export function info(msg) {
     console.log(`  ${blue(symbols.info)} ${msg}`);
 }
 export function label(key, value) {
-    console.log(`  ${dim(key + ':')} ${value}`);
+    console.log(`  ${dim(`${key}:`)} ${value}`);
 }
 export function newline() {
     console.log('');
@@ -191,7 +187,7 @@ export function divider() {
 // ---------------------------------------------------------------------------
 export function banner() {
     console.log('');
-    console.log(`  ${bold(cyan('Turbine ORM'))}`);
+    console.log(`  ${bold(cyan('turbine-orm'))}`);
     console.log(`  ${dim('TypeScript ORM with json_agg nested queries')}`);
     console.log('');
 }
@@ -208,7 +204,7 @@ export function elapsed(startMs) {
 // Strip ANSI codes (for width calculation)
 // ---------------------------------------------------------------------------
 export 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/client.d.ts

@@ -22,10 +22,63 @@
  * ```
  */
 import pg from 'pg';
-import { QueryInterface, type DeferredQuery } from './query.js';
 import { type PipelineResults } from './pipeline.js';
+import { type DeferredQuery, QueryInterface, type QueryInterfaceOptions } from './query.js';
 import type { SchemaMetadata } from './schema.js';
+/**
+ * Minimal pg-compatible query result.
+ * `pg.Pool`, `@neondatabase/serverless` Pool, `@vercel/postgres` Pool and
+ * any driver speaking the node-postgres API all satisfy this shape.
+ */
+export interface PgCompatQueryResult<R = Record<string, unknown>> {
+    rows: R[];
+    rowCount: number | null;
+    fields?: Array<{
+        name: string;
+        dataTypeID: number;
+    }>;
+}
+/**
+ * Minimal pg-compatible client used by TurbineClient for transactions.
+ * `pg.PoolClient` satisfies this; so do Neon and Vercel's equivalents.
+ */
+export interface PgCompatPoolClient {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
+    release(err?: Error | boolean): void;
+}
+/**
+ * Minimal pg-compatible pool. Pass any driver that satisfies this interface
+ * via `TurbineConfig.pool` — lets Turbine run on Neon HTTP, Vercel Postgres,
+ * Cloudflare Hyperdrive, or any other serverless Postgres driver.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { TurbineClient } from 'turbine-orm';
+ *
+ * const neonPool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = new TurbineClient({ pool: neonPool }, schema);
+ * ```
+ */
+export interface PgCompatPool {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+    /** Optional — pools that expose stats (pg.Pool does; Neon HTTP does not) */
+    readonly totalCount?: number;
+    readonly idleCount?: number;
+    readonly waitingCount?: number;
+    /** Optional — pg.Pool supports 'error' event; HTTP drivers typically do not */
+    on?(event: 'error', listener: (err: Error) => void): this;
+}
 export interface TurbineConfig {
+    /**
+     * An external pg-compatible pool. Use this to plug in serverless drivers
+     * like `@neondatabase/serverless`, `@vercel/postgres`, or any other pg-API
+     * compatible pool. When provided, all connection-string fields are ignored
+     * and Turbine will NOT create its own pg.Pool.
+     */
+    pool?: PgCompatPool;
     /** Postgres connection string (e.g. postgres://user:pass@host:5432/db) */
     connectionString?: string;
     /** Host (used if connectionString is not set) */
@@ -38,6 +91,13 @@ export interface TurbineConfig {
     user?: string;
     /** Password */
     password?: string;
+    /** SSL/TLS options for the connection (required for most cloud providers) */
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+        ca?: string;
+        key?: string;
+        cert?: string;
+    };
     /** Maximum number of connections in the pool (default: 10) */
     poolSize?: number;
     /** Idle timeout in ms before a connection is closed (default: 30000) */
@@ -46,6 +106,10 @@ export interface TurbineConfig {
     connectionTimeoutMs?: number;
     /** Enable query logging to console (default: false) */
     logging?: boolean;
+    /** Default LIMIT applied to findMany() when no limit is specified (opt-in, default: undefined) */
+    defaultLimit?: number;
+    /** Log a warning when findMany() is called without a limit (default: false) */
+    warnOnUnlimited?: boolean;
 }
 /** Parameters passed to middleware functions */
 export interface MiddlewareParams {
@@ -75,9 +139,10 @@ export declare class TransactionClient {
     private readonly client;
     readonly schema: SchemaMetadata;
     private readonly middlewares;
+    private readonly queryOptions?;
     private readonly tableCache;
     private savepointCounter;
-    constructor(client: pg.PoolClient, schema: SchemaMetadata, middlewares: Middleware[]);
+    constructor(client: pg.PoolClient, schema: SchemaMetadata, middlewares: Middleware[], queryOptions?: QueryInterfaceOptions | undefined);
     /**
      * Get a QueryInterface for a table within this transaction.
      * Uses the dedicated transaction connection instead of the pool.
@@ -96,6 +161,10 @@ export declare class TransactionClient {
      * 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.
      */
     private createTxPool;
 }
@@ -104,13 +173,22 @@ export declare class TurbineClient {
     readonly pool: pg.Pool;
     /** The schema metadata this client was built from */
     readonly schema: SchemaMetadata;
+    private static int8ParserRegistered;
     private readonly logging;
     private readonly tableCache;
     private readonly middlewares;
+    private readonly queryOptions;
+    /** True when Turbine created the pool and is responsible for tearing it down */
+    private readonly ownsPool;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
      * Register a middleware function that runs before/after 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.
+     *
      * @example
      * ```ts
      * // Query timing middleware
@@ -198,11 +276,17 @@ export declare class TurbineClient {
     connect(): Promise<void>;
     /**
      * 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.
      */
     disconnect(): Promise<void>;
     /** Alias for disconnect() */
     end(): Promise<void>;
-    /** 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(): {
         totalCount: number;
         idleCount: number;