turbine-orm 0.4.0 → 0.7.0

package/dist/cjs/errors.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * turbine-orm — Error types
+ *
+ * Typed errors with error codes for programmatic handling.
+ * All Turbine errors extend TurbineError which includes a `code` property.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckConstraintError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.TurbineError = exports.TurbineErrorCode = void 0;
+exports.wrapPgError = wrapPgError;
+/** Error codes for all Turbine errors */
+exports.TurbineErrorCode = {
+    NOT_FOUND: 'TURBINE_E001',
+    TIMEOUT: 'TURBINE_E002',
+    VALIDATION: 'TURBINE_E003',
+    CONNECTION: 'TURBINE_E004',
+    RELATION: 'TURBINE_E005',
+    MIGRATION: 'TURBINE_E006',
+    CIRCULAR_RELATION: 'TURBINE_E007',
+    UNIQUE_VIOLATION: 'TURBINE_E008',
+    FOREIGN_KEY_VIOLATION: 'TURBINE_E009',
+    NOT_NULL_VIOLATION: 'TURBINE_E010',
+    CHECK_VIOLATION: 'TURBINE_E011',
+};
+/** Base error class for all Turbine errors */
+class TurbineError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'TurbineError';
+        this.code = code;
+    }
+}
+exports.TurbineError = TurbineError;
+/**
+ * Thrown when a record is not found (findUniqueOrThrow, findFirstOrThrow,
+ * update/delete against a non-matching row, etc.)
+ *
+ * Supports two call styles for back-compat:
+ *   - `new NotFoundError()` / `new NotFoundError('custom message')`
+ *   - `new NotFoundError({ table, where, operation, cause, message })`
+ *
+ * When called with an options object and no explicit `message`, a Prisma-style
+ * message is built automatically, e.g.:
+ *   `[turbine] findUniqueOrThrow on "users" found no record matching where: {"id":1}`
+ */
+class NotFoundError extends TurbineError {
+    table;
+    where;
+    operation;
+    constructor(input) {
+        // Back-compat: string argument (or undefined) — replicate legacy behavior.
+        if (typeof input === 'string' || input === undefined) {
+            super(exports.TurbineErrorCode.NOT_FOUND, input ?? 'Record not found');
+            this.name = 'NotFoundError';
+            return;
+        }
+        const { table, where, operation, cause } = input;
+        let message = input.message;
+        if (!message) {
+            if (operation && table) {
+                const wherePart = where !== undefined ? ` matching where: ${JSON.stringify(where)}` : '';
+                message = `[turbine] ${operation} on "${table}" found no record${wherePart}`;
+            }
+            else if (table) {
+                const wherePart = where !== undefined ? ` matching where ${JSON.stringify(where)}` : '';
+                message = `[turbine] No record found in "${table}"${wherePart}`;
+            }
+            else {
+                message = '[turbine] Record not found';
+            }
+        }
+        super(exports.TurbineErrorCode.NOT_FOUND, message, { cause });
+        this.name = 'NotFoundError';
+        this.table = table;
+        this.where = where;
+        this.operation = operation;
+    }
+}
+exports.NotFoundError = NotFoundError;
+/** Thrown when a query or transaction exceeds the configured timeout */
+class TimeoutError extends TurbineError {
+    timeoutMs;
+    constructor(timeoutMs, context = 'Query') {
+        super(exports.TurbineErrorCode.TIMEOUT, `[turbine] ${context} timed out after ${timeoutMs}ms`);
+        this.name = 'TimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+exports.TimeoutError = TimeoutError;
+/** Thrown when query arguments fail validation (unknown column, invalid operator, etc.) */
+class ValidationError extends TurbineError {
+    constructor(message) {
+        super(exports.TurbineErrorCode.VALIDATION, message);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+/** Thrown when a database connection fails */
+class ConnectionError extends TurbineError {
+    constructor(message) {
+        super(exports.TurbineErrorCode.CONNECTION, message);
+        this.name = 'ConnectionError';
+    }
+}
+exports.ConnectionError = ConnectionError;
+/** Thrown when a relation reference is invalid */
+class RelationError extends TurbineError {
+    constructor(message) {
+        super(exports.TurbineErrorCode.RELATION, message);
+        this.name = 'RelationError';
+    }
+}
+exports.RelationError = RelationError;
+/** Thrown when a migration operation fails */
+class MigrationError extends TurbineError {
+    constructor(message) {
+        super(exports.TurbineErrorCode.MIGRATION, message);
+        this.name = 'MigrationError';
+    }
+}
+exports.MigrationError = MigrationError;
+/** Thrown when circular relation nesting is detected */
+class CircularRelationError extends TurbineError {
+    path;
+    constructor(path) {
+        super(exports.TurbineErrorCode.CIRCULAR_RELATION, `[turbine] Circular or too-deep relation nesting detected: ${path.join(' → ')}. Maximum nesting depth is 10.`);
+        this.name = 'CircularRelationError';
+        this.path = path;
+    }
+}
+exports.CircularRelationError = CircularRelationError;
+// ---------------------------------------------------------------------------
+// Database constraint violation errors
+// ---------------------------------------------------------------------------
+/**
+ * Extract the `detail` string from a pg-style error stored as `cause`.
+ * Returns undefined if the cause is not an object or has no detail.
+ */
+function detailFromCause(cause) {
+    if (!cause || typeof cause !== 'object')
+        return undefined;
+    const d = cause.detail;
+    return typeof d === 'string' && d.length > 0 ? d : undefined;
+}
+/** Thrown when a UNIQUE constraint is violated (pg code 23505) */
+class UniqueConstraintError extends TurbineError {
+    constraint;
+    columns;
+    table;
+    constructor(opts = {}) {
+        const { constraint, columns, table, cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const constraintPart = constraint ? ` on ${constraint}` : '';
+            const columnsPart = columns && columns.length > 0 ? ` (${columns.join(', ')})` : '';
+            message = `[turbine] Unique constraint violation${constraintPart}${columnsPart}`;
+            const detail = detailFromCause(cause);
+            if (detail)
+                message += `: ${detail}`;
+        }
+        super(exports.TurbineErrorCode.UNIQUE_VIOLATION, message, { cause });
+        this.name = 'UniqueConstraintError';
+        this.constraint = constraint;
+        this.columns = columns;
+        this.table = table;
+    }
+}
+exports.UniqueConstraintError = UniqueConstraintError;
+/** Thrown when a FOREIGN KEY constraint is violated (pg code 23503) */
+class ForeignKeyError extends TurbineError {
+    constraint;
+    table;
+    constructor(opts = {}) {
+        const { constraint, table, cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const constraintPart = constraint ? ` on ${constraint}` : '';
+            message = `[turbine] Foreign key constraint violation${constraintPart}`;
+            const detail = detailFromCause(cause);
+            if (detail)
+                message += `: ${detail}`;
+        }
+        super(exports.TurbineErrorCode.FOREIGN_KEY_VIOLATION, message, { cause });
+        this.name = 'ForeignKeyError';
+        this.constraint = constraint;
+        this.table = table;
+    }
+}
+exports.ForeignKeyError = ForeignKeyError;
+/** Thrown when a NOT NULL constraint is violated (pg code 23502) */
+class NotNullViolationError extends TurbineError {
+    column;
+    table;
+    constructor(opts = {}) {
+        const { column, table, cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const columnPart = column ? ` on column "${column}"` : '';
+            message = `[turbine] NOT NULL constraint violation${columnPart}`;
+            const detail = detailFromCause(cause);
+            if (detail)
+                message += `: ${detail}`;
+        }
+        super(exports.TurbineErrorCode.NOT_NULL_VIOLATION, message, { cause });
+        this.name = 'NotNullViolationError';
+        this.column = column;
+        this.table = table;
+    }
+}
+exports.NotNullViolationError = NotNullViolationError;
+/** Thrown when a CHECK constraint is violated (pg code 23514) */
+class CheckConstraintError extends TurbineError {
+    constraint;
+    table;
+    constructor(opts = {}) {
+        const { constraint, table, cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const constraintPart = constraint ? ` on ${constraint}` : '';
+            message = `[turbine] Check constraint violation${constraintPart}`;
+            const detail = detailFromCause(cause);
+            if (detail)
+                message += `: ${detail}`;
+        }
+        super(exports.TurbineErrorCode.CHECK_VIOLATION, message, { cause });
+        this.name = 'CheckConstraintError';
+        this.constraint = constraint;
+        this.table = table;
+    }
+}
+exports.CheckConstraintError = CheckConstraintError;
+/**
+ * Parse column names out of a pg `detail` string like:
+ *   "Key (email)=(foo@bar) already exists."
+ *   "Key (col1, col2)=(v1, v2) already exists."
+ */
+function parseColumnsFromDetail(detail) {
+    const m = detail.match(/^Key \(([^)]+)\)/);
+    if (!m)
+        return undefined;
+    return m[1].split(',').map((s) => s.trim());
+}
+/**
+ * Translate a pg driver error into a typed Turbine error.
+ * If the error doesn't match a known constraint code, returns it unchanged.
+ *
+ * Maps:
+ *   23505 (unique_violation)      -> UniqueConstraintError
+ *   23503 (foreign_key_violation) -> ForeignKeyError
+ *   23502 (not_null_violation)    -> NotNullViolationError
+ *   23514 (check_violation)       -> CheckConstraintError
+ *
+ * The original pg error is preserved as `.cause` on the wrapped error.
+ */
+function wrapPgError(err) {
+    if (!err || typeof err !== 'object')
+        return err;
+    const e = err;
+    if (!e.code)
+        return err;
+    switch (e.code) {
+        case '23505': {
+            const cols = e.detail ? parseColumnsFromDetail(e.detail) : undefined;
+            return new UniqueConstraintError({
+                constraint: e.constraint,
+                columns: cols,
+                table: e.table,
+                cause: err,
+            });
+        }
+        case '23503':
+            return new ForeignKeyError({
+                constraint: e.constraint,
+                table: e.table,
+                cause: err,
+            });
+        case '23502':
+            return new NotNullViolationError({
+                column: e.column,
+                table: e.table,
+                cause: err,
+            });
+        case '23514':
+            return new CheckConstraintError({
+                constraint: e.constraint,
+                table: e.table,
+                cause: err,
+            });
+        default:
+            return err;
+    }
+}

package/dist/cjs/generate.js

@@ -0,0 +1,321 @@
+"use strict";
+/**
+ * turbine-orm — Code generator
+ *
+ * Takes an IntrospectedSchema and emits TypeScript files:
+ *   - types.ts     — Entity interfaces, Create/Update input types
+ *   - metadata.ts  — Runtime schema metadata (column maps, relations, etc.)
+ *   - index.ts     — Configured TurbineClient with typed table accessors
+ *
+ * Output goes to the specified directory (default: ./generated/turbine/).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generate = generate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const schema_js_1 = require("./schema.js");
+/** Get the TypeScript type name for a table (singularized PascalCase) */
+function entityName(tableName) {
+    return (0, schema_js_1.snakeToPascal)((0, schema_js_1.singularize)(tableName));
+}
+/** Escape a value for embedding in a single-quoted TypeScript string literal */
+function escSQ(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+// ---------------------------------------------------------------------------
+// Main generate function
+// ---------------------------------------------------------------------------
+function generate(options) {
+    const outDir = options.outDir ?? './generated/turbine';
+    // Path traversal protection — ensure output stays within project root
+    const resolved = (0, node_path_1.resolve)(outDir);
+    const rel = (0, node_path_1.relative)(process.cwd(), resolved);
+    if (rel.startsWith('..') || (0, node_path_1.resolve)(rel) !== resolved) {
+        throw new Error(`Output directory must be within the project root. Got: ${outDir}`);
+    }
+    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    const files = [];
+    // Generate types.ts
+    const typesContent = generateTypes(options.schema);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'types.ts'), typesContent, 'utf-8');
+    files.push('types.ts');
+    // Generate metadata.ts
+    const metadataContent = generateMetadata(options.schema);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'metadata.ts'), metadataContent, 'utf-8');
+    files.push('metadata.ts');
+    // Generate index.ts (configured client)
+    const indexContent = generateIndex(options.schema);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'index.ts'), indexContent, 'utf-8');
+    files.push('index.ts');
+    return { outDir, files };
+}
+// ---------------------------------------------------------------------------
+// types.ts generator
+// ---------------------------------------------------------------------------
+function generatedFileHeader() {
+    return [
+        '/**',
+        ' * Auto-generated by turbine-orm — DO NOT EDIT',
+        ' *',
+        ` * Generated at: ${new Date().toISOString()}`,
+        ' * @see https://turbineorm.dev',
+        ' */',
+        '',
+    ];
+}
+function generateTypes(schema) {
+    const lines = [...generatedFileHeader()];
+    // Generate enum types
+    for (const [enumName, labels] of Object.entries(schema.enums)) {
+        const typeName = (0, schema_js_1.snakeToPascal)(enumName);
+        lines.push(`/** Database enum: ${enumName} */`);
+        lines.push(`export type ${typeName} = ${labels.map((l) => `'${escSQ(l)}'`).join(' | ')};`);
+        lines.push('');
+    }
+    // Generate entity types for each table
+    for (const table of Object.values(schema.tables)) {
+        const typeName = entityName(table.name);
+        // --- Base entity interface ---
+        lines.push(`/** Row type for the \`${table.name}\` table */`);
+        lines.push(`export interface ${typeName} {`);
+        for (const col of table.columns) {
+            const pkNote = table.primaryKey.includes(col.name) ? ' (primary key)' : '';
+            const nullNote = col.nullable ? ' (nullable)' : '';
+            lines.push(`  /** Column: ${col.name} — ${col.pgType}${pkNote}${nullNote} */`);
+            lines.push(`  ${col.field}: ${col.tsType};`);
+        }
+        lines.push('}');
+        lines.push('');
+        // --- Create input type ---
+        // Required: non-nullable columns without defaults (except PK)
+        // Optional: nullable columns (default to NULL) or columns with explicit defaults
+        lines.push(`/** Input type for creating a row in \`${table.name}\` */`);
+        lines.push(`export type ${typeName}Create = {`);
+        for (const col of table.columns) {
+            const isPk = table.primaryKey.includes(col.name);
+            const isOptional = col.hasDefault || col.nullable || isPk;
+            if (isOptional) {
+                const reason = isPk ? 'auto-generated' : col.hasDefault ? 'has default' : 'nullable';
+                lines.push(`  /** Optional: ${reason} */`);
+                lines.push(`  ${col.field}?: ${col.tsType};`);
+            }
+            else {
+                lines.push(`  ${col.field}: ${col.tsType};`);
+            }
+        }
+        lines.push('};');
+        lines.push('');
+        // --- Update input type (all fields optional except PK) ---
+        const nonPkCols = table.columns.filter((c) => !table.primaryKey.includes(c.name));
+        lines.push(`/** Input type for updating a row in \`${table.name}\` */`);
+        lines.push(`export type ${typeName}Update = {`);
+        for (const col of nonPkCols) {
+            lines.push(`  ${col.field}?: ${col.tsType};`);
+        }
+        lines.push('};');
+        lines.push('');
+        // --- Relations map (for type-safe `with` clauses) ---
+        const hasRelations = Object.keys(table.relations).length > 0;
+        if (hasRelations) {
+            lines.push(`/** Available relations for the \`${table.name}\` table */`);
+            lines.push(`export interface ${typeName}Relations {`);
+            for (const [relName, rel] of Object.entries(table.relations)) {
+                const targetType = entityName(rel.to);
+                if (rel.type === 'hasMany') {
+                    lines.push(`  ${relName}: ${targetType}[];`);
+                }
+                else {
+                    lines.push(`  ${relName}: ${targetType} | null;`);
+                }
+            }
+            lines.push('}');
+            lines.push('');
+            // --- Legacy per-relation interfaces (kept for backward compatibility) ---
+            for (const [relName, rel] of Object.entries(table.relations)) {
+                const targetType = entityName(rel.to);
+                if (rel.type === 'hasMany') {
+                    lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
+                    lines.push(`export interface ${typeName}With${(0, schema_js_1.snakeToPascal)(relName)} extends ${typeName} {`);
+                    lines.push(`  ${relName}: ${targetType}[];`);
+                    lines.push('}');
+                }
+                else {
+                    lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
+                    lines.push(`export interface ${typeName}With${(0, schema_js_1.snakeToPascal)(relName)} extends ${typeName} {`);
+                    lines.push(`  ${relName}: ${targetType} | null;`);
+                    lines.push('}');
+                }
+                lines.push('');
+            }
+        }
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// metadata.ts generator
+// ---------------------------------------------------------------------------
+function generateMetadata(schema) {
+    const lines = [
+        ...generatedFileHeader(),
+        "import type { SchemaMetadata } from 'turbine-orm';",
+        '',
+        'export const SCHEMA: SchemaMetadata = {',
+        '  tables: {',
+    ];
+    for (const table of Object.values(schema.tables)) {
+        lines.push(`    ${table.name}: {`);
+        lines.push(`      name: '${escSQ(table.name)}',`);
+        // columns
+        lines.push('      columns: [');
+        for (const col of table.columns) {
+            lines.push(`        ${serializeColumn(col)},`);
+        }
+        lines.push('      ],');
+        // columnMap
+        lines.push('      columnMap: {');
+        for (const [field, col] of Object.entries(table.columnMap)) {
+            lines.push(`        ${field}: '${escSQ(col)}',`);
+        }
+        lines.push('      },');
+        // reverseColumnMap
+        lines.push('      reverseColumnMap: {');
+        for (const [col, field] of Object.entries(table.reverseColumnMap)) {
+            lines.push(`        ${quoteIfNeeded(col)}: '${escSQ(field)}',`);
+        }
+        lines.push('      },');
+        // dateColumns
+        const dateCols = [...table.dateColumns];
+        lines.push(`      dateColumns: new Set([${dateCols.map((c) => `'${escSQ(c)}'`).join(', ')}]),`);
+        // pgTypes
+        lines.push('      pgTypes: {');
+        for (const [col, pgType] of Object.entries(table.pgTypes)) {
+            lines.push(`        ${quoteIfNeeded(col)}: '${escSQ(pgType)}',`);
+        }
+        lines.push('      },');
+        // allColumns
+        lines.push(`      allColumns: [${table.allColumns.map((c) => `'${escSQ(c)}'`).join(', ')}],`);
+        // primaryKey
+        lines.push(`      primaryKey: [${table.primaryKey.map((c) => `'${escSQ(c)}'`).join(', ')}],`);
+        // uniqueColumns
+        lines.push(`      uniqueColumns: [${table.uniqueColumns.map((uc) => `[${uc.map((c) => `'${escSQ(c)}'`).join(', ')}]`).join(', ')}],`);
+        // relations
+        lines.push('      relations: {');
+        for (const [relName, rel] of Object.entries(table.relations)) {
+            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: '${escSQ(rel.foreignKey)}', referenceKey: '${escSQ(rel.referenceKey)}' },`);
+        }
+        lines.push('      },');
+        // indexes
+        lines.push('      indexes: [');
+        for (const idx of table.indexes) {
+            lines.push(`        { name: '${escSQ(idx.name)}', columns: [${idx.columns.map((c) => `'${escSQ(c)}'`).join(', ')}], unique: ${idx.unique}, definition: ${JSON.stringify(idx.definition)} },`);
+        }
+        lines.push('      ],');
+        lines.push('    },');
+    }
+    lines.push('  },');
+    // enums
+    lines.push('  enums: {');
+    for (const [enumName, labels] of Object.entries(schema.enums)) {
+        lines.push(`    ${enumName}: [${labels.map((l) => `'${escSQ(l)}'`).join(', ')}],`);
+    }
+    lines.push('  },');
+    lines.push('};');
+    lines.push('');
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// index.ts generator (configured client with typed table accessors)
+// ---------------------------------------------------------------------------
+function generateIndex(schema) {
+    const tableEntries = Object.values(schema.tables);
+    const lines = [
+        ...generatedFileHeader(),
+        "import { TurbineClient as BaseTurbineClient, QueryInterface } from 'turbine-orm';",
+        "import type { TurbineConfig } from 'turbine-orm';",
+        "import { SCHEMA } from './metadata.js';",
+    ];
+    // Import all entity types and relations maps
+    const typeImports = [];
+    for (const t of tableEntries) {
+        typeImports.push(entityName(t.name));
+        if (Object.keys(t.relations).length > 0) {
+            typeImports.push(`${entityName(t.name)}Relations`);
+        }
+    }
+    lines.push(`import type { ${typeImports.join(', ')} } from './types.js';`);
+    lines.push('');
+    // Generate the client class with JSDoc
+    lines.push('/**');
+    lines.push(' * Generated Turbine client with typed table accessors.');
+    lines.push(' *');
+    lines.push(' * Tables:');
+    for (const table of tableEntries) {
+        lines.push(` *   - \`${snakeToCamelStr(table.name)}\` (${table.name})`);
+    }
+    lines.push(' *');
+    lines.push(' * @example');
+    lines.push(' * ```ts');
+    lines.push(' * const db = turbine({ connectionString: process.env.DATABASE_URL });');
+    if (tableEntries.length > 0) {
+        const firstTable = tableEntries[0];
+        const accessor = snakeToCamelStr(firstTable.name);
+        lines.push(` * const rows = await db.${accessor}.findMany();`);
+    }
+    lines.push(' * ```');
+    lines.push(' */');
+    lines.push('export class TurbineClient extends BaseTurbineClient {');
+    for (const table of tableEntries) {
+        const typeName = entityName(table.name);
+        const accessor = snakeToCamelStr(table.name);
+        const hasRelations = Object.keys(table.relations).length > 0;
+        const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
+        lines.push(`  /** Query interface for the \`${table.name}\` table */`);
+        lines.push(`  declare readonly ${accessor}: QueryInterface<${genericArgs}>;`);
+    }
+    lines.push('');
+    lines.push('  constructor(config?: TurbineConfig) {');
+    lines.push('    super(config, SCHEMA);');
+    lines.push('  }');
+    lines.push('}');
+    lines.push('');
+    // Factory function with JSDoc
+    lines.push('/**');
+    lines.push(' * Create a new Turbine client instance.');
+    lines.push(' *');
+    lines.push(' * @param config - Connection configuration. Falls back to DATABASE_URL env var.');
+    lines.push(' * @returns A fully-typed TurbineClient with table accessors.');
+    lines.push(' */');
+    lines.push('export function turbine(config?: TurbineConfig): TurbineClient {');
+    lines.push('  return new TurbineClient(config);');
+    lines.push('}');
+    lines.push('');
+    // Re-export everything
+    lines.push("export * from './types.js';");
+    lines.push("export { SCHEMA } from './metadata.js';");
+    lines.push('');
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function serializeColumn(col) {
+    const parts = [
+        `name: '${escSQ(col.name)}'`,
+        `field: '${escSQ(col.field)}'`,
+        `pgType: '${escSQ(col.pgType)}'`,
+        `tsType: '${escSQ(col.tsType)}'`,
+        `nullable: ${col.nullable}`,
+        `hasDefault: ${col.hasDefault}`,
+        `isArray: ${col.isArray}`,
+        `pgArrayType: '${escSQ(col.pgArrayType)}'`,
+    ];
+    if (col.maxLength !== undefined)
+        parts.push(`maxLength: ${col.maxLength}`);
+    return `{ ${parts.join(', ')} }`;
+}
+function quoteIfNeeded(s) {
+    return /[^a-zA-Z0-9_$]/.test(s) ? `'${s}'` : s;
+}
+function snakeToCamelStr(s) {
+    return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}