turbine-orm 0.28.3 → 0.30.0

package/dist/schema-metadata.d.ts

@@ -0,0 +1,77 @@
+/**
+ * turbine-orm — defineSchema() → SchemaMetadata bridge
+ *
+ * Converts a code-first {@link SchemaDef} (the output of `defineSchema()`)
+ * into the runtime {@link SchemaMetadata} shape that the query builder,
+ * `TurbineClient`, and the non-SQL engines consume — without touching a
+ * live database.
+ *
+ * Why this exists: the historical converter path (`introspect()` +
+ * `generate()`) requires a running SQL database, but code-first engines
+ * (PowDB, in-memory SQLite bootstraps, tests) only have the `SchemaDef`.
+ * `schemaDefToMetadata()` is the pure-function equivalent: its output
+ * matches what `turbine generate` would emit into `metadata.ts` for the
+ * same schema, minus the pieces only a live catalog can know (real index
+ * names, constraint names, view flags).
+ *
+ * Parity notes (ground truth = introspect.ts + generate.ts):
+ *   - Relations are derived from `references:` exactly like introspection
+ *     derives them from foreign keys: a `belongsTo` on the child table and
+ *     a `hasMany` on the parent, with the same disambiguation rules when
+ *     multiple FKs point at the same target.
+ *   - Pure junction tables (2-column composite PK that IS the two
+ *     single-column FKs to two distinct tables, no payload columns) get
+ *     the same conservative auto-`manyToMany` treatment as introspection.
+ *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
+ *     {@link applyManyToManyRelations} (additive, never clobbering).
+ *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
+ *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
+ *     and the dev-mode missing-index warning stay silent instead of
+ *     producing blanket false positives.
+ *
+ * @example
+ * ```ts
+ * import { defineSchema, schemaDefToMetadata } from 'turbine-orm';
+ *
+ * const def = defineSchema({
+ *   users: { id: { type: 'serial', primaryKey: true }, name: { type: 'text', notNull: true } },
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            userId: { type: 'integer', notNull: true, references: 'users.id' } },
+ * });
+ * const metadata = schemaDefToMetadata(def);
+ * // → usable anywhere SchemaMetadata is expected (e.g. turbinePowDB, TurbineClient)
+ * ```
+ */
+import { type SchemaMetadata } from './schema.js';
+import { type SchemaDef } from './schema-builder.js';
+/**
+ * Convert a code-first {@link SchemaDef} into runtime {@link SchemaMetadata}.
+ *
+ * Pure function — no database connection, no side effects, input untouched.
+ * The output is shaped identically to the `SCHEMA` constant `turbine generate`
+ * emits from introspection, so it can be handed to any consumer that expects
+ * introspected metadata: `new TurbineClient(config, metadata)`,
+ * `turbinePowDB(..., metadata)`, `QueryInterface`, the index advisor, etc.
+ *
+ * What maps:
+ *   - Columns → full {@link ColumnMetadata} (snake_case name, camelCase field,
+ *     pg type names, TS types, nullability, defaults, `isGenerated` for
+ *     serial/bigserial, array + varchar length info, date-column tracking).
+ *   - Column-level `primaryKey` and table-level composite `primaryKey`.
+ *   - `unique: true` columns → single-column `uniqueColumns` entries.
+ *   - `references:` FKs → `belongsTo` (child) + `hasMany` (parent) relations,
+ *     including `onDelete`/`onUpdate` actions (the `'no action'` default is
+ *     omitted, matching introspection).
+ *   - Pure junction tables → auto-detected `manyToMany` relations (same
+ *     conservative rules as introspection).
+ *   - Explicit `manyToMany` declarations → merged additively.
+ *   - Schema-level `enums`.
+ *
+ * What SchemaDef cannot express (and how it degrades):
+ *   - Indexes → every table gets `indexes: []`, which keeps
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
+ *     false positives on code-first metadata.
+ *   - Views → never marked (`isView` is introspection-only).
+ *   - Composite foreign keys → `references:` is single-column by design.
+ */
+export declare function schemaDefToMetadata(def: SchemaDef): SchemaMetadata;

package/dist/schema-metadata.js

@@ -0,0 +1,313 @@
+/**
+ * turbine-orm — defineSchema() → SchemaMetadata bridge
+ *
+ * Converts a code-first {@link SchemaDef} (the output of `defineSchema()`)
+ * into the runtime {@link SchemaMetadata} shape that the query builder,
+ * `TurbineClient`, and the non-SQL engines consume — without touching a
+ * live database.
+ *
+ * Why this exists: the historical converter path (`introspect()` +
+ * `generate()`) requires a running SQL database, but code-first engines
+ * (PowDB, in-memory SQLite bootstraps, tests) only have the `SchemaDef`.
+ * `schemaDefToMetadata()` is the pure-function equivalent: its output
+ * matches what `turbine generate` would emit into `metadata.ts` for the
+ * same schema, minus the pieces only a live catalog can know (real index
+ * names, constraint names, view flags).
+ *
+ * Parity notes (ground truth = introspect.ts + generate.ts):
+ *   - Relations are derived from `references:` exactly like introspection
+ *     derives them from foreign keys: a `belongsTo` on the child table and
+ *     a `hasMany` on the parent, with the same disambiguation rules when
+ *     multiple FKs point at the same target.
+ *   - Pure junction tables (2-column composite PK that IS the two
+ *     single-column FKs to two distinct tables, no payload columns) get
+ *     the same conservative auto-`manyToMany` treatment as introspection.
+ *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
+ *     {@link applyManyToManyRelations} (additive, never clobbering).
+ *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
+ *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
+ *     and the dev-mode missing-index warning stay silent instead of
+ *     producing blanket false positives.
+ *
+ * @example
+ * ```ts
+ * import { defineSchema, schemaDefToMetadata } from 'turbine-orm';
+ *
+ * const def = defineSchema({
+ *   users: { id: { type: 'serial', primaryKey: true }, name: { type: 'text', notNull: true } },
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            userId: { type: 'integer', notNull: true, references: 'users.id' } },
+ * });
+ * const metadata = schemaDefToMetadata(def);
+ * // → usable anywhere SchemaMetadata is expected (e.g. turbinePowDB, TurbineClient)
+ * ```
+ */
+import { addAutoManyToManyRelations, buildRelationsFromForeignKeys, isUnknownTsType, } from './introspect.js';
+import { camelToSnake, isDateType, pgArrayType, pgTypeToTs, } from './schema.js';
+import { applyManyToManyRelations } from './schema-builder.js';
+// ---------------------------------------------------------------------------
+// DDL type → Postgres udt_name (what introspection reads from the catalog)
+// ---------------------------------------------------------------------------
+const DDL_TO_UDT = {
+    SERIAL: 'int4',
+    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',
+};
+/** Resolve a ColumnConfig's Postgres base type name (udt_name form). */
+function udtName(config) {
+    if (config.type === 'ENUM')
+        return config.enumName ?? 'text';
+    if (config.type === 'VECTOR')
+        return 'vector';
+    return DDL_TO_UDT[config.type];
+}
+/** Server-generated (sequence-backed) types — pg's `nextval(...)` default. */
+function isSerialType(type) {
+    return type === 'SERIAL' || type === 'BIGSERIAL';
+}
+/**
+ * Resolve the raw column part of a `references: 'table.column'` target to a
+ * snake_case column name — accepting either the camelCase field name or the
+ * snake_case DDL name, mirroring how schema-sql.ts accepts both table forms.
+ */
+function resolveColumnName(raw, target) {
+    if (target) {
+        const viaField = target.fieldToColumn.get(raw);
+        if (viaField !== undefined)
+            return viaField;
+        if (target.columnNames.has(raw))
+            return raw;
+    }
+    return camelToSnake(raw);
+}
+// ---------------------------------------------------------------------------
+// The converter
+// ---------------------------------------------------------------------------
+/**
+ * Convert a code-first {@link SchemaDef} into runtime {@link SchemaMetadata}.
+ *
+ * Pure function — no database connection, no side effects, input untouched.
+ * The output is shaped identically to the `SCHEMA` constant `turbine generate`
+ * emits from introspection, so it can be handed to any consumer that expects
+ * introspected metadata: `new TurbineClient(config, metadata)`,
+ * `turbinePowDB(..., metadata)`, `QueryInterface`, the index advisor, etc.
+ *
+ * What maps:
+ *   - Columns → full {@link ColumnMetadata} (snake_case name, camelCase field,
+ *     pg type names, TS types, nullability, defaults, `isGenerated` for
+ *     serial/bigserial, array + varchar length info, date-column tracking).
+ *   - Column-level `primaryKey` and table-level composite `primaryKey`.
+ *   - `unique: true` columns → single-column `uniqueColumns` entries.
+ *   - `references:` FKs → `belongsTo` (child) + `hasMany` (parent) relations,
+ *     including `onDelete`/`onUpdate` actions (the `'no action'` default is
+ *     omitted, matching introspection).
+ *   - Pure junction tables → auto-detected `manyToMany` relations (same
+ *     conservative rules as introspection).
+ *   - Explicit `manyToMany` declarations → merged additively.
+ *   - Schema-level `enums`.
+ *
+ * What SchemaDef cannot express (and how it degrades):
+ *   - Indexes → every table gets `indexes: []`, which keeps
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
+ *     false positives on code-first metadata.
+ *   - Views → never marked (`isView` is introspection-only).
+ *   - Composite foreign keys → `references:` is single-column by design.
+ */
+export function schemaDefToMetadata(def) {
+    // ----- Pass 1: resolve every table's snake_case names for FK lookups -----
+    // Lookup accepts the accessor key (camelCase), the DDL name (snake_case),
+    // and the explicit `accessor` field — same tolerance as schema-sql.ts.
+    const lookup = new Map();
+    for (const [key, tableDef] of Object.entries(def.tables)) {
+        const fieldToColumn = new Map();
+        const columnNames = new Set();
+        for (const field of Object.keys(tableDef.columns)) {
+            const snake = camelToSnake(field);
+            fieldToColumn.set(field, snake);
+            columnNames.add(snake);
+        }
+        const resolved = { name: tableDef.name, fieldToColumn, columnNames };
+        lookup.set(key, resolved);
+        if (tableDef.name)
+            lookup.set(tableDef.name, resolved);
+        if (tableDef.accessor)
+            lookup.set(tableDef.accessor, resolved);
+    }
+    // ----- Pass 2: collect resolved single-column FKs -----
+    const foreignKeys = [];
+    for (const tableDef of Object.values(def.tables)) {
+        for (const [field, config] of Object.entries(tableDef.columns)) {
+            if (!config.referencesTarget)
+                continue;
+            const parts = config.referencesTarget.split('.');
+            if (parts.length !== 2)
+                continue;
+            const target = lookup.get(parts[0]);
+            // Reference to a table outside this SchemaDef — skip, exactly like
+            // introspection skips FKs whose target is excluded from the table set.
+            if (!target)
+                continue;
+            foreignKeys.push({
+                sourceTable: tableDef.name,
+                sourceColumn: camelToSnake(field),
+                targetTable: target.name,
+                targetColumn: resolveColumnName(parts[1], target),
+                onDelete: config.onDelete ?? undefined,
+                onUpdate: config.onUpdate ?? undefined,
+            });
+        }
+    }
+    // ----- Pass 3: derive belongsTo / hasMany relations (SHARED with introspect)
+    //
+    // Delegates to the exact same builder introspection uses
+    // (`buildRelationsFromForeignKeys`), so the same logical schema yields
+    // IDENTICAL relation names whether it arrives via `defineSchema()` or a live
+    // catalog: legacy-first naming, per-column disambiguation for several FKs to
+    // the same target, and collision resolution against scalar column fields
+    // (json/jsonb `unknown`-typed shadows keep the historical name). The old
+    // local reimplementation had NO collision guard — `posts.user` (text) +
+    // `userId references users.id` produced a relation `user` that shadowed the
+    // scalar, and two FKs deriving the same name silently clobbered each other
+    // (N-4).
+    //
+    // Constraint names are synthesized in pg's default `<table>_<column>_fkey`
+    // form; they only feed the referential-action lookup and composite-FK
+    // naming (never hit here — `references:` is single-column by design).
+    const fkEntries = [];
+    const fkActions = new Map();
+    for (const fk of foreignKeys) {
+        const constraintName = `${fk.sourceTable}_${fk.sourceColumn}_fkey`;
+        fkEntries.push({
+            sourceTable: fk.sourceTable,
+            sourceColumns: [fk.sourceColumn],
+            targetTable: fk.targetTable,
+            targetColumns: [fk.targetColumn],
+            constraintName,
+        });
+        fkActions.set(constraintName, {
+            onDelete: fk.onDelete ?? 'no action',
+            onUpdate: fk.onUpdate ?? 'no action',
+        });
+    }
+    // Taken-name seeds: every table's camelCase column fields (the SchemaDef
+    // keys ARE the fields) + which of them are json/jsonb (`unknown`-typed).
+    const columnFieldsByTable = new Map();
+    const unknownTypedFieldsByTable = new Map();
+    for (const tableDef of Object.values(def.tables)) {
+        const fields = Object.keys(tableDef.columns);
+        columnFieldsByTable.set(tableDef.name, new Set(fields));
+        // ENUM columns map to concrete union types in the generated layer, so
+        // only genuine json/jsonb (`unknown`-typed) columns qualify as shadows.
+        unknownTypedFieldsByTable.set(tableDef.name, new Set(fields.filter((f) => {
+            const config = tableDef.columns[f];
+            if (config.type === 'ENUM')
+                return false;
+            const wire = config.isArray ? `_${udtName(config)}` : udtName(config);
+            return isUnknownTsType(pgTypeToTs(wire, false));
+        })));
+    }
+    const relationsByTable = buildRelationsFromForeignKeys(fkEntries, columnFieldsByTable, fkActions, unknownTypedFieldsByTable);
+    // ----- Pass 4: conservative junction auto-m2m (SHARED with introspect) ---
+    // Same shared detector + naming/collision rules as introspection: a table J
+    // is a PURE junction only when its PK is exactly the two single-column FKs
+    // to two DISTINCT tables and it has no payload columns.
+    const pkByTable = new Map();
+    const columnNamesByTable = new Map();
+    for (const tableDef of Object.values(def.tables)) {
+        const pkFields = tableDef.primaryKey && tableDef.primaryKey.length > 0
+            ? [...tableDef.primaryKey]
+            : Object.entries(tableDef.columns)
+                .filter(([, c]) => c.isPrimaryKey)
+                .map(([f]) => f);
+        pkByTable.set(tableDef.name, pkFields.map(camelToSnake));
+        columnNamesByTable.set(tableDef.name, Object.keys(tableDef.columns).map(camelToSnake));
+    }
+    addAutoManyToManyRelations(Object.values(def.tables).map((t) => t.name), fkEntries, pkByTable, columnNamesByTable, relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable);
+    // ----- Pass 5: assemble TableMetadata -----
+    const tables = {};
+    for (const tableDef of Object.values(def.tables)) {
+        const columns = [];
+        const columnMap = {};
+        const reverseColumnMap = {};
+        const dateColumns = new Set();
+        const dialectTypes = {};
+        const pgTypes = {};
+        const allColumns = [];
+        const primaryKey = [];
+        const uniqueColumns = [];
+        for (const [field, config] of Object.entries(tableDef.columns)) {
+            const name = camelToSnake(field);
+            const base = udtName(config);
+            // Introspection reports array columns with pg's leading-underscore
+            // udt_name (`_text`), which pgTypeToTs also understands.
+            const wireType = config.isArray ? `_${base}` : base;
+            const serial = isSerialType(config.type);
+            // PK members and serials are NOT NULL in Postgres regardless of flags.
+            const nullable = !(config.isPrimaryKey || config.isNotNull || serial);
+            const col = {
+                name,
+                field,
+                dialectType: wireType,
+                pgType: wireType,
+                tsType: pgTypeToTs(wireType, nullable),
+                nullable,
+                hasDefault: config.defaultValue != null || serial,
+                isArray: config.isArray,
+                arrayType: pgArrayType(base),
+                pgArrayType: pgArrayType(base),
+                ...(serial ? { isGenerated: true } : {}),
+                ...(config.maxLength != null ? { maxLength: config.maxLength } : {}),
+            };
+            columns.push(col);
+            columnMap[field] = name;
+            reverseColumnMap[name] = field;
+            allColumns.push(name);
+            dialectTypes[name] = wireType;
+            pgTypes[name] = wireType;
+            if (isDateType(base))
+                dateColumns.add(name);
+            if (config.isPrimaryKey)
+                primaryKey.push(name);
+            if (config.isUnique)
+                uniqueColumns.push([name]);
+        }
+        // Table-level composite PK takes precedence (defineSchema already cleared
+        // the column-level flags for its members).
+        const pk = tableDef.primaryKey && tableDef.primaryKey.length > 0 ? tableDef.primaryKey.map(camelToSnake) : primaryKey;
+        tables[tableDef.name] = {
+            name: tableDef.name,
+            columns,
+            columnMap,
+            reverseColumnMap,
+            dateColumns,
+            dialectTypes,
+            pgTypes,
+            allColumns,
+            primaryKey: pk,
+            uniqueColumns,
+            relations: relationsByTable.get(tableDef.name) ?? {},
+            // SchemaDef cannot express indexes. An empty list keeps
+            // schemaHasIndexInfo() false → no index-advisor false positives.
+            indexes: [],
+        };
+    }
+    const enums = {};
+    for (const [name, labels] of Object.entries(def.enums ?? {})) {
+        enums[name] = [...labels];
+    }
+    // ----- Pass 6: merge explicit manyToMany declarations (additive) ---------
+    return applyManyToManyRelations({ tables, enums }, def);
+}

package/dist/schema.d.ts

@@ -67,6 +67,16 @@ export interface ColumnMetadata {
     dialectType?: string;
     /** Postgres base type (e.g. 'int8', 'text', 'timestamptz'). Back-compat alias for dialectType. */
     pgType: string;
+    /**
+     * Schema the column's Postgres type lives in, recorded by introspection
+     * ONLY when it differs from the introspected schema (and isn't a
+     * `pg_catalog` builtin) — e.g. an enum or domain owned by another schema.
+     * Consumers use it as a cross-schema guard: a same-named enum in another
+     * schema must not receive this schema's `::"enum"` cast (search_path would
+     * resolve it to the wrong type). Absent for same-schema types, builtins,
+     * `defineSchema()` output, and legacy generated metadata.
+     */
+    pgTypeSchema?: string;
     /** TypeScript type string (e.g. 'number', 'string', 'Date') */
     tsType: string;
     /** Whether the column allows NULL */

package/dist/sqlite.js

@@ -49,7 +49,8 @@ import { createRequire } from 'node:module';
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
 import { ConnectionError } from './errors.js';
-import { isDateType, singularize, snakeToCamel, } from './schema.js';
+import { deriveEngineRelations } from './introspect.js';
+import { isDateType, snakeToCamel, } from './schema.js';
 let cachedDatabaseSync;
 /**
  * Lazily load `node:sqlite`'s `DatabaseSync` constructor.
@@ -637,95 +638,13 @@ export function introspectSqliteDatabase(db, options = {}) {
         indexesByTable.set(tableName, idxMeta);
         uniqueByTable.set(tableName, uniques);
     }
-    // ----- Build relations from foreign keys (belongsTo + hasMany) -----
-    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 needsDisambiguation = (fkCounts.get(`${fk.sourceTable}->${fk.targetTable}`) ?? 0) > 1;
-        const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
-        const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-        const belongsToName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
-            : singularize(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,
-            referenceKey,
-        };
-        const hasManyName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-            : 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,
-            referenceKey,
-        };
-    }
-    // ----- Conservative many-to-many auto-detection (additive) -----
-    // A table J is a pure junction iff: PK is exactly two columns, exactly two
-    // single-column FKs whose source columns ARE the PK, two distinct target
-    // tables, and no payload columns. Mirrors the Postgres introspector.
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2)
-            continue;
-        if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((c) => pkSet.has(c)))
-            continue;
-        if (new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
-        if (jCols.length !== 2)
-            continue;
-        const addM2M = (self, other) => {
-            const sourceTbl = self.targetTable;
-            const targetTbl = other.targetTable;
-            const relName = snakeToCamel(targetTbl);
-            if (!relationsByTable.has(sourceTbl))
-                relationsByTable.set(sourceTbl, {});
-            const existing = relationsByTable.get(sourceTbl);
-            if (existing[relName])
-                return;
-            existing[relName] = {
-                type: 'manyToMany',
-                name: relName,
-                from: sourceTbl,
-                to: targetTbl,
-                referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                through: {
-                    table: tableName,
-                    sourceKey: self.sourceColumns[0],
-                    targetKey: other.sourceColumns[0],
-                },
-            };
-        };
-        addM2M(fkA, fkB);
-        addM2M(fkB, fkA);
-    }
+    // ----- Build relations from foreign keys (belongsTo + hasMany + m2m) -----
+    // Delegated to the SHARED introspection pipeline (introspect.ts) so SQLite
+    // derives IDENTICAL relation names to the Postgres introspector for the
+    // same logical schema — legacy-first naming, per-column disambiguation,
+    // collision resolution against scalar column fields, and the conservative
+    // pure-junction manyToMany auto-detection included.
+    const relationsByTable = deriveEngineRelations(tableNames, foreignKeys, pkByTable, columnsByTable);
     // ----- Assemble TableMetadata -----
     const tables = {};
     for (const tableName of tableNames) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.28.3",
+  "version": "0.30.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {
@@ -114,8 +114,8 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@zvndev/powdb-client": "^0.7.1 || ^0.8.0",
-    "@zvndev/powdb-embedded": "^0.7.1 || ^0.8.0",
+    "@zvndev/powdb-client": ">=0.7.1 <1.0.0",
+    "@zvndev/powdb-embedded": ">=0.7.1 <1.0.0",
     "mssql": "^10.0.0 || ^11.0.0 || ^12.0.0",
     "mysql2": "^3.0.0"
   },