turbine-orm 0.65.0 → 0.66.0

package/dist/cjs/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/cjs/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/cjs/sqlite.js

@@ -57,6 +57,7 @@ const client_js_1 = require("./client.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
 const introspect_js_1 = require("./introspect.js");
+const utils_js_1 = require("./query/utils.js");
 const schema_js_1 = require("./schema.js");
 let cachedDatabaseSync;
 /**
@@ -130,14 +131,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 = (0, node_module_1.createRequire)(process.cwd())('node:sqlite');
+        }
+        catch {
+            cachedSqliteNamespace = null;
+        }
+    }
+    return typeof cachedSqliteNamespace?.StatementSync?.prototype?.columns === 'function';
+}
 // ---------------------------------------------------------------------------
 // Statement classification + error translation
 // ---------------------------------------------------------------------------
@@ -241,7 +329,7 @@ function toNamedBinding(values) {
     }
     return named;
 }
-function runStatement(db, sql, values) {
+function runStatement(db, sql, values, booleanCache) {
     const binding = toNamedBinding(values);
     let stmt;
     try {
@@ -253,7 +341,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();
@@ -276,21 +372,28 @@ 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 utils_js_1.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.
@@ -375,6 +478,7 @@ exports.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,
@@ -447,6 +551,33 @@ exports.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.
@@ -531,9 +662,14 @@ exports.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) {
@@ -616,7 +752,12 @@ exports.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/cjs/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/cjs/typed-sql.js

@@ -96,24 +96,42 @@ 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 (0, errors_js_1.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 (0, errors_js_1.wrapPgError)(err);
+            }
+        });
     }
     /**
      * PromiseLike implementation: `await db.sql<T>\`...\`` resolves to `T[]`.

package/dist/cli/destructive.d.ts

@@ -18,15 +18,27 @@
  * Row removal hides in more than a leading `DELETE`, so the scan also covers:
  * the optional-`COLUMN` shorthand (`ALTER TABLE t DROP email`), data-modifying
  * CTEs (`WITH d AS (DELETE ...) SELECT ...`), `MERGE ... THEN DELETE`, dynamic
- * SQL inside a `DO`/function body, and an `UPDATE` whose only WHERE sits inside
- * a subquery (which restricts nothing).
+ * SQL inside a `DO`/function body, an `UPDATE` whose only WHERE sits inside a
+ * subquery (which restricts nothing), a `DROP ... CASCADE` of a non-table
+ * object (which takes dependent COLUMNS with it), a detached partition, and an
+ * `EXPLAIN ANALYZE` of any of the above (which really executes it).
+ *
+ * The lexing, "where does a statement end" and "which characters are code",
+ * is NOT done here: it lives in `sql-statements.ts` and is shared with the
+ * migration runner. Two lexers is how this guard came to disagree with the
+ * executor about what a file contained (see that module's header).
  */
-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 type DestructiveKind = 'drop-table' | 'drop-schema' | 'drop-database' | 'drop-owned' | 'drop-matview' | 'drop-column' | 'drop-cascade' | 'detach-partition' | 'truncate' | 'delete' | 'update-without-where' | 'alter-column-type' | 'merge-delete' | 'rename' | 'dynamic-destructive';
 export interface DestructiveStatement {
     /** The offending SQL statement (trimmed, possibly long, display truncated) */
     statement: string;
     kind: DestructiveKind;
-    /** Best-effort extracted object name (table, schema, or table.column) */
+    /**
+     * Best-effort extracted object name (table, schema, or table.column). For
+     * `drop-cascade` it is prefixed with the object kind (`TYPE order_status`),
+     * because the same rule covers eight different kinds of object and the bare
+     * name would not tell the operator what they are about to lose.
+     */
     target: string;
 }
 /** Human explanation per kind, used in CLI output. */
@@ -36,3 +48,5 @@ export declare const DESTRUCTIVE_KIND_LABEL: Record<DestructiveKind, string>;
  * return every statement that can destroy data.
  */
 export declare function scanDestructiveSql(sql: string): DestructiveStatement[];
+/** Shown in place of an object name that does not exist until the block runs. */
+export declare const DYNAMIC_TARGET = "<name assembled at run time>";