turbine-orm 0.65.0 → 0.66.0

package/dist/schema.d.ts

@@ -115,7 +115,9 @@ export interface ColumnMetadata {
      * Tagged in `defineSchema` (`pii: true`) and carried through generated
      * metadata. A PII column is EXCLUDED from default projections: it comes back
      * only when explicitly named in `select` or when the query passes
-     * `includePii: true` (full opt-in). Studio redacts PII cells by default.
+     * `includePii: UNSAFE` (full opt-in, the imported sentinel symbol, since a
+     * literal `true` is what a stray JSON body deserializes to). Studio redacts
+     * PII cells by default.
      * Optional / defaults to `false`; untagged schemas behave exactly as before.
      * Introspection never auto-tags PII (it is a code-first declaration).
      */

package/dist/sqlite.d.ts

@@ -67,6 +67,12 @@ export declare class SqlitePool implements PgCompatPool {
     /** The underlying `node:sqlite` handle, exposed as an escape hatch (seed/DDL). */
     readonly db: DatabaseSync;
     private closed;
+    /**
+     * `sql -> declared-boolean result columns` (or `null` for none). Bounded like
+     * the query builder's SQL-template cache, since a caller can generate
+     * unbounded distinct statements (raw SQL, an IN-list that inlines).
+     */
+    private readonly booleanCache;
     constructor(db: DatabaseSync);
     query(text: QueryArg, values?: unknown[]): Promise<any>;
     connect(): Promise<PgCompatPoolClient>;

package/dist/sqlite.js

@@ -50,6 +50,7 @@ import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
 import { ConnectionError, UnsupportedFeatureError } from './errors.js';
 import { applyTableFilters, deriveEngineRelations } from './introspect.js';
+import { LRUCache } from './query/utils.js';
 import { isDateType, snakeToCamel, } from './schema.js';
 let cachedDatabaseSync;
 /**
@@ -123,14 +124,101 @@ function normalizeValue(value) {
     }
     return value;
 }
-/** Convert a `node:sqlite` null-prototype row into a normalized plain object. */
-function normalizeRow(row) {
+/**
+ * Convert a `node:sqlite` null-prototype row into a normalized plain object.
+ *
+ * `booleanKeys`, when present, names the result columns whose ORIGIN column is
+ * declared with a boolean affinity; their 1/0 storage is turned back into
+ * `true`/`false` (see {@link booleanResultColumns}). Anything else in such a
+ * column, and every column not listed, passes through untouched.
+ */
+function normalizeRow(row, booleanKeys) {
     const out = {};
     for (const key of Object.keys(row)) {
-        out[key] = normalizeValue(row[key]);
+        const value = normalizeValue(row[key]);
+        out[key] = booleanKeys?.has(key) && (value === 1 || value === 0) ? value === 1 : value;
     }
     return out;
 }
+/**
+ * The result columns of a prepared statement whose ORIGIN column is declared
+ * boolean, or `null` when there are none (the overwhelmingly common case).
+ *
+ * WHY THIS EXISTS. SQLite has no boolean storage class: a `BOOLEAN` column
+ * holds 1/0 integers. Turbine still generates `ok: boolean` for it
+ * ({@link sqliteTypeToTs} maps `/bool/` to `boolean`), so `row.ok === true` was
+ * false, `JSON.stringify(row)` emitted `1`, and a value the ORM itself wrote as
+ * `true` came back as a number. The declared type is the ONLY thing that says
+ * "this integer is a boolean", and it lives in the schema, not in the value.
+ *
+ * The decltype comes from the driver rather than from Turbine's metadata
+ * because the driver knows which TABLE each result column came from.
+ * `StatementSync.columns()` reports `type` as `sqlite3_column_decltype`, which
+ * is non-null only for a direct table-column reference and null for any
+ * expression, so a computed column can never be coerced by accident.
+ *
+ * Node gained `columns()` in 22.13 / 23.4 while this engine's floor is 22.5, so
+ * it is feature-detected: on the narrow band without it, booleans keep reading
+ * back as 1/0 exactly as before rather than the engine refusing to run.
+ */
+function booleanResultColumns(stmt) {
+    const columnsFn = stmt.columns;
+    if (typeof columnsFn !== 'function')
+        return null;
+    let described;
+    try {
+        described = columnsFn.call(stmt);
+    }
+    catch {
+        // A statement the driver cannot describe (some PRAGMA forms) is not worth
+        // failing a query over; skip the coercion for it.
+        return null;
+    }
+    let out = null;
+    for (const c of described) {
+        if (typeof c.name !== 'string' || typeof c.type !== 'string')
+            continue;
+        if (!/bool/i.test(c.type))
+            continue;
+        if (out === null)
+            out = new Set();
+        out.add(c.name);
+    }
+    return out;
+}
+/**
+ * The `node:sqlite` namespace, looked up once, or `null` when this Node build
+ * has no such builtin. Deliberately separate from {@link loadDatabaseSync},
+ * which THROWS: this is a capability question asked from the pure dialect,
+ * which must stay importable on Node 20.
+ */
+let cachedSqliteNamespace;
+/**
+ * Can the driver report a result column's DECLARED type?
+ *
+ * This is the same capability {@link booleanResultColumns} feature-detects, and
+ * the two have to be asked the SAME question or they split: that helper is what
+ * turns 1/0 into `true`/`false` on every direct read, and the boolean
+ * `jsonWireRule` is what does it on the join path. On the Node band with
+ * `node:sqlite` but without `StatementSync.columns()` (>= 22.5, < 22.13 / 23.4)
+ * the helper returns `null` and every direct read keeps 1/0, so a join that
+ * still converted would produce exactly the strategy-dependent type flip the
+ * rule exists to prevent, on the one runtime where nothing else can catch it.
+ *
+ * The prototype property is re-read on each call rather than memoized as a
+ * boolean, so the answer cannot outlive the capability.
+ */
+function driverReportsDeclaredTypes() {
+    if (cachedSqliteNamespace === undefined) {
+        try {
+            cachedSqliteNamespace = createRequire(process.cwd())('node:sqlite');
+        }
+        catch {
+            cachedSqliteNamespace = null;
+        }
+    }
+    return typeof cachedSqliteNamespace?.StatementSync?.prototype?.columns === 'function';
+}
 // ---------------------------------------------------------------------------
 // Statement classification + error translation
 // ---------------------------------------------------------------------------
@@ -234,7 +322,7 @@ function toNamedBinding(values) {
     }
     return named;
 }
-function runStatement(db, sql, values) {
+function runStatement(db, sql, values, booleanCache) {
     const binding = toNamedBinding(values);
     let stmt;
     try {
@@ -246,7 +334,15 @@ function runStatement(db, sql, values) {
     stmt.setReadBigInts(true);
     try {
         if (statementReturnsRows(sql)) {
-            const rows = (binding ? stmt.all(binding) : stmt.all()).map(normalizeRow);
+            // Describe each distinct statement ONCE. `null` (no boolean column) is a
+            // cached answer too, so the ordinary query pays a single Map hit per call
+            // and nothing per row.
+            let booleanKeys = booleanCache?.get(sql);
+            if (booleanKeys === undefined) {
+                booleanKeys = booleanResultColumns(stmt);
+                booleanCache?.set(sql, booleanKeys);
+            }
+            const rows = (binding ? stmt.all(binding) : stmt.all()).map((r) => normalizeRow(r, booleanKeys ?? undefined));
             return { rows, rowCount: rows.length };
         }
         const info = binding ? stmt.run(binding) : stmt.run();
@@ -269,21 +365,28 @@ export class SqlitePool {
     /** The underlying `node:sqlite` handle, exposed as an escape hatch (seed/DDL). */
     db;
     closed = false;
+    /**
+     * `sql -> declared-boolean result columns` (or `null` for none). Bounded like
+     * the query builder's SQL-template cache, since a caller can generate
+     * unbounded distinct statements (raw SQL, an IN-list that inlines).
+     */
+    booleanCache = new LRUCache(1000);
     constructor(db) {
         this.db = db;
     }
     // biome-ignore lint/suspicious/noExplicitAny: pg-compat query is generic over the row shape; runStatement returns plain objects.
     async query(text, values) {
         const { text: sql, params } = normalizeQueryArgs(text, values);
-        return runStatement(this.db, sql, params);
+        return runStatement(this.db, sql, params, this.booleanCache);
     }
     async connect() {
         const db = this.db;
+        const booleanCache = this.booleanCache;
         return {
             // biome-ignore lint/suspicious/noExplicitAny: see query() above.
             query: async (text, values) => {
                 const { text: sql, params } = normalizeQueryArgs(text, values);
-                return runStatement(db, sql, params);
+                return runStatement(db, sql, params, booleanCache);
             },
             release: () => {
                 // Single shared connection, nothing to return to a pool.
@@ -367,6 +470,7 @@ export const sqliteDialect = {
     supportsReturning: true,
     supportsILike: false,
     supportsVector: false,
+    supportsJsonContains: false,
     // FTS5 is a virtual-table feature with its own MATCH syntax, not the
     // `to_tsvector @@ to_tsquery` shape Turbine's `search` filter emits.
     supportsFullTextSearch: false,
@@ -439,6 +543,33 @@ export const sqliteDialect = {
                 },
             };
         }
+        // A declared-boolean column is 1/0 in storage, and the driver shim turns
+        // that back into true/false on every direct read (see
+        // booleanResultColumns). `json_object` sees the raw integer and has no
+        // decltype to consult, so the join strategy alone would have kept handing
+        // back 1/0 while the top-level read, the batched loader and the flatten
+        // plan returned booleans, which is the same strategy-dependent type flip
+        // the bigint rule above exists to prevent. No cast is needed, only the
+        // decode: the JSON number IS the stored value, it just has to be read the
+        // same way.
+        //
+        // Gated on the SAME capability the direct-read half feature-detects (see
+        // driverReportsDeclaredTypes). Without it the shim cannot name a boolean
+        // result column, so 1/0 is the answer everywhere; converting here alone
+        // would put the flip back, pointing the other way.
+        if (t.includes('BOOL') && driverReportsDeclaredTypes()) {
+            return {
+                // Carried as TEXT because that is how the decode half is reached at
+                // all: the parser only runs `decode` on a string cell, so a rule that
+                // left the JSON number alone would never fire. The CASE narrows the
+                // carrier to EXACTLY the two values that mean true/false, so anything
+                // else a declared-boolean column happens to hold (SQLite does not
+                // enforce the type) stays in its own JSON form and reads back as the
+                // driver would have returned it, rather than being stringified.
+                sql: (ref) => `CASE WHEN ${ref} IN (0, 1) THEN CAST(${ref} AS TEXT) ELSE ${ref} END`,
+                decode: (value) => (value === '1' ? true : value === '0' ? false : 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.
@@ -523,9 +654,14 @@ export const sqliteDialect = {
         // COLLATE NOCASE is ASCII-only (no Unicode case folding), documented limit.
         return `${column} LIKE ${paramRef} COLLATE NOCASE`;
     },
+    // UNREACHABLE while `supportsJsonContains` is false, and kept deliberately:
+    // it is the emulation this dialect would use if the encoding mismatch were
+    // repaired, and deleting it would delete the record of what was tried. The
+    // param is bound as JSON text (`'"gold"'`) while `json_each.value` yields the
+    // decoded SQL value (`gold`), so this predicate never holds for ANY operand.
+    // See `supportsJsonContains` in dialect.ts for the measurements and the shape
+    // a faithful version needs (`json_each.type` alongside the value).
     buildJsonContains(column, paramRef) {
-        // Emulated containment: true when any top-level JSON value equals the param.
-        // 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) {
@@ -608,7 +744,12 @@ export const sqliteDialect = {
 function pragma(db, sql) {
     // 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);
+    // No boolean-key set: PRAGMA output columns are catalog metadata (`notnull`,
+    // `pk`, `unique`), which are 0/1 integers the introspector reads AS integers.
+    return db
+        .prepare(sql)
+        .all()
+        .map((r) => normalizeRow(r));
 }
 /**
  * Read a live SQLite database (an open `DatabaseSync` handle) into the same

package/dist/typed-sql.d.ts

@@ -79,7 +79,35 @@ export declare class TypedSqlQuery<T extends Record<string, unknown>> implements
     private readonly sql;
     private readonly params;
     private readonly logging;
-    constructor(pool: PgCompatPool, sql: string, params: unknown[], logging: boolean);
+    /**
+     * Runs the execution under the owning client's `errorMessages` mode. Passed
+     * in rather than read here because this module must not import the client.
+     *
+     * It has to reach the EXECUTION, not the construction, and that is the whole
+     * reason it is a constructor parameter instead of a wrapper around
+     * `client.sql\`...\``: this builder is lazy, so a scope established around
+     * the tagged-template call is torn down before a single row is fetched.
+     * Wrapping the template call compiled, ran, and protected nothing.
+     *
+     * Defaults to calling through, so a `TypedSqlQuery` built outside a client
+     * behaves exactly as before.
+     */
+    private readonly runScoped;
+    constructor(pool: PgCompatPool, sql: string, params: unknown[], logging: boolean, 
+    /**
+     * Runs the execution under the owning client's `errorMessages` mode. Passed
+     * in rather than read here because this module must not import the client.
+     *
+     * It has to reach the EXECUTION, not the construction, and that is the whole
+     * reason it is a constructor parameter instead of a wrapper around
+     * `client.sql\`...\``: this builder is lazy, so a scope established around
+     * the tagged-template call is torn down before a single row is fetched.
+     * Wrapping the template call compiled, ran, and protected nothing.
+     *
+     * Defaults to calling through, so a `TypedSqlQuery` built outside a client
+     * behaves exactly as before.
+     */
+    runScoped?: <R>(fn: () => R) => R);
     /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
     private run;
     /**

package/dist/typed-sql.js

@@ -92,24 +92,42 @@ export class TypedSqlQuery {
     sql;
     params;
     logging;
-    constructor(pool, sql, params, logging) {
+    runScoped;
+    constructor(pool, sql, params, logging, 
+    /**
+     * Runs the execution under the owning client's `errorMessages` mode. Passed
+     * in rather than read here because this module must not import the client.
+     *
+     * It has to reach the EXECUTION, not the construction, and that is the whole
+     * reason it is a constructor parameter instead of a wrapper around
+     * `client.sql\`...\``: this builder is lazy, so a scope established around
+     * the tagged-template call is torn down before a single row is fetched.
+     * Wrapping the template call compiled, ran, and protected nothing.
+     *
+     * Defaults to calling through, so a `TypedSqlQuery` built outside a client
+     * behaves exactly as before.
+     */
+    runScoped = (fn) => fn()) {
         this.pool = pool;
         this.sql = sql;
         this.params = params;
         this.logging = logging;
+        this.runScoped = runScoped;
     }
     /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
-    async run() {
-        if (this.logging) {
-            console.log(`[turbine] Typed SQL: ${this.sql.trim().substring(0, 120)}...`);
-        }
-        try {
-            const result = await this.pool.query(this.sql, this.params);
-            return result.rows;
-        }
-        catch (err) {
-            throw wrapPgError(err);
-        }
+    run() {
+        return this.runScoped(async () => {
+            if (this.logging) {
+                console.log(`[turbine] Typed SQL: ${this.sql.trim().substring(0, 120)}...`);
+            }
+            try {
+                const result = await this.pool.query(this.sql, this.params);
+                return result.rows;
+            }
+            catch (err) {
+                throw wrapPgError(err);
+            }
+        });
     }
     /**
      * PromiseLike implementation: `await db.sql<T>\`...\`` resolves to `T[]`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.65.0",
+  "version": "0.66.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).",
@@ -124,13 +124,15 @@
     "test:unit": "DATABASE_URL= tsx --test src/test/*.test.ts",
     "test:coverage": "c8 tsx --test --test-concurrency=1 src/test/*.test.ts",
     "//coverage:cli": "The CLI coverage gate, split into ONE collection run plus FOUR threshold checks. c8 enforces a single threshold set per invocation and its --per-file applies the SAME numbers to every file, neither of which can express 'destructive.ts holds 100 while migrate.ts holds 70'. An aggregate-only floor lets the least-covered file spend the whole slack the best-covered file earned: at the measured 3623/2951 lines, migrate.ts could fall from 70.3% to 66.6% with the aggregate still green. So each file gets its OWN floor, checked by re-reporting the coverage already on disk (c8 report re-reads ./coverage/tmp, so this costs no extra test run). The aggregate check is kept as well: it catches all three sagging together inside their individual margins. Per-file gates run FIRST because their failure names the file. DATABASE_URL is neutralized on the collection run: these test files include live migration tests that create and drop tables, and this script runs from prepublishOnly.",
-    "test:coverage:cli": "npm run coverage:cli:collect && npm run coverage:cli:gate:destructive && npm run coverage:cli:gate:studio && npm run coverage:cli:gate:migrate && npm run coverage:cli:gate:aggregate",
-    "coverage:cli:collect": "DATABASE_URL= c8 --all --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts tsx --test src/test/studio-write.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts",
+    "test:coverage:cli": "npm run coverage:cli:collect && npm run coverage:cli:gate:destructive && npm run coverage:cli:gate:sql-statements && npm run coverage:cli:gate:pii-guard && npm run coverage:cli:gate:studio && npm run coverage:cli:gate:migrate && npm run coverage:cli:gate:aggregate",
+    "coverage:cli:collect": "DATABASE_URL= c8 --all --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts tsx --test src/test/studio-write.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts",
     "coverage:cli:gate": "c8 report --all --exclude 'src/test/**' --reporter text --check-coverage",
     "coverage:cli:gate:destructive": "npm run coverage:cli:gate -- --include src/cli/destructive.ts --lines 98 --statements 98 --branches 84 --functions 98",
+    "coverage:cli:gate:sql-statements": "npm run coverage:cli:gate -- --include src/cli/sql-statements.ts --lines 100 --statements 100 --branches 98 --functions 100",
+    "coverage:cli:gate:pii-guard": "npm run coverage:cli:gate -- --include src/cli/pii-predicate-guard.ts --lines 97 --statements 97 --branches 88 --functions 100",
     "coverage:cli:gate:studio": "npm run coverage:cli:gate -- --include src/cli/studio.ts --lines 82 --statements 82 --branches 81 --functions 86",
     "coverage:cli:gate:migrate": "npm run coverage:cli:gate -- --include src/cli/migrate.ts --lines 69 --statements 69 --branches 91 --functions 73",
-    "coverage:cli:gate:aggregate": "npm run coverage:cli:gate -- --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --lines 78 --statements 78 --branches 84 --functions 82",
+    "coverage:cli:gate:aggregate": "npm run coverage:cli:gate -- --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts --lines 78 --statements 78 --branches 84 --functions 82",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",