uql-orm 0.21.0 → 0.23.0

package/dist/sqlite/abstractSqliteQuerier.js

@@ -1,3 +1,47 @@
 import { AbstractSqlQuerier } from '../querier/index.js';
+import { throwPendingTransaction } from '../util/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; it only asserts the unit of work was finished. Drivers owning a
+     * closable per-querier connection override this.
+     */
+    async internalRelease() {
+        if (this.hasOpenTransaction) {
+            throwPendingTransaction();
+        }
+    }
+}
+/**
+ * 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 class PreparedSqliteQuerier extends AbstractSqliteQuerier {
+    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;
+        }
+    }
+    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 });
+    }
 }

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

@@ -0,0 +1,26 @@
+import type { SqliteBindValue, SqliteRunResult } from './abstractSqliteQuerier.js';
+import type { SqliteDatabase } from './sqliteQuerier.js';
+/** A `bun:sqlite` statement: better-sqlite3-shaped, except it reports columns instead of `reader`. */
+type BunStatement = {
+    columnNames: string[];
+    all(...values: SqliteBindValue[]): unknown[];
+    run(...values: SqliteBindValue[]): SqliteRunResult;
+    iterate(...values: SqliteBindValue[]): Iterable<unknown>;
+};
+type BunDatabase = {
+    prepare(sql: string): BunStatement;
+    loadExtension(path: string): void;
+    close(): unknown;
+};
+/**
+ * Presents a `bun: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.
+ * `columnNames` is non-empty for exactly the statements better-sqlite3 marks as readers.
+ *
+ * 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 {};

package/dist/sqlite/bunSqliteAdapter.bun.js

@@ -0,0 +1,25 @@
+/**
+ * Presents a `bun: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.
+ * `columnNames` is non-empty for exactly the statements better-sqlite3 marks as readers.
+ *
+ * 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 function adaptBunSqlite(db) {
+    return {
+        prepare: (sql) => {
+            const stmt = db.prepare(sql);
+            return {
+                reader: stmt.columnNames.length > 0,
+                all: (...values) => stmt.all(...values),
+                run: (...values) => stmt.run(...values),
+                iterate: (...values) => stmt.iterate(...values),
+            };
+        },
+        loadExtension: (path) => db.loadExtension(path),
+        close: () => db.close(),
+    };
+}

package/dist/sqlite/hranaQuerier.d.ts

@@ -0,0 +1,54 @@
+import type { ExtraOptions, TransactionOptions } from '../type/index.js';
+import { AbstractSqliteQuerier, type SqliteBindValue } from './abstractSqliteQuerier.js';
+import type { SqliteDialect } from './sqliteDialect.js';
+/**
+ * Structural subset of the Hrana client API, the wire protocol shared by `@libsql/client` and
+ * `@tursodatabase/serverless/compat`. Declared here rather than imported so a querier works with
+ * any client of this shape (including `@libsql/client/web` and `@libsql/client-wasm`) without
+ * depending on vendor types.
+ */
+export type HranaInValue = SqliteBindValue | ArrayBuffer | Date;
+export type HranaResultSet = {
+    rows: unknown[];
+    rowsAffected: number;
+    lastInsertRowid?: bigint;
+};
+export type HranaExecutor = {
+    execute(stmt: {
+        sql: string;
+        args?: HranaInValue[];
+    }): Promise<HranaResultSet>;
+};
+export type HranaTransaction = HranaExecutor & {
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+};
+export type HranaClient = HranaExecutor & {
+    transaction(mode?: 'write' | 'read' | 'deferred'): Promise<HranaTransaction>;
+    close(): void;
+};
+/** Connection lifecycle for a {@link HranaQuerier} (separate from {@link ExtraOptions}). */
+export type HranaQuerierConnectionOptions = {
+    /** When set, {@link release} closes {@link HranaQuerier.client} (one-shot migration connections). */
+    closeClientOnRelease?: boolean;
+};
+/**
+ * Querier for SQLite databases reached through a Hrana client.
+ *
+ * @remarks Transactions use the client's own session handle rather than `BEGIN`/`COMMIT` statements,
+ * because over plain HTTP consecutive requests need not share a connection.
+ */
+export declare class HranaQuerier extends AbstractSqliteQuerier {
+    readonly client: HranaClient;
+    readonly extra?: ExtraOptions | undefined;
+    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>;
+    get hasOpenTransaction(): boolean;
+    beginTransaction(_opts?: TransactionOptions): Promise<void>;
+    commitTransaction(): Promise<void>;
+    rollbackTransaction(): Promise<void>;
+    internalRelease(): Promise<void>;
+}

package/dist/sqlite/hranaQuerier.js

@@ -0,0 +1,68 @@
+import { throwNoPendingTransaction, throwPendingTransaction } from '../util/index.js';
+import { AbstractSqliteQuerier } from './abstractSqliteQuerier.js';
+/**
+ * Querier for SQLite databases reached through a Hrana client.
+ *
+ * @remarks Transactions use the client's own session handle rather than `BEGIN`/`COMMIT` statements,
+ * because over plain HTTP consecutive requests need not share a connection.
+ */
+export class HranaQuerier extends AbstractSqliteQuerier {
+    client;
+    extra;
+    tx;
+    closeClientOnRelease;
+    constructor(client, dialect, extra, connection) {
+        super(dialect, extra);
+        this.client = client;
+        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 });
+    }
+    get hasOpenTransaction() {
+        return !!this.tx;
+    }
+    async beginTransaction(_opts) {
+        return this.serialize(async () => {
+            if (this.tx) {
+                throwPendingTransaction();
+            }
+            this.tx = await this.client.transaction('write');
+        });
+    }
+    async commitTransaction() {
+        return this.serialize(async () => {
+            if (!this.tx) {
+                throwNoPendingTransaction();
+            }
+            await this.tx.commit();
+            this.tx = undefined;
+        });
+    }
+    async rollbackTransaction() {
+        return this.serialize(async () => {
+            if (!this.tx) {
+                throwNoPendingTransaction();
+            }
+            await this.tx.rollback();
+            this.tx = undefined;
+        });
+    }
+    async internalRelease() {
+        await super.internalRelease();
+        if (this.closeClientOnRelease) {
+            this.client.close();
+        }
+    }
+}

package/dist/sqlite/hranaQuerierPool.d.ts

@@ -0,0 +1,21 @@
+import { AbstractSqlQuerierPool } from '../querier/index.js';
+import type { HranaClient, HranaQuerier, HranaQuerierConnectionOptions } from './hranaQuerier.js';
+import type { SqliteDialect } from './sqliteDialect.js';
+/**
+ * Pool for SQLite databases reached over the Hrana wire protocol (`@libsql/client`,
+ * `@tursodatabase/serverless/compat`).
+ *
+ * @remarks The client is shared by every querier, since Hrana keeps no per-connection state: a
+ * transaction takes its own session handle. It is resolved on first use rather than in the
+ * constructor, so building a pool never throws when the optional driver peer is absent, which is what
+ * lets a Workers bundle construct one at module scope.
+ */
+export declare abstract class AbstractHranaQuerierPool<Q extends HranaQuerier, D extends SqliteDialect> extends AbstractSqlQuerierPool<Q, D> {
+    private client?;
+    /** False when the caller injected their own client, in which case they own its lifecycle. */
+    protected readonly ownsClient: boolean;
+    protected abstract openClient(): Promise<HranaClient>;
+    protected abstract buildQuerier(client: HranaClient, connection?: HranaQuerierConnectionOptions): Q;
+    getQuerier(): Promise<Q>;
+    end(): Promise<void>;
+}

package/dist/sqlite/hranaQuerierPool.js

@@ -0,0 +1,25 @@
+import { AbstractSqlQuerierPool } from '../querier/index.js';
+/**
+ * Pool for SQLite databases reached over the Hrana wire protocol (`@libsql/client`,
+ * `@tursodatabase/serverless/compat`).
+ *
+ * @remarks The client is shared by every querier, since Hrana keeps no per-connection state: a
+ * transaction takes its own session handle. It is resolved on first use rather than in the
+ * constructor, so building a pool never throws when the optional driver peer is absent, which is what
+ * lets a Workers bundle construct one at module scope.
+ */
+export class AbstractHranaQuerierPool extends AbstractSqlQuerierPool {
+    client;
+    /** False when the caller injected their own client, in which case they own its lifecycle. */
+    ownsClient = true;
+    async getQuerier() {
+        this.client ??= await this.openClient();
+        return this.buildQuerier(this.client);
+    }
+    async end() {
+        if (this.ownsClient) {
+            this.client?.close();
+        }
+        this.client = undefined;
+    }
+}

package/dist/sqlite/index.d.ts

@@ -1,5 +1,7 @@
 export * from './abstractSqliteQuerier.js';
-export * from './betterSqlite3Dialect.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,5 +1,7 @@
 export * from './abstractSqliteQuerier.js';
-export * from './betterSqlite3Dialect.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, FieldOptions, QueryComparisonOptions, QueryConflictPaths, QueryContext, QueryOptions, QuerySizeComparisonOps, 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;
@@ -14,6 +14,11 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     readonly alterColumnSyntax = "none";
     readonly booleanLiteral = "integer";
     readonly insertIdSource = "returning";
+    /**
+     * The [sqlite-vec](https://github.com/asg017/sqlite-vec) functions, which need that extension
+     * loaded on the connection (see `Sqlite3QuerierPool`'s `extensions` option). libSQL and Turso ship
+     * their own vector functions instead, so `LibsqlDialect` overrides this.
+     */
     protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
     /**
      * SQLite does not support the `DEFAULT` keyword inside `VALUES`. Inline the metadata default
@@ -23,7 +28,11 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     protected ilikeExpr(f: string, ph: string): string;
     protected get neOp(): string;
     normalizeValue(value: unknown): unknown;
-    compare<E>(ctx: QueryContext, entity: Type<E>, key: string, val: unknown, opts?: QueryComparisonOptions): void;
+    /**
+     * FTS5 matches the table itself rather than its columns, so this only works when the table *is* an
+     * FTS5 virtual table (UQL does not create those; declare it outside your entities).
+     */
+    protected appendTextSearch<E>(ctx: QueryContext, entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
     /**
      * SQLite compares an exploded element as whole JSON text, so containment cannot express "this
      * element includes these keys" - `$elemMatch` always expands to per-field conditions.
@@ -43,8 +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;
-    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
-    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
@@ -53,7 +60,13 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      */
     protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
     protected jsonSet(ctx: QueryContext, expr: string, set: Record<string, unknown>, field?: FieldOptions): string;
-    /** `[#]` appends, creating the array when the key is absent. */
+    /**
+     * `[#]` appends, creating the array when the key is absent.
+     *
+     * @remarks `json_set` rather than `json_insert`: the two are equivalent here because `[#]` always
+     * resolves past the end of the array, and Turso's engine implements `json_insert` as create-only,
+     * so it silently drops the element when the array already exists.
+     */
     protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;
     protected jsonUnset(_ctx: QueryContext, expr: string, unset: readonly string[]): string;
 }

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 = {
@@ -13,7 +12,7 @@ export class SqliteDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: false, // SQLite does not support adding FKs to existing tables
         columnComment: false, // SQLite does not support column comments
-        vectorIndexStyle: 'create',
+        inlineVectorIndex: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,
         defaultStringAsText: true,
@@ -30,10 +29,15 @@ export class SqliteDialect extends AbstractSqlDialect {
     booleanLiteral = 'integer';
     // SQLite supports `RETURNING` (including on `INSERT ... ON CONFLICT`), so IDs are exact per row.
     insertIdSource = 'returning';
+    /**
+     * The [sqlite-vec](https://github.com/asg017/sqlite-vec) functions, which need that extension
+     * loaded on the connection (see `Sqlite3QuerierPool`'s `extensions` option). libSQL and Turso ship
+     * their own vector functions instead, so `LibsqlDialect` overrides this.
+     */
     vectorDistanceFns = new Map([
         ['cosine', 'vec_distance_cosine'],
         ['l2', 'vec_distance_L2'],
-        ['hamming', 'vec_distance_hamming'],
+        ['l1', 'vec_distance_L1'],
     ]);
     /**
      * SQLite does not support the `DEFAULT` keyword inside `VALUES`. Inline the metadata default
@@ -58,21 +62,14 @@ export class SqliteDialect extends AbstractSqlDialect {
             return value.getTime();
         return super.normalizeValue(value);
     }
-    compare(ctx, entity, key, val, opts) {
-        if (key === '$text') {
-            const meta = getMeta(entity);
-            const search = val;
-            const fields = search.$fields.map((fKey) => {
-                const field = meta.fields[fKey];
-                const columnName = this.resolveColumnName(fKey, field);
-                return this.escapeId(columnName);
-            });
-            const tableName = this.resolveTableName(entity, meta);
-            ctx.append(`${this.escapeId(tableName)} MATCH {${fields.join(' ')}} : `);
-            ctx.addValue(search.$value);
-            return;
-        }
-        super.compare(ctx, entity, key, val, opts);
+    /**
+     * FTS5 matches the table itself rather than its columns, so this only works when the table *is* an
+     * FTS5 virtual table (UQL does not create those; declare it outside your entities).
+     */
+    appendTextSearch(ctx, entity, meta, search) {
+        const columns = search.$fields.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+        ctx.append(`${this.escapeId(this.resolveTableName(entity, meta))} MATCH {${columns.join(' ')}} : `);
+        ctx.addValue(search.$value);
     }
     /**
      * SQLite compares an exploded element as whole JSON text, so containment cannot express "this
@@ -111,22 +108,6 @@ export class SqliteDialect extends AbstractSqlDialect {
     numericCast(expr) {
         return `CAST(${expr} AS REAL)`;
     }
-    insert(ctx, entity, payload, opts) {
-        super.insert(ctx, entity, payload, opts);
-        ctx.append(' ' + this.returningId(entity));
-    }
-    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.
-        super.insert(ctx, entity, payload);
-        ctx.append(` ON CONFLICT (${keysStr}) ${onConflict} ${this.returningId(entity)}`);
-        ctx.pushValue(...updateCtx.values);
-    }
     jsonCast(operand) {
         return `json(${operand})`;
     }
@@ -144,9 +125,15 @@ export class SqliteDialect extends AbstractSqlDialect {
     jsonSet(ctx, expr, set, field) {
         return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'json_set', jsonSetTarget(expr, field, `'{}'`), set);
     }
-    /** `[#]` appends, creating the array when the key is absent. */
+    /**
+     * `[#]` appends, creating the array when the key is absent.
+     *
+     * @remarks `json_set` rather than `json_insert`: the two are equivalent here because `[#]` always
+     * resolves past the end of the array, and Turso's engine implements `json_insert` as create-only,
+     * so it silently drops the element when the array already exists.
+     */
     jsonPush(ctx, expr, push) {
-        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'json_insert', expr, push, '[#]');
+        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'json_set', expr, push, '[#]');
     }
     jsonUnset(_ctx, expr, unset) {
         return jsonRemoveCall('json_remove', expr, unset);