uql-orm 0.22.0 → 0.23.0

package/dist/querier/querierContext.js

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * The querier `@Transactional()` opened for the current async flow.
+ *
+ * Separate from the `UqlContext` storage in `context/context.ts` on purpose: that one is remapped to a
+ * synchronous browser shim which cannot propagate across `await`, and a querier handle must. Nothing in
+ * a browser bundle opens a transaction, so this stays server-only and `verify-dist` keeps it out of the
+ * browser-facing graph.
+ */
+const querierStorage = new AsyncLocalStorage();
+/** Runs `callback` with `querier` as the ambient one, for the whole async flow beneath it. */
+export function withQuerierContext(querier, callback) {
+    return querierStorage.run(querier, callback);
+}
+/**
+ * The querier of the enclosing `@Transactional()` method.
+ *
+ * This is what replaced `@InjectQuerier()`: the standard decorator spec has no parameter decorators, so
+ * the querier can no longer be injected into an argument and is read from the ambient flow instead.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   @Transactional()
+ *   async register(data: Partial<User>) {
+ *     await currentQuerier().insertOne(User, data);
+ *   }
+ * }
+ * ```
+ */
+export function currentQuerier() {
+    const querier = querierStorage.getStore();
+    if (!querier) {
+        throw new TypeError('currentQuerier() found no active querier. Call it inside a @Transactional() method, or take a querier ' +
+            'from the pool yourself with `await using querier = await pool.getQuerier()`.');
+    }
+    return querier;
+}
+/** The ambient querier, or `undefined` outside a transaction. For callers that can work without one. */
+export function currentQuerierIfAny() {
+    return querierStorage.getStore();
+}

package/dist/querier/queryError.d.ts

@@ -0,0 +1,22 @@
+import type { LoggerWrapper } from '../util/logger.js';
+/**
+ * A driver error enriched with context by {@link enrichError}. `query` is always attached; `values`
+ * only when the querier's logger is configured to surface them (see {@link enrichError}) - they can
+ * carry sensitive data (PII, tokens, etc.) and would otherwise leak into whatever error-tracking
+ * pipeline (Sentry, console.error, ...) serializes the error, without the developer opting in.
+ */
+export interface QueryError extends Error {
+    query?: string;
+    values?: unknown[];
+}
+/**
+ * Tags `err` with the query it failed on (as {@link QueryError}) and hands it back for the caller to
+ * throw. `values` is only attached when `logger?.willLogValues()` is true, i.e. the app already has
+ * query values surfacing somewhere (query-level or slow-query logging), so attaching them here does not
+ * introduce a new leak surface. Shared by every query call site (timed queries, streams, transaction
+ * statements) so the logic lives in one place.
+ *
+ * Returns rather than throws so `throw enrichError(...)` reads as the control flow it is, which also
+ * means callers need no `never` annotation and no unreachable-code suppression.
+ */
+export declare function enrichError(err: unknown, logger: LoggerWrapper | undefined, query: string, values?: unknown[]): unknown;

package/dist/querier/queryError.js

@@ -0,0 +1,20 @@
+/**
+ * Tags `err` with the query it failed on (as {@link QueryError}) and hands it back for the caller to
+ * throw. `values` is only attached when `logger?.willLogValues()` is true, i.e. the app already has
+ * query values surfacing somewhere (query-level or slow-query logging), so attaching them here does not
+ * introduce a new leak surface. Shared by every query call site (timed queries, streams, transaction
+ * statements) so the logic lives in one place.
+ *
+ * Returns rather than throws so `throw enrichError(...)` reads as the control flow it is, which also
+ * means callers need no `never` annotation and no unreachable-code suppression.
+ */
+export function enrichError(err, logger, query, values) {
+    if (err instanceof Error) {
+        const queryError = err;
+        queryError.query ??= query;
+        if (values !== undefined && logger?.willLogValues()) {
+            queryError.values ??= values;
+        }
+    }
+    return err;
+}

package/dist/querier/transactional.d.ts

@@ -0,0 +1,26 @@
+import type { IsolationLevel, QuerierPool } from '../type/index.js';
+export type TransactionalOptions = {
+    /** `required` opens a transaction when none is active; `supported` joins one but never starts one. */
+    readonly propagation?: 'supported' | 'required';
+    readonly pool?: QuerierPool;
+    readonly isolationLevel?: IsolationLevel;
+};
+/**
+ * Wraps the method in a transaction and publishes its querier for {@link currentQuerier} to pick up.
+ *
+ * @remarks Replaces the `@InjectQuerier()` parameter that used to receive the querier. The standard
+ * decorator spec has no parameter decorators, and the separate TC39 proposal for them is still Stage 1,
+ * so the querier travels through async-local storage instead. A nested call joins the transaction
+ * already in flight rather than opening a second one.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   @Transactional()
+ *   async register(data: Partial<User>) {
+ *     await currentQuerier().insertOne(User, data);
+ *   }
+ * }
+ * ```
+ */
+export declare function Transactional({ propagation, pool, isolationLevel }?: TransactionalOptions): <This, Args extends unknown[], R>(original: (this: This, ...args: Args) => Promise<R>, context: ClassMethodDecoratorContext<This>) => (this: This, ...args: Args) => Promise<R>;

package/dist/querier/transactional.js

@@ -0,0 +1,43 @@
+import { getQuerierPool } from '../options.js';
+import { currentQuerierIfAny, withQuerierContext } from './querierContext.js';
+/**
+ * Wraps the method in a transaction and publishes its querier for {@link currentQuerier} to pick up.
+ *
+ * @remarks Replaces the `@InjectQuerier()` parameter that used to receive the querier. The standard
+ * decorator spec has no parameter decorators, and the separate TC39 proposal for them is still Stage 1,
+ * so the querier travels through async-local storage instead. A nested call joins the transaction
+ * already in flight rather than opening a second one.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   @Transactional()
+ *   async register(data: Partial<User>) {
+ *     await currentQuerier().insertOne(User, data);
+ *   }
+ * }
+ * ```
+ */
+export function Transactional({ propagation = 'required', pool, isolationLevel } = {}) {
+    return (original, context) => {
+        // Checked at decoration time rather than on the first call: a synchronous method cannot be wrapped in
+        // a transaction, and finding that out at startup beats finding out mid-request.
+        if (original.constructor.name !== 'AsyncFunction') {
+            throw new TypeError(`@Transactional() needs an async method, but '${String(context.name)}' is not one.`);
+        }
+        return async function (...args) {
+            // Already inside a transactional flow: join it and let the outermost call own commit and release.
+            if (currentQuerierIfAny()) {
+                return original.apply(this, args);
+            }
+            // `withQuerier` releases; `transaction` commits or rolls back. `supported` joins a transaction but
+            // never starts one, so it takes only the first half.
+            return (pool ?? getQuerierPool()).withQuerier((querier) => {
+                const run = () => original.apply(this, args);
+                return withQuerierContext(querier, () => propagation === 'supported'
+                    ? run()
+                    : querier.transaction(run, isolationLevel ? { isolationLevel } : undefined));
+            });
+        };
+    };
+}

package/dist/schema/index.d.ts

@@ -22,4 +22,4 @@ export type { BuildFromEntitiesOptions } from './schemaASTBuilder.js';
 export { SchemaASTBuilder } from './schemaASTBuilder.js';
 export type { DiffOptions } from './schemaASTDiffer.js';
 export { diffSchemas, SchemaASTDiffer } from './schemaASTDiffer.js';
-export type { CanonicalType, ColumnDiff, ColumnNode, DetectedRelation, Drift, DriftReport, DriftSeverity, DriftStatus, DriftType, ForeignKeyAction, IndexDiff, IndexNode, IndexSource, IndexSyncStatus, IndexType, RelationshipDiff, RelationshipNode, RelationshipSource, RelationshipType, SchemaAST as ISchemaAST, SchemaDiffResult, SizeVariant, TableDiff, TableNode, TypeCategory, ValidationError, ValidationErrorType, } from './types.js';
+export type { CanonicalType, ColumnDiff, ColumnNode, Drift, DriftReport, DriftSeverity, DriftStatus, DriftType, ForeignKeyAction, IndexDiff, IndexNode, IndexSource, IndexSyncStatus, IndexType, RelationshipDiff, RelationshipNode, RelationshipSource, RelationshipType, SchemaAST as ISchemaAST, SchemaDiffResult, SizeVariant, TableDiff, TableNode, TypeCategory, ValidationError, ValidationErrorType, } from './types.js';

package/dist/schema/schemaASTBuilder.d.ts

@@ -54,7 +54,7 @@ export declare class SchemaASTBuilder {
      * foreign key column whose type doesn't match the UUID primary key it
      * references, which Postgres (and most databases) reject outright.
      *
-     * `field.typeInferred` (set by `defineField`, see entity/metadata/definition.ts)
+     * `field.typeFromReference` (set by `defineField`, see entity/metadata/definition.ts)
      * is what distinguishes "no type was given" from "the decorator explicitly set
      * a type" - including explicit constructor overrides like `type: BigInt`, which
      * a value-based check (e.g. `typeof field.type === 'string'`) would miss since

package/dist/schema/schemaASTBuilder.js

@@ -74,7 +74,7 @@ export class SchemaASTBuilder {
      * foreign key column whose type doesn't match the UUID primary key it
      * references, which Postgres (and most databases) reject outright.
      *
-     * `field.typeInferred` (set by `defineField`, see entity/metadata/definition.ts)
+     * `field.typeFromReference` (set by `defineField`, see entity/metadata/definition.ts)
      * is what distinguishes "no type was given" from "the decorator explicitly set
      * a type" - including explicit constructor overrides like `type: BigInt`, which
      * a value-based check (e.g. `typeof field.type === 'string'`) would miss since
@@ -82,7 +82,7 @@ export class SchemaASTBuilder {
      * `columnType` remains the unambiguous, always-respected explicit override.
      */
     resolveColumnCanonicalType(field, seen = new Set()) {
-        const hasExplicitType = !!field.columnType || !field.typeInferred;
+        const hasExplicitType = !!field.columnType || !field.typeFromReference;
         if (!hasExplicitType && field.references && !seen.has(field.references)) {
             seen.add(field.references);
             const referencedMeta = getMeta(field.references());

package/dist/schema/types.d.ts

@@ -256,27 +256,6 @@ export interface ValidationError {
     readonly relationship?: RelationshipNode;
     readonly tables?: TableNode[];
 }
-/**
- * A detected/inferred relationship with confidence score.
- */
-export interface DetectedRelation {
-    readonly type: RelationshipType;
-    readonly from: {
-        readonly table: TableNode;
-        readonly columns: ColumnNode[];
-    };
-    readonly to: {
-        readonly table: TableNode;
-        readonly columns: ColumnNode[];
-    };
-    readonly through?: TableNode;
-    /** Confidence level (0-1) */
-    readonly confidence: number;
-    /** How this relation was detected */
-    readonly source: RelationshipSource;
-    /** Suggested constraint name */
-    readonly suggestedName?: string;
-}
 /**
  * Severity level for schema drift issues.
  */

package/dist/sqlite/abstractSqliteQuerier.d.ts

@@ -1,6 +1,13 @@
 import { AbstractSqlQuerier } from '../querier/index.js';
-/** Values every SQLite driver accepts as a bound parameter. */
-export type SqliteBindValue = null | string | number | bigint | boolean | Uint8Array;
+/**
+ * Values every SQLite driver accepts as a bound parameter.
+ *
+ * @remarks No `boolean`: SQLite has no boolean storage class, and both `better-sqlite3` ("SQLite3 can
+ * only bind numbers, strings, bigints, buffers, and null") and `node:sqlite` reject one outright. The
+ * dialect already binds booleans as integers (`booleanLiteral: 'integer'`), so nothing reaches a
+ * 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;

package/dist/sqlite/hranaQuerier.js

@@ -1,13 +1,3 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-import { Serialized } from '../querier/decorator/index.js';
 import { throwNoPendingTransaction, throwPendingTransaction } from '../util/index.js';
 import { AbstractSqliteQuerier } from './abstractSqliteQuerier.js';
 /**
@@ -44,24 +34,30 @@ export class HranaQuerier extends AbstractSqliteQuerier {
         return !!this.tx;
     }
     async beginTransaction(_opts) {
-        if (this.tx) {
-            throwPendingTransaction();
-        }
-        this.tx = await this.client.transaction('write');
+        return this.serialize(async () => {
+            if (this.tx) {
+                throwPendingTransaction();
+            }
+            this.tx = await this.client.transaction('write');
+        });
     }
     async commitTransaction() {
-        if (!this.tx) {
-            throwNoPendingTransaction();
-        }
-        await this.tx.commit();
-        this.tx = undefined;
+        return this.serialize(async () => {
+            if (!this.tx) {
+                throwNoPendingTransaction();
+            }
+            await this.tx.commit();
+            this.tx = undefined;
+        });
     }
     async rollbackTransaction() {
-        if (!this.tx) {
-            throwNoPendingTransaction();
-        }
-        await this.tx.rollback();
-        this.tx = undefined;
+        return this.serialize(async () => {
+            if (!this.tx) {
+                throwNoPendingTransaction();
+            }
+            await this.tx.rollback();
+            this.tx = undefined;
+        });
     }
     async internalRelease() {
         await super.internalRelease();
@@ -70,21 +66,3 @@ export class HranaQuerier extends AbstractSqliteQuerier {
         }
     }
 }
-__decorate([
-    Serialized(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
-    __metadata("design:returntype", Promise)
-], HranaQuerier.prototype, "beginTransaction", null);
-__decorate([
-    Serialized(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", []),
-    __metadata("design:returntype", Promise)
-], HranaQuerier.prototype, "commitTransaction", null);
-__decorate([
-    Serialized(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", []),
-    __metadata("design:returntype", Promise)
-], HranaQuerier.prototype, "rollbackTransaction", null);

package/dist/sqlite/index.d.ts

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

package/dist/sqlite/index.js

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

package/dist/sqlite/localSqliteQuerierPool.d.ts

@@ -0,0 +1,31 @@
+import { AbstractSqlQuerierPool } from '../querier/index.js';
+import type { ExtraOptions } from '../type/index.js';
+import { SqliteDialect } from './sqliteDialect.js';
+import { type SqliteDatabase, SqliteQuerier } from './sqliteQuerier.js';
+/** What every local SQLite pool accepts on top of its driver's own options. */
+export type LocalSqlitePoolOptions = {
+    /**
+     * Paths of loadable extensions to install when the connection opens - e.g. what `sqlite-vec`'s
+     * `getLoadablePath()` returns, which vector search needs because SQLite itself has no vector
+     * functions.
+     */
+    extensions?: readonly string[];
+};
+/**
+ * Pool for a SQLite database opened in this process, whichever driver provides it.
+ *
+ * The handle is shared - SQLite gives one connection per file - but each acquisition gets its own
+ * querier, so transaction state stays per unit of work. Subclasses supply only {@link createDb}: the
+ * lifecycle, and loading the extensions on the way up, are the same for `better-sqlite3`, `bun:sqlite`
+ * and `node:sqlite`, and were written out once per pool before.
+ */
+export declare abstract class AbstractLocalSqliteQuerierPool<O extends LocalSqlitePoolOptions> extends AbstractSqlQuerierPool<SqliteQuerier, SqliteDialect> {
+    readonly opts?: O | undefined;
+    private db?;
+    constructor(opts?: O | undefined, extra?: ExtraOptions);
+    /** Opens the driver's database. Extensions are loaded by the caller, not here. */
+    protected abstract createDb(): Promise<SqliteDatabase>;
+    getQuerier(): Promise<SqliteQuerier>;
+    private openDb;
+    end(): Promise<void>;
+}

package/dist/sqlite/localSqliteQuerierPool.js

@@ -0,0 +1,34 @@
+import { AbstractSqlQuerierPool } from '../querier/index.js';
+import { SqliteDialect } from './sqliteDialect.js';
+import { SqliteQuerier } from './sqliteQuerier.js';
+/**
+ * Pool for a SQLite database opened in this process, whichever driver provides it.
+ *
+ * The handle is shared - SQLite gives one connection per file - but each acquisition gets its own
+ * querier, so transaction state stays per unit of work. Subclasses supply only {@link createDb}: the
+ * lifecycle, and loading the extensions on the way up, are the same for `better-sqlite3`, `bun:sqlite`
+ * and `node:sqlite`, and were written out once per pool before.
+ */
+export class AbstractLocalSqliteQuerierPool extends AbstractSqlQuerierPool {
+    opts;
+    db;
+    constructor(opts, extra) {
+        super(new SqliteDialect({ namingStrategy: extra?.namingStrategy }), extra);
+        this.opts = opts;
+    }
+    async getQuerier() {
+        this.db ??= await this.openDb();
+        return new SqliteQuerier(this.db, this.dialect, this.extra);
+    }
+    async openDb() {
+        const db = await this.createDb();
+        for (const extension of this.opts?.extensions ?? []) {
+            db.loadExtension(extension);
+        }
+        return db;
+    }
+    async end() {
+        await this.db?.close();
+        this.db = undefined;
+    }
+}

package/dist/sqlite/nodeSqliteAdapter.d.ts

@@ -0,0 +1,35 @@
+import type { SqliteBindValue } from './abstractSqliteQuerier.js';
+import type { SqliteDatabase } from './sqliteQuerier.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`.
+ */
+type NodeSqliteStatement = {
+    columns(): readonly unknown[];
+    all(...values: SqliteBindValue[]): unknown[];
+    run(...values: SqliteBindValue[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    iterate(...values: SqliteBindValue[]): Iterable<unknown>;
+};
+/**
+ * Structural subset of `node:sqlite`'s `DatabaseSync`, declared locally for the same reason the rest
+ * of this folder declares its driver shapes: nothing here depends on `@types/node` being in scope.
+ */
+export type NodeSqliteDatabase = {
+    prepare(sql: string): NodeSqliteStatement;
+    exec(sql: string): void;
+    loadExtension(path: string): void;
+    close(): void;
+};
+/**
+ * Presents a `node:sqlite` handle as a {@link SqliteDatabase}.
+ *
+ * @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 {};

package/dist/sqlite/nodeSqliteAdapter.js

@@ -0,0 +1,28 @@
+/**
+ * Presents a `node:sqlite` handle as a {@link SqliteDatabase}.
+ *
+ * @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 function adaptNodeSqlite(db) {
+    return {
+        prepare: (sql) => {
+            const stmt = db.prepare(sql);
+            return {
+                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 };
+                },
+                iterate: (...values) => stmt.iterate(...values),
+            };
+        },
+        loadExtension: (path) => db.loadExtension(path),
+        close: () => db.close(),
+    };
+}

package/dist/sqlite/nodeSqliteQuerierPool.d.ts

@@ -0,0 +1,28 @@
+import type { ExtraOptions } from '../type/index.js';
+import { AbstractLocalSqliteQuerierPool, type LocalSqlitePoolOptions } from './localSqliteQuerierPool.js';
+import type { SqliteDatabase } from './sqliteQuerier.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
+ * are ignored by the driver, so the list only has to cover what callers actually set.
+ */
+export type NodeSqlitePoolOptions = LocalSqlitePoolOptions & {
+    readonly readOnly?: boolean;
+    readonly enableForeignKeyConstraints?: boolean;
+    /** Milliseconds a locked database is retried before `SQLITE_BUSY`. */
+    readonly timeout?: number;
+};
+/**
+ * Pool backed by Node's built-in `node:sqlite`, so SQLite works with **no dependency at all** rather
+ * than requiring the `better-sqlite3` native build. Use {@link Sqlite3QuerierPool} instead when you
+ * want `better-sqlite3`, or are on Bun.
+ *
+ * @remarks `node:sqlite` needs no CLI flag from Node 22.13, and is still a release candidate
+ * (stability 1.2) as of Node 26, so `better-sqlite3` via {@link Sqlite3QuerierPool} remains the
+ * faster option for read-heavy work.
+ */
+export declare class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool<NodeSqlitePoolOptions> {
+    readonly filename: string;
+    constructor(filename?: string, opts?: NodeSqlitePoolOptions, extra?: ExtraOptions);
+    protected createDb(): Promise<SqliteDatabase>;
+}

package/dist/sqlite/nodeSqliteQuerierPool.js

@@ -0,0 +1,29 @@
+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
+ * than requiring the `better-sqlite3` native build. Use {@link Sqlite3QuerierPool} instead when you
+ * want `better-sqlite3`, or are on Bun.
+ *
+ * @remarks `node:sqlite` needs no CLI flag from Node 22.13, and is still a release candidate
+ * (stability 1.2) as of Node 26, so `better-sqlite3` via {@link Sqlite3QuerierPool} remains the
+ * faster option for read-heavy work.
+ */
+export class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool {
+    filename;
+    constructor(filename = ':memory:', opts, extra) {
+        super(opts, extra);
+        this.filename = filename;
+    }
+    async createDb() {
+        const { DatabaseSync } = await import('node:sqlite');
+        const { extensions, ...driverOpts } = this.opts ?? {};
+        const nodeDb = new DatabaseSync(this.filename, {
+            ...driverOpts,
+            // `node:sqlite` refuses `loadExtension` unless the database was opened with this on.
+            ...(extensions?.length ? { allowExtension: true } : undefined),
+        });
+        nodeDb.exec('PRAGMA journal_mode = WAL');
+        return adaptNodeSqlite(nodeDb);
+    }
+}

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,5 +1,5 @@
 import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
-import type { DialectFeatures, EntityMeta, FieldOptions, QueryConflictPaths, QueryContext, QuerySizeComparisonOps, QueryTextSearchOptions, Type, VectorDistance } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, QueryContext, QuerySizeComparisonOps, QueryTextSearchOptions, Type, VectorDistance } from '../type/index.js';
 export declare class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
     protected readonly featureDefaults: DialectFeatures;
@@ -52,7 +52,6 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     protected jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
     protected getJsonPathScalarExpr(escapedColumn: string, jsonPathStr: string): string;
     protected numericCast(expr: string): string;
-    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     protected jsonCast(operand: string): string;
     /**
      * `json_replace` leaves an absent key (and a NULL column) untouched. Elements are read back

package/dist/sqlite/sqliteDialect.js

@@ -1,6 +1,5 @@
 import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
 import { JSON_ELEM_ALIAS_PREFIX, JSON_PULL_ALIAS, jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
-import { getMeta } from '../entity/index.js';
 export class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
     featureDefaults = {
@@ -109,18 +108,6 @@ export class SqliteDialect extends AbstractSqlDialect {
     numericCast(expr) {
         return `CAST(${expr} AS REAL)`;
     }
-    upsert(ctx, entity, conflictPaths, payload) {
-        const meta = getMeta(entity);
-        const updateCtx = this.createContext();
-        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `EXCLUDED.${name}`);
-        const keysStr = this.getUpsertConflictPathsStr(meta, conflictPaths);
-        const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
-        // Use the base (non-RETURNING) insert here: the appended RETURNING below would otherwise
-        // be doubled by `this.insert`'s own.
-        this.appendInsertValues(ctx, entity, payload);
-        ctx.append(` ON CONFLICT (${keysStr}) ${onConflict} ${this.returningId(entity)}`);
-        ctx.pushValue(...updateCtx.values);
-    }
     jsonCast(operand) {
         return `json(${operand})`;
     }

package/dist/sqlite/sqliteQuerierPool.d.ts

@@ -1,28 +1,15 @@
 import type { Options } from 'better-sqlite3';
-import { AbstractSqlQuerierPool } from '../querier/index.js';
 import type { ExtraOptions } from '../type/index.js';
-import { SqliteDialect } from './sqliteDialect.js';
-import { SqliteQuerier } from './sqliteQuerier.js';
+import { AbstractLocalSqliteQuerierPool, type LocalSqlitePoolOptions } from './localSqliteQuerierPool.js';
+import type { SqliteDatabase } from './sqliteQuerier.js';
 /** Driver options, plus the loadable extensions to install on the connection. */
-export type Sqlite3PoolOptions = Options & {
-    /**
-     * Paths of loadable extensions to install when the connection opens - e.g. what `sqlite-vec`'s
-     * `getLoadablePath()` returns, which vector search needs because SQLite itself has no vector
-     * functions.
-     */
-    extensions?: readonly string[];
-};
-export declare class Sqlite3QuerierPool extends AbstractSqlQuerierPool<SqliteQuerier, SqliteDialect> {
+export type Sqlite3PoolOptions = Options & LocalSqlitePoolOptions;
+/**
+ * Pool for `better-sqlite3`, or `bun:sqlite` when running under Bun - the same file, through whichever
+ * driver the runtime provides.
+ */
+export declare class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool<Sqlite3PoolOptions> {
     readonly filename: string | Buffer;
-    readonly opts?: Sqlite3PoolOptions | undefined;
-    private db?;
-    constructor(filename?: string | Buffer, opts?: Sqlite3PoolOptions | undefined, extra?: ExtraOptions);
-    /**
-     * The database handle is shared (single connection), but each acquisition gets its own querier
-     * so transaction state stays per unit of work.
-     */
-    getQuerier(): Promise<SqliteQuerier>;
-    private openDb;
-    private openDriverDb;
-    end(): Promise<void>;
+    constructor(filename?: string | Buffer, opts?: Sqlite3PoolOptions, extra?: ExtraOptions);
+    protected createDb(): Promise<SqliteDatabase>;
 }