turbine-orm 0.4.0 → 0.5.0

package/dist/cjs/schema-builder.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * @batadata/turbine — Schema Builder
+ *
+ * TypeScript-first schema definition API. Define your database schema
+ * as plain objects — no method chaining, no DSL. Fully type-checked,
+ * JSON-serializable, and easy to read.
+ *
+ * @example
+ * ```ts
+ * import { defineSchema } from '@batadata/turbine';
+ *
+ * export default defineSchema({
+ *   users: {
+ *     id:        { type: 'serial', primaryKey: true },
+ *     email:     { type: 'text', unique: true, notNull: true },
+ *     name:      { type: 'text', notNull: true },
+ *     bio:       { type: 'text' },
+ *     role:      { type: 'varchar', maxLength: 50, default: "'user'" },
+ *     orgId:     { type: 'bigint', notNull: true, references: 'organizations.id' },
+ *     createdAt: { type: 'timestamp', default: 'now()' },
+ *   },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.camelToSnake = exports.column = exports.ColumnBuilder = void 0;
+exports.defineSchema = defineSchema;
+exports.table = table;
+/** Maps shorthand names to actual Postgres type strings */
+const TYPE_MAP = {
+    serial: 'BIGSERIAL',
+    bigint: 'BIGINT',
+    integer: 'INTEGER',
+    smallint: 'SMALLINT',
+    text: 'TEXT',
+    varchar: 'VARCHAR',
+    boolean: 'BOOLEAN',
+    timestamp: 'TIMESTAMPTZ',
+    date: 'DATE',
+    json: 'JSONB',
+    uuid: 'UUID',
+    real: 'REAL',
+    double: 'DOUBLE PRECISION',
+    numeric: 'NUMERIC',
+    bytea: 'BYTEA',
+};
+/** Convert a user-facing ColumnDef to the internal ColumnConfig */
+function resolveColumn(def) {
+    return {
+        type: TYPE_MAP[def.type],
+        isPrimaryKey: def.primaryKey ?? false,
+        isNotNull: def.notNull ?? false,
+        isNullable: def.nullable ?? false,
+        isUnique: def.unique ?? false,
+        defaultValue: def.default ?? null,
+        referencesTarget: def.references ?? null,
+        maxLength: def.maxLength ?? null,
+    };
+}
+/** Check if a value is a TableDef (from legacy table() builder) */
+function isTableDef(v) {
+    return typeof v === 'object' && v !== null && 'columns' in v && 'name' in v;
+}
+/**
+ * Define the full database schema using plain objects.
+ *
+ * @example
+ * ```ts
+ * export default defineSchema({
+ *   users: {
+ *     id:    { type: 'serial', primaryKey: true },
+ *     email: { type: 'text', unique: true, notNull: true },
+ *     name:  { type: 'text', notNull: true },
+ *   },
+ *   posts: {
+ *     id:     { type: 'serial', primaryKey: true },
+ *     userId: { type: 'bigint', notNull: true, references: 'users.id' },
+ *     title:  { type: 'text', notNull: true },
+ *   },
+ * });
+ * ```
+ */
+function defineSchema(input) {
+    const tables = {};
+    for (const [tableName, value] of Object.entries(input)) {
+        if (isTableDef(value)) {
+            // Legacy format: defineSchema({ users: table({ ... }) })
+            value.name = tableName;
+            tables[tableName] = value;
+        }
+        else {
+            // Object format: defineSchema({ users: { id: { type: 'serial' }, ... } })
+            const columns = {};
+            for (const [fieldName, def] of Object.entries(value)) {
+                columns[fieldName] = resolveColumn(def);
+            }
+            tables[tableName] = { name: tableName, columns };
+        }
+    }
+    return { tables };
+}
+// ---------------------------------------------------------------------------
+// Legacy compat — ColumnBuilder still works for existing code
+// ---------------------------------------------------------------------------
+class ColumnBuilder {
+    _config;
+    constructor() {
+        this._config = {
+            type: 'TEXT',
+            isPrimaryKey: false,
+            isNotNull: false,
+            isNullable: false,
+            isUnique: false,
+            defaultValue: null,
+            referencesTarget: null,
+            maxLength: null,
+        };
+    }
+    serial() { this._config.type = 'BIGSERIAL'; return this; }
+    bigint() { this._config.type = 'BIGINT'; return this; }
+    integer() { this._config.type = 'INTEGER'; return this; }
+    smallint() { this._config.type = 'SMALLINT'; return this; }
+    text() { this._config.type = 'TEXT'; return this; }
+    varchar(length) { this._config.type = 'VARCHAR'; this._config.maxLength = length; return this; }
+    boolean() { this._config.type = 'BOOLEAN'; return this; }
+    timestamp() { this._config.type = 'TIMESTAMPTZ'; return this; }
+    date() { this._config.type = 'DATE'; return this; }
+    json() { this._config.type = 'JSONB'; return this; }
+    uuid() { this._config.type = 'UUID'; return this; }
+    real() { this._config.type = 'REAL'; return this; }
+    doublePrecision() { this._config.type = 'DOUBLE PRECISION'; return this; }
+    numeric() { this._config.type = 'NUMERIC'; return this; }
+    bytea() { this._config.type = 'BYTEA'; return this; }
+    primaryKey() { this._config.isPrimaryKey = true; return this; }
+    notNull() { this._config.isNotNull = true; return this; }
+    nullable() { this._config.isNullable = true; return this; }
+    unique() { this._config.isUnique = true; return this; }
+    default(val) { this._config.defaultValue = val; return this; }
+    references(target) { this._config.referencesTarget = target; return this; }
+    build() { return { ...this._config }; }
+}
+exports.ColumnBuilder = ColumnBuilder;
+/** @deprecated Use defineSchema() with plain objects instead */
+exports.column = new Proxy({}, {
+    get(_target, prop) {
+        if (prop === 'varchar')
+            return (length) => new ColumnBuilder().varchar(length);
+        return () => {
+            const builder = new ColumnBuilder();
+            if (typeof builder[prop] === 'function')
+                return builder[prop].call(builder);
+            throw new Error(`Unknown column type: ${prop}`);
+        };
+    },
+});
+/** @deprecated Use defineSchema() with plain objects instead */
+function table(columns) {
+    const built = {};
+    for (const [fieldName, builder] of Object.entries(columns)) {
+        built[fieldName] = builder.build();
+    }
+    return { name: '', columns: built };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+var schema_js_1 = require("./schema.js");
+Object.defineProperty(exports, "camelToSnake", { enumerable: true, get: function () { return schema_js_1.camelToSnake; } });

package/dist/cjs/schema-sql.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * @batadata/turbine — Schema SQL Generator
+ *
+ * Converts a SchemaDef (from defineSchema) into executable DDL statements.
+ * Also provides diff and push commands for syncing schema to a live database.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaToSQL = schemaToSQL;
+exports.schemaDiff = schemaDiff;
+exports.schemaPush = schemaPush;
+exports.schemaToSQLString = schemaToSQLString;
+const pg_1 = __importDefault(require("pg"));
+const schema_js_1 = require("./schema.js");
+const query_js_1 = require("./query.js");
+// ---------------------------------------------------------------------------
+// SQL Generation — SchemaDef → CREATE TABLE statements
+// ---------------------------------------------------------------------------
+/**
+ * Convert a SchemaDef into an ordered array of SQL DDL statements.
+ *
+ * Returns CREATE TABLE statements (in dependency order based on references)
+ * followed by CREATE INDEX statements for foreign key columns.
+ */
+function schemaToSQL(schema) {
+    const statements = [];
+    // Topologically sort tables by their foreign key references
+    const sorted = topologicalSort(schema);
+    // Generate CREATE TABLE statements
+    for (const tableName of sorted) {
+        const table = schema.tables[tableName];
+        statements.push(generateCreateTable(table));
+    }
+    // Generate CREATE INDEX for foreign key columns
+    for (const tableName of sorted) {
+        const table = schema.tables[tableName];
+        const indexes = generateForeignKeyIndexes(table);
+        statements.push(...indexes);
+    }
+    return statements;
+}
+/**
+ * Topologically sort tables so that referenced tables come before referencing ones.
+ * Falls back to input order for tables with no dependency ordering.
+ */
+function topologicalSort(schema) {
+    const tableNames = Object.keys(schema.tables);
+    const resolved = new Set();
+    const result = [];
+    const visiting = new Set();
+    function visit(name) {
+        if (resolved.has(name))
+            return;
+        if (visiting.has(name)) {
+            // Circular reference — just add it
+            return;
+        }
+        visiting.add(name);
+        const table = schema.tables[name];
+        if (table) {
+            // Visit all tables this table references
+            for (const col of Object.values(table.columns)) {
+                if (col.referencesTarget) {
+                    const refTable = col.referencesTarget.split('.')[0];
+                    if (refTable !== name && schema.tables[refTable]) {
+                        visit(refTable);
+                    }
+                }
+            }
+        }
+        visiting.delete(name);
+        resolved.add(name);
+        result.push(name);
+    }
+    for (const name of tableNames) {
+        visit(name);
+    }
+    return result;
+}
+/**
+ * Generate a CREATE TABLE statement for a single table definition.
+ */
+function generateCreateTable(table) {
+    const tableName = table.name;
+    const columnDefs = [];
+    for (const [fieldName, config] of Object.entries(table.columns)) {
+        columnDefs.push(generateColumnDef(fieldName, config));
+    }
+    const body = columnDefs.map((d) => `    ${d}`).join(',\n');
+    return `CREATE TABLE ${(0, query_js_1.quoteIdent)(tableName)} (\n${body}\n);`;
+}
+/**
+ * Generate a single column definition line (e.g. "id BIGSERIAL PRIMARY KEY").
+ */
+function generateColumnDef(fieldName, config) {
+    const snakeName = (0, schema_js_1.camelToSnake)(fieldName);
+    const parts = [(0, query_js_1.quoteIdent)(snakeName)];
+    // Type
+    if (config.type === 'VARCHAR' && config.maxLength != null) {
+        parts.push(`VARCHAR(${config.maxLength})`);
+    }
+    else {
+        parts.push(config.type);
+    }
+    // PRIMARY KEY
+    if (config.isPrimaryKey) {
+        parts.push('PRIMARY KEY');
+    }
+    // UNIQUE (only if not primary key — PK is implicitly unique)
+    if (config.isUnique && !config.isPrimaryKey) {
+        parts.push('UNIQUE');
+    }
+    // NOT NULL — serial types are implicitly NOT NULL, but explicit is fine.
+    // A column is NOT NULL if:
+    //   1. Explicitly marked .notNull(), OR
+    //   2. Is a serial (BIGSERIAL implies NOT NULL), OR
+    //   3. Has a primary key (PKs are NOT NULL)
+    // A column is left nullable if .nullable() was called.
+    const isSerial = config.type === 'BIGSERIAL';
+    const implicitNotNull = isSerial || config.isPrimaryKey;
+    if (config.isNotNull && !implicitNotNull) {
+        parts.push('NOT NULL');
+    }
+    // DEFAULT
+    if (config.defaultValue != null) {
+        const sqlDefault = normalizeDefault(config.defaultValue);
+        parts.push(`DEFAULT ${sqlDefault}`);
+    }
+    // REFERENCES
+    if (config.referencesTarget) {
+        const refParts = config.referencesTarget.split('.');
+        if (refParts.length === 2) {
+            parts.push(`REFERENCES ${(0, query_js_1.quoteIdent)(refParts[0])}(${(0, query_js_1.quoteIdent)(refParts[1])})`);
+        }
+    }
+    return parts.join(' ');
+}
+/**
+ * Normalize a default value from the user's schema definition to valid SQL.
+ *
+ * Examples:
+ *   'now()'  → NOW()
+ *   "'free'" → 'free'
+ *   'false'  → false
+ *   '0'      → 0
+ */
+function normalizeDefault(val) {
+    const upper = val.toUpperCase().trim();
+    // Known SQL constants
+    if (['TRUE', 'FALSE', 'NULL'].includes(upper)) {
+        return upper;
+    }
+    // Known SQL function calls: NOW(), CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME, GEN_RANDOM_UUID()
+    const allowedFunctions = [
+        'NOW()', 'CURRENT_TIMESTAMP', 'CURRENT_DATE', 'CURRENT_TIME', 'GEN_RANDOM_UUID()',
+    ];
+    if (allowedFunctions.includes(upper)) {
+        return upper;
+    }
+    // Numeric literals (integer or decimal, optionally negative)
+    if (/^-?\d+(\.\d+)?$/.test(val.trim())) {
+        return val.trim();
+    }
+    // Simple single-quoted string literals (no nested quotes)
+    if (/^'[^']*'$/.test(val.trim())) {
+        return val.trim();
+    }
+    throw new Error(`Unsupported default value: ${val}. Use a SQL function, numeric, string literal, or NULL.`);
+}
+/**
+ * Generate CREATE INDEX statements for foreign key columns.
+ * Only generates indexes for columns that have a REFERENCES clause.
+ */
+function generateForeignKeyIndexes(table) {
+    const indexes = [];
+    for (const [fieldName, config] of Object.entries(table.columns)) {
+        if (config.referencesTarget) {
+            const snakeName = (0, schema_js_1.camelToSnake)(fieldName);
+            const indexName = `idx_${table.name}_${snakeName}`;
+            indexes.push(`CREATE INDEX ${(0, query_js_1.quoteIdent)(indexName)} ON ${(0, query_js_1.quoteIdent)(table.name)}(${(0, query_js_1.quoteIdent)(snakeName)});`);
+        }
+    }
+    return indexes;
+}
+/**
+ * Compare a SchemaDef against a live Postgres database and return the diff.
+ *
+ * Connects to the database, inspects the public schema, and computes what
+ * DDL is needed to make the database match the schema definition.
+ */
+async function schemaDiff(schema, connectionString) {
+    const client = new pg_1.default.Client({ connectionString });
+    await client.connect();
+    try {
+        // Get existing tables in the public schema
+        const tableResult = await client.query(`SELECT tablename FROM pg_tables WHERE schemaname = 'public'`);
+        const existingTables = new Set(tableResult.rows.map((r) => r.tablename));
+        // Get existing columns for all tables
+        const columnResult = await client.query(`SELECT table_name, column_name, data_type, udt_name, is_nullable, column_default, character_maximum_length
+       FROM information_schema.columns
+       WHERE table_schema = 'public'
+       ORDER BY table_name, ordinal_position`);
+        const dbColumns = {};
+        for (const row of columnResult.rows) {
+            if (!dbColumns[row.table_name]) {
+                dbColumns[row.table_name] = {};
+            }
+            dbColumns[row.table_name][row.column_name] = {
+                dataType: row.data_type,
+                udtName: row.udt_name,
+                isNullable: row.is_nullable === 'YES',
+                columnDefault: row.column_default,
+                maxLength: row.character_maximum_length,
+            };
+        }
+        const schemaTableNames = new Set(Object.keys(schema.tables));
+        const result = { create: [], alter: [], drop: [], statements: [] };
+        // Tables to create (in schema but not in DB)
+        const sorted = topologicalSort(schema);
+        for (const tableName of sorted) {
+            if (!existingTables.has(tableName)) {
+                const tableDef = schema.tables[tableName];
+                result.create.push(tableDef);
+                result.statements.push(generateCreateTable(tableDef));
+                // Also add FK indexes
+                result.statements.push(...generateForeignKeyIndexes(tableDef));
+            }
+        }
+        // Tables to drop (in DB but not in schema)
+        for (const existingTable of existingTables) {
+            if (!schemaTableNames.has(existingTable)) {
+                result.drop.push(existingTable);
+                // We don't auto-generate DROP statements for safety
+            }
+        }
+        // Tables to alter (exist in both)
+        for (const tableName of sorted) {
+            if (!existingTables.has(tableName))
+                continue;
+            const tableDef = schema.tables[tableName];
+            const dbCols = dbColumns[tableName] ?? {};
+            const alterDef = { table: tableName, columns: [] };
+            for (const [fieldName, config] of Object.entries(tableDef.columns)) {
+                const snakeName = (0, schema_js_1.camelToSnake)(fieldName);
+                const dbCol = dbCols[snakeName];
+                if (!dbCol) {
+                    // Column exists in schema but not in DB — ADD COLUMN
+                    const colDef = generateColumnDef(fieldName, config);
+                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ADD COLUMN ${colDef};`;
+                    alterDef.columns.push({ column: snakeName, action: 'add', sql });
+                    result.statements.push(sql);
+                    continue;
+                }
+                // Check type mismatch
+                const expectedUdt = schemaTypeToUdt(config);
+                if (expectedUdt && dbCol.udtName !== expectedUdt) {
+                    const sqlType = config.type === 'VARCHAR' && config.maxLength
+                        ? `VARCHAR(${config.maxLength})`
+                        : config.type;
+                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} TYPE ${sqlType};`;
+                    alterDef.columns.push({ column: snakeName, action: 'alter_type', sql });
+                    result.statements.push(sql);
+                }
+                // Check NOT NULL mismatch
+                const shouldBeNotNull = config.isNotNull || config.isPrimaryKey || config.type === 'BIGSERIAL';
+                const isCurrentlyNullable = dbCol.isNullable;
+                if (shouldBeNotNull && isCurrentlyNullable && !config.isNullable) {
+                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} SET NOT NULL;`;
+                    alterDef.columns.push({ column: snakeName, action: 'set_not_null', sql });
+                    result.statements.push(sql);
+                }
+                else if (!shouldBeNotNull && !isCurrentlyNullable && config.isNullable) {
+                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} ALTER COLUMN ${(0, query_js_1.quoteIdent)(snakeName)} DROP NOT NULL;`;
+                    alterDef.columns.push({ column: snakeName, action: 'drop_not_null', sql });
+                    result.statements.push(sql);
+                }
+            }
+            // Check for columns in DB that are not in schema
+            for (const dbColName of Object.keys(dbCols)) {
+                const hasField = Object.entries(tableDef.columns).some(([fieldName]) => (0, schema_js_1.camelToSnake)(fieldName) === dbColName);
+                if (!hasField) {
+                    const sql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} DROP COLUMN ${(0, query_js_1.quoteIdent)(dbColName)};`;
+                    alterDef.columns.push({ column: dbColName, action: 'drop', sql });
+                    // Don't auto-add drops to statements for safety — user must opt in
+                }
+            }
+            if (alterDef.columns.length > 0) {
+                result.alter.push(alterDef);
+            }
+        }
+        return result;
+    }
+    finally {
+        await client.end();
+    }
+}
+/**
+ * Map a schema column type to its expected PostgreSQL UDT name.
+ */
+function schemaTypeToUdt(config) {
+    const map = {
+        BIGSERIAL: 'int8',
+        BIGINT: 'int8',
+        INTEGER: 'int4',
+        SMALLINT: 'int2',
+        TEXT: 'text',
+        VARCHAR: 'varchar',
+        BOOLEAN: 'bool',
+        TIMESTAMPTZ: 'timestamptz',
+        DATE: 'date',
+        JSONB: 'jsonb',
+        UUID: 'uuid',
+        REAL: 'float4',
+        'DOUBLE PRECISION': 'float8',
+        NUMERIC: 'numeric',
+        BYTEA: 'bytea',
+    };
+    return map[config.type] ?? null;
+}
+/**
+ * Push a schema definition to a live database.
+ *
+ * Computes the diff, then executes the resulting DDL statements in a
+ * single transaction. This is a destructive operation for ADD/ALTER —
+ * it will NOT drop tables or columns unless explicitly configured.
+ */
+async function schemaPush(schema, connectionString, options = {}) {
+    const diff = await schemaDiff(schema, connectionString);
+    const result = {
+        statementsExecuted: 0,
+        statements: diff.statements,
+        tablesCreated: diff.create.map((t) => t.name),
+        tablesAltered: diff.alter.map((a) => a.table),
+    };
+    if (options.dryRun || diff.statements.length === 0) {
+        return result;
+    }
+    // Execute all statements in a transaction
+    const client = new pg_1.default.Client({ connectionString });
+    await client.connect();
+    try {
+        await client.query('BEGIN');
+        for (const sql of diff.statements) {
+            await client.query(sql);
+            result.statementsExecuted++;
+        }
+        await client.query('COMMIT');
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        await client.end();
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Utility: format schema as SQL string (convenience for debugging/printing)
+// ---------------------------------------------------------------------------
+/**
+ * Generate the full DDL as a single formatted string.
+ * Useful for printing or saving to a .sql file.
+ */
+function schemaToSQLString(schema) {
+    const statements = schemaToSQL(schema);
+    return statements.join('\n\n') + '\n';
+}

package/dist/cjs/schema.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * @batadata/turbine — Schema metadata types
+ *
+ * These types represent the introspected database schema at runtime.
+ * They're used by the query builder, code generator, and CLI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pgTypeToTs = pgTypeToTs;
+exports.isDateType = isDateType;
+exports.pgArrayType = pgArrayType;
+exports.snakeToCamel = snakeToCamel;
+exports.camelToSnake = camelToSnake;
+exports.snakeToPascal = snakeToPascal;
+exports.singularize = singularize;
+// ---------------------------------------------------------------------------
+// Type mapping: Postgres → TypeScript
+// ---------------------------------------------------------------------------
+const PG_TO_TS = {
+    // Integers
+    int2: 'number',
+    int4: 'number',
+    int8: 'number',
+    float4: 'number',
+    float8: 'number',
+    oid: 'number',
+    // Precision-sensitive — keep as string to avoid JS float issues
+    numeric: 'string',
+    money: 'string',
+    // Boolean
+    bool: 'boolean',
+    // Strings
+    text: 'string',
+    varchar: 'string',
+    char: 'string',
+    bpchar: 'string',
+    name: 'string',
+    uuid: 'string',
+    citext: 'string',
+    xml: 'string',
+    // Dates & times
+    timestamptz: 'Date',
+    timestamp: 'Date',
+    date: 'Date',
+    time: 'string',
+    timetz: 'string',
+    interval: 'string',
+    // JSON
+    json: 'unknown',
+    jsonb: 'unknown',
+    // Binary
+    bytea: 'Buffer',
+    // Network
+    inet: 'string',
+    cidr: 'string',
+    macaddr: 'string',
+    // Geometric
+    point: 'string',
+    line: 'string',
+    lseg: 'string',
+    box: 'string',
+    path: 'string',
+    polygon: 'string',
+    circle: 'string',
+    // TSVector
+    tsvector: 'string',
+    tsquery: 'string',
+};
+const DATE_TYPES = new Set(['timestamptz', 'timestamp', 'date']);
+const PG_TO_ARRAY = {
+    int2: 'smallint[]',
+    int4: 'integer[]',
+    int8: 'bigint[]',
+    float4: 'real[]',
+    float8: 'double precision[]',
+    numeric: 'numeric[]',
+    bool: 'boolean[]',
+    text: 'text[]',
+    varchar: 'text[]',
+    char: 'text[]',
+    bpchar: 'text[]',
+    uuid: 'uuid[]',
+    timestamptz: 'timestamptz[]',
+    timestamp: 'timestamp[]',
+    date: 'date[]',
+    json: 'json[]',
+    jsonb: 'jsonb[]',
+    bytea: 'bytea[]',
+    inet: 'inet[]',
+};
+/** Map a Postgres type to its TypeScript equivalent */
+function pgTypeToTs(pgType, nullable) {
+    // Array types: udt_name starts with '_'
+    if (pgType.startsWith('_')) {
+        const elementType = pgTypeToTs(pgType.slice(1), false);
+        const tsType = `${elementType}[]`;
+        return nullable ? `${tsType} | null` : tsType;
+    }
+    const tsType = PG_TO_TS[pgType] ?? 'unknown';
+    return nullable ? `${tsType} | null` : tsType;
+}
+/** Check if a Postgres type is a date/timestamp that needs Date parsing */
+function isDateType(pgType) {
+    return DATE_TYPES.has(pgType);
+}
+/** Get the Postgres array cast type for UNNEST batch inserts */
+function pgArrayType(pgType) {
+    return PG_TO_ARRAY[pgType] ?? 'text[]';
+}
+// ---------------------------------------------------------------------------
+// Name conversion utilities
+// ---------------------------------------------------------------------------
+/** snake_case → camelCase */
+function snakeToCamel(s) {
+    return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+/** camelCase → snake_case */
+function camelToSnake(s) {
+    return s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+/** snake_case → PascalCase (for type names) */
+function snakeToPascal(s) {
+    return s
+        .split('_')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('');
+}
+/** Naive singularize: "posts" → "post", "categories" → "category" */
+function singularize(s) {
+    if (s.endsWith('ies'))
+        return s.slice(0, -3) + 'y';
+    if (s.endsWith('ses') || s.endsWith('xes') || s.endsWith('zes'))
+        return s.slice(0, -2);
+    if (s.endsWith('s') && !s.endsWith('ss'))
+        return s.slice(0, -1);
+    return s;
+}