uql-orm 0.62.0 → 0.64.0

package/dist/migrate/schemaGenerator.js

@@ -6,10 +6,12 @@ import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
 import { isAutoIncrement, qualifyName } from '../util/index.js';
 import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
+import { splitSqlStatements } from './builder/splitSqlStatements.js';
 import { indexDdlFor, tableDdlFor } from './ddl/index.js';
 import { sizedType } from './ddl/tableDdl.js';
 import { columnForeignKey, columnIndex, fullColumnDefinitionToNode, renderIndexDefinition, tableDefinitionToNode, } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
+import { assertIndexPredicate } from './indexPredicate.js';
 /**
  * Unified SQL schema generator.
  * Parameterized by dialect to handle Postgres, MySQL, MariaDB, and SQLite.
@@ -48,6 +50,10 @@ export class SqlSchemaGenerator {
     compileDdl(sql, entity) {
         return this.dialect.compileDdl(sql, entity);
     }
+    compileIndexPredicate(where, entity, indexName) {
+        assertIndexPredicate(where, this.dialect.dialectName, indexName);
+        return this.dialect.compileDdl(where, entity);
+    }
     /** Escape an identifier (table name, column name, etc.) */
     escapeId(identifier) {
         return this.dialect.escapeId(identifier);
@@ -577,13 +583,43 @@ export class SqlSchemaGenerator {
     generateRenameTableSql(oldName, newName) {
         return this.tableDdl.renameTable(oldName, newName);
     }
+    /** `raw` is split, being the one SQL no generator wrote. */
+    generateOperation(operation) {
+        switch (operation.type) {
+            case 'createTable':
+                return this.generateCreateTableFromDefinition(operation.table);
+            case 'dropTable':
+                return [
+                    this.generateDropTable(operation.tableName, { ifExists: operation.ifExists, cascade: operation.cascade }),
+                ];
+            case 'renameTable':
+                return [this.generateRenameTableSql(operation.oldName, operation.newName)];
+            case 'addColumn':
+                return this.generateAddColumnSql(operation.tableName, operation.column);
+            case 'dropColumn':
+                return this.generateDropColumnSql(operation.tableName, operation.columnName);
+            case 'renameColumn':
+                return [this.generateRenameColumnSql(operation.tableName, operation.oldName, operation.newName)];
+            case 'alterColumn':
+                return this.generateAlterColumnSql(operation.tableName, operation.columnName, operation.changes);
+            case 'createIndex':
+                return [this.generateCreateIndexFromDefinition(operation.tableName, operation.index)];
+            case 'dropIndex':
+                return [this.generateDropIndex(operation.tableName, operation.indexName)];
+            case 'addForeignKey':
+                return [this.generateAddForeignKeySql(operation.tableName, operation.foreignKey)];
+            case 'dropForeignKey':
+                return [this.generateDropForeignKeySql(operation.tableName, operation.constraintName)];
+            case 'raw':
+                return splitSqlStatements(operation.sql);
+        }
+    }
     /**
      * `ADD COLUMN`, plus the constraint and index the column declares.
      *
      * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
      * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
-     * dropped both without a word. Several statements in one string is what `generateAlterColumnSql`
-     * already returns, and `execute` splits them.
+     * dropped both without a word.
      */
     generateAddColumnSql(tableName, column) {
         this.assertColumnAddable(tableName, column);
@@ -598,14 +634,14 @@ export class SqlSchemaGenerator {
             statements.push(this.generateCreateIndex(tableName, index));
         }
         statements.push(...this.generateColumnCommentStatement(tableName, column));
-        return statements.join('\n');
+        return statements;
     }
     generateAlterColumnSql(tableName, columnName, column) {
         const node = fullColumnDefinitionToNode(column, tableName);
-        return this.generateAlterColumnStatements(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node)).join('\n');
+        return this.generateAlterColumnStatements(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node));
     }
     generateDropColumnSql(tableName, columnName) {
-        return this.tableDdl.dropColumn(tableName, columnName).join('\n');
+        return this.tableDdl.dropColumn(tableName, columnName);
     }
     generateRenameColumnSql(tableName, oldName, newName) {
         return this.tableDdl.renameColumn(tableName, oldName, newName);
@@ -726,13 +762,11 @@ export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
         resolveSchema: (meta) => generator.resolveSchema(meta),
         resolveColumnName: (key, field) => generator.resolveColumnName(key, field),
         compileDdl: (sql, entity) => generator.compileDdl(sql, entity),
+        compileIndexPredicate: (where, entity, indexName) => generator.compileIndexPredicate(where, entity, indexName),
         defaultForeignKeyAction,
     });
 }
-/**
- * Synchronous factory for SQL schema generators only.
- * For MongoDB, use `createSchemaGeneratorAsync` from `./schemaGeneratorAsync.js` so the optional `mongodb` peer is not loaded at import time.
- */
+/** The SQL schema generator for `dialect`, `undefined` on MongoDB, whose generator needs its optional peer. */
 export function createSchemaGenerator(dialect, defaultForeignKeyAction) {
     return dialect.dialectName === 'mongodb' ? undefined : new SqlSchemaGenerator(dialect, defaultForeignKeyAction);
 }

package/dist/mongo/mongoDialect.d.ts

@@ -10,6 +10,11 @@ type MongoReadStages = {
     /** Keys merged into the query's projection, when it has one: a vector search's score. */
     readonly project?: Record<string, 1>;
 };
+/** Accumulator threaded through `$where` rendering: the relation lookups it needs, and their temp fields. */
+type RelationLookups = {
+    readonly stages: MongoAggregationPipelineEntry<Document>[];
+    readonly temps: string[];
+};
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export declare const mongoDialectFeatures: DialectFeatures;
 export declare class MongoDialect extends AbstractDialect {
@@ -46,7 +51,7 @@ export declare class MongoDialect extends AbstractDialect {
      * recursion). Relation keys need `$lookup` stages, so they are only accepted when `lookups` is
      * given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
-    private renderFilter;
+    protected renderFilter<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, lookups?: RelationLookups): Filter<E>;
     /**
      * Renders `$and`/`$or`/`$not`/`$nor` into `filter`. MongoDB has no root-level `$not`, so both
      * negating operators become its `$nor`, which is exactly `NOT (a OR b)` - and by De Morgan that

package/dist/querier/abstractSharedHandleQuerierPool.d.ts

@@ -2,13 +2,13 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SqlQuerier } from '../type/index.js';
 import { AbstractSqlQuerierPool } from './abstractSqlQuerierPool.js';
 /**
- * Base pool for an engine that gives one connection per database and keeps it open for the pool's
- * lifetime: every local SQLite driver, the embedded Turso engine, and PGlite.
+ * Base pool for a handle opened once and kept for the pool's lifetime: the one connection every local
+ * SQLite driver, the embedded Turso engine and PGlite give per database, or libSQL's client.
  *
  * The handle is shared, but each acquisition gets its own querier, so transaction state stays per unit
- * of work. That state is not *isolated*, which is the one way these differ from a real pool: there is a
- * single connection under every querier, so two of them cannot hold independent transactions, and a
- * unit of work that needs one needs its own pool and therefore its own database.
+ * of work. On a single connection that state is not *isolated*, which is the one way these differ from
+ * a real pool: two queriers cannot hold independent transactions, and a unit of work that needs one needs
+ * its own pool and therefore its own database. libSQL's client opens a session per transaction instead.
  *
  * What a second `BEGIN` then does is the engine's, not this class's: SQLite and the embedded Turso
  * engine both refuse it ("cannot start a transaction within a transaction"), while PGlite accepts it

package/dist/querier/abstractSharedHandleQuerierPool.js

@@ -1,12 +1,12 @@
 import { AbstractSqlQuerierPool } from './abstractSqlQuerierPool.js';
 /**
- * Base pool for an engine that gives one connection per database and keeps it open for the pool's
- * lifetime: every local SQLite driver, the embedded Turso engine, and PGlite.
+ * Base pool for a handle opened once and kept for the pool's lifetime: the one connection every local
+ * SQLite driver, the embedded Turso engine and PGlite give per database, or libSQL's client.
  *
  * The handle is shared, but each acquisition gets its own querier, so transaction state stays per unit
- * of work. That state is not *isolated*, which is the one way these differ from a real pool: there is a
- * single connection under every querier, so two of them cannot hold independent transactions, and a
- * unit of work that needs one needs its own pool and therefore its own database.
+ * of work. On a single connection that state is not *isolated*, which is the one way these differ from
+ * a real pool: two queriers cannot hold independent transactions, and a unit of work that needs one needs
+ * its own pool and therefore its own database. libSQL's client opens a session per transaction instead.
  *
  * What a second `BEGIN` then does is the engine's, not this class's: SQLite and the embedded Turso
  * engine both refuse it ("cannot start a transaction within a transaction"), while PGlite accepts it

package/dist/schema/schemaASTBuilder.d.ts

@@ -29,6 +29,8 @@ export interface BuildSchemaASTOptions {
      * predicate - which only a dialect can render. `buildEntityAST` supplies it from the generator.
      */
     compileDdl?: (sql: EntityWhereMeta<object>, entity: Type<object>) => string;
+    /** A partial index's predicate as the engine writes it, `compileDdl` where none is given. `buildEntityAST` supplies it. */
+    compileIndexPredicate?: (where: EntityWhereMeta<object>, entity: Type<object>, indexName: string) => string;
 }
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).

package/dist/schema/schemaASTBuilder.js

@@ -6,7 +6,7 @@
  * - Database introspection results (TableSchema[])
  */
 import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
-import { indexNameParts, renderIndexColumn } from '../util/ddlExpression.util.js';
+import { declaredIndexes, indexNameParts, renderIndexColumn } from '../util/ddlExpression.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
@@ -23,6 +23,7 @@ import { DEFAULT_FOREIGN_KEY_ACTION, } from './types.js';
  */
 export function buildSchemaAST(entities, options = {}) {
     const { namingStrategy } = options;
+    const compileDdl = options.compileDdl ?? refuseDdl;
     const ctx = {
         ast: new SchemaAST(),
         resolveTableName: options.resolveTableName ??
@@ -30,7 +31,8 @@ export function buildSchemaAST(entities, options = {}) {
         resolveSchema: options.resolveSchema ?? ((m) => m.schema),
         resolveColumnName: options.resolveColumnName ?? ((k, f) => namingStrategy?.columnName(f.name ?? k) ?? f.name ?? k),
         defaultForeignKeyAction: options.defaultForeignKeyAction ?? DEFAULT_FOREIGN_KEY_ACTION,
-        compileDdl: options.compileDdl ?? refuseDdl,
+        compileDdl,
+        compileIndexPredicate: options.compileIndexPredicate ?? compileDdl,
     };
     for (const pass of [addTableFromEntity, addRelationshipsFromEntity, addIndexesFromEntity]) {
         for (const entity of entities) {
@@ -180,23 +182,7 @@ function addIndexesFromEntity(ctx, meta) {
     const table = tableOf(ctx, meta);
     if (!table)
         return;
-    for (const key of Object.keys(meta.fields)) {
-        const field = meta.fields[key];
-        if (!field?.index)
-            continue;
-        const column = table.columns.get(ctx.resolveColumnName(key, field));
-        if (!column)
-            continue;
-        ctx.ast.addIndex({
-            name: typeof field.index === 'string' ? field.index : derivedIndexName(table.name, [column.name]),
-            table,
-            entries: [{ column: column.name }],
-            unique: field.unique ?? false,
-            source: 'entity',
-            syncStatus: 'entity_only',
-        });
-    }
-    for (const idxMeta of meta.indexes ?? []) {
+    for (const idxMeta of declaredIndexes(meta)) {
         addCompositeIndex(ctx, table, meta, idxMeta);
     }
     addForeignKeyIndexes(ctx, meta, table);
@@ -235,7 +221,7 @@ function resolveIncludeColumn(ctx, meta, column) {
     return field ? ctx.resolveColumnName(column, field) : column;
 }
 /**
- * One `@Index`. Its entries keep the authored form (expression, prefix length, order) with
+ * One index the entity declares. Its entries keep the authored form (expression, prefix length, order) with
  * names resolved, so the generator renders exactly what was declared; `columns` is the resolvable
  * subset, which is what diffing and introspection compare.
  */
@@ -251,14 +237,15 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
     });
     if (!resolved.length)
         return;
+    const name = idxMeta.name ?? derivedIndexName(table.name, indexNameParts(resolved));
     ctx.ast.addIndex({
-        name: idxMeta.name ?? derivedIndexName(table.name, indexNameParts(resolved)),
+        name,
         table,
         entries: resolved.map((entry) => renderIndexColumn(entry, (sql) => ctx.compileDdl(sql, meta.entity))),
         include: idxMeta.include?.map((column) => resolveIncludeColumn(ctx, meta, column)),
         unique: idxMeta.unique ?? false,
         type: idxMeta.type,
-        where: idxMeta.where && ctx.compileDdl(idxMeta.where, meta.entity),
+        where: idxMeta.where && ctx.compileIndexPredicate(idxMeta.where, meta.entity, name),
         distance: idxMeta.distance,
         m: idxMeta.m,
         efConstruction: idxMeta.efConstruction,

package/dist/sqlite/abstractSqliteQuerier.d.ts

@@ -1,4 +1,5 @@
 import { AbstractSqlQuerier } from '../querier/index.js';
+import type { RawRow } from '../type/index.js';
 /**
  * Values every SQLite driver accepts as a bound parameter.
  *
@@ -8,41 +9,23 @@ import { AbstractSqlQuerier } from '../querier/index.js';
  * driver as one; leaving `boolean` here only invited a runtime throw that is now a compile error.
  */
 export type SqliteBindValue = null | string | number | bigint | Uint8Array;
-/** Header a SQLite driver returns for a statement without a `RETURNING` clause. */
-export type SqliteRunResult = {
-    changes: number;
-    lastInsertRowid: number | bigint;
+/** What a statement came back with on a SQLite driver: the rows it read, and how many rows it changed. */
+export type SqliteExecution = {
+    readonly rows: RawRow[];
+    readonly changes: number;
 };
-/** Bound parameters reach a driver as `unknown[]` from the compiler; every driver types them narrowly. */
-export declare function toSqliteBindValues(values?: unknown[]): SqliteBindValue[];
 /**
- * A prepared statement from a driver with better-sqlite3 semantics. `better-sqlite3` and `bun:sqlite`
- * answer synchronously, `@tursodatabase/database` with promises, and {@link PreparedSqliteQuerier}
- * awaits either.
+ * Querier for every SQLite driver. Each supplies one hook, {@link execute}; what they share - the
+ * wide-integer decode, and a RETURNING statement counted by its rows - is written once here.
  */
-export type SqlitePreparedStatement = {
-    /** True for any statement returning rows, including one with a `RETURNING` clause. */
-    readonly reader: boolean;
-    all(...values: SqliteBindValue[]): unknown[] | Promise<unknown[]>;
-    run(...values: SqliteBindValue[]): SqliteRunResult | Promise<SqliteRunResult>;
-    iterate(...values: SqliteBindValue[]): Iterable<unknown> | AsyncIterable<unknown>;
-};
 export declare abstract class AbstractSqliteQuerier extends AbstractSqlQuerier {
+    /** Runs one statement, answering its rows as the driver read them. */
+    protected abstract execute(query: string, values?: unknown[]): Promise<SqliteExecution>;
+    internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
+    internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
     /**
      * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
      * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
      */
     internalRelease(): Promise<void>;
 }
-/**
- * Querier for the SQLite drivers that expose prepared statements: `better-sqlite3`, `bun:sqlite`
- * (through `adaptBunSqlite`) and the embedded Turso engine. They differ only in whether preparing and
- * stepping are synchronous, which `await` and `for await` absorb, so the read/write/stream logic -
- * including the `reader` rule below, whose loss silently drops inserted ids - is written once.
- */
-export declare abstract class PreparedSqliteQuerier extends AbstractSqliteQuerier {
-    protected abstract prepare(query: string): SqlitePreparedStatement | Promise<SqlitePreparedStatement>;
-    internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
-    internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
-    internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
-}

package/dist/sqlite/abstractSqliteQuerier.js

@@ -1,41 +1,22 @@
 import { AbstractSqlQuerier } from '../querier/index.js';
-/** Bound parameters reach a driver as `unknown[]` from the compiler; every driver types them narrowly. */
-export function toSqliteBindValues(values) {
-    return (values || []);
-}
-export class AbstractSqliteQuerier extends AbstractSqlQuerier {
-    /**
-     * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
-     * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
-     */
-    async internalRelease() { }
-}
+import { decodeBigInts } from '../util/wideNumber.js';
 /**
- * Querier for the SQLite drivers that expose prepared statements: `better-sqlite3`, `bun:sqlite`
- * (through `adaptBunSqlite`) and the embedded Turso engine. They differ only in whether preparing and
- * stepping are synchronous, which `await` and `for await` absorb, so the read/write/stream logic -
- * including the `reader` rule below, whose loss silently drops inserted ids - is written once.
+ * Querier for every SQLite driver. Each supplies one hook, {@link execute}; what they share - the
+ * wide-integer decode, and a RETURNING statement counted by its rows - is written once here.
  */
-export class PreparedSqliteQuerier extends AbstractSqliteQuerier {
+export class AbstractSqliteQuerier extends AbstractSqlQuerier {
     async internalAll(query, values) {
-        const stmt = await this.prepare(query);
-        return (await stmt.all(...toSqliteBindValues(values)));
-    }
-    async *internalStream(query, values) {
-        const stmt = await this.prepare(query);
-        for await (const row of stmt.iterate(...toSqliteBindValues(values))) {
-            yield row;
-        }
+        const { rows } = await this.execute(query, values);
+        return rows.map(decodeBigInts);
     }
     async internalRun(query, values) {
-        const stmt = await this.prepare(query);
-        // `reader` is true for any statement with a RETURNING clause; `.run()` silently discards
-        // returned rows, so those statements must go through `.all()` instead.
-        if (stmt.reader) {
-            const rows = (await stmt.all(...toSqliteBindValues(values)));
-            return this.buildUpdateResult({ rows });
-        }
-        const { changes, lastInsertRowid } = await stmt.run(...toSqliteBindValues(values));
-        return this.buildUpdateResult({ changes, id: lastInsertRowid });
+        const { rows, changes } = await this.execute(query, values);
+        // A driver's own count is unreliable for a RETURNING statement (Hrana answers 0), so its rows answer.
+        return this.buildUpdateResult({ rows: rows.map(decodeBigInts), changes: rows.length || changes });
     }
+    /**
+     * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
+     * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
+     */
+    async internalRelease() { }
 }

package/dist/sqlite/bunSqliteAdapter.bun.d.ts

@@ -1,5 +1,6 @@
-import type { SqliteBindValue, SqliteRunResult } from './abstractSqliteQuerier.js';
-import type { SqliteDatabase } from './sqliteQuerier.js';
+import type { SqliteBindValue } from './abstractSqliteQuerier.js';
+import type { LocalSqliteDatabase } from './localSqliteQuerierPool.js';
+import type { SqliteRunResult } from './sqliteQuerier.js';
 /** A `bun:sqlite` statement: better-sqlite3-shaped, except it reports columns instead of `reader`. */
 type BunStatement = {
     columnNames: string[];
@@ -13,7 +14,7 @@ type BunDatabase = {
     close(): unknown;
 };
 /**
- * Presents a `bun:sqlite` handle as a {@link SqliteDatabase}.
+ * Presents a `bun:sqlite` handle as a {@link LocalSqliteDatabase}.
  *
  * @remarks Its statements expose no `reader`, so without deriving one every `RETURNING` statement
  * would take the `run()` path, which discards returned rows, and inserts would report no ids.
@@ -22,5 +23,5 @@ type BunDatabase = {
  * Lives in a `.bun.ts` file because it only ever executes under Bun: the Node coverage run cannot
  * reach it, and `sqliteQuerier.bun.test.ts` covers it under `test:bun` instead.
  */
-export declare function adaptBunSqlite(db: BunDatabase): SqliteDatabase;
+export declare function adaptBunSqlite(db: BunDatabase): LocalSqliteDatabase;
 export {};

package/dist/sqlite/bunSqliteAdapter.bun.js

@@ -1,5 +1,5 @@
 /**
- * Presents a `bun:sqlite` handle as a {@link SqliteDatabase}.
+ * Presents a `bun:sqlite` handle as a {@link LocalSqliteDatabase}.
  *
  * @remarks Its statements expose no `reader`, so without deriving one every `RETURNING` statement
  * would take the `run()` path, which discards returned rows, and inserts would report no ids.

package/dist/sqlite/hranaQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { ExtraOptions } from '../type/index.js';
+import type { ExtraOptions, RawRow } from '../type/index.js';
 import { AbstractSqliteQuerier, type SqliteBindValue } from './abstractSqliteQuerier.js';
 import type { SqliteDialect } from './sqliteDialect.js';
 /**
@@ -11,7 +11,6 @@ export type HranaInValue = SqliteBindValue | ArrayBuffer | Date;
 export type HranaResultSet = {
     rows: unknown[];
     rowsAffected: number;
-    lastInsertRowid?: bigint;
 };
 export type HranaExecutor = {
     execute(stmt: {
@@ -44,8 +43,11 @@ export declare class HranaQuerier extends AbstractSqliteQuerier {
     private tx?;
     private readonly closeClientOnRelease;
     constructor(client: HranaClient, dialect: SqliteDialect, extra?: ExtraOptions | undefined, connection?: HranaQuerierConnectionOptions);
-    internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
-    internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
+    /** Runs on the open transaction's handle when there is one. */
+    protected execute(query: string, values?: unknown[]): Promise<{
+        rows: RawRow[];
+        changes: number;
+    }>;
     protected internalBegin(): Promise<void>;
     /**
      * Both drop the handle before the call, not after: one that outlived a failed commit would carry

package/dist/sqlite/hranaQuerier.js

@@ -16,18 +16,10 @@ export class HranaQuerier extends AbstractSqliteQuerier {
         this.extra = extra;
         this.closeClientOnRelease = connection?.closeClientOnRelease ?? false;
     }
-    async internalAll(query, values) {
-        const target = this.tx || this.client;
-        const res = await target.execute({ sql: query, args: values });
-        return res.rows;
-    }
-    async internalRun(query, values) {
-        const target = this.tx || this.client;
-        const res = await target.execute({ sql: query, args: values });
-        const rows = res.rows;
-        // `rowsAffected` is unreliably 0 whenever the statement has a RETURNING clause, so prefer
-        // the actual row count when rows were returned.
-        return this.buildUpdateResult({ rows, changes: rows.length || res.rowsAffected, id: res.lastInsertRowid });
+    /** Runs on the open transaction's handle when there is one. */
+    async execute(query, values) {
+        const res = await (this.tx ?? this.client).execute({ sql: query, args: values });
+        return { rows: res.rows, changes: res.rowsAffected };
     }
     async internalBegin() {
         this.tx = await this.client.transaction('write');
@@ -47,7 +39,6 @@ export class HranaQuerier extends AbstractSqliteQuerier {
         await tx?.rollback();
     }
     async internalRelease() {
-        await super.internalRelease();
         if (this.closeClientOnRelease) {
             this.client.close();
         }

package/dist/sqlite/index.d.ts

@@ -1,6 +1,5 @@
 export * from './abstractSqliteQuerier.js';
 export * from './hranaQuerier.js';
-export * from './hranaQuerierPool.js';
 export * from './nodeSqliteQuerierPool.js';
 export * from './sqliteDialect.js';
 export * from './sqliteQuerier.js';

package/dist/sqlite/index.js

@@ -1,6 +1,5 @@
 export * from './abstractSqliteQuerier.js';
 export * from './hranaQuerier.js';
-export * from './hranaQuerierPool.js';
 export * from './nodeSqliteQuerierPool.js';
 export * from './sqliteDialect.js';
 export * from './sqliteQuerier.js';

package/dist/sqlite/localSqliteQuerierPool.d.ts

@@ -1,7 +1,7 @@
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
 import type { ExtraOptions } from '../type/index.js';
 import { SqliteDialect } from './sqliteDialect.js';
-import { type SqliteDatabase, SqliteQuerier } from './sqliteQuerier.js';
+import { type SqlitePreparedStatement, SqliteQuerier } from './sqliteQuerier.js';
 /** What every local SQLite pool accepts on top of its driver's own options. */
 export type LocalSqlitePoolOptions = {
     /**
@@ -11,6 +11,15 @@ export type LocalSqlitePoolOptions = {
      */
     extensions?: readonly string[];
 };
+/**
+ * A database opened in this process by a driver that answers at once, and installs loadable extensions
+ * (`sqlite-vec`, ...) into its connection.
+ */
+export type LocalSqliteDatabase = {
+    prepare(sql: string): SqlitePreparedStatement;
+    loadExtension(path: string): void;
+    close(): unknown;
+};
 /**
  * Pool for a SQLite database opened in this process, whichever driver provides it. SQLite gives one
  * connection per file, so the shared-handle lifecycle is {@link AbstractSharedHandleQuerierPool}'s.
@@ -18,11 +27,11 @@ export type LocalSqlitePoolOptions = {
  * Subclasses supply only {@link createDb}: configuring the connection on the way up - the pragmas,
  * then the extensions - is the same for `better-sqlite3`, `bun:sqlite` and `node:sqlite`.
  */
-export declare abstract class AbstractLocalSqliteQuerierPool<O extends LocalSqlitePoolOptions> extends AbstractSharedHandleQuerierPool<SqliteDatabase, SqliteQuerier, SqliteDialect> {
+export declare abstract class AbstractLocalSqliteQuerierPool<O extends LocalSqlitePoolOptions> extends AbstractSharedHandleQuerierPool<LocalSqliteDatabase, SqliteQuerier, SqliteDialect> {
     readonly opts?: O | undefined;
     constructor(opts?: O | undefined, extra?: ExtraOptions);
     /** Opens the driver's database, and nothing more: the caller configures it. */
-    protected abstract createDb(): Promise<SqliteDatabase>;
-    protected openDb(): Promise<SqliteDatabase>;
-    protected buildQuerier(db: SqliteDatabase): SqliteQuerier;
+    protected abstract createDb(): Promise<LocalSqliteDatabase>;
+    protected openDb(): Promise<LocalSqliteDatabase>;
+    protected buildQuerier(db: LocalSqliteDatabase): SqliteQuerier;
 }

package/dist/sqlite/nodeSqliteAdapter.d.ts

@@ -1,5 +1,5 @@
 import type { SqliteBindValue } from './abstractSqliteQuerier.js';
-import type { SqliteDatabase } from './sqliteQuerier.js';
+import type { LocalSqliteDatabase } from './localSqliteQuerierPool.js';
 /**
  * A `node:sqlite` statement: better-sqlite3-shaped, except it describes columns instead of reporting
  * `reader`, and types `changes` as possibly `bigint` where better-sqlite3 always answers a `number`.
@@ -9,7 +9,6 @@ type NodeSqliteStatement = {
     all(...values: SqliteBindValue[]): unknown[];
     run(...values: SqliteBindValue[]): {
         changes: number | bigint;
-        lastInsertRowid: number | bigint;
     };
     iterate(...values: SqliteBindValue[]): Iterable<unknown>;
 };
@@ -23,12 +22,12 @@ export type NodeSqliteDatabase = {
     close(): void;
 };
 /**
- * Presents a `node:sqlite` handle as a {@link SqliteDatabase}.
+ * Presents a `node:sqlite` handle as a {@link LocalSqliteDatabase}.
  *
  * @remarks Its statements expose no `reader`, so without deriving one every `RETURNING` statement
  * would take the `run()` path, which discards returned rows, and inserts would report no ids.
  * `columns()` is non-empty for exactly the statements better-sqlite3 marks as readers, including
  * `INSERT ... RETURNING` and `DELETE ... RETURNING`.
  */
-export declare function adaptNodeSqlite(db: NodeSqliteDatabase): SqliteDatabase;
+export declare function adaptNodeSqlite(db: NodeSqliteDatabase): LocalSqliteDatabase;
 export {};

package/dist/sqlite/nodeSqliteAdapter.js

@@ -1,5 +1,5 @@
 /**
- * Presents a `node:sqlite` handle as a {@link SqliteDatabase}.
+ * Presents a `node:sqlite` handle as a {@link LocalSqliteDatabase}.
  *
  * @remarks Its statements expose no `reader`, so without deriving one every `RETURNING` statement
  * would take the `run()` path, which discards returned rows, and inserts would report no ids.
@@ -14,11 +14,8 @@ export function adaptNodeSqlite(db) {
                 reader: stmt.columns().length > 0,
                 all: (...values) => stmt.all(...values),
                 // `changes` is narrowed to `number` to match every other driver; a row count cannot exceed
-                // the safe-integer range, so nothing is lost. `lastInsertRowid` keeps its `bigint` arm.
-                run: (...values) => {
-                    const { changes, lastInsertRowid } = stmt.run(...values);
-                    return { changes: Number(changes), lastInsertRowid };
-                },
+                // the safe-integer range, so nothing is lost.
+                run: (...values) => ({ changes: Number(stmt.run(...values).changes) }),
                 iterate: (...values) => stmt.iterate(...values),
             };
         },

package/dist/sqlite/nodeSqliteQuerierPool.d.ts

@@ -1,6 +1,5 @@
 import type { ExtraOptions } from '../type/index.js';
-import { AbstractLocalSqliteQuerierPool, type LocalSqlitePoolOptions } from './localSqliteQuerierPool.js';
-import type { SqliteDatabase } from './sqliteQuerier.js';
+import { AbstractLocalSqliteQuerierPool, type LocalSqliteDatabase, type LocalSqlitePoolOptions } from './localSqliteQuerierPool.js';
 /**
  * The `DatabaseSync` options worth surfacing, plus the loadable extensions to install. Declared here
  * rather than imported from `node:sqlite` so this module needs no ambient Node types; unknown keys
@@ -24,5 +23,5 @@ export type NodeSqlitePoolOptions = LocalSqlitePoolOptions & {
 export declare class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool<NodeSqlitePoolOptions> {
     readonly filename: string;
     constructor(filename?: string, opts?: NodeSqlitePoolOptions, extra?: ExtraOptions);
-    protected createDb(): Promise<SqliteDatabase>;
+    protected createDb(): Promise<LocalSqliteDatabase>;
 }

package/dist/sqlite/nodeSqliteQuerierPool.js

@@ -1,4 +1,4 @@
-import { AbstractLocalSqliteQuerierPool } from './localSqliteQuerierPool.js';
+import { AbstractLocalSqliteQuerierPool, } from './localSqliteQuerierPool.js';
 import { adaptNodeSqlite } from './nodeSqliteAdapter.js';
 /**
  * Pool backed by Node's built-in `node:sqlite`, so SQLite works with **no dependency at all** rather
@@ -20,6 +20,8 @@ export class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool {
         const { extensions, ...driverOpts } = this.opts ?? {};
         const nodeDb = new DatabaseSync(this.filename, {
             ...driverOpts,
+            // Integers as `bigint`, which the querier decodes exactly past 2^53.
+            readBigInts: true,
             // `node:sqlite` refuses `loadExtension` unless the database was opened with this on.
             ...(extensions?.length ? { allowExtension: true } : undefined),
         });

package/dist/sqlite/sqliteDialect.d.ts

@@ -16,7 +16,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     /** SQLite locks the whole database, not rows, so `$lock` has nothing to map onto. */
     readonly supportsRowLocks = false;
     readonly booleanLiteral = "integer";
-    /** A function call takes 127 arguments before SQLite 3.48, as libSQL and Turso embed. */
+    /** SQLite's own cap on a function call before 3.48, which libSQL and `bun:sqlite`'s build still have. */
     readonly maxFunctionArgs: number;
     readonly insertIdSource = "returning";
     /**

package/dist/sqlite/sqliteDialect.js

@@ -39,7 +39,7 @@ export class SqliteDialect extends AbstractSqlDialect {
     /** SQLite locks the whole database, not rows, so `$lock` has nothing to map onto. */
     supportsRowLocks = false;
     booleanLiteral = 'integer';
-    /** A function call takes 127 arguments before SQLite 3.48, as libSQL and Turso embed. */
+    /** SQLite's own cap on a function call before 3.48, which libSQL and `bun:sqlite`'s build still have. */
     maxFunctionArgs = 127;
     // SQLite supports `RETURNING` (including on `INSERT ... ON CONFLICT`), so IDs are exact per row.
     insertIdSource = 'returning';