turbine-orm 0.50.0 → 0.51.0

package/dist/sqlite.js

@@ -1,16 +1,16 @@
 /**
- * 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.
  *
@@ -24,7 +24,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
@@ -34,7 +34,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';
@@ -56,8 +56,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()`.
@@ -79,7 +79,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 ConnectionError("[turbine] 'node:sqlite' loaded but did not export a DatabaseSync constructor — this Node build may lack SQLite support.");
+        throw new ConnectionError("[turbine] 'node:sqlite' loaded but did not export a DatabaseSync constructor, this Node build may lack SQLite support.");
     }
     cachedDatabaseSync = ctor;
     return cachedDatabaseSync;
@@ -112,7 +112,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).
  */
@@ -153,7 +153,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) {
@@ -221,7 +221,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.
  */
@@ -261,12 +261,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.
  */
 export 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) {
@@ -286,7 +286,7 @@ export 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.
             },
         };
     }
@@ -349,7 +349,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 `"…"`
@@ -386,7 +386,7 @@ export const 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
@@ -418,6 +418,37 @@ export const 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'})`;
     },
@@ -438,7 +469,7 @@ export const 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
@@ -461,12 +492,12 @@ export const 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) {
@@ -547,7 +578,7 @@ export const 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);
 }
@@ -650,7 +681,7 @@ export 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 = deriveEngineRelations(tableNames, foreignKeys, pkByTable, columnsByTable);
@@ -732,7 +763,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/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/typed-sql.js

@@ -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
@@ -82,7 +82,7 @@ export function buildTypedSql(strings, values, dialect = 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).
@@ -114,7 +114,7 @@ export 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "turbine-orm",
-  "version": "0.50.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",
+  "version": "0.51.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": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",
   "exports": {