turbine-orm 0.28.3 → 0.30.0

package/dist/client.d.ts

@@ -57,6 +57,17 @@ export interface PgCompatQueryResult<R = Record<string, unknown>> {
 export interface PgCompatPoolClient {
     query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
     release(err?: Error | boolean): void;
+    /**
+     * Optional driver capability: `true` when `query()` may be called again on
+     * this connection while earlier calls are still in flight, with replies
+     * delivered to callers in FIFO submission order. Drivers that set this let
+     * the batch `$transaction([...])` overload dispatch every statement in one
+     * write burst (~1 network round trip plus server time) instead of awaiting
+     * each reply before sending the next (N round trips). Leave unset for
+     * drivers (node-postgres included) whose batch path must stay strictly
+     * sequential.
+     */
+    readonly supportsPipelining?: boolean;
 }
 /**
  * Minimal pg-compatible pool. Pass any driver that satisfies this interface
@@ -138,8 +149,12 @@ export interface TurbineConfig {
     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;
+    /**
+     * Log a warning when findMany() is called without a limit (default: false).
+     * Pass a per-table map (`{ users: false }`) to override the default for
+     * specific tables; per-call `warnOnUnlimited` on findMany args wins over both.
+     */
+    warnOnUnlimited?: boolean | Record<string, boolean>;
     /**
      * Interpret Postgres `timestamp` (without time zone) values as UTC — both
      * at the driver level (OID 1114 type parser, registered only when Turbine
@@ -564,8 +579,13 @@ export declare class TurbineClient {
      * of each query's transformed result; any failure rolls the whole batch back.
      *
      * Unlike {@link pipeline}, this never uses the extended-query pipeline
-     * protocol — it executes sequentially on the transaction connection, so it is
-     * safe on every driver (including HTTP/serverless pools).
+     * protocol. Statements run on the single transaction connection: strictly
+     * sequentially by default (safe on every driver, including HTTP/serverless
+     * pools), or — when the checked-out connection advertises
+     * {@link PgCompatPoolClient.supportsPipelining} — dispatched in one write
+     * burst with replies collected in order, saving a network round trip per
+     * statement. Either way the failure contract is identical: the first
+     * (lowest-index) failure aborts the batch and rolls everything back.
      *
      * @example
      * ```ts
@@ -580,8 +600,26 @@ export declare class TurbineClient {
      * Execute a batch of {@link DeferredQuery} objects atomically inside one
      * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
      * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
-     * queries run sequentially on the single transaction connection and each
-     * result is passed through its query's `transform`.
+     * each result is passed through its query's `transform`.
+     *
+     * Execution strategy on the single transaction connection:
+     *   - **Sequential (default).** Await each statement's reply before sending
+     *     the next. Safe on every driver; on a networked driver a batch of N
+     *     costs N round trips.
+     *   - **Pipelined.** When the checked-out connection advertises
+     *     {@link PgCompatPoolClient.supportsPipelining} (its `query()` accepts
+     *     concurrent calls and completes them in FIFO submission order), all
+     *     statements are dispatched in one write burst and the replies are
+     *     collected in order — ~1 round trip plus server time. Only taken when
+     *     the dialect's writes surface rows directly (`resultStrategy` !==
+     *     'reselect'): a reselect plan is itself a sequential write+read pair.
+     *
+     * The two paths share one failure contract: the first (lowest-index) failed
+     * statement's error is thrown (wrapped via {@link wrapPgError}) and the
+     * surrounding transaction rolls back, so no statement's effect survives. The
+     * pipelined path drains every in-flight reply (`Promise.allSettled`) before
+     * rethrowing, which keeps the connection's request/reply pairing intact and
+     * means ROLLBACK is only issued once no statement is still in flight.
      */
     private transactionBatch;
     /**

package/dist/client.js

@@ -763,14 +763,31 @@ export class TurbineClient {
      */
     async transaction(fn) {
         const client = await this.pool.connect();
+        /**
+         * Only true once BEGIN has actually succeeded. If BEGIN itself throws
+         * (e.g. a single-writer engine's transaction gate times out or rejects a
+         * re-entrant begin), issuing a "best-effort" ROLLBACK would be a stray
+         * statement from a context that never opened a transaction — on a driver
+         * with one shared engine handle (PowDB embedded) it would roll back a
+         * DIFFERENT caller's open transaction.
+         */
+        let began = false;
         try {
             await client.query(this.dialect.beginStatement());
+            began = true;
             const result = await fn(client);
             await client.query(this.dialect.commitStatement());
             return result;
         }
         catch (err) {
-            await client.query(this.dialect.rollbackStatement());
+            if (began) {
+                try {
+                    await client.query(this.dialect.rollbackStatement());
+                }
+                catch {
+                    // Best-effort rollback — the connection may have died mid-query.
+                }
+            }
             throw err;
         }
         finally {
@@ -804,11 +821,21 @@ export class TurbineClient {
             }
         };
         let timedOut = false;
+        /**
+         * Only true once BEGIN has actually succeeded. If BEGIN itself throws —
+         * e.g. a single-writer engine's transaction gate times out in its FIFO
+         * queue or rejects a re-entrant begin (PowDB, E002/E017) — this context
+         * never opened a transaction, so the catch below must NOT issue its
+         * best-effort ROLLBACK: on a driver with one shared engine handle that
+         * stray ROLLBACK would tear down a DIFFERENT caller's open transaction.
+         */
+        let began = false;
         try {
             // BEGIN with optional isolation level — the dialect owns the keyword and
             // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
             const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
             await client.query(this.dialect.beginStatement(isolationSql));
+            began = true;
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
             // user fn. Any error here propagates to the catch below and rolls back
@@ -881,8 +908,11 @@ export class TurbineClient {
             // If the timeout fired we already destroyed the connection — issuing a
             // ROLLBACK on a released client would throw "Client has already been
             // released". Skip the rollback in that case (the backend rolled back
-            // when its socket was closed).
-            if (!timedOut && !released) {
+            // when its socket was closed). Likewise skip it when BEGIN never
+            // succeeded (`began` false) — there is no transaction to roll back and
+            // the stray statement could hit another caller's transaction on a
+            // shared-handle engine.
+            if (began && !timedOut && !released) {
                 try {
                     await client.query(this.dialect.rollbackStatement());
                 }
@@ -903,14 +933,48 @@ export class TurbineClient {
      * Execute a batch of {@link DeferredQuery} objects atomically inside one
      * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
      * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
-     * queries run sequentially on the single transaction connection and each
-     * result is passed through its query's `transform`.
+     * each result is passed through its query's `transform`.
+     *
+     * Execution strategy on the single transaction connection:
+     *   - **Sequential (default).** Await each statement's reply before sending
+     *     the next. Safe on every driver; on a networked driver a batch of N
+     *     costs N round trips.
+     *   - **Pipelined.** When the checked-out connection advertises
+     *     {@link PgCompatPoolClient.supportsPipelining} (its `query()` accepts
+     *     concurrent calls and completes them in FIFO submission order), all
+     *     statements are dispatched in one write burst and the replies are
+     *     collected in order — ~1 round trip plus server time. Only taken when
+     *     the dialect's writes surface rows directly (`resultStrategy` !==
+     *     'reselect'): a reselect plan is itself a sequential write+read pair.
+     *
+     * The two paths share one failure contract: the first (lowest-index) failed
+     * statement's error is thrown (wrapped via {@link wrapPgError}) and the
+     * surrounding transaction rolls back, so no statement's effect survives. The
+     * pipelined path drains every in-flight reply (`Promise.allSettled`) before
+     * rethrowing, which keeps the connection's request/reply pairing intact and
+     * means ROLLBACK is only issued once no statement is still in flight.
      */
     async transactionBatch(queries) {
         if (queries.length === 0) {
             return [];
         }
         return this.transaction(async (client) => {
+            const pipelined = client.supportsPipelining === true &&
+                this.dialect.resultStrategy !== 'reselect';
+            if (pipelined) {
+                // Dispatch every statement before awaiting any reply. The driver's
+                // FIFO guarantee makes settled[i] the reply to queries[i].
+                const settled = await Promise.allSettled(queries.map((dq) => client.query(dq.sql, dq.params)));
+                const results = [];
+                for (let i = 0; i < settled.length; i++) {
+                    const outcome = settled[i];
+                    if (outcome.status === 'rejected') {
+                        throw wrapPgError(outcome.reason);
+                    }
+                    results.push(queries[i].transform(outcome.value));
+                }
+                return results;
+            }
             const results = [];
             for (const dq of queries) {
                 let raw;

package/dist/generate.d.ts

@@ -23,6 +23,18 @@ export interface GenerateOptions {
      * library's dependency graph. Default: `false`.
      */
     zod?: boolean;
+    /**
+     * Omit the `Generated at: <ISO timestamp>` line from every generated file
+     * header (T-8b — reproducible codegen). With this set, byte-identical
+     * schemas regenerate to byte-identical output, so regens produce empty
+     * diffs. Default: `false` (timestamp included, unchanged behavior).
+     */
+    noTimestamp?: boolean;
+}
+/** Per-file generator options (subset of {@link GenerateOptions} the emitters need). */
+export interface GenerateFileOptions {
+    /** Omit the `Generated at:` header line for reproducible output. */
+    noTimestamp?: boolean;
 }
 export declare function generate(options: GenerateOptions): {
     outDir: string;
@@ -33,7 +45,7 @@ export declare function generate(options: GenerateOptions): {
  * and *Relations brand-field interfaces). Exported so tests can pin the
  * generator output without writing files to disk.
  */
-export declare function generateTypes(schema: SchemaMetadata): string;
+export declare function generateTypes(schema: SchemaMetadata, options?: GenerateFileOptions): string;
 /**
  * Generate the contents of `zod.ts`. Emits, per table, `XSchema` (the full
  * row), `XCreateSchema` (PK/defaulted/nullable columns optional, STORED
@@ -41,6 +53,6 @@ export declare function generateTypes(schema: SchemaMetadata): string;
  * columns omitted, every remaining column optional). Exported so tests can pin
  * the output without writing files.
  */
-export declare function generateZod(schema: SchemaMetadata): string;
-export declare function generateMetadata(schema: SchemaMetadata): string;
-export declare function generateIndex(schema: SchemaMetadata): string;
+export declare function generateZod(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+export declare function generateMetadata(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+export declare function generateIndex(schema: SchemaMetadata, options?: GenerateFileOptions): string;

package/dist/generate.js

@@ -50,21 +50,22 @@ export function generate(options) {
     }
     mkdirSync(outDir, { recursive: true });
     const files = [];
+    const fileOptions = { noTimestamp: options.noTimestamp };
     // Generate types.ts
-    const typesContent = generateTypes(options.schema);
+    const typesContent = generateTypes(options.schema, fileOptions);
     writeFileSync(join(outDir, 'types.ts'), typesContent, 'utf-8');
     files.push('types.ts');
     // Generate metadata.ts
-    const metadataContent = generateMetadata(options.schema);
+    const metadataContent = generateMetadata(options.schema, fileOptions);
     writeFileSync(join(outDir, 'metadata.ts'), metadataContent, 'utf-8');
     files.push('metadata.ts');
     // Generate index.ts (configured client)
-    const indexContent = generateIndex(options.schema);
+    const indexContent = generateIndex(options.schema, fileOptions);
     writeFileSync(join(outDir, 'index.ts'), indexContent, 'utf-8');
     files.push('index.ts');
     // Generate zod.ts (optional — --zod flag)
     if (options.zod) {
-        const zodContent = generateZod(options.schema);
+        const zodContent = generateZod(options.schema, fileOptions);
         writeFileSync(join(outDir, 'zod.ts'), zodContent, 'utf-8');
         files.push('zod.ts');
     }
@@ -73,24 +74,51 @@ export function generate(options) {
 // ---------------------------------------------------------------------------
 // types.ts generator
 // ---------------------------------------------------------------------------
-function generatedFileHeader() {
+function generatedFileHeader(options) {
+    // `noTimestamp` omits the volatile line entirely (T-8b) so regenerating an
+    // unchanged schema produces byte-identical files.
     return [
         '/**',
         ' * Auto-generated by turbine-orm — DO NOT EDIT',
         ' *',
-        ` * Generated at: ${new Date().toISOString()}`,
+        ...(options?.noTimestamp ? [] : [` * Generated at: ${new Date().toISOString()}`]),
         ' * @see https://turbineorm.dev',
         ' */',
         '',
     ];
 }
+/**
+ * The relations of a table that are safe to surface in the generated TYPE
+ * layer. A relation whose name equals a scalar column field would shadow the
+ * column: `interface XWithY extends X` becomes TS2430, the `XCreate & { y?: … }`
+ * intersection collapses (TS2322), and neither the column nor the relation is
+ * targetable. Introspection no longer produces such names (they are
+ * disambiguated at the source), but hand-written or legacy metadata may —
+ * skip those relations here with a warning instead of emitting broken types.
+ * The runtime metadata (metadata.ts) still carries every relation.
+ */
+function typeSafeRelations(table, warn = true) {
+    const columnFields = new Set(table.columns.map((c) => c.field));
+    const usable = [];
+    for (const [relName, rel] of Object.entries(table.relations)) {
+        if (columnFields.has(relName)) {
+            if (warn) {
+                console.warn(`[turbine] Relation "${relName}" on table "${table.name}" shadows a column field of the same name — ` +
+                    `omitting it from the generated types. Rename the relation (or the column) to expose it.`);
+            }
+            continue;
+        }
+        usable.push([relName, rel]);
+    }
+    return usable;
+}
 /**
  * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
  * and *Relations brand-field interfaces). Exported so tests can pin the
  * generator output without writing files to disk.
  */
-export function generateTypes(schema) {
-    const lines = [...generatedFileHeader()];
+export function generateTypes(schema, options) {
+    const lines = [...generatedFileHeader(options)];
     // We import UpdateOperatorInput so generated *Update types can express
     // atomic increment / decrement / multiply / divide / set operators on
     // numeric columns (TASK-3.4).
@@ -106,9 +134,15 @@ export function generateTypes(schema) {
     // `${TargetType}Relations` (for deep inference) or `{}` (the no-relations
     // default) into each `RelationDescriptor`. Built once up-front because
     // relations can point at tables we haven't iterated to yet.
+    // Relations that can be surfaced in the type layer, computed once per table
+    // (relations that would shadow a scalar column field are excluded + warned).
+    const safeRelationsByTable = new Map();
+    for (const t of Object.values(schema.tables)) {
+        safeRelationsByTable.set(t.name, typeSafeRelations(t));
+    }
     const tablesWithRelations = new Set();
     for (const t of Object.values(schema.tables)) {
-        if (Object.keys(t.relations).length > 0)
+        if ((safeRelationsByTable.get(t.name) ?? []).length > 0)
             tablesWithRelations.add(t.name);
     }
     // Generate enum types
@@ -173,11 +207,12 @@ export function generateTypes(schema) {
         // any depth — `RelationRelations<R[K]>` reads the third type parameter
         // and threads it into the next recursion step. If the target table has
         // no relations of its own, the descriptor uses `{}` (the default).
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const safeRelations = safeRelationsByTable.get(table.name) ?? [];
+        const hasRelations = safeRelations.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)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 // manyToMany is a collection too → 'many' cardinality (same as hasMany).
                 const cardinality = rel.type === 'hasMany' || rel.type === 'manyToMany' ? "'many'" : "'one'";
@@ -187,7 +222,7 @@ export function generateTypes(schema) {
             lines.push('}');
             lines.push('');
             // --- Legacy per-relation interfaces (kept for backward compatibility) ---
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 if (rel.type === 'hasMany' || rel.type === 'manyToMany') {
                     lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
@@ -211,7 +246,8 @@ export function generateTypes(schema) {
     // ---------------------------------------------------------------------------
     for (const table of Object.values(schema.tables)) {
         const typeName = entityName(table.name);
-        const hasRels = Object.keys(table.relations).length > 0;
+        const safeRelations = safeRelationsByTable.get(table.name) ?? [];
+        const hasRels = safeRelations.length > 0;
         // WhereUnique — union of unique constraint shapes, deduplicating PK
         const seen = new Set();
         const uniqueSets = [];
@@ -243,14 +279,14 @@ export function generateTypes(schema) {
         // CreateInput / UpdateInput — extends base type with optional relation fields
         if (hasRels) {
             lines.push(`export type ${typeName}CreateInput = ${typeName}Create & {`);
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 lines.push(`  ${relName}?: ${targetType}NestedCreateInput;`);
             }
             lines.push('};');
             lines.push('');
             lines.push(`export type ${typeName}UpdateInput = ${typeName}Update & {`);
-            for (const [relName, rel] of Object.entries(table.relations)) {
+            for (const [relName, rel] of safeRelations) {
                 const targetType = entityName(rel.to);
                 if (rel.type === 'hasMany') {
                     lines.push(`  ${relName}?: ${targetType}NestedUpdateInput;`);
@@ -266,7 +302,7 @@ export function generateTypes(schema) {
     // Emit NestedCreateInput, NestedUpdateInput, ConnectOrCreate for every table
     for (const table of Object.values(schema.tables)) {
         const typeName = entityName(table.name);
-        const hasRels = Object.keys(table.relations).length > 0;
+        const hasRels = (safeRelationsByTable.get(table.name) ?? []).length > 0;
         // NestedCreateInput uses *CreateInput (which includes relation fields) when
         // the table has relations, otherwise falls back to the plain *Create type.
         const createRefType = hasRels ? `${typeName}CreateInput` : `${typeName}Create`;
@@ -351,8 +387,8 @@ function zodBaseType(col, enums) {
  * columns omitted, every remaining column optional). Exported so tests can pin
  * the output without writing files.
  */
-export function generateZod(schema) {
-    const lines = [...generatedFileHeader()];
+export function generateZod(schema, options) {
+    const lines = [...generatedFileHeader(options)];
     // `zod` is a USER dependency — this generated file imports it, but the Turbine
     // library runtime never does, so Zod stays out of the package's dep graph.
     lines.push("import { z } from 'zod';");
@@ -409,9 +445,9 @@ export function generateZod(schema) {
 // ---------------------------------------------------------------------------
 // metadata.ts generator
 // ---------------------------------------------------------------------------
-export function generateMetadata(schema) {
+export function generateMetadata(schema, options) {
     const lines = [
-        ...generatedFileHeader(),
+        ...generatedFileHeader(options),
         "import type { SchemaMetadata } from 'turbine-orm';",
         '',
         'export const SCHEMA: SchemaMetadata = {',
@@ -511,10 +547,15 @@ export function generateMetadata(schema) {
 // ---------------------------------------------------------------------------
 // index.ts generator (configured client with typed table accessors)
 // ---------------------------------------------------------------------------
-export function generateIndex(schema) {
+export function generateIndex(schema, options) {
     const tableEntries = Object.values(schema.tables);
+    // Must mirror generateTypes: `XRelations` only exists in types.ts when the
+    // table has at least one type-safe (non-column-shadowing) relation.
+    const hasSafeRelations = new Map();
+    for (const t of tableEntries)
+        hasSafeRelations.set(t.name, typeSafeRelations(t, false).length > 0);
     const lines = [
-        ...generatedFileHeader(),
+        ...generatedFileHeader(options),
         "import { TurbineClient as BaseTurbineClient, TransactionClient as BaseTransactionClient, QueryInterface } from 'turbine-orm';",
         "import type { TurbineConfig, TransactionOptions, DeferredQuery, PipelineResults } from 'turbine-orm';",
         "import { SCHEMA } from './metadata.js';",
@@ -523,7 +564,7 @@ export function generateIndex(schema) {
     const typeImports = [];
     for (const t of tableEntries) {
         typeImports.push(entityName(t.name));
-        if (Object.keys(t.relations).length > 0) {
+        if (hasSafeRelations.get(t.name)) {
             typeImports.push(`${entityName(t.name)}Relations`);
         }
     }
@@ -545,7 +586,7 @@ export function generateIndex(schema) {
     for (const table of tableEntries) {
         const typeName = entityName(table.name);
         const accessor = snakeToCamelStr(table.name);
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const hasRelations = hasSafeRelations.get(table.name) === true;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
         lines.push(`  /** Query interface for the \`${table.name}\` table (transaction-scoped) */`);
         lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
@@ -587,7 +628,7 @@ export function generateIndex(schema) {
     for (const table of tableEntries) {
         const typeName = entityName(table.name);
         const accessor = snakeToCamelStr(table.name);
-        const hasRelations = Object.keys(table.relations).length > 0;
+        const hasRelations = hasSafeRelations.get(table.name) === true;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
         lines.push(`  /** Query interface for the \`${table.name}\` table */`);
         lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
@@ -670,6 +711,11 @@ function serializeColumn(col) {
         `arrayType: '${escSQ(col.arrayType ?? col.pgArrayType)}'`,
         `pgArrayType: '${escSQ(col.pgArrayType)}'`,
     ];
+    // Cross-schema type marker — introspection records it only for types living
+    // outside the introspected schema; it must survive codegen or the runtime
+    // enum-cast guard in query/builder.ts loses the signal (N-5).
+    if (col.pgTypeSchema !== undefined)
+        parts.push(`pgTypeSchema: '${escSQ(col.pgTypeSchema)}'`);
     // Emit isGenerated only when set (server-generated serial/identity), so the
     // output stays byte-identical for the common client-default columns.
     if (col.isGenerated)

package/dist/index.d.ts

@@ -48,6 +48,7 @@ export { type ActiveSubscription, type NotificationHandler, type Subscription, v
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, defineSchema, type ManyToManyDef, type ReferenceDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
+export { schemaDefToMetadata } from './schema-metadata.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';
 export { type TurbineHttpOptions, turbineHttp } from './serverless.js';

package/dist/index.js

@@ -56,6 +56,8 @@ export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs,
 export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, 
 // Legacy compat (deprecated — use object format with defineSchema)
 table, } from './schema-builder.js';
+// Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB
+export { schemaDefToMetadata } from './schema-metadata.js';
 // Schema SQL — generate DDL, diff, and push
 export { schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 // Seed helper

package/dist/introspect.d.ts

@@ -8,7 +8,7 @@
  * This is the foundation of `npx turbine generate`.
  */
 import { type Dialect } from './dialect.js';
-import { type ReferentialAction, type SchemaMetadata } from './schema.js';
+import { type ColumnMetadata, type ReferentialAction, type RelationDef, type SchemaMetadata } from './schema.js';
 /**
  * Map a `pg_constraint.confdeltype` / `confupdtype` character to a
  * {@link ReferentialAction}. Postgres encodes: `a` = NO ACTION, `r` = RESTRICT,
@@ -56,3 +56,96 @@ export declare function introspectPostgresCatalog(options: IntrospectOptions): P
  * balanced outer paren pair; leaves anything unexpected untouched.
  */
 export declare function stripCheckWrapper(def: string): string;
+/** A foreign-key constraint grouped by constraint name (composite FKs carry column arrays). */
+export interface ForeignKeyEntry {
+    sourceTable: string;
+    sourceColumns: string[];
+    targetTable: string;
+    targetColumns: string[];
+    constraintName: string;
+}
+/**
+ * Derive a belongsTo relation name from its FK column. Strips a trailing
+ * `_id` (snake_case) or `Id` (camelCase column names — common in Prisma-ported
+ * schemas where columns are quoted camelCase identifiers), then camelCases:
+ * `current_version_id` and `currentVersionId` both yield `currentVersion`.
+ * Stripping is what keeps the scalar FK field (`currentVersionId`) targetable
+ * alongside the relation. A column literally named `id` (nothing left after
+ * stripping) keeps its own name.
+ */
+export declare function relationNameFromColumn(column: string): string;
+/**
+ * True for the tsType forms a json/jsonb column maps to (`unknown`, nullable
+ * `unknown | null`). A relation shadowing such a column is a HISTORICAL shadow
+ * that worked at runtime and compiled (`unknown` absorbs the relation
+ * payload), so the legacy-first naming keeps it instead of renaming.
+ */
+export declare function isUnknownTsType(tsType: string): boolean;
+/**
+ * Build the belongsTo/hasMany relation maps for every table from its foreign
+ * keys. Naming rules (LEGACY-FIRST — a relation name that previously worked at
+ * runtime must never change out from under a regenerating app):
+ *
+ *   1. First compute the historical derivation exactly as it shipped before
+ *      the collision guard existed: belongsTo strips a case-SENSITIVE `_id`
+ *      suffix (`snakeToCamel(col.replace(/_id$/, ''))` when several FKs point
+ *      at the same target, else the singularized target table), and hasMany is
+ *      `snakeToCamel(`${source}_by_${strippedColumn}`)` (else the source
+ *      table). If that legacy name is free, KEEP IT — even when it looks odd
+ *      (`blogPostsByAuthorId`, `postsBy_Author`): those names were collision-
+ *      free and worked, so regenerating must not rename them.
+ *   2. If the legacy name collides ONLY with a scalar column whose tsType is
+ *      `unknown` (json/jsonb), keep it anyway with a warning: the shadow is
+ *      historical, ran fine at runtime, and compiled (`unknown` absorbs the
+ *      relation payload; generate.ts's typeSafeRelations omits the relation
+ *      from the type layer).
+ *   3. On a genuine collision (concrete-typed column shadow, or a previously
+ *      assigned relation), fall back to the modern derivation — the `_id`/`Id`
+ *      case-insensitive strip of {@link relationNameFromColumn} plus the
+ *      `By`-composed reverse name — which fixes the camelCase-FK shadowing
+ *      shapes that were actually BROKEN before (relation name === scalar FK
+ *      field → unusable types).
+ *   4. Last resort: deterministic `Rel`/`Rel2` suffix + warning.
+ *
+ * @param columnFieldsByTable camelCase column *fields* per table — used to
+ *   guarantee relations never shadow concrete-typed scalar columns.
+ * @param unknownTypedFieldsByTable subset of the column fields whose tsType is
+ *   `unknown` (json/jsonb) — legacy shadows of these are preserved (rule 2).
+ */
+export declare function buildRelationsFromForeignKeys(foreignKeys: ForeignKeyEntry[], columnFieldsByTable: Map<string, Set<string>>, fkActions?: Map<string, {
+    onDelete: ReferentialAction;
+    onUpdate: ReferentialAction;
+}>, unknownTypedFieldsByTable?: Map<string, Set<string>>): Map<string, Record<string, RelationDef>>;
+/**
+ * Conservative auto-`manyToMany` detection over pure junction tables, shared
+ * by the Postgres introspector, the engine introspectors (SQLite / MySQL /
+ * MSSQL), the MCP server, and `schemaDefToMetadata()` so all surfaces derive
+ * IDENTICAL relation names for the same logical schema.
+ *
+ * A table J is a PURE junction only when ALL of these hold:
+ *   1. J's primary key is exactly two columns.
+ *   2. J has exactly two FKs, each single-column.
+ *   3. Each FK's source column is one of J's two PK columns.
+ *   4. The two FKs target two DISTINCT tables (A and B).
+ *   5. J has no payload columns beyond the two FK/PK columns.
+ *
+ * For such a J linking A and B this ADDS a `manyToMany` on A → B and B → A
+ * routed `through` J. It never removes or renames an existing relation:
+ *   - an already-assigned relation with the same name → SKIP (additive-only,
+ *     unchanged historical behavior);
+ *   - a shadowed json/jsonb (`unknown`-typed) column → keep the historical
+ *     name + warn (it worked at runtime and compiled);
+ *   - a shadowed concrete-typed column → deterministic `Rel` suffix + warn
+ *     instead of silently dropping the relation.
+ */
+export declare function addAutoManyToManyRelations(tableNames: Iterable<string>, foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnNamesByTable: Map<string, string[]>, relationsByTable: Map<string, Record<string, RelationDef>>, columnFieldsByTable?: Map<string, Set<string>>, unknownTypedFieldsByTable?: Map<string, Set<string>>): void;
+/**
+ * One-stop relation derivation for the engine introspectors (SQLite / MySQL /
+ * MSSQL): filters the FK list to the introspected table set, seeds the
+ * taken-name / json-shadow maps from the engine's column metadata, and runs
+ * the SAME `buildRelationsFromForeignKeys` + `addAutoManyToManyRelations`
+ * pipeline as the Postgres introspector — so every engine derives identical
+ * relation names for the same logical schema (the engines previously carried
+ * stale copies of a retired naming scheme).
+ */
+export declare function deriveEngineRelations(tableNames: string[], foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnsByTable: Map<string, Pick<ColumnMetadata, 'name' | 'field' | 'tsType'>[]>): Map<string, Record<string, RelationDef>>;