turbine-orm 0.4.0 → 0.5.0

package/dist/cjs/serverless.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * @batadata/turbine/serverless — HTTP-based query driver for edge functions
+ *
+ * Use this driver when you cannot establish a direct TCP connection to Postgres
+ * (e.g., Vercel Edge Functions, Cloudflare Workers, Deno Deploy).
+ *
+ * It sends queries as JSON over HTTP to a Turbine query endpoint, which executes
+ * them against the actual database and returns typed results.
+ *
+ * NOTE: This is a scaffold. The server-side query endpoint does not exist yet.
+ * The HTTP protocol and response format are defined here and will be implemented
+ * on the server side in a future release.
+ *
+ * @example
+ * ```ts
+ * import { createServerlessClient } from '@batadata/turbine/serverless';
+ *
+ * const db = createServerlessClient({
+ *   endpoint: 'https://your-turbine-proxy.fly.dev/query',
+ *   authToken: process.env.TURBINE_AUTH_TOKEN!,
+ * });
+ *
+ * const result = await db.query('SELECT * FROM users WHERE id = $1', [1]);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerlessClient = void 0;
+exports.createServerlessClient = createServerlessClient;
+// ---------------------------------------------------------------------------
+// Serverless client
+// ---------------------------------------------------------------------------
+/**
+ * HTTP-based Postgres query client for serverless/edge environments.
+ *
+ * Sends SQL queries as JSON POST requests to a Turbine query endpoint.
+ * Does not require a direct TCP connection to Postgres.
+ */
+class ServerlessClient {
+    config;
+    fetchFn;
+    constructor(config) {
+        if (!config.endpoint) {
+            throw new Error('[turbine/serverless] endpoint is required');
+        }
+        if (!config.authToken) {
+            throw new Error('[turbine/serverless] authToken is required');
+        }
+        this.config = {
+            ...config,
+            timeout: config.timeout ?? 10_000,
+        };
+        this.fetchFn = config.fetch ?? globalThis.fetch;
+    }
+    /**
+     * Execute a single SQL query.
+     *
+     * @param sql - SQL string with $1, $2, ... placeholders
+     * @param params - Parameter values
+     * @returns Query result with typed rows
+     *
+     * @example
+     * ```ts
+     * const result = await client.query<{ id: number; name: string }>(
+     *   'SELECT id, name FROM users WHERE org_id = $1',
+     *   [42]
+     * );
+     * console.log(result.rows);
+     * ```
+     */
+    async query(sql, params) {
+        const request = { sql, params, mode: 'rows' };
+        const response = await this.post('/query', request);
+        return response;
+    }
+    /**
+     * Execute a single SQL query and return the first row, or null.
+     */
+    async queryOne(sql, params) {
+        const request = { sql, params, mode: 'one' };
+        const response = await this.post('/query', request);
+        return response.rows[0] ?? null;
+    }
+    /**
+     * Execute a batch of queries in a single HTTP request.
+     * Optionally wraps them in a transaction.
+     *
+     * @param queries - Array of queries to execute
+     * @param options - Batch options
+     * @returns Array of results, one per query
+     *
+     * @example
+     * ```ts
+     * const results = await client.batch([
+     *   { sql: 'SELECT * FROM users WHERE id = $1', params: [1] },
+     *   { sql: 'SELECT COUNT(*) FROM posts WHERE user_id = $1', params: [1] },
+     * ], { transaction: true });
+     * ```
+     */
+    async batch(queries, options) {
+        const request = {
+            queries,
+            transaction: options?.transaction ?? false,
+        };
+        return this.post('/batch', request);
+    }
+    /**
+     * Tagged template helper for SQL queries.
+     *
+     * @example
+     * ```ts
+     * const users = await client.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE org_id = ${orgId}
+     * `;
+     * ```
+     */
+    async sql(strings, ...values) {
+        let sqlStr = '';
+        strings.forEach((str, i) => {
+            sqlStr += str;
+            if (i < values.length) {
+                sqlStr += `$${i + 1}`;
+            }
+        });
+        const result = await this.query(sqlStr, values);
+        return result.rows;
+    }
+    // -------------------------------------------------------------------------
+    // Internal HTTP transport
+    // -------------------------------------------------------------------------
+    async post(path, body) {
+        const url = this.config.endpoint.replace(/\/$/, '') + path;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await this.fetchFn(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.config.authToken}`,
+                    'User-Agent': '@batadata/turbine-serverless',
+                    ...this.config.headers,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                let parsed;
+                try {
+                    parsed = JSON.parse(errorBody);
+                }
+                catch {
+                    // Not JSON
+                }
+                const message = parsed?.error ?? `HTTP ${response.status}: ${errorBody.slice(0, 200)}`;
+                const err = new Error(`[turbine/serverless] ${message}`);
+                err['status'] = response.status;
+                err['code'] = parsed?.code;
+                throw err;
+            }
+            return (await response.json());
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                throw new Error(`[turbine/serverless] Request timed out after ${this.config.timeout}ms`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+exports.ServerlessClient = ServerlessClient;
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Create a serverless Turbine client for edge/serverless environments.
+ *
+ * @param config - Endpoint URL and auth token
+ * @returns A ServerlessClient instance
+ *
+ * @example
+ * ```ts
+ * import { createServerlessClient } from '@batadata/turbine/serverless';
+ *
+ * const db = createServerlessClient({
+ *   endpoint: process.env.TURBINE_ENDPOINT!,
+ *   authToken: process.env.TURBINE_AUTH_TOKEN!,
+ * });
+ *
+ * const users = await db.sql`SELECT * FROM users LIMIT 10`;
+ * ```
+ */
+function createServerlessClient(config) {
+    return new ServerlessClient(config);
+}

package/dist/cli/config.js

@@ -92,7 +92,7 @@ export function configTemplate(connectionString) {
 
 /**
  * Turbine configuration
- * @see https://github.com/zvndev/turbine-orm
+ * @see https://batadata.com/docs/turbine/config
  */
 const config: TurbineCliConfig = {
   /** Postgres connection string */

package/dist/cli/index.js

@@ -231,7 +231,7 @@ async function cmdInit(args, config) {
  * Define your database schema in TypeScript.
  * Use \`npx turbine push\` to sync it to your database.
  *
- * @see https://github.com/zvndev/turbine-orm
+ * @see https://batadata.com/docs/turbine/schema
  */
 
 import { defineSchema } from 'turbine-orm';
@@ -248,13 +248,20 @@ export default defineSchema({
 `, 'utf-8');
         success(`Created ${cyan(config.schemaFile)}`);
     }
-    // Add .gitignore entry for generated output
+    // Add .gitignore entries for generated output and config (may contain connection strings)
     const gitignorePath = '.gitignore';
     if (existsSync(gitignorePath)) {
         const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
+        const additions = [];
         if (!gitignoreContent.includes('generated/turbine')) {
-            appendFileSync(gitignorePath, '\n# Turbine generated client\ngenerated/turbine/\n');
-            success(`Added ${cyan('generated/turbine/')} to ${cyan('.gitignore')}`);
+            additions.push('generated/turbine/');
+        }
+        if (!gitignoreContent.includes('turbine.config.ts')) {
+            additions.push('turbine.config.ts');
+        }
+        if (additions.length > 0) {
+            appendFileSync(gitignorePath, `\n# Turbine generated client & config\n${additions.join('\n')}\n`);
+            success(`Added ${cyan(additions.join(', '))} to ${cyan('.gitignore')}`);
         }
     }
     // If we have a URL, run initial generate
@@ -669,10 +676,12 @@ async function cmdSeed(args, config) {
             { cmd: 'npx tsx', name: 'tsx' },
             { cmd: 'node --experimental-strip-types', name: 'node' },
         ];
+        // Shell-escape the seed file path to prevent injection
+        const escapedSeedFile = seedFile.replace(/'/g, "'\\''");
         let ran = false;
         for (const runner of runners) {
             try {
-                execSync(`${runner.cmd} ${seedFile}`, {
+                execSync(`${runner.cmd} '${escapedSeedFile}'`, {
                     stdio: 'inherit',
                     env: {
                         ...process.env,
@@ -768,7 +777,7 @@ async function cmdStudio(_args, _config) {
         'A local web UI for browsing your database,',
         'exploring relations, and managing data.',
         '',
-        `Follow ${cyan('@zvndev')} for updates.`,
+        `Follow ${cyan('@batadata')} for updates.`,
     ].join('\n'), { title: bold(cyan('Studio')), padding: 2 }));
     newline();
 }
@@ -819,8 +828,7 @@ function showHelp() {
 // Version
 // ---------------------------------------------------------------------------
 function showVersion() {
-    // Read version from package.json at build time
-    console.log(`turbine-orm v0.3.0`);
+    console.log(`turbine-orm v0.5.0`);
 }
 // ---------------------------------------------------------------------------
 // Main

package/dist/cli/migrate.d.ts

@@ -12,16 +12,14 @@
  *   DROP TABLE users;
  */
 export interface MigrationFile {
-    /** Full filename (e.g. "20260325_001_create_users.sql") */
+    /** Full filename (e.g. "20260325120000_create_users.sql") */
     filename: string;
     /** Absolute path to the file */
     path: string;
-    /** Extracted name portion (e.g. "create_users") */
+    /** Extracted name portion (e.g. "20260325120000_create_users") */
     name: string;
-    /** Timestamp prefix (e.g. "20260325") */
+    /** Timestamp prefix (e.g. "20260325120000") — YYYYMMDDHHMMSS */
     timestamp: string;
-    /** Sequence number (e.g. "001") */
-    sequence: string;
 }
 export interface AppliedMigration {
     id: number;
@@ -36,10 +34,36 @@ export interface MigrationStatus {
     /** True if the file checksum matches the stored checksum (only set for applied migrations) */
     checksumValid?: boolean;
 }
+/**
+ * Parse a migration filename into its components.
+ * Expected format: YYYYMMDDHHMMSS_description.sql
+ */
+export declare function parseMigrationFilename(filename: string): MigrationFile | null;
+/**
+ * Sanitize a migration name: lowercase, replace non-alnum with _, collapse duplicates, trim.
+ */
+export declare function sanitizeName(name: string): string;
+/**
+ * Generate a YYYYMMDDHHMMSS timestamp string from a Date.
+ */
+export declare function formatTimestamp(date: Date): string;
+/**
+ * Get pending migration files — those not yet applied.
+ * Returns files sorted by timestamp (ascending).
+ */
+export declare function getPendingMigrations(migrationsDir: string, applied: string[]): MigrationFile[];
 /**
  * List all migration files in the migrations directory, sorted by name.
  */
 export declare function listMigrationFiles(migrationsDir: string): MigrationFile[];
+/**
+ * Parse migration content string into UP and DOWN sections.
+ * Exported for unit testing.
+ */
+export declare function parseMigrationContent(content: string): {
+    up: string;
+    down: string;
+};
 /**
  * Parse a migration file into UP and DOWN sections.
  */

package/dist/cli/migrate.js

@@ -12,7 +12,7 @@
  *   DROP TABLE users;
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { join } from 'node:path';
 import pg from 'pg';
 // ---------------------------------------------------------------------------
 // Tracking table management
@@ -39,10 +39,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 +50,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 +103,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 = [];
@@ -101,6 +131,13 @@ export function parseMigrationSQL(filePath) {
         down: downLines.join('\n').trim(),
     };
 }
+/**
+ * Parse a migration file into UP and DOWN sections.
+ */
+export function parseMigrationSQL(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    return parseMigrationContent(content);
+}
 /**
  * Simple checksum for a migration file (for drift detection).
  */
@@ -120,40 +157,26 @@ function checksum(content) {
  */
 export function createMigration(migrationsDir, name) {
     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
+    const template = `-- Migration: ${name}
+-- Created: ${now.toISOString()}
 
+-- UP
+-- Write your migration SQL here
 
 -- DOWN
--- Write the rollback SQL here
-
+-- Write your rollback SQL here
 `;
     writeFileSync(filePath, template, 'utf-8');
     return {
         filename,
         path: filePath,
         name: filename.replace(/\.sql$/, ''),
-        timestamp: datePart,
-        sequence: nextSeq,
+        timestamp: ts,
     };
 }
 // ---------------------------------------------------------------------------
@@ -215,7 +238,7 @@ export async function migrateUp(connectionString, migrationsDir, options) {
             return {
                 applied: [],
                 errors: [{
-                        file: { filename: '', path: '', name: '', timestamp: '', sequence: '' },
+                        file: { filename: '', path: '', name: '', timestamp: '' },
                         error: 'Could not acquire migration lock — another migration is already running',
                     }],
             };
@@ -229,7 +252,7 @@ export async function migrateUp(connectionString, migrationsDir, options) {
                 return {
                     applied: [],
                     errors: [{
-                            file: { filename: '', path: '', name: '', timestamp: '', sequence: '' },
+                            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.`,
                         }],
                 };
@@ -293,7 +316,7 @@ export async function migrateDown(connectionString, migrationsDir, options) {
             return {
                 rolledBack: [],
                 errors: [{
-                        file: { filename: '', path: '', name: '', timestamp: '', sequence: '' },
+                        file: { filename: '', path: '', name: '', timestamp: '' },
                         error: 'Could not acquire migration lock — another migration is already running',
                     }],
             };
@@ -314,7 +337,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;

package/dist/cli/ui.js

@@ -191,7 +191,7 @@ export function divider() {
 // ---------------------------------------------------------------------------
 export function banner() {
     console.log('');
-    console.log(`  ${bold(cyan('Turbine ORM'))}`);
+    console.log(`  ${bold(cyan('turbine'))} ${dim('by')} ${bold('BataData')}`);
     console.log(`  ${dim('TypeScript ORM with json_agg nested queries')}`);
     console.log('');
 }

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — TurbineClient
+ * @batadata/turbine — TurbineClient
  *
  * The main entry point for the Turbine TypeScript SDK.
  * Manages connection pooling and provides typed table accessors.
@@ -16,13 +16,13 @@
  * const user = await db.users.findUnique({ where: { id: 1 } });
  *
  * // With base client (dynamic):
- * import { TurbineClient } from 'turbine-orm';
+ * import { TurbineClient } from '@batadata/turbine';
  * const db = new TurbineClient({ connectionString: '...' }, schema);
  * const users = db.table<User>('users');
  * ```
  */
 import pg from 'pg';
-import { QueryInterface, type DeferredQuery } from './query.js';
+import { QueryInterface, type DeferredQuery, type QueryInterfaceOptions } from './query.js';
 import { type PipelineResults } from './pipeline.js';
 import type { SchemaMetadata } from './schema.js';
 export interface TurbineConfig {
@@ -46,6 +46,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 +79,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.
@@ -107,10 +112,16 @@ export declare class TurbineClient {
     private readonly logging;
     private readonly tableCache;
     private readonly middlewares;
+    private readonly queryOptions;
     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