ts-prorm-orm 1.2.2 → 2.0.0

package/dist/dialects/partial-index.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Partial-index predicates (`IndexOptions.where`).
+ *
+ * A partial index predicate lives inside DDL, and DDL is executed without a
+ * parameter list. Compiling `where` through the ordinary WHERE builder
+ * therefore produced `CREATE INDEX ... WHERE "status" = ?` with the values
+ * silently dropped on the floor - SQLite rejects that outright ("parameters
+ * prohibited in partial index WHERE clauses") and PostgreSQL fails on the
+ * dangling `$1`. So predicates are compiled here instead, with every value
+ * inlined as a literal through the dialect's own `escape()`.
+ *
+ * That inlining makes `escape()` the security boundary for this path: nothing
+ * in this module hand-rolls quoting, and no user value ever reaches the SQL by
+ * concatenation. `escapeId()` does the same job for column names.
+ *
+ * Only the operator forms that mean something in a predicate are supported.
+ * Anything else throws with a reason rather than emitting SQL the server will
+ * reject - the same convention as {@link UnsupportedSchemaObjectError} in
+ * `src/schema-objects.ts`, which this module reuses for dialects that have no
+ * partial indexes at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsPartialIndexes = supportsPartialIndexes;
+exports.unsupportedPartialIndex = unsupportedPartialIndex;
+exports.buildPartialIndexPredicate = buildPartialIndexPredicate;
+const schema_objects_1 = require("../schema-objects");
+const operators_1 = require("../operators");
+/**
+ * Databases whose `CREATE INDEX` accepts a predicate.
+ *
+ * PostgreSQL calls them partial indexes, SQL Server calls them filtered
+ * indexes, SQLite copied PostgreSQL's syntax. Derived dialects report their own
+ * `name` (TimescaleDBDialect extends PostgresDialect but calls itself
+ * 'timescaledb'), so membership is listed explicitly rather than inferred from
+ * the class hierarchy - the same reasoning as the family sets in
+ * `src/schema-objects.ts`.
+ *
+ * Deliberately absent: MySQL/MariaDB/TiDB/SingleStore (no predicate on CREATE
+ * INDEX at all), Oracle (function-based index on a CASE expression is the
+ * workaround, not a predicate), DuckDB, ClickHouse, Redshift, Snowflake, HANA,
+ * DB2, Spanner, Vertica, Firebird, Exasol, CrateDB, QuestDB, Databricks and
+ * Trino.
+ */
+const PARTIAL_INDEX_DIALECTS = new Set([
+    // PostgreSQL family
+    'postgres',
+    'postgresql',
+    'cockroachdb',
+    'greenplum',
+    'timescaledb',
+    'yugabytedb',
+    // SQLite family (Turso/libSQL is SQLite over the wire)
+    'sqlite',
+    'turso',
+    // SQL Server filtered indexes
+    'mssql',
+]);
+/** Whether `dialect` supports a `WHERE` predicate on `CREATE INDEX`. */
+function supportsPartialIndexes(dialect) {
+    return PARTIAL_INDEX_DIALECTS.has(String(dialect).toLowerCase());
+}
+/**
+ * Raise the standard "this database has no partial indexes" error.
+ *
+ * Exported so a dialect can fail the same way from its own `createPartialIndex`.
+ */
+function unsupportedPartialIndex(dialect) {
+    return new schema_objects_1.UnsupportedSchemaObjectError('Partial (filtered) index', dialect, `${dialect} has no WHERE clause on CREATE INDEX - index the whole table, or index a generated/expression column that encodes the predicate.`);
+}
+function unsupportedOperator(op) {
+    return new Error(`Partial index predicate does not support the "${op}" operator. ` +
+        'Supported forms: { col: value }, { col: [..] }, Op.eq, Op.ne, Op.gt, Op.gte, Op.lt, Op.lte, ' +
+        'Op.in, Op.notIn, Op.between, Op.notBetween, Op.like, Op.notLike, Op.is, Op.not, Op.isNull, ' +
+        'Op.isNotNull, Op.col, Op.and, Op.or. ' +
+        'For anything else, pass the predicate as a literal SQL string (`where: "..."`) or use ' +
+        'createPartialIndex(table, name, fields, predicate).');
+}
+/**
+ * Copy an object's Symbol operator keys onto their `$`-prefixed string
+ * equivalents, so `{ [Op.gt]: 5 }` and `{ $gt: 5 }` compile down one path.
+ */
+function normalizeOperatorKeys(input) {
+    const raw = input;
+    const normalized = { ...raw };
+    for (const sym of Object.getOwnPropertySymbols(raw)) {
+        const key = (0, operators_1.operatorToWhereKey)(sym);
+        if (key)
+            normalized[key] = raw[sym];
+    }
+    return normalized;
+}
+function isPlainValueObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Date) &&
+        !Buffer.isBuffer(value));
+}
+/**
+ * Compile one `IndexOptions.where` into a self-contained SQL predicate with all
+ * values inlined as escaped literals.
+ *
+ * A string `where` is a predicate the caller already wrote by hand and is
+ * returned unchanged, which is also what `createPartialIndex()` takes.
+ *
+ * @param where - Predicate object, or raw SQL predicate string
+ * @param dialect - Dialect name, used for the unsupported-database error
+ * @param escaper - The dialect itself; supplies `escape` / `escapeId`
+ * @returns The predicate SQL, or `''` when `where` is empty (emit no WHERE)
+ * @throws {UnsupportedSchemaObjectError} when the dialect has no partial indexes
+ */
+function buildPartialIndexPredicate(where, dialect, escaper) {
+    if (where === undefined || where === null) {
+        return '';
+    }
+    if (!supportsPartialIndexes(dialect)) {
+        throw unsupportedPartialIndex(dialect);
+    }
+    // A hand-written predicate passes through untouched.
+    if (typeof where === 'string') {
+        return where.trim();
+    }
+    const escapeValue = (value) => {
+        if (value === undefined) {
+            throw new Error('Partial index predicate got `undefined` as a value. A predicate is baked into the ' +
+                'index definition, so every value must be known up front - use Op.isNull for "no value".');
+        }
+        return escaper.escape(value);
+    };
+    const column = (name) => escaper.escapeId(name);
+    const compileField = (field, value) => {
+        if (value === null) {
+            return `${column(field)} IS NULL`;
+        }
+        // `{ id: [1, 2, 3] }` is the shorthand for IN, matching the WHERE builders.
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                // An empty IN list is a syntax error everywhere; say so rather than emit it.
+                throw new Error(`Partial index predicate for "${field}" got an empty IN list, which is not valid SQL.`);
+            }
+            return `${column(field)} IN (${value.map(escapeValue).join(', ')})`;
+        }
+        if (!isPlainValueObject(value)) {
+            return `${column(field)} = ${escapeValue(value)}`;
+        }
+        const ops = normalizeOperatorKeys(value);
+        const opKeys = Object.keys(ops).filter((k) => k.startsWith('$'));
+        // A field object with no operator keys is a plain value (e.g. a Literal, or
+        // a JSON payload) - escape it whole.
+        if (opKeys.length === 0) {
+            return `${column(field)} = ${escapeValue(value)}`;
+        }
+        // Several operators on one field (e.g. { age: { $gte: 18, $lt: 65 } }) AND together.
+        const parts = opKeys.map((op) => compileOperator(field, op, ops[op]));
+        return parts.length > 1 ? `(${parts.join(' AND ')})` : parts[0];
+    };
+    const compileOperator = (field, op, operand) => {
+        const col = column(field);
+        switch (op) {
+            case '$eq':
+                return operand === null ? `${col} IS NULL` : `${col} = ${escapeValue(operand)}`;
+            case '$ne':
+                return operand === null ? `${col} IS NOT NULL` : `${col} != ${escapeValue(operand)}`;
+            case '$is':
+                return operand === null ? `${col} IS NULL` : `${col} IS ${escapeValue(operand)}`;
+            case '$not':
+                return operand === null ? `${col} IS NOT NULL` : `${col} != ${escapeValue(operand)}`;
+            case '$gt':
+                return `${col} > ${escapeValue(operand)}`;
+            case '$gte':
+                return `${col} >= ${escapeValue(operand)}`;
+            case '$lt':
+                return `${col} < ${escapeValue(operand)}`;
+            case '$lte':
+                return `${col} <= ${escapeValue(operand)}`;
+            case '$like':
+                return `${col} LIKE ${escapeValue(operand)}`;
+            case '$notLike':
+                return `${col} NOT LIKE ${escapeValue(operand)}`;
+            case '$isNull':
+                return operand ? `${col} IS NULL` : `${col} IS NOT NULL`;
+            case '$isNotNull':
+                return operand ? `${col} IS NOT NULL` : `${col} IS NULL`;
+            case '$col':
+                return `${col} = ${column(String(operand))}`;
+            case '$in':
+            case '$notIn': {
+                const list = operand;
+                if (!Array.isArray(list) || list.length === 0) {
+                    throw new Error(`Partial index predicate for "${field}" got an empty ${op} list, which is not valid SQL.`);
+                }
+                const keyword = op === '$in' ? 'IN' : 'NOT IN';
+                return `${col} ${keyword} (${list.map(escapeValue).join(', ')})`;
+            }
+            case '$between':
+            case '$notBetween': {
+                const range = operand;
+                if (!Array.isArray(range) || range.length !== 2) {
+                    throw new Error(`Partial index predicate for "${field}": ${op} needs a [min, max] pair.`);
+                }
+                const keyword = op === '$between' ? 'BETWEEN' : 'NOT BETWEEN';
+                return `${col} ${keyword} ${escapeValue(range[0])} AND ${escapeValue(range[1])}`;
+            }
+            default:
+                throw unsupportedOperator(op);
+        }
+    };
+    const compile = (condition) => {
+        if (condition === undefined || condition === null) {
+            return '';
+        }
+        // A raw predicate fragment nested inside $and/$or.
+        if (typeof condition === 'string') {
+            return condition.trim();
+        }
+        if (!isPlainValueObject(condition)) {
+            throw new Error(`Partial index predicate expected an object or a SQL string, got ${typeof condition}.`);
+        }
+        const cond = normalizeOperatorKeys(condition);
+        // Logical groups lead, then the sibling field conditions - the same order
+        // the dialects' own WHERE builders produce, so the two read alike.
+        const logical = [];
+        const fields = [];
+        for (const [key, value] of Object.entries(cond)) {
+            if (key === '$and' || key === '$or') {
+                const branches = (Array.isArray(value) ? value : [value])
+                    .map(compile)
+                    .filter((s) => s.length > 0);
+                if (branches.length === 0)
+                    continue;
+                const joined = branches.join(key === '$and' ? ' AND ' : ' OR ');
+                logical.push(branches.length > 1 ? `(${joined})` : joined);
+                continue;
+            }
+            if (key === '$not') {
+                const inner = compile(value);
+                if (inner)
+                    logical.push(`NOT (${inner})`);
+                continue;
+            }
+            if (key.startsWith('$')) {
+                // A bare operator at condition level has no column to apply to.
+                throw unsupportedOperator(key);
+            }
+            fields.push(compileField(key, value));
+        }
+        return [...logical, ...fields].join(' AND ');
+    };
+    return compile(where);
+}

package/dist/dialects/postgres/index.d.ts

@@ -850,7 +850,7 @@ export declare class PostgresDialect implements Dialect {
         type?: string;
         using?: string;
         fields: string[];
-        where?: WhereOptions;
+        where?: WhereOptions | string;
         expression?: string;
         include?: string[];
     }): Promise<void>;

package/dist/dialects/postgres/index.js

@@ -7,7 +7,10 @@ exports.PostgresTransaction = exports.PostgresDialect = void 0;
 exports.createPostgresDialect = createPostgresDialect;
 const operators_1 = require("../../operators");
 const operators_2 = require("../../operators");
+const lock_clause_helper_1 = require("../lock-clause-helper");
+const partial_index_1 = require("../partial-index");
 const prorm_1 = require("../../prorm");
+const order_expression_helper_1 = require("../order-expression-helper");
 // Lazily-loaded `pg` driver. Required only when a connection is opened, so
 // importing this ORM never loads the pg driver.
 let pgModule = null;
@@ -814,13 +817,18 @@ class PostgresDialect {
      * Build constraint SQL for table creation
      */
     buildConstraintSql(constraint) {
-        const name = constraint.name ? `"${constraint.name}"` : '';
+        // A named table constraint is `CONSTRAINT "name" UNIQUE (...)`. The
+        // CONSTRAINT keyword was missing here, so every named constraint came out
+        // as `"name" UNIQUE (...)`, which PostgreSQL reads as a column definition
+        // and rejects with a syntax error - the constraint never reached the
+        // database. Every other dialect in this repo emits the keyword.
+        const name = constraint.name ? `CONSTRAINT "${constraint.name}" ` : '';
         const fields = constraint.fields?.map((f) => this.escapeId(f)).join(', ') || '';
         switch (constraint.type) {
             case 'PRIMARY KEY':
-                return `${name ? name + ' ' : ''}PRIMARY KEY (${fields})`;
+                return `${name}PRIMARY KEY (${fields})`;
             case 'UNIQUE':
-                return `${name ? name + ' ' : ''}UNIQUE (${fields})`;
+                return `${name}UNIQUE (${fields})`;
             case 'FOREIGN KEY':
                 if (!constraint.references)
                     return null;
@@ -829,7 +837,7 @@ class PostgresDialect {
                 const refFieldSql = Array.isArray(refField)
                     ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
                     : `(${this.escapeId(refField)})`;
-                let fkSql = `${name ? name + ' ' : ''}FOREIGN KEY (${fields}) `;
+                let fkSql = `${name}FOREIGN KEY (${fields}) `;
                 fkSql += `REFERENCES ${this.escapeId(constraint.references.table)}${refFieldSql}`;
                 if (constraint.references.onDelete) {
                     fkSql += ` ON DELETE ${constraint.references.onDelete}`;
@@ -841,7 +849,7 @@ class PostgresDialect {
             case 'CHECK':
                 if (!constraint.check)
                     return null;
-                return `${name ? name + ' ' : ''}CHECK (${constraint.check})`;
+                return `${name}CHECK (${constraint.check})`;
             default:
                 return null;
         }
@@ -2615,9 +2623,14 @@ class PostgresDialect {
         if (options?.include && options.include.length > 0) {
             sql += ` INCLUDE (${options.include.map((f) => this.escapeId(f)).join(', ')})`;
         }
+        // Partial index predicate. The ordinary WHERE builder emits `$1`-style
+        // placeholders and this DDL is executed without a value list, so the
+        // predicate is compiled with its values inlined as escaped literals.
         if (options?.where) {
-            const whereClause = this.buildWhereClause(options.where);
-            sql += ` WHERE ${whereClause.sql}`;
+            const predicate = (0, partial_index_1.buildPartialIndexPredicate)(options.where, this.name, this);
+            if (predicate) {
+                sql += ` WHERE ${predicate}`;
+            }
         }
         await this.query(sql);
     }
@@ -2658,9 +2671,12 @@ class PostgresDialect {
         if (indexDef.include && indexDef.include.length > 0) {
             sql += ` INCLUDE (${indexDef.include.map((f) => this.escapeId(f)).join(', ')})`;
         }
-        if (indexDef.where && Object.keys(indexDef.where).length > 0) {
-            const whereClause = this.buildWhereClause(indexDef.where);
-            sql += ` WHERE ${whereClause.sql}`;
+        // Partial index predicate - inlined literals, not placeholders. See addIndex.
+        if (indexDef.where) {
+            const predicate = (0, partial_index_1.buildPartialIndexPredicate)(indexDef.where, this.name, this);
+            if (predicate) {
+                sql += ` WHERE ${predicate}`;
+            }
         }
         await this.query(sql);
     }
@@ -3505,12 +3521,18 @@ class PostgresDialect {
      * Build an ORDER BY clause
      */
     buildOrderClause(order, options) {
-        const orderArray = order;
-        if (!orderArray || !Array.isArray(orderArray) || orderArray.length === 0) {
+        const orderArray = (0, order_expression_helper_1.normalizeOrderItems)(order);
+        if (orderArray.length === 0) {
             return '';
         }
         const orderParts = [];
         for (const item of orderArray) {
+            // Order helpers: asc('name') / desc('name') / random()
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, item);
+            if (orderExpr !== null) {
+                orderParts.push(orderExpr);
+                continue;
+            }
             if (Array.isArray(item)) {
                 const field = typeof item[0] === 'string' ? this.escapeId(item[0]) : item[0];
                 const direction = item[1] ? ` ${item[1]}` : '';
@@ -4326,35 +4348,11 @@ class PostgresDialect {
         }
         // Build LIMIT/OFFSET clause
         sql += this.buildLimitOffset(options.limit, options.offset);
-        // Handle row-level locking (PostgreSQL specific)
-        if (options.lock) {
-            let lockType;
-            // lock: true is equivalent to 'UPDATE'
-            if (options.lock === true) {
-                lockType = 'UPDATE';
-            }
-            else if (typeof options.lock === 'string') {
-                lockType = options.lock;
-            }
-            else if (typeof options.lock === 'object' && options.lock.of) {
-                // lock: { of: Model } - defaults to FOR UPDATE for table-specific locking
-                lockType = 'UPDATE';
-            }
-            if (lockType === 'UPDATE') {
-                sql += ' FOR UPDATE';
-            }
-            else if (lockType === 'SHARE') {
-                sql += ' FOR SHARE';
-            }
-            else if (lockType === 'KEY SHARE') {
-                sql += ' FOR KEY SHARE';
-            }
-            // Handle lock on specific table (PostgreSQL supports OF clause)
-            if (typeof options.lock === 'object' && options.lock.of) {
-                const model = options.lock.of;
-                sql += ` OF ${this.escapeId(model.tableName || '')}`;
-            }
-        }
+        // Handle row-level locking. Every documented `lock` shape (true, a level
+        // string, `{ of }`, and the `{ level, nowait, skipLocked }` object form) is
+        // parsed by the shared helper so none of them can silently compile to no
+        // lock at all; see src/dialects/lock-clause-helper.ts.
+        sql += (0, lock_clause_helper_1.appendLockClause)(options.lock, lock_clause_helper_1.POSTGRES_LOCK_SPEC, (id) => this.escapeId(id));
         // Build UNION clause if provided
         if (options.union && options.union.length > 0) {
             const unionType = options.unionType || 'UNION';
@@ -4515,33 +4513,10 @@ class PostgresDialect {
      * Get PostgreSQL specific lock options
      */
     getLockOptions(lock) {
-        const params = [];
-        let sql = '';
-        const lockType = typeof lock === 'string' ? lock : lock?.level;
-        switch (lockType) {
-            case 'UPDATE':
-                sql = 'FOR UPDATE';
-                break;
-            case 'SHARE':
-                sql = 'FOR SHARE';
-                break;
-            case 'KEY SHARE':
-                sql = 'FOR KEY SHARE';
-                break;
-            default:
-                return { sql: '', params };
-        }
-        if (typeof lock === 'object' && lock?.of) {
-            const model = lock.of;
-            sql += ` OF ${this.escapeId(model.tableName || '')}`;
-        }
-        if (typeof lock === 'object' && lock?.nowait) {
-            sql += ' NOWAIT';
-        }
-        else if (typeof lock === 'object' && lock?.skipLocked) {
-            sql += ' SKIP LOCKED';
-        }
-        return { sql, params };
+        return {
+            sql: (0, lock_clause_helper_1.buildLockClause)(lock, lock_clause_helper_1.POSTGRES_LOCK_SPEC, (id) => this.escapeId(id)),
+            params: [],
+        };
     }
     // ---------------------------------------------------------------------------
     // Advisory locks — PostgreSQL dialect

package/dist/dialects/redshift/index.js

@@ -74,6 +74,7 @@ const prorm_1 = require("../../prorm");
 const index_1 = require("../../errors/index");
 const index_2 = require("../../utils/index");
 const operators_1 = require("../../operators");
+const order_expression_helper_1 = require("../order-expression-helper");
 const DEFAULT_RETRY_OPTIONS = {
     max: 3,
     timeout: 1000,
@@ -1564,11 +1565,17 @@ class RedshiftDialect {
         return { sql: buildCondition(where), values };
     }
     buildOrderClause(order, _options) {
-        const orderArray = order;
-        if (!orderArray || !Array.isArray(orderArray) || orderArray.length === 0)
+        const orderArray = (0, order_expression_helper_1.normalizeOrderItems)(order);
+        if (orderArray.length === 0)
             return '';
         const orderParts = [];
         for (const item of orderArray) {
+            // Order helpers: asc('name') / desc('name') / random()
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, item);
+            if (orderExpr !== null) {
+                orderParts.push(orderExpr);
+                continue;
+            }
             if (Array.isArray(item)) {
                 const field = typeof item[0] === 'string' ? this.escapeId(item[0]) : item[0];
                 const direction = item[1] ? ` ${item[1]}` : '';

package/dist/dialects/snowflake/index.js

@@ -46,6 +46,7 @@ function loadSnowflake() {
 const types_1 = require("../../types");
 const query_stream_helper_1 = require("../query-stream-helper");
 const prorm_1 = require("../../prorm");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * Default retry options for connection/query errors
  */
@@ -1090,6 +1091,12 @@ class SnowflakeDialect {
             return '';
         const orderParts = [];
         const processOrder = (orderItem) => {
+            // Order helpers: asc('name') / desc('name') / random()
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, orderItem);
+            if (orderExpr !== null) {
+                orderParts.push(orderExpr);
+                return;
+            }
             if (typeof orderItem === 'string') {
                 const parts = orderItem.split(' ');
                 if (parts.length === 1) {
@@ -1099,6 +1106,16 @@ class SnowflakeDialect {
                     orderParts.push(`${this.escapeId(parts[0])} ${parts[1].toUpperCase()}`);
                 }
             }
+            else if (Array.isArray(orderItem)) {
+                // Tuple form — `['name', 'DESC']` / `['name']`, the elements of the
+                // primary documented `[['name', 'DESC'], ['id', 'ASC']]` shape. An
+                // array is also an object, so without this branch each tuple fell
+                // through to the map branch below and its *indices* were emitted as
+                // column names (`ORDER BY "0" NAME, "1" DESC`).
+                const [field, direction] = orderItem;
+                const column = typeof field === 'string' ? this.escapeId(field) : String(field);
+                orderParts.push(direction ? `${column} ${String(direction).toUpperCase()}` : column);
+            }
             else if (typeof orderItem === 'object' && orderItem !== null) {
                 for (const [key, value] of Object.entries(orderItem)) {
                     if (key === '$raw') {

package/dist/dialects/spanner/index.js

@@ -106,6 +106,7 @@ const { Spanner } = require('@google-cloud/spanner');
 const types_1 = require("../../types");
 const query_stream_helper_1 = require("../query-stream-helper");
 const prorm_1 = require("../../prorm");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * A Spanner read-write transaction, bridging the driver's callback-based
  * `database.runTransaction()` API to the imperative
@@ -1490,10 +1491,14 @@ class SpannerDialect {
         return { sql, values };
     }
     buildOrderClause(order) {
-        const orderArray = order;
-        if (!orderArray || !Array.isArray(orderArray) || orderArray.length === 0)
+        const orderArray = (0, order_expression_helper_1.normalizeOrderItems)(order);
+        if (orderArray.length === 0)
             return '';
         const parts = orderArray.map((item) => {
+            // Order helpers: asc('name') / desc('name') / random()
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, item);
+            if (orderExpr !== null)
+                return orderExpr;
             if (Array.isArray(item)) {
                 const field = typeof item[0] === 'string' ? this.escapeId(item[0]) : item[0];
                 const direction = item[1] ? ` ${item[1]}` : '';

package/dist/dialects/sqlite/driver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Runtime-appropriate SQLite driver.
+ *
+ * Node uses `better-sqlite3`, a native addon. Bun ships its own SQLite as the
+ * built-in `bun:sqlite`, which is faster there and needs no native build step —
+ * and under Bun the `better-sqlite3` addon may not be installable at all.
+ *
+ * The two APIs were designed to look alike, so the dialect can talk to either
+ * one unchanged. They differ in exactly one place: better-sqlite3 has
+ * `db.pragma()`, and bun:sqlite does not. This module adds it, so the dialect
+ * has a single shape to code against and no `if (isBun)` branches leak into the
+ * SQL layer.
+ *
+ * The driver is loaded lazily on first connect, so importing the ORM never
+ * dlopens a native binding or touches a `bun:` module on Node.
+ */
+/** The slice of better-sqlite3's Statement the dialect relies on. */
+export interface SqliteStatement {
+    all(...params: unknown[]): unknown[];
+    get(...params: unknown[]): unknown;
+    run(...params: unknown[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    iterate(...params: unknown[]): IterableIterator<unknown>;
+}
+/** The slice of better-sqlite3's Database the dialect relies on. */
+export interface SqliteDatabase {
+    prepare(sql: string): SqliteStatement;
+    exec(sql: string): unknown;
+    pragma(source: string, options?: {
+        simple?: boolean;
+    }): unknown;
+    close(): void;
+}
+export interface SqliteDriverOptions {
+    readonly?: boolean;
+    fileMustExist?: boolean;
+    timeout?: number;
+    verbose?: ((message?: unknown, ...args: unknown[]) => void) | undefined;
+}
+/** True when running under Bun. */
+export declare function isBun(): boolean;
+type DatabaseCtor = new (filename: string, options?: SqliteDriverOptions) => SqliteDatabase;
+/**
+ * Resolve the SQLite driver for the current runtime.
+ *
+ * Under Bun this prefers `bun:sqlite` but falls back to `better-sqlite3` if it
+ * is installed and the built-in cannot be loaded, so an existing Bun project
+ * that already depends on better-sqlite3 keeps working.
+ */
+export declare function loadSqliteDriver(): DatabaseCtor;
+/** Test seam: forget the resolved driver. */
+export declare function resetSqliteDriver(): void;
+export {};