turbine-orm 0.4.0 → 0.7.0

package/dist/cjs/index.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * turbine-orm
+ *
+ * Turbine TypeScript SDK — type-safe Postgres queries with nested relations
+ * and pipeline batching. Feels like Prisma, runs at raw-SQL speed.
+ *
+ * @example
+ * ```ts
+ * // 1. Generate types from your database:
+ * //    npx turbine generate
+ *
+ * // 2. Import the generated client:
+ * import { turbine } from './generated/turbine';
+ *
+ * const db = turbine({ connectionString: process.env.DATABASE_URL });
+ *
+ * // Type-safe queries with auto-complete
+ * const user = await db.users.findUnique({ where: { id: 1 } });
+ *
+ * // Nested relations in a single query (json_agg, no N+1)
+ * const userWithPosts = await db.users.findUnique({
+ *   where: { id: 1 },
+ *   with: { posts: { with: { comments: true } } },
+ * });
+ *
+ * // Pipeline: multiple queries in one round-trip
+ * const [user, count] = await db.pipeline(
+ *   db.users.buildFindUnique({ where: { id: 1 } }),
+ *   db.posts.buildCount({ where: { orgId: 1 } }),
+ * );
+ *
+ * await db.disconnect();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.turbineHttp = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.table = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.isDateType = exports.camelToSnake = exports.QueryInterface = exports.executePipeline = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.RelationError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.ForeignKeyError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.TurbineClient = exports.TransactionClient = void 0;
+// Client
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "TransactionClient", { enumerable: true, get: function () { return client_js_1.TransactionClient; } });
+Object.defineProperty(exports, "TurbineClient", { enumerable: true, get: function () { return client_js_1.TurbineClient; } });
+// Error types
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "CheckConstraintError", { enumerable: true, get: function () { return errors_js_1.CheckConstraintError; } });
+Object.defineProperty(exports, "CircularRelationError", { enumerable: true, get: function () { return errors_js_1.CircularRelationError; } });
+Object.defineProperty(exports, "ConnectionError", { enumerable: true, get: function () { return errors_js_1.ConnectionError; } });
+Object.defineProperty(exports, "ForeignKeyError", { enumerable: true, get: function () { return errors_js_1.ForeignKeyError; } });
+Object.defineProperty(exports, "MigrationError", { enumerable: true, get: function () { return errors_js_1.MigrationError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+Object.defineProperty(exports, "NotNullViolationError", { enumerable: true, get: function () { return errors_js_1.NotNullViolationError; } });
+Object.defineProperty(exports, "RelationError", { enumerable: true, get: function () { return errors_js_1.RelationError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "TurbineError", { enumerable: true, get: function () { return errors_js_1.TurbineError; } });
+Object.defineProperty(exports, "TurbineErrorCode", { enumerable: true, get: function () { return errors_js_1.TurbineErrorCode; } });
+Object.defineProperty(exports, "UniqueConstraintError", { enumerable: true, get: function () { return errors_js_1.UniqueConstraintError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+Object.defineProperty(exports, "wrapPgError", { enumerable: true, get: function () { return errors_js_1.wrapPgError; } });
+// Code generation
+var generate_js_1 = require("./generate.js");
+Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return generate_js_1.generate; } });
+// Introspection
+var introspect_js_1 = require("./introspect.js");
+Object.defineProperty(exports, "introspect", { enumerable: true, get: function () { return introspect_js_1.introspect; } });
+// Pipeline
+var pipeline_js_1 = require("./pipeline.js");
+Object.defineProperty(exports, "executePipeline", { enumerable: true, get: function () { return pipeline_js_1.executePipeline; } });
+// Query builder
+var query_js_1 = require("./query.js");
+Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return query_js_1.QueryInterface; } });
+// Schema utilities
+var schema_js_1 = require("./schema.js");
+Object.defineProperty(exports, "camelToSnake", { enumerable: true, get: function () { return schema_js_1.camelToSnake; } });
+Object.defineProperty(exports, "isDateType", { enumerable: true, get: function () { return schema_js_1.isDateType; } });
+Object.defineProperty(exports, "pgArrayType", { enumerable: true, get: function () { return schema_js_1.pgArrayType; } });
+Object.defineProperty(exports, "pgTypeToTs", { enumerable: true, get: function () { return schema_js_1.pgTypeToTs; } });
+Object.defineProperty(exports, "singularize", { enumerable: true, get: function () { return schema_js_1.singularize; } });
+Object.defineProperty(exports, "snakeToCamel", { enumerable: true, get: function () { return schema_js_1.snakeToCamel; } });
+Object.defineProperty(exports, "snakeToPascal", { enumerable: true, get: function () { return schema_js_1.snakeToPascal; } });
+// Schema builder — define schemas in TypeScript
+var schema_builder_js_1 = require("./schema-builder.js");
+Object.defineProperty(exports, "ColumnBuilder", { enumerable: true, get: function () { return schema_builder_js_1.ColumnBuilder; } });
+Object.defineProperty(exports, "column", { enumerable: true, get: function () { return schema_builder_js_1.column; } });
+Object.defineProperty(exports, "defineSchema", { enumerable: true, get: function () { return schema_builder_js_1.defineSchema; } });
+// Legacy compat (deprecated — use object format with defineSchema)
+Object.defineProperty(exports, "table", { enumerable: true, get: function () { return schema_builder_js_1.table; } });
+// Schema SQL — generate DDL, diff, and push
+var schema_sql_js_1 = require("./schema-sql.js");
+Object.defineProperty(exports, "schemaDiff", { enumerable: true, get: function () { return schema_sql_js_1.schemaDiff; } });
+Object.defineProperty(exports, "schemaPush", { enumerable: true, get: function () { return schema_sql_js_1.schemaPush; } });
+Object.defineProperty(exports, "schemaToSQL", { enumerable: true, get: function () { return schema_sql_js_1.schemaToSQL; } });
+Object.defineProperty(exports, "schemaToSQLString", { enumerable: true, get: function () { return schema_sql_js_1.schemaToSQLString; } });
+// Serverless / edge factory
+var serverless_js_1 = require("./serverless.js");
+Object.defineProperty(exports, "turbineHttp", { enumerable: true, get: function () { return serverless_js_1.turbineHttp; } });

package/dist/cjs/introspect.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * turbine-orm — Schema introspection
+ *
+ * Connects to a live Postgres database, reads information_schema + pg_catalog,
+ * and produces a SchemaMetadata object describing every table, column, relation,
+ * and index in the target schema.
+ *
+ * This is the foundation of `npx turbine generate`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.introspect = introspect;
+const pg_1 = __importDefault(require("pg"));
+const schema_js_1 = require("./schema.js");
+// ---------------------------------------------------------------------------
+// SQL queries (all parameterized, no interpolation)
+// ---------------------------------------------------------------------------
+const SQL_TABLES = `
+  SELECT table_name
+  FROM information_schema.tables
+  WHERE table_schema = $1
+    AND table_type = 'BASE TABLE'
+  ORDER BY table_name
+`;
+const SQL_COLUMNS = `
+  SELECT
+    table_name,
+    column_name,
+    udt_name,
+    data_type,
+    is_nullable,
+    column_default,
+    ordinal_position,
+    character_maximum_length
+  FROM information_schema.columns
+  WHERE table_schema = $1
+  ORDER BY table_name, ordinal_position
+`;
+const SQL_PRIMARY_KEYS = `
+  SELECT
+    tc.table_name,
+    kcu.column_name,
+    kcu.ordinal_position
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name
+    AND tc.table_schema = kcu.table_schema
+  WHERE tc.constraint_type = 'PRIMARY KEY'
+    AND tc.table_schema = $1
+  ORDER BY tc.table_name, kcu.ordinal_position
+`;
+const SQL_FOREIGN_KEYS = `
+  SELECT
+    tc.table_name AS source_table,
+    kcu.column_name AS source_column,
+    ccu.table_name AS target_table,
+    ccu.column_name AS target_column,
+    tc.constraint_name
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name
+    AND tc.table_schema = kcu.table_schema
+  JOIN information_schema.constraint_column_usage ccu
+    ON tc.constraint_name = ccu.constraint_name
+    AND tc.table_schema = ccu.table_schema
+  WHERE tc.constraint_type = 'FOREIGN KEY'
+    AND tc.table_schema = $1
+`;
+const SQL_UNIQUE_CONSTRAINTS = `
+  SELECT
+    tc.table_name,
+    kcu.column_name
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name
+    AND tc.table_schema = kcu.table_schema
+  WHERE tc.constraint_type = 'UNIQUE'
+    AND tc.table_schema = $1
+`;
+const SQL_INDEXES = `
+  SELECT tablename, indexname, indexdef
+  FROM pg_indexes
+  WHERE schemaname = $1
+`;
+const SQL_ENUMS = `
+  SELECT t.typname, e.enumlabel
+  FROM pg_type t
+  JOIN pg_enum e ON t.oid = e.enumtypid
+  JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+  WHERE n.nspname = $1
+  ORDER BY t.typname, e.enumsortorder
+`;
+// ---------------------------------------------------------------------------
+// Main introspection function
+// ---------------------------------------------------------------------------
+async function introspect(options) {
+    const schema = options.schema ?? 'public';
+    const pool = new pg_1.default.Pool({
+        connectionString: options.connectionString,
+        max: 1,
+        connectionTimeoutMillis: 10_000,
+    });
+    try {
+        // Run all information_schema queries in parallel
+        const [tablesResult, columnsResult, pkResult, fkResult, uniqueResult, indexResult, enumResult] = await Promise.all([
+            pool.query(SQL_TABLES, [schema]),
+            pool.query(SQL_COLUMNS, [schema]),
+            pool.query(SQL_PRIMARY_KEYS, [schema]),
+            pool.query(SQL_FOREIGN_KEYS, [schema]),
+            pool.query(SQL_UNIQUE_CONSTRAINTS, [schema]),
+            pool.query(SQL_INDEXES, [schema]),
+            pool.query(SQL_ENUMS, [schema]),
+        ]);
+        // Filter tables by include/exclude
+        let tableNames = tablesResult.rows.map((r) => r.table_name);
+        if (options.include?.length) {
+            const includeSet = new Set(options.include);
+            tableNames = tableNames.filter((t) => includeSet.has(t));
+        }
+        if (options.exclude?.length) {
+            const excludeSet = new Set(options.exclude);
+            tableNames = tableNames.filter((t) => !excludeSet.has(t));
+        }
+        const tableSet = new Set(tableNames);
+        // ----- Group columns by table -----
+        const columnsByTable = new Map();
+        for (const row of columnsResult.rows) {
+            const tableName = row.table_name;
+            if (!tableSet.has(tableName))
+                continue;
+            const isNullable = row.is_nullable === 'YES';
+            const isArray = row.data_type === 'ARRAY';
+            const baseType = isArray ? row.udt_name.slice(1) : row.udt_name;
+            const col = {
+                name: row.column_name,
+                field: (0, schema_js_1.snakeToCamel)(row.column_name),
+                pgType: row.udt_name,
+                tsType: (0, schema_js_1.pgTypeToTs)(isArray ? row.udt_name : baseType, isNullable),
+                nullable: isNullable,
+                hasDefault: row.column_default !== null,
+                isArray,
+                pgArrayType: (0, schema_js_1.pgArrayType)(baseType),
+                maxLength: row.character_maximum_length ?? undefined,
+            };
+            if (!columnsByTable.has(tableName))
+                columnsByTable.set(tableName, []);
+            columnsByTable.get(tableName).push(col);
+        }
+        // ----- Group primary keys by table -----
+        const pkByTable = new Map();
+        for (const row of pkResult.rows) {
+            if (!tableSet.has(row.table_name))
+                continue;
+            if (!pkByTable.has(row.table_name))
+                pkByTable.set(row.table_name, []);
+            pkByTable.get(row.table_name).push(row.column_name);
+        }
+        // ----- Group unique constraints by table -----
+        const uniqueByTable = new Map();
+        for (const row of uniqueResult.rows) {
+            if (!tableSet.has(row.table_name))
+                continue;
+            if (!uniqueByTable.has(row.table_name))
+                uniqueByTable.set(row.table_name, []);
+            // Each unique constraint may be multi-column; for simplicity, treat as single-col here
+            uniqueByTable.get(row.table_name).push([row.column_name]);
+        }
+        // ----- Group indexes by table -----
+        const indexesByTable = new Map();
+        for (const row of indexResult.rows) {
+            if (!tableSet.has(row.tablename))
+                continue;
+            if (!indexesByTable.has(row.tablename))
+                indexesByTable.set(row.tablename, []);
+            const isUnique = row.indexdef.includes('UNIQUE');
+            // Extract column names from indexdef (e.g. "CREATE INDEX idx ON tbl USING btree (col1, col2)")
+            const colMatch = row.indexdef.match(/\((.+)\)/);
+            const columns = colMatch ? colMatch[1].split(',').map((c) => c.trim().replace(/ (ASC|DESC)/i, '')) : [];
+            indexesByTable.get(row.tablename).push({
+                name: row.indexname,
+                columns,
+                unique: isUnique,
+                definition: row.indexdef,
+            });
+        }
+        // ----- Collect enums -----
+        const enums = {};
+        for (const row of enumResult.rows) {
+            if (!enums[row.typname])
+                enums[row.typname] = [];
+            enums[row.typname].push(row.enumlabel);
+        }
+        const foreignKeys = [];
+        for (const row of fkResult.rows) {
+            if (!tableSet.has(row.source_table) || !tableSet.has(row.target_table))
+                continue;
+            foreignKeys.push({
+                sourceTable: row.source_table,
+                sourceColumn: row.source_column,
+                targetTable: row.target_table,
+                targetColumn: row.target_column,
+            });
+        }
+        // ----- Build relations from foreign keys -----
+        // Count FKs per (source, target) pair for disambiguation
+        const fkCounts = new Map();
+        for (const fk of foreignKeys) {
+            const key = `${fk.sourceTable}→${fk.targetTable}`;
+            fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
+        }
+        const relationsByTable = new Map();
+        for (const fk of foreignKeys) {
+            const pairKey = `${fk.sourceTable}→${fk.targetTable}`;
+            const needsDisambiguation = (fkCounts.get(pairKey) ?? 0) > 1;
+            // --- belongsTo on the source (child) table ---
+            // e.g. posts.user_id → users.id creates posts.user (belongsTo)
+            const belongsToName = needsDisambiguation
+                ? (0, schema_js_1.snakeToCamel)(fk.sourceColumn.replace(/_id$/, ''))
+                : (0, schema_js_1.singularize)((0, schema_js_1.snakeToCamel)(fk.targetTable));
+            if (!relationsByTable.has(fk.sourceTable))
+                relationsByTable.set(fk.sourceTable, {});
+            relationsByTable.get(fk.sourceTable)[belongsToName] = {
+                type: 'belongsTo',
+                name: belongsToName,
+                from: fk.sourceTable,
+                to: fk.targetTable,
+                foreignKey: fk.sourceColumn,
+                referenceKey: fk.targetColumn,
+            };
+            // --- hasMany on the target (parent) table ---
+            // e.g. posts.user_id → users.id creates users.posts (hasMany)
+            const hasManyName = needsDisambiguation
+                ? (0, schema_js_1.snakeToCamel)(`${fk.sourceTable}_by_${fk.sourceColumn.replace(/_id$/, '')}`)
+                : (0, schema_js_1.snakeToCamel)(fk.sourceTable);
+            if (!relationsByTable.has(fk.targetTable))
+                relationsByTable.set(fk.targetTable, {});
+            relationsByTable.get(fk.targetTable)[hasManyName] = {
+                type: 'hasMany',
+                name: hasManyName,
+                from: fk.targetTable,
+                to: fk.sourceTable,
+                foreignKey: fk.sourceColumn,
+                referenceKey: fk.targetColumn,
+            };
+        }
+        // ----- Assemble TableMetadata for each table -----
+        const tables = {};
+        for (const tableName of tableNames) {
+            const columns = columnsByTable.get(tableName) ?? [];
+            const columnMap = {};
+            const reverseColumnMap = {};
+            const dateColumns = new Set();
+            const pgTypes = {};
+            const allColumns = [];
+            for (const col of columns) {
+                columnMap[col.field] = col.name;
+                reverseColumnMap[col.name] = col.field;
+                allColumns.push(col.name);
+                pgTypes[col.name] = col.pgType;
+                const baseType = col.isArray ? col.pgType.slice(1) : col.pgType;
+                if ((0, schema_js_1.isDateType)(baseType)) {
+                    dateColumns.add(col.name);
+                }
+            }
+            tables[tableName] = {
+                name: tableName,
+                columns,
+                columnMap,
+                reverseColumnMap,
+                dateColumns,
+                pgTypes,
+                allColumns,
+                primaryKey: pkByTable.get(tableName) ?? [],
+                uniqueColumns: uniqueByTable.get(tableName) ?? [],
+                relations: relationsByTable.get(tableName) ?? {},
+                indexes: indexesByTable.get(tableName) ?? [],
+            };
+        }
+        return { tables, enums };
+    }
+    finally {
+        await pool.end();
+    }
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/pipeline.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * turbine-orm — Pipeline execution
+ *
+ * Pipelines batch multiple independent queries into a single database round-trip.
+ * Instead of N sequential awaits (N round-trips), you get 1 round-trip for all N queries.
+ *
+ * How it works:
+ *   1. Each query method (findUnique, count, etc.) can produce a DeferredQuery descriptor
+ *      containing the SQL, params, and a transform function.
+ *   2. pipeline() collects these descriptors, executes them in a single Postgres
+ *      pipeline/transaction, and maps each result through its transform.
+ *
+ * In the production Turbine engine, this would go through the Rust proxy which uses
+ * actual Postgres pipeline protocol (libpq PQpipelineEnter). For the TS SDK prototype,
+ * we simulate it by running queries concurrently on a single connection or via
+ * a multi-statement batch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executePipeline = executePipeline;
+const errors_js_1 = require("./errors.js");
+// ---------------------------------------------------------------------------
+// Pipeline executor
+// ---------------------------------------------------------------------------
+/**
+ * Execute multiple deferred queries in a single batch.
+ *
+ * Uses a single connection from the pool and runs all queries within
+ * a transaction to guarantee consistency and minimize round-trips.
+ *
+ * @example
+ * ```ts
+ * const [user, count, posts] = await executePipeline(pool, [
+ *   db.users.buildFindUnique({ where: { id: 1 } }),
+ *   db.posts.buildCount({ where: { orgId: 1 } }),
+ *   db.posts.buildFindMany({ where: { userId: 1 }, limit: 10 }),
+ * ]);
+ * ```
+ */
+async function executePipeline(pool, queries) {
+    if (queries.length === 0) {
+        return [];
+    }
+    // Acquire a single connection for the entire batch
+    const client = await pool.connect();
+    try {
+        // Wrap in a transaction for consistency
+        await client.query('BEGIN');
+        // Execute all queries on the same connection — in sequence on a single
+        // connection this avoids pool checkout overhead, and the Postgres server
+        // processes them as a tight batch.
+        //
+        // Execute queries sequentially on the same connection to avoid the
+        // "already executing a query" deprecation in pg@8. This is still faster
+        // than separate pool checkouts because we skip N-1 acquire/release cycles.
+        // Future: use actual Postgres pipeline protocol for true pipelining.
+        const results = [];
+        for (const q of queries) {
+            let raw;
+            try {
+                raw = await client.query(q.sql, q.params);
+            }
+            catch (err) {
+                throw (0, errors_js_1.wrapPgError)(err);
+            }
+            results.push(q.transform(raw));
+        }
+        await client.query('COMMIT');
+        return results;
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}