uql-orm 0.21.0 → 0.23.0

package/dist/sqlite/sqliteQuerier.d.ts

@@ -1,13 +1,20 @@
-import type { Database } from 'better-sqlite3';
 import type { ExtraOptions } from '../type/index.js';
-import { AbstractSqliteQuerier } from './abstractSqliteQuerier.js';
+import { PreparedSqliteQuerier, type SqlitePreparedStatement } from './abstractSqliteQuerier.js';
 import type { SqliteDialect } from './sqliteDialect.js';
-export declare class SqliteQuerier extends AbstractSqliteQuerier {
-    readonly db: Database;
+/**
+ * Structural subset of a synchronous better-sqlite3-compatible driver, declared locally so this
+ * querier carries no vendor type. A real `better-sqlite3` `Database` satisfies it directly;
+ * `bun:sqlite` is adapted to it by {@link Sqlite3QuerierPool}.
+ */
+export type SqliteDatabase = {
+    prepare(sql: string): SqlitePreparedStatement;
+    /** Installs a loadable extension (`sqlite-vec`, ...) into this connection. */
+    loadExtension(path: string): void;
+    close(): unknown;
+};
+export declare class SqliteQuerier extends PreparedSqliteQuerier {
+    readonly db: SqliteDatabase;
     readonly extra?: ExtraOptions | undefined;
-    constructor(db: Database, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
-    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>;
-    internalRelease(): Promise<void>;
+    constructor(db: SqliteDatabase, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
+    protected prepare(query: string): SqlitePreparedStatement;
 }

package/dist/sqlite/sqliteQuerier.js

@@ -1,6 +1,5 @@
-import { throwPendingTransaction } from '../util/index.js';
-import { AbstractSqliteQuerier } from './abstractSqliteQuerier.js';
-export class SqliteQuerier extends AbstractSqliteQuerier {
+import { PreparedSqliteQuerier } from './abstractSqliteQuerier.js';
+export class SqliteQuerier extends PreparedSqliteQuerier {
     db;
     extra;
     constructor(db, dialect, extra) {
@@ -8,29 +7,7 @@ export class SqliteQuerier extends AbstractSqliteQuerier {
         this.db = db;
         this.extra = extra;
     }
-    async internalAll(query, values) {
-        return this.db.prepare(query).all(values || []);
-    }
-    async *internalStream(query, values) {
-        for (const row of this.db.prepare(query).iterate(values || [])) {
-            yield row;
-        }
-    }
-    async internalRun(query, values) {
-        const stmt = this.db.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 = stmt.all(values || []);
-            return this.buildUpdateResult({ rows });
-        }
-        const { changes, lastInsertRowid } = stmt.run(values || []);
-        return this.buildUpdateResult({ changes, id: lastInsertRowid });
-    }
-    async internalRelease() {
-        if (this.hasOpenTransaction) {
-            throwPendingTransaction();
-        }
-        // no-op
+    prepare(query) {
+        return this.db.prepare(query);
     }
 }

package/dist/sqlite/sqliteQuerierPool.d.ts

@@ -1,18 +1,15 @@
 import type { Options } from 'better-sqlite3';
-import { AbstractSqlQuerierPool } from '../querier/index.js';
 import type { ExtraOptions } from '../type/index.js';
-import { BetterSqlite3Dialect } from './betterSqlite3Dialect.js';
-import { SqliteQuerier } from './sqliteQuerier.js';
-export declare class Sqlite3QuerierPool extends AbstractSqlQuerierPool<SqliteQuerier, BetterSqlite3Dialect> {
+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 & 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?: Options | undefined;
-    private db?;
-    constructor(filename?: string | Buffer, opts?: Options | 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;
-    end(): Promise<void>;
+    constructor(filename?: string | Buffer, opts?: Sqlite3PoolOptions, extra?: ExtraOptions);
+    protected createDb(): Promise<SqliteDatabase>;
 }

package/dist/sqlite/sqliteQuerierPool.js

@@ -1,37 +1,29 @@
-import { AbstractSqlQuerierPool } from '../querier/index.js';
-import { BetterSqlite3Dialect } from './betterSqlite3Dialect.js';
-import { SqliteQuerier } from './sqliteQuerier.js';
-export class Sqlite3QuerierPool extends AbstractSqlQuerierPool {
+import { AbstractLocalSqliteQuerierPool } from './localSqliteQuerierPool.js';
+/**
+ * Pool for `better-sqlite3`, or `bun:sqlite` when running under Bun - the same file, through whichever
+ * driver the runtime provides.
+ */
+export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
     filename;
-    opts;
-    db;
     constructor(filename = ':memory:', opts, extra) {
-        super(new BetterSqlite3Dialect({ namingStrategy: extra?.namingStrategy }), extra);
+        super(opts, extra);
         this.filename = filename;
-        this.opts = opts;
     }
-    /**
-     * The database handle is shared (single connection), but each acquisition gets its own querier
-     * so transaction state stays per unit of work.
-     */
-    async getQuerier() {
-        this.db ??= await this.openDb();
-        return new SqliteQuerier(this.db, this.dialect, this.extra);
-    }
-    async openDb() {
+    async createDb() {
+        // `bun:sqlite` rejects option keys it does not know, and rejects an options object carrying no
+        // open flags, so `extensions` is stripped out and what remains of it collapses back to nothing.
+        const { extensions, ...driverOpts } = this.opts ?? {};
+        const opts = Object.keys(driverOpts).length > 0 ? driverOpts : undefined;
         if (typeof Bun !== 'undefined') {
             const { Database: BunDatabase } = await import('bun:sqlite');
-            const bunDb = new BunDatabase(this.filename, this.opts);
+            const { adaptBunSqlite } = await import('./bunSqliteAdapter.bun.js');
+            const bunDb = new BunDatabase(this.filename, opts);
             bunDb.run('PRAGMA journal_mode = WAL');
-            return bunDb;
+            return adaptBunSqlite(bunDb);
         }
         const { default: BetterSqlite3 } = await import('better-sqlite3');
-        const db = new BetterSqlite3(this.filename, this.opts);
+        const db = new BetterSqlite3(this.filename, opts);
         db.pragma('journal_mode = WAL');
         return db;
     }
-    async end() {
-        await this.db?.close();
-        this.db = undefined;
-    }
 }

package/dist/turso/index.d.ts

@@ -0,0 +1,3 @@
+export * from './tursoDialect.js';
+export * from './tursoQuerier.js';
+export * from './tursoQuerierPool.js';

package/dist/turso/index.js

@@ -0,0 +1,3 @@
+export * from './tursoDialect.js';
+export * from './tursoQuerier.js';
+export * from './tursoQuerierPool.js';

package/dist/turso/local.d.ts

@@ -0,0 +1,3 @@
+export * from './tursoDialect.js';
+export * from './tursoLocalQuerier.js';
+export * from './tursoLocalQuerierPool.js';

package/dist/turso/local.js

@@ -0,0 +1,3 @@
+export * from './tursoDialect.js';
+export * from './tursoLocalQuerier.js';
+export * from './tursoLocalQuerierPool.js';

package/dist/turso/tursoDialect.d.ts

@@ -0,0 +1,15 @@
+import { LibsqlDialect } from '../libsql/libsqlDialect.js';
+import type { VectorDistance } from '../type/index.js';
+/**
+ * SQLite Dialect specialization for Turso Database.
+ *
+ * @remarks Shared by `TursoQuerierPool` (remote, `@tursodatabase/serverless`) and
+ * `TursoLocalQuerierPool` (embedded, `@tursodatabase/database`). Built on `LibsqlDialect` because
+ * Turso is that engine's successor and keeps its SQL surface, vector functions included. Imports
+ * nothing vendor-specific, so the embedded entry point cannot pull native code into an edge bundle
+ * through it.
+ */
+export declare class TursoDialect extends LibsqlDialect {
+    /** The Rust engine adds a dot-product distance to libSQL's cosine and L2. */
+    protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
+}

package/dist/turso/tursoDialect.js

@@ -0,0 +1,18 @@
+import { LibsqlDialect } from '../libsql/libsqlDialect.js';
+/**
+ * SQLite Dialect specialization for Turso Database.
+ *
+ * @remarks Shared by `TursoQuerierPool` (remote, `@tursodatabase/serverless`) and
+ * `TursoLocalQuerierPool` (embedded, `@tursodatabase/database`). Built on `LibsqlDialect` because
+ * Turso is that engine's successor and keeps its SQL surface, vector functions included. Imports
+ * nothing vendor-specific, so the embedded entry point cannot pull native code into an edge bundle
+ * through it.
+ */
+export class TursoDialect extends LibsqlDialect {
+    /** The Rust engine adds a dot-product distance to libSQL's cosine and L2. */
+    vectorDistanceFns = new Map([
+        ['cosine', 'vector_distance_cos'],
+        ['l2', 'vector_distance_l2'],
+        ['inner', 'vector_distance_dot'],
+    ]);
+}

package/dist/turso/tursoLocalQuerier.d.ts

@@ -0,0 +1,25 @@
+import { PreparedSqliteQuerier, type SqlitePreparedStatement } from '../sqlite/abstractSqliteQuerier.js';
+import type { SqliteDialect } from '../sqlite/sqliteDialect.js';
+import type { ExtraOptions } from '../type/index.js';
+/**
+ * Structural subset of the `@tursodatabase/database` API actually used here, declared locally so
+ * this package does not couple its published types to a pre-1.0 dependency.
+ */
+export type TursoDatabase = {
+    prepare(sql: string): Promise<SqlitePreparedStatement>;
+    pragma(source: string, options?: unknown): Promise<unknown[]>;
+    close(): Promise<void>;
+};
+/**
+ * Querier for the embedded Turso engine.
+ *
+ * @remarks The engine exposes better-sqlite3 semantics (`reader`, `{changes, lastInsertRowid}`,
+ * array-bound values) over an async API, so all it supplies is the awaited `prepare`.
+ * `BEGIN`/`COMMIT` work as plain statements, leaving transactions to the base class.
+ */
+export declare class TursoLocalQuerier extends PreparedSqliteQuerier {
+    readonly db: TursoDatabase;
+    readonly extra?: ExtraOptions | undefined;
+    constructor(db: TursoDatabase, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
+    protected prepare(query: string): Promise<SqlitePreparedStatement>;
+}

package/dist/turso/tursoLocalQuerier.js

@@ -0,0 +1,20 @@
+import { PreparedSqliteQuerier } from '../sqlite/abstractSqliteQuerier.js';
+/**
+ * Querier for the embedded Turso engine.
+ *
+ * @remarks The engine exposes better-sqlite3 semantics (`reader`, `{changes, lastInsertRowid}`,
+ * array-bound values) over an async API, so all it supplies is the awaited `prepare`.
+ * `BEGIN`/`COMMIT` work as plain statements, leaving transactions to the base class.
+ */
+export class TursoLocalQuerier extends PreparedSqliteQuerier {
+    db;
+    extra;
+    constructor(db, dialect, extra) {
+        super(dialect, extra);
+        this.db = db;
+        this.extra = extra;
+    }
+    prepare(query) {
+        return this.db.prepare(query);
+    }
+}

package/dist/turso/tursoLocalQuerierPool.d.ts

@@ -0,0 +1,32 @@
+import { AbstractSqlQuerierPool } from '../querier/index.js';
+import type { ExtraOptions } from '../type/index.js';
+import { TursoDialect } from './tursoDialect.js';
+import { TursoLocalQuerier } from './tursoLocalQuerier.js';
+/** Subset of `DatabaseOpts` from `@tursodatabase/database`, declared locally to avoid the coupling. */
+export type TursoLocalOptions = {
+    readonly?: boolean;
+    fileMustExist?: boolean;
+    timeout?: number;
+    defaultQueryTimeout?: number;
+    tracing?: 'info' | 'debug' | 'trace';
+};
+/**
+ * Pool for the embedded Turso engine (`@tursodatabase/database`), the Rust rewrite of SQLite.
+ *
+ * @remarks Kept on the `uql-orm/turso/local` entry point rather than `uql-orm/turso`, because this
+ * package ships native binaries that do not resolve on edge runtimes. Separating them guarantees a
+ * bundle targeting Workers never reaches the native import.
+ */
+export declare class TursoLocalQuerierPool extends AbstractSqlQuerierPool<TursoLocalQuerier, TursoDialect> {
+    readonly filename: string;
+    readonly opts?: TursoLocalOptions | undefined;
+    private db?;
+    constructor(filename?: string, opts?: TursoLocalOptions | 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<TursoLocalQuerier>;
+    private openDb;
+    end(): Promise<void>;
+}

package/dist/turso/tursoLocalQuerierPool.js

@@ -0,0 +1,39 @@
+import { AbstractSqlQuerierPool } from '../querier/index.js';
+import { TursoDialect } from './tursoDialect.js';
+import { TursoLocalQuerier } from './tursoLocalQuerier.js';
+/**
+ * Pool for the embedded Turso engine (`@tursodatabase/database`), the Rust rewrite of SQLite.
+ *
+ * @remarks Kept on the `uql-orm/turso/local` entry point rather than `uql-orm/turso`, because this
+ * package ships native binaries that do not resolve on edge runtimes. Separating them guarantees a
+ * bundle targeting Workers never reaches the native import.
+ */
+export class TursoLocalQuerierPool extends AbstractSqlQuerierPool {
+    filename;
+    opts;
+    db;
+    constructor(filename = ':memory:', opts, extra) {
+        super(new TursoDialect({ namingStrategy: extra?.namingStrategy }), extra);
+        this.filename = filename;
+        this.opts = opts;
+    }
+    /**
+     * The database handle is shared (single connection), but each acquisition gets its own querier
+     * so transaction state stays per unit of work.
+     */
+    async getQuerier() {
+        this.db ??= await this.openDb();
+        return new TursoLocalQuerier(this.db, this.dialect, this.extra);
+    }
+    async openDb() {
+        const { connect } = await import('@tursodatabase/database');
+        // Annotated rather than cast, so the structural contract is checked against the real driver.
+        const db = await connect(this.filename, this.opts);
+        await db.pragma('journal_mode = WAL');
+        return db;
+    }
+    async end() {
+        await this.db?.close();
+        this.db = undefined;
+    }
+}

package/dist/turso/tursoQuerier.d.ts

@@ -0,0 +1,10 @@
+import { HranaQuerier } from '../sqlite/hranaQuerier.js';
+/**
+ * Querier for remote Turso Cloud databases over `@tursodatabase/serverless/compat`.
+ *
+ * @remarks Empty subclass by design: that compat client speaks the Hrana protocol, so the whole
+ * implementation is inherited. Kept as a distinct type so `TursoQuerierPool` does not expose a
+ * libsql-named class.
+ */
+export declare class TursoQuerier extends HranaQuerier {
+}

package/dist/turso/tursoQuerier.js

@@ -0,0 +1,10 @@
+import { HranaQuerier } from '../sqlite/hranaQuerier.js';
+/**
+ * Querier for remote Turso Cloud databases over `@tursodatabase/serverless/compat`.
+ *
+ * @remarks Empty subclass by design: that compat client speaks the Hrana protocol, so the whole
+ * implementation is inherited. Kept as a distinct type so `TursoQuerierPool` does not expose a
+ * libsql-named class.
+ */
+export class TursoQuerier extends HranaQuerier {
+}

package/dist/turso/tursoQuerierPool.d.ts

@@ -0,0 +1,39 @@
+import type { HranaClient } from '../sqlite/hranaQuerier.js';
+import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
+import type { ExtraOptions } from '../type/index.js';
+import { TursoDialect } from './tursoDialect.js';
+import { TursoQuerier } from './tursoQuerier.js';
+/**
+ * Connection settings for Turso Cloud, mirroring `@tursodatabase/serverless`.
+ *
+ * @remarks Declared here rather than imported so this package does not couple its published types
+ * to a pre-1.0 dependency.
+ */
+export type TursoConfig = {
+    /** `libsql://<db>.turso.io` or `https://<db>.turso.io`. */
+    url: string;
+    authToken?: string;
+    remoteEncryptionKey?: string;
+    /** Extra HTTP headers attached to every request, e.g. for routing through a gateway. */
+    requestHeaders?: Record<string, string>;
+};
+/**
+ * Pool for remote Turso Cloud databases, driven by `@tursodatabase/serverless/compat`.
+ *
+ * @remarks The compat entry point is required rather than the native one: the native
+ * `conn.transaction()` takes a callback, which cannot satisfy the explicit
+ * `beginTransaction`/`commitTransaction` contract, and issuing a bare `BEGIN` is not an option
+ * because over plain HTTP consecutive requests need not share a connection. Compat's session-backed
+ * transaction handle is the piece that makes it work.
+ */
+export declare class TursoQuerierPool extends AbstractHranaQuerierPool<TursoQuerier, TursoDialect> {
+    protected readonly ownsClient: boolean;
+    private readonly conf;
+    /**
+     * Accepts either connection settings or an already-built client. The latter covers any driver
+     * with the same shape: `@libsql/client/web`, `@libsql/client-wasm`, or a test double.
+     */
+    constructor(conf: TursoConfig | HranaClient, extra?: ExtraOptions);
+    protected openClient(): Promise<HranaClient>;
+    protected buildQuerier(client: HranaClient): TursoQuerier;
+}

package/dist/turso/tursoQuerierPool.js

@@ -0,0 +1,38 @@
+import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
+import { TursoDialect } from './tursoDialect.js';
+import { TursoQuerier } from './tursoQuerier.js';
+function isClient(conf) {
+    return typeof conf.execute === 'function';
+}
+/**
+ * Pool for remote Turso Cloud databases, driven by `@tursodatabase/serverless/compat`.
+ *
+ * @remarks The compat entry point is required rather than the native one: the native
+ * `conn.transaction()` takes a callback, which cannot satisfy the explicit
+ * `beginTransaction`/`commitTransaction` contract, and issuing a bare `BEGIN` is not an option
+ * because over plain HTTP consecutive requests need not share a connection. Compat's session-backed
+ * transaction handle is the piece that makes it work.
+ */
+export class TursoQuerierPool extends AbstractHranaQuerierPool {
+    ownsClient;
+    conf;
+    /**
+     * Accepts either connection settings or an already-built client. The latter covers any driver
+     * with the same shape: `@libsql/client/web`, `@libsql/client-wasm`, or a test double.
+     */
+    constructor(conf, extra) {
+        super(new TursoDialect({ namingStrategy: extra?.namingStrategy }), extra);
+        this.conf = conf;
+        this.ownsClient = !isClient(conf);
+    }
+    async openClient() {
+        if (isClient(this.conf)) {
+            return this.conf;
+        }
+        const { createClient } = await import('@tursodatabase/serverless/compat');
+        return createClient(this.conf);
+    }
+    buildQuerier(client) {
+        return new TursoQuerier(client, this.dialect, this.extra);
+    }
+}

package/dist/type/config.d.ts

@@ -1,6 +1,5 @@
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { ForeignKeyAction } from '../schema/types.js';
-import type { NamingStrategy } from './namingStrategy.js';
 import type { Querier } from './querier.js';
 import type { QuerierPool } from './querierPool.js';
 import type { Type } from './utility.js';
@@ -29,11 +28,6 @@ export interface Config {
      * @default 'uql_migrations'
      */
     tableName?: string;
-    /**
-     * The naming strategy for mapping class/property names to database table/column names.
-     * @default DefaultNamingStrategy (camelCase -> camelCase)
-     */
-    namingStrategy?: NamingStrategy;
     /**
      * Default action for foreign key ON DELETE and ON UPDATE clauses.
      * @default 'NO ACTION'

package/dist/type/dialect.d.ts

@@ -74,11 +74,11 @@ export interface EngineFeatures {
     /** Whether the dialect supports inline COMMENT on columns (MySQL/MariaDB). */
     readonly columnComment: boolean;
     /**
-     * How vector indexes are emitted: inline in CREATE TABLE (MySQL/MariaDB), a standalone
-     * `CREATE INDEX ... USING <type> (col opclass)` (Postgres/SQLite), or a standalone
-     * `CREATE VECTOR INDEX (col opclass)` with no access-method keyword (CockroachDB's native type).
+     * Whether a vector index is declared inline in `CREATE TABLE` (MySQL/MariaDB) rather than as its own
+     * `CREATE INDEX` statement. The statement's shape itself is the dialect's business, see
+     * `AbstractSqlDialect.getCreateIndexStatement`.
      */
-    readonly vectorIndexStyle: 'inline' | 'create' | 'native';
+    readonly inlineVectorIndex: boolean;
     /** Whether the dialect requires/allows (n) length constraints on vector types. */
     readonly vectorSupportsLength: boolean;
     /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
@@ -196,3 +196,11 @@ export interface SqlQueryDialect extends QueryDialect {
      */
     placeholder(index: number): string;
 }
+/**
+ * An index capability that some engines have and others reject outright. Verified live: expression
+ * indexes exist everywhere but MariaDB 12.3 (which needs a generated column); prefix lengths are
+ * MySQL-family only and *required* there to index `TEXT`; `NULLS FIRST/LAST` and operator classes are
+ * Postgres-only (CockroachDB 26.2 answers "unimplemented"); `INCLUDE` is Postgres-wire only.
+ */
+export type IndexFeature = 'expression' | 'prefixLength' | 'nullsOrder' | 'opsClass' | 'include';
+export declare const INDEX_FEATURE_LABELS: Record<IndexFeature, string>;

package/dist/type/dialect.js

@@ -1 +1,7 @@
-export {};
+export const INDEX_FEATURE_LABELS = {
+    expression: 'expression indexes',
+    prefixLength: 'index prefix lengths',
+    nullsOrder: 'NULLS FIRST/LAST in an index',
+    opsClass: 'index operator classes',
+    include: 'covering indexes (INCLUDE)',
+};