turbine-orm 0.50.0 → 0.51.0

package/dist/cjs/sqlite.js

@@ -1,17 +1,17 @@
 "use strict";
 /**
- * turbine-orm/sqlite — zero-dependency SQLite engine
+ * turbine-orm/sqlite, zero-dependency SQLite engine
  *
  * Binds Turbine to SQLite via Node's built-in `node:sqlite` driver
  * (`DatabaseSync`), so SQLite is a **zero new dependency** engine: the root
  * package's runtime dependency stays exactly `pg`. This is the in-process
- * test / edge / "try it in 10 seconds" engine — `:memory:` databases run
+ * test / edge / "try it in 10 seconds" engine, `:memory:` databases run
  * entirely in-process with no service container.
  *
  * ## Driver
  *
  * - **Primary:** `node:sqlite` `DatabaseSync` (Node ≥ 22.5, experimental). Emits
- *   an `ExperimentalWarning` — harmless. No native build, no extra dependency.
+ *   an `ExperimentalWarning`, harmless. No native build, no extra dependency.
  * - **Fallback:** `better-sqlite3` for Node < 22.5. Not bundled and not required;
  *   wrap a `better-sqlite3` handle in the same `PgCompatPool` shape if needed.
  *
@@ -25,7 +25,7 @@
  *   WAL` is enabled for file databases to allow concurrent readers.
  * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
  *   LISTEN/NOTIFY (`$listen` / `$notify`), RLS `sessionContext`. Advisory-lock
- *   migration locking is unavailable — SQLite is single-writer, so migrations
+ *   migration locking is unavailable, SQLite is single-writer, so migrations
  *   serialize naturally.
  * - **Type affinity caveats:** SQLite has no native `BOOLEAN` (0/1 integers) or
  *   `DATE` (TEXT/INTEGER). Booleans bind as 1/0; `Date` values bind as ISO-8601
@@ -35,7 +35,7 @@
  * - **Case-insensitive matching** uses `COLLATE NOCASE`, which is **ASCII-only**
  *   (no Unicode case folding).
  *
- * ## Example — `:memory:` database
+ * ## Example, `:memory:` database
  *
  * ```ts
  * import { turbineSqlite } from 'turbine-orm/sqlite';
@@ -63,8 +63,8 @@ let cachedDatabaseSync;
  * Lazily load `node:sqlite`'s `DatabaseSync` constructor.
  *
  * `node:sqlite` is a built-in only on Node >= 22.5, so importing it at module
- * top-level would make `import 'turbine-orm/sqlite'` — and any module that
- * merely re-exports `sqliteDialect` (e.g. the dialect test suite) — throw
+ * top-level would make `import 'turbine-orm/sqlite'`, and any module that
+ * merely re-exports `sqliteDialect` (e.g. the dialect test suite), throw
  * `ERR_UNKNOWN_BUILTIN_MODULE` on Node 20. Deferring the require to the moment a
  * connection is actually opened keeps the dialect (pure SQL generation) usable
  * everywhere and scopes the Node-version requirement to `turbineSqlite()`.
@@ -86,7 +86,7 @@ function loadDatabaseSync() {
             `Upgrade Node to >= 22.5, or pass an already-open better-sqlite3-compatible handle. (${err.message})`);
     }
     if (typeof ctor !== 'function') {
-        throw new errors_js_1.ConnectionError("[turbine] 'node:sqlite' loaded but did not export a DatabaseSync constructor — this Node build may lack SQLite support.");
+        throw new errors_js_1.ConnectionError("[turbine] 'node:sqlite' loaded but did not export a DatabaseSync constructor, this Node build may lack SQLite support.");
     }
     cachedDatabaseSync = ctor;
     return cachedDatabaseSync;
@@ -119,7 +119,7 @@ function toSqliteParam(value) {
 /**
  * Normalize a single column value read from SQLite. With `setReadBigInts(true)`
  * every integer column comes back as a `bigint`; apply the same safe-integer
- * policy Turbine uses for Postgres `int8` — number when it fits in a JS safe
+ * policy Turbine uses for Postgres `int8`, number when it fits in a JS safe
  * integer, otherwise the decimal string to avoid precision loss. Never mutates
  * any global parser state (the policy lives entirely in this shim).
  */
@@ -160,7 +160,7 @@ function statementReturnsRows(sql) {
  * recognizable SQLite error.
  *
  * `wrapPgError` is invoked downstream (in the query executor and the
- * transaction proxy), so we only annotate here — we never throw a `new`
+ * transaction proxy), so we only annotate here, we never throw a `new`
  * Turbine error from the driver itself.
  */
 function augmentSqliteError(err) {
@@ -228,7 +228,7 @@ function normalizeQueryArgs(arg, values) {
 /**
  * Bind the positional `params[]` (in 1-indexed generation order) to the named
  * `:p1`, `:p2`, … placeholders the dialect emits. Mapping by NAME makes binding
- * independent of where each placeholder lands in the SQL text — the same
+ * independent of where each placeholder lands in the SQL text, the same
  * guarantee Postgres' numbered `$N` gives. Returns `undefined` when there are no
  * params so parameter-less statements (BEGIN/COMMIT/DDL) bind nothing.
  */
@@ -268,12 +268,12 @@ function runStatement(db, sql, values) {
 /**
  * A `PgCompatPool` backed by a single `node:sqlite` `DatabaseSync` connection.
  * SQLite is single-connection by nature (a `:memory:` database is per-handle),
- * so `connect()` hands back a client over the **same** handle — transactions
+ * so `connect()` hands back a client over the **same** handle, transactions
  * (`BEGIN`/`COMMIT`/`ROLLBACK`, `SAVEPOINT` nesting) just run on it. Queries are
  * serialized; this is the documented single-writer model.
  */
 class SqlitePool {
-    /** The underlying `node:sqlite` handle — exposed as an escape hatch (seed/DDL). */
+    /** The underlying `node:sqlite` handle, exposed as an escape hatch (seed/DDL). */
     db;
     closed = false;
     constructor(db) {
@@ -293,7 +293,7 @@ class SqlitePool {
                 return runStatement(db, sql, params);
             },
             release: () => {
-                // Single shared connection — nothing to return to a pool.
+                // Single shared connection, nothing to return to a pool.
             },
         };
     }
@@ -357,7 +357,7 @@ function sqliteColumnAffinity(type) {
     return 'TEXT';
 }
 // ---------------------------------------------------------------------------
-// sqliteDialect — the full Dialect contract for SQLite
+// sqliteDialect, the full Dialect contract for SQLite
 // ---------------------------------------------------------------------------
 /**
  * SQLite implementation of the {@link Dialect} contract. Standardizes on `"…"`
@@ -394,7 +394,7 @@ exports.sqliteDialect = {
     jsonPathSupport: 'function',
     emptyJsonArrayLiteral: "json('[]')",
     nullJsonLiteral: 'NULL',
-    // Named placeholders (`:p1`, `:p2`, …) — NOT positional `?`. Turbine pushes
+    // Named placeholders (`:p1`, `:p2`, …), NOT positional `?`. Turbine pushes
     // params in 1-indexed generation order but may EMIT them in a different SQL
     // text position (e.g. a `with`-relation LIMIT lands in the SELECT list, ahead
     // of the outer WHERE). Postgres reconciles this via numbered `$N`; positional
@@ -426,6 +426,37 @@ exports.sqliteDialect = {
     wrapJsonSubresult(subquery, fallback) {
         return `COALESCE(json((${subquery})), ${fallback})`;
     },
+    jsonWireRule(columnType) {
+        // SQLite's storage classes, as introspection records them.
+        const t = columnType.toUpperCase();
+        // INTEGER is 64-bit, and `json_object` renders it as a JSON number, which
+        // is an IEEE double: 9007199254740993 came back through a `with` join as
+        // …992 while a top-level read and the batched loader both returned the
+        // exact decimal string. Carry the text and re-apply the SAME safe-integer
+        // policy `normalizeValue` applies to the driver's bigint, so all three
+        // paths agree for both small and large values.
+        if (t.includes('INT')) {
+            return {
+                sql: (ref) => `CAST(${ref} AS TEXT)`,
+                decode: (value) => {
+                    if (typeof value !== 'string' || !/^-?\d+$/.test(value))
+                        return value;
+                    const asNumber = Number(value);
+                    return Number.isSafeInteger(asNumber) ? asNumber : value;
+                },
+            };
+        }
+        // A BLOB cannot go into JSON at all: SQLite raises "JSON cannot hold BLOB
+        // values" and the whole query fails with a raw SQL logic error, where the
+        // batched loader returns the row fine. Carry hex and rebuild the bytes.
+        if (t.includes('BLOB')) {
+            return {
+                sql: (ref) => `hex(${ref})`,
+                decode: (value) => (typeof value === 'string' ? Uint8Array.from(Buffer.from(value, 'hex')) : value),
+            };
+        }
+        return undefined;
+    },
     castAggregate(expr, target) {
         return `CAST(${expr} AS ${target === 'int' ? 'INTEGER' : 'REAL'})`;
     },
@@ -446,7 +477,7 @@ exports.sqliteDialect = {
             `VALUES (${input.valuePlaceholders.join(', ')})${this.buildReturningClause(input.returning)}`);
     },
     buildBulkInsertStatement(input) {
-        // No UNNEST in SQLite — emit multi-row VALUES with flattened, named
+        // No UNNEST in SQLite, emit multi-row VALUES with flattened, named
         // placeholders (`:p1`, `:p2`, …) matching the flat param order.
         let n = 0;
         const placeholders = input.rowValues
@@ -469,12 +500,12 @@ exports.sqliteDialect = {
             this.buildReturningClause(input.returning));
     },
     buildInsensitiveLike(column, paramRef) {
-        // COLLATE NOCASE is ASCII-only (no Unicode case folding) — documented limit.
+        // COLLATE NOCASE is ASCII-only (no Unicode case folding), documented limit.
         return `${column} LIKE ${paramRef} COLLATE NOCASE`;
     },
     buildJsonContains(column, paramRef) {
         // Emulated containment: true when any top-level JSON value equals the param.
-        // Limited vs Postgres `@>` (no deep/object containment) — jsonPathSupport='function'.
+        // Limited vs Postgres `@>` (no deep/object containment), jsonPathSupport='function'.
         return `EXISTS (SELECT 1 FROM json_each(${column}) WHERE json_each.value = ${paramRef})`;
     },
     buildJsonPathExtract(column, pathParamRef) {
@@ -555,7 +586,7 @@ exports.sqliteDialect = {
     },
 };
 function pragma(db, sql) {
-    // PRAGMA / SELECT against sqlite_master — read-only, identifiers are SQLite
+    // PRAGMA / SELECT against sqlite_master, read-only, identifiers are SQLite
     // catalog names (never user input here), values normalized for safe ints.
     return db.prepare(sql).all().map(normalizeRow);
 }
@@ -658,7 +689,7 @@ function introspectSqliteDatabase(db, options = {}) {
     // ----- 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,
+    // 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 = (0, introspect_js_1.deriveEngineRelations)(tableNames, foreignKeys, pkByTable, columnsByTable);
@@ -740,7 +771,7 @@ function openSqliteDatabase(target, options) {
             db.exec('PRAGMA journal_mode = WAL');
         }
         catch {
-            // Some filesystems (network mounts) reject WAL — fall back silently.
+            // Some filesystems (network mounts) reject WAL, fall back silently.
         }
     }
     return db;

package/dist/cjs/typed-sql.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Typed raw SQL (Turbine's answer to Prisma's TypedSQL)
+ * turbine-orm, Typed raw SQL (Turbine's answer to Prisma's TypedSQL)
  *
  * `client.raw()` returns untyped rows. This module adds a *typed* escape hatch:
  * a generic tagged template where the caller supplies the row shape, and the
@@ -9,13 +9,13 @@
  * Design goals & guarantees:
  *
  *  1. **Compile-time only types.** `T` is supplied by the caller and never
- *     validated at runtime — exactly like Prisma's TypedSQL and the existing
+ *     validated at runtime, exactly like Prisma's TypedSQL and the existing
  *     `raw<T>()`. Postgres still returns whatever the SQL selects; the generic
  *     is a convenience for autocomplete and downstream type-checking.
  *
  *  2. **Mandatory parameterization.** Only the *static* string segments of the
  *     template literal ever reach the SQL text. Every interpolated `${value}`
- *     becomes a `$N` placeholder and is passed in the params array — it is
+ *     becomes a `$N` placeholder and is passed in the params array, it is
  *     impossible to string-concatenate a value into the query through this API.
  *     This is the whole point of the tagged-template shape: the literal segments
  *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
@@ -69,7 +69,7 @@ export declare function buildTypedSql(strings: TemplateStringsArray, values: rea
  * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
  *
  * The query is executed lazily and exactly once per terminal call (`then`,
- * `one`, `scalar`). Each terminal method runs the query independently — this is
+ * `one`, `scalar`). Each terminal method runs the query independently, this is
  * an escape hatch, not a cached query object, so don't call two terminals on
  * the same builder expecting a single round-trip; build a fresh template each
  * time (the common pattern is `await db.sql\`...\`` inline).

package/dist/cjs/typed-sql.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * turbine-orm — Typed raw SQL (Turbine's answer to Prisma's TypedSQL)
+ * turbine-orm, Typed raw SQL (Turbine's answer to Prisma's TypedSQL)
  *
  * `client.raw()` returns untyped rows. This module adds a *typed* escape hatch:
  * a generic tagged template where the caller supplies the row shape, and the
@@ -10,13 +10,13 @@
  * Design goals & guarantees:
  *
  *  1. **Compile-time only types.** `T` is supplied by the caller and never
- *     validated at runtime — exactly like Prisma's TypedSQL and the existing
+ *     validated at runtime, exactly like Prisma's TypedSQL and the existing
  *     `raw<T>()`. Postgres still returns whatever the SQL selects; the generic
  *     is a convenience for autocomplete and downstream type-checking.
  *
  *  2. **Mandatory parameterization.** Only the *static* string segments of the
  *     template literal ever reach the SQL text. Every interpolated `${value}`
- *     becomes a `$N` placeholder and is passed in the params array — it is
+ *     becomes a `$N` placeholder and is passed in the params array, it is
  *     impossible to string-concatenate a value into the query through this API.
  *     This is the whole point of the tagged-template shape: the literal segments
  *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
@@ -86,7 +86,7 @@ function buildTypedSql(strings, values, dialect = dialect_js_1.postgresDialect)
  * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
  *
  * The query is executed lazily and exactly once per terminal call (`then`,
- * `one`, `scalar`). Each terminal method runs the query independently — this is
+ * `one`, `scalar`). Each terminal method runs the query independently, this is
  * an escape hatch, not a cached query object, so don't call two terminals on
  * the same builder expecting a single round-trip; build a fresh template each
  * time (the common pattern is `await db.sql\`...\`` inline).
@@ -118,7 +118,7 @@ class TypedSqlQuery {
     /**
      * PromiseLike implementation: `await db.sql<T>\`...\`` resolves to `T[]`.
      */
-    // biome-ignore lint/suspicious/noThenProperty: intentional thenable — this IS the PromiseLike contract that makes `await db.sql\`...\`` resolve to rows
+    // biome-ignore lint/suspicious/noThenProperty: intentional thenable, this IS the PromiseLike contract that makes `await db.sql\`...\`` resolve to rows
     then(onfulfilled, onrejected) {
         return this.run().then(onfulfilled, onrejected);
     }

package/dist/cli/config.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm CLI — Configuration file support
+ * turbine-orm CLI, Configuration file support
  *
  * Loads turbine.config.ts (or .js/.mjs) via dynamic import.
  * Falls back to CLI args and environment variables.
@@ -15,6 +15,15 @@ export interface TurbineCliConfig {
     include?: string[];
     /** Tables to exclude */
     exclude?: string[];
+    /**
+     * Rename derived relations, as `{ table: { derivedName: desiredName } }`.
+     *
+     * Relation names are composed by introspection (a database does not name its
+     * relationships), so two foreign keys to the same table produce names nobody
+     * would predict, and a port from another ORM that named them differently has
+     * to hand-edit every call site. A typo here is an error, not a silent no-op.
+     */
+    relationNames?: Record<string, Record<string, string>>;
     /**
      * Extension for the generated `index.ts` sibling imports (F3):
      * `'js'` (`./types.js`), `'none'` (`./types`), or `'auto'` (default:
@@ -69,7 +78,7 @@ export type TurbineConfig = TurbineCliConfig;
  * path rather than a Postgres schema name? `schema` is the Postgres namespace
  * to introspect (default `public`); the schema-builder file goes in `schemaFile`.
  * A value containing a path separator or a JS/TS extension is almost certainly a
- * mis-set `schemaFile` — introspecting `WHERE table_schema = './turbine/schema.ts'`
+ * mis-set `schemaFile`, introspecting `WHERE table_schema = './turbine/schema.ts'`
  * silently matches zero tables. Used by `turbine generate` to fail loudly.
  */
 export declare function looksLikeSchemaFilePath(schema: string): boolean;
@@ -156,6 +165,8 @@ export interface ResolvedConfig {
     keepColumnNames: boolean;
     /** Resolved opt-out of the unique-FK → hasOne introspection flip (F2). */
     legacyToManyUniques: boolean;
+    /** Resolved derived-relation rename map, or undefined when none is declared. */
+    relationNames?: Record<string, Record<string, string>>;
 }
 export interface CliOverrides {
     url?: string;

package/dist/cli/config.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm CLI — Configuration file support
+ * turbine-orm CLI, Configuration file support
  *
  * Loads turbine.config.ts (or .js/.mjs) via dynamic import.
  * Falls back to CLI args and environment variables.
@@ -12,7 +12,7 @@ import { pathToFileURL } from 'node:url';
  * path rather than a Postgres schema name? `schema` is the Postgres namespace
  * to introspect (default `public`); the schema-builder file goes in `schemaFile`.
  * A value containing a path separator or a JS/TS extension is almost certainly a
- * mis-set `schemaFile` — introspecting `WHERE table_schema = './turbine/schema.ts'`
+ * mis-set `schemaFile`, introspecting `WHERE table_schema = './turbine/schema.ts'`
  * silently matches zero tables. Used by `turbine generate` to fail loudly.
  */
 export function looksLikeSchemaFilePath(schema) {
@@ -158,6 +158,7 @@ export function resolveConfig(fileConfig, overrides) {
         out: overrides.out ?? fileConfig.out ?? './generated/turbine',
         schema: overrides.schema ?? fileConfig.schema ?? 'public',
         include: overrides.include ?? fileConfig.include ?? [],
+        relationNames: fileConfig.relationNames,
         exclude: overrides.exclude ?? fileConfig.exclude ?? [],
         migrationsDir: fileConfig.migrationsDir ?? './turbine/migrations',
         // `seedFile` is canonical (what the docs and `turbine init` use); `seed` is a

package/dist/cli/destructive.d.ts

@@ -23,7 +23,7 @@
  */
 export type DestructiveKind = 'drop-table' | 'drop-schema' | 'drop-database' | 'drop-owned' | 'drop-matview' | 'drop-column' | 'truncate' | 'delete' | 'update-without-where' | 'alter-column-type' | 'merge-delete';
 export interface DestructiveStatement {
-    /** The offending SQL statement (trimmed, possibly long — display truncated) */
+    /** The offending SQL statement (trimmed, possibly long, display truncated) */
     statement: string;
     kind: DestructiveKind;
     /** Best-effort extracted object name (table, schema, or table.column) */

package/dist/cli/destructive.js

@@ -129,7 +129,7 @@ function isEscapeStringPrefix(sql, quoteAt) {
 /** Unquote a "quoted" identifier for display. */
 const ident = (raw) => (raw ?? '?').replace(/^"|"$/g, '');
 const IDENT = String.raw `("[^"]+"|[a-zA-Z_][\w$]*)(\.("[^"]+"|[a-zA-Z_][\w$]*))?`;
-/** Ordered rules — first match per statement wins. */
+/** Ordered rules, first match per statement wins. */
 const RULES = [
     {
         kind: 'drop-table',

package/dist/cli/index.d.ts

@@ -3,21 +3,21 @@
  * turbine-orm CLI
  *
  * Commands:
- *   turbine init                  — Initialize a Turbine project
- *   turbine generate | pull       — Introspect database and generate TypeScript types
+ *   turbine init                 , Initialize a Turbine project
+ *   turbine generate | pull      , Introspect database and generate TypeScript types
  *   turbine migrate-from-prisma   - Parse a schema.prisma and emit a Prisma->Turbine name map + report
  *   turbine push                  - Apply schema-builder definitions to database (destructive ops gated)
  *   turbine migrate create <name> - Create a new SQL migration file (--auto | --from-diff | --recipe <name>)
- *   turbine migrate up            — Apply pending migrations
- *   turbine migrate deploy        — Apply pending migrations without prompts
- *   turbine migrate down          — Rollback last migration
- *   turbine migrate status        — Show migration status
- *   turbine seed                  — Run seed file
- *   turbine status                — Show schema summary
+ *   turbine migrate up           , Apply pending migrations
+ *   turbine migrate deploy       , Apply pending migrations without prompts
+ *   turbine migrate down         , Rollback last migration
+ *   turbine migrate status       , Show migration status
+ *   turbine seed                 , Run seed file
+ *   turbine status               , Show schema summary
  *   turbine doctor                - Cost-aware missing-FK-index triage (--fix, --json, --no-concurrently, --unused, --audit)
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
- *   turbine mcp                   — Start read-only MCP server over JSON-RPC stdio
- *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
+ *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
+ *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate