uql-orm 0.62.0 → 0.64.0

package/dist/bunSql/bunSql.util.d.ts

@@ -1,14 +1,13 @@
 import type { SQL } from 'bun';
 import type { PrimaryKey, RawRow } from '../type/index.js';
-export type BunSqlResult<T = RawRow> = T[] & {
+/** The header a `bun:sql` result carries next to its rows. */
+export type BunSqlHeader = {
     count?: number;
-    affectedRows?: number;
+    affectedRows?: number | null;
     lastInsertRowid?: PrimaryKey;
 };
-/**
- * The connection a {@link BunSqlQuerier} holds. `ReservedSQL` satisfies it as it is; the SQLite
- * adapter, which has no reservation, is given the pool's own handle with an inert `release`.
- */
+export type BunSqlResult<T = RawRow> = T[] & BunSqlHeader;
+/** The connection a {@link BunSqlQuerier} holds: what a `ReservedSQL` exposes of itself. */
 export type BunSqlConn = Pick<SQL, 'unsafe'> & {
     release(): void;
 };
@@ -17,24 +16,25 @@ export type BunSqlConn = Pick<SQL, 'unsafe'> & {
  * engine uql supports reaches it through a dedicated pool, and keeping this one total means Bun
  * gaining an adapter is a compile error here until the dialect is named.
  */
-export type BunSqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb' | 'sqlite';
+export type BunSqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb';
 /**
- * Rows a statement read or wrote, from whichever field this adapter fills: Postgres, CockroachDB and
- * SQLite report `count` and leave `affectedRows` null, MySQL and MariaDB the other way around - and
- * `count` is 0 on a MySQL write, so the two are read in that order rather than coalesced.
+ * Rows a statement read or wrote, from whichever field this adapter fills: Postgres and CockroachDB
+ * report `count` and leave `affectedRows` null, MySQL and MariaDB the other way around - and `count`
+ * is 0 on a MySQL write, so the two are read in that order rather than coalesced.
  *
  * `undefined` when the header carries neither, which leaves the returned rows to answer for it -
  * `buildUpdateResult` already falls back to their count, and it is the only one that should.
  */
 export declare function getAffectedRows(res: BunSqlResult): number | undefined;
 /**
- * Normalizes SQL.Options into a structure that Bun's SQL engine expects for a given dialect.
- * Crucially handles 'filename' mapping for SQLite and alias resolution for Cockroach/MariaDB.
+ * Normalizes `SQL.Options` into what Bun's SQL engine expects for a given dialect: the adapter a
+ * CockroachDB URL dials, and every BIGINT read as a `bigint` whatever the config asks, for
+ * `decodeBigInts` to decode exactly.
  */
-export declare function normalizeBunOpts(config: SQL.Options, dialectName: BunSqlDialectName): SQL.Options;
+export declare function normalizeBunOpts(config: SQL.Options, dialectName: BunSqlDialectName): SQL.PostgresOrMySQLOptions;
 /**
- * The engine a Bun `SQL.Options` points at: a SQLite file or `:memory:`, then the URL's scheme, then
- * the `adapter` Bun itself would read, and Postgres last - which is Bun's own fallback.
+ * The engine a Bun `SQL.Options` points at: the URL's scheme - a SQLite file or `:memory:` counting as
+ * `sqlite` - then the `adapter` Bun itself would read, and Postgres last, which is Bun's own fallback.
  */
 export declare function inferDialectName(config: SQL.Options): BunSqlDialectName;
 /** The id a MySQL-family insert reports, by the same wide-integer rule as every other BIGINT. */

package/dist/bunSql/bunSql.util.js

@@ -1,8 +1,8 @@
 import { decodeWideNumber } from '../util/wideNumber.js';
 /**
- * Rows a statement read or wrote, from whichever field this adapter fills: Postgres, CockroachDB and
- * SQLite report `count` and leave `affectedRows` null, MySQL and MariaDB the other way around - and
- * `count` is 0 on a MySQL write, so the two are read in that order rather than coalesced.
+ * Rows a statement read or wrote, from whichever field this adapter fills: Postgres and CockroachDB
+ * report `count` and leave `affectedRows` null, MySQL and MariaDB the other way around - and `count`
+ * is 0 on a MySQL write, so the two are read in that order rather than coalesced.
  *
  * `undefined` when the header carries neither, which leaves the returned rows to answer for it -
  * `buildUpdateResult` already falls back to their count, and it is the only one that should.
@@ -11,21 +11,13 @@ export function getAffectedRows(res) {
     return res.affectedRows || res.count || undefined;
 }
 /**
- * Normalizes SQL.Options into a structure that Bun's SQL engine expects for a given dialect.
- * Crucially handles 'filename' mapping for SQLite and alias resolution for Cockroach/MariaDB.
+ * Normalizes `SQL.Options` into what Bun's SQL engine expects for a given dialect: the adapter a
+ * CockroachDB URL dials, and every BIGINT read as a `bigint` whatever the config asks, for
+ * `decodeBigInts` to decode exactly.
  */
 export function normalizeBunOpts(config, dialectName) {
-    if (dialectName === 'sqlite') {
-        const rawFilename = ('filename' in config ? config.filename : null) || ('url' in config ? config.url : null) || ':memory:';
-        return {
-            ...config,
-            adapter: 'sqlite',
-            filename: rawFilename.toString(),
-        };
-    }
     const adapter = dialectName === 'cockroachdb' ? 'postgres' : dialectName;
-    // BIGINT as a `bigint`, so a wide one reaches uql exact for `decodeBigInts` to decode.
-    const opts = { bigint: true, ...config, adapter };
+    const opts = { ...config, adapter, bigint: true };
     if (!opts.url) {
         return opts;
     }
@@ -41,30 +33,24 @@ export function normalizeBunOpts(config, dialectName) {
     return opts;
 }
 /**
- * The engine a Bun `SQL.Options` points at: a SQLite file or `:memory:`, then the URL's scheme, then
- * the `adapter` Bun itself would read, and Postgres last - which is Bun's own fallback.
+ * The engine a Bun `SQL.Options` points at: the URL's scheme - a SQLite file or `:memory:` counting as
+ * `sqlite` - then the `adapter` Bun itself would read, and Postgres last, which is Bun's own fallback.
  */
 export function inferDialectName(config) {
-    if ('filename' in config && config.filename) {
-        return 'sqlite';
-    }
     const url = 'url' in config ? config.url?.toString() : undefined;
-    if (url) {
-        if (url === ':memory:' || url.endsWith('.db') || url.endsWith('.sqlite')) {
-            return 'sqlite';
-        }
-        const scheme = url.split(':')[0];
-        const elsewhere = ELSEWHERE.get(scheme);
+    const file = ('filename' in config && !!config.filename) || url === ':memory:' || /\.(db|sqlite)$/.test(url ?? '');
+    // Every Bun adapter name is a scheme here too, so the same two tables answer both.
+    for (const name of [file ? 'sqlite' : url?.split(':')[0], config.adapter]) {
+        const elsewhere = name && ELSEWHERE.get(name);
         if (elsewhere) {
-            throw new TypeError(`Bun SQL has no ${elsewhere} driver; use the dedicated uql-orm/${elsewhere} pool`);
+            throw new TypeError(`uql-orm/bunSql does not drive ${elsewhere}; use the dedicated uql-orm/${elsewhere} pool`);
         }
-        const dialect = SCHEMES.get(scheme);
+        const dialect = name && SCHEMES.get(name);
         if (dialect) {
             return dialect;
         }
     }
-    // Every Bun adapter name is a scheme here too, so the one table answers both questions.
-    return (config.adapter && SCHEMES.get(config.adapter)) || 'postgres';
+    return 'postgres';
 }
 /** A `Map` rather than an object literal, whose inherited keys would answer for a `constructor://` URL. */
 const SCHEMES = new Map([
@@ -73,18 +59,19 @@ const SCHEMES = new Map([
     ['mysql', 'mysql'],
     ['mysql2', 'mysql'],
     ['mariadb', 'mariadb'],
-    ['sqlite', 'sqlite'],
-    ['sqlite3', 'sqlite'],
     ['cockroachdb', 'cockroachdb'],
 ]);
 /**
- * Engines uql drives elsewhere but Bun cannot dial. Named rather than left out: Bun's `SQL` falls
- * back to Postgres for any scheme it does not know, so an unlisted `mssql://` would have connected
- * as Postgres and failed on the first statement instead of on the pool.
+ * Engines uql drives through another pool. Named rather than left out: Bun's `SQL` falls back to
+ * Postgres for any scheme it does not know, so an unlisted `mssql://` would have connected as Postgres
+ * and failed on the first statement instead of on the pool. SQLite runs on `Sqlite3QuerierPool`, which
+ * uses `bun:sqlite` under Bun.
  */
 const ELSEWHERE = new Map([
     ['mssql', 'mssql'],
     ['sqlserver', 'mssql'],
+    ['sqlite', 'sqlite'],
+    ['sqlite3', 'sqlite'],
 ]);
 /** The id a MySQL-family insert reports, by the same wide-integer rule as every other BIGINT. */
 export function getInsertId(res) {

package/dist/bunSql/bunSqlQuerier.d.ts

@@ -1,7 +1,7 @@
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import { type BunSqlConn } from './bunSql.util.js';
 /**
- * Querier for `bun:sql`, Bun's built-in driver for Postgres, MySQL, MariaDB, CockroachDB and SQLite.
+ * Querier for `bun:sql`, Bun's built-in driver for Postgres, MySQL, MariaDB and CockroachDB.
  *
  * @remarks Exposes no `SQL` of its own: the pool's would run a statement on any connection, outside
  * the transaction this one's reserved connection holds. Raw access is `pool.sql`.
@@ -14,7 +14,7 @@ export declare class BunSqlQuerier extends AbstractPoolQuerier<BunSqlConn> {
      *
      * Bun's `SQL.Query` is a `Promise` with no cursor or async-iterator API
      * ([oven-sh/bun#17181](https://github.com/oven-sh/bun/issues/17181)), so the rows have to be paged
-     * in SQL instead - which the Postgres wire family can do and MySQL and SQLite cannot.
+     * in SQL instead - which the Postgres wire family can do and MySQL cannot.
      */
     protected internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, any>;
     private execute;

package/dist/bunSql/bunSqlQuerier.js

@@ -3,7 +3,7 @@ import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import { decodeBigInts } from '../util/wideNumber.js';
 import { getAffectedRows, getInsertId } from './bunSql.util.js';
 /**
- * Querier for `bun:sql`, Bun's built-in driver for Postgres, MySQL, MariaDB, CockroachDB and SQLite.
+ * Querier for `bun:sql`, Bun's built-in driver for Postgres, MySQL, MariaDB and CockroachDB.
  *
  * @remarks Exposes no `SQL` of its own: the pool's would run a statement on any connection, outside
  * the transaction this one's reserved connection holds. Raw access is `pool.sql`.
@@ -18,7 +18,7 @@ export class BunSqlQuerier extends AbstractPoolQuerier {
             rows: Array.from(res, decodeBigInts),
             changes: getAffectedRows(res),
             id: getInsertId(res),
-            upsertStatus: res.affectedRows,
+            upsertStatus: res.affectedRows ?? undefined,
         });
     }
     /**
@@ -26,7 +26,7 @@ export class BunSqlQuerier extends AbstractPoolQuerier {
      *
      * Bun's `SQL.Query` is a `Promise` with no cursor or async-iterator API
      * ([oven-sh/bun#17181](https://github.com/oven-sh/bun/issues/17181)), so the rows have to be paged
-     * in SQL instead - which the Postgres wire family can do and MySQL and SQLite cannot.
+     * in SQL instead - which the Postgres wire family can do and MySQL cannot.
      */
     async *internalStream(query, values) {
         if (!this.dialect.features.serverSideCursors) {

package/dist/bunSql/bunSqlQuerierPool.d.ts

@@ -8,12 +8,7 @@ export declare class BunSqlQuerierPool extends AbstractSqlQuerierPool<BunSqlQuer
     readonly config: SQL.Options;
     readonly sql: SQL;
     readonly sqlDialectName: BunSqlDialectName;
-    private sqliteConfigured?;
-    /**
-     * @param config Bun's own `SQL.Options`, from which the engine is inferred. SQLite through here is
-     * deprecated: `Sqlite3QuerierPool` (`uql-orm/sqlite`) runs on `bun:sqlite` under Bun, and streams,
-     * loads extensions and prepares statements, none of which `bun:sql`'s SQLite adapter can.
-     */
+    /** @param config Bun's own `SQL.Options`, from which the engine is inferred. */
     constructor(config: SQL.Options, extra?: ExtraOptions);
     /**
      * Provides a pg-compatible interface for libraries like connect-pg-simple.
@@ -21,12 +16,5 @@ export declare class BunSqlQuerierPool extends AbstractSqlQuerierPool<BunSqlQuer
      */
     get pool(): SqlPoolCompat;
     getQuerier(): Promise<BunSqlQuerier>;
-    /**
-     * Bun's SQLite adapter does not support connection reservation (it's unpooled), so the pool hands out
-     * its one handle, configured like every other local SQLite connection on the first acquisition, and
-     * a `release` that does nothing: the handle is the pool's, and outlives every querier over it.
-     */
-    private acquire;
-    private configureSqlite;
     end(): Promise<void>;
 }

package/dist/bunSql/bunSqlQuerierPool.js

@@ -6,8 +6,6 @@ import { MySqlDialect } from '../mysql/mysqlDialect.js';
 import { PostgresDialect } from '../postgres/postgresDialect.js';
 import { POSTGRES_WIRE_DRIVER_CAPABILITIES } from '../postgres/postgresWireDriverCapabilities.js';
 import { AbstractSqlQuerierPool } from '../querier/index.js';
-import { SqliteDialect } from '../sqlite/sqliteDialect.js';
-import { SQLITE_PRAGMAS } from '../sqlite/sqlitePragmas.js';
 import { decodeBigInts } from '../util/wideNumber.js';
 import { getAffectedRows, inferDialectName, normalizeBunOpts, } from './bunSql.util.js';
 import { BunSqlQuerier } from './bunSqlQuerier.js';
@@ -24,30 +22,19 @@ const DialectMap = {
     cockroachdb: [CockroachDialect, POSTGRES_WIRE_DRIVER_CAPABILITIES],
     mysql: [MySqlDialect],
     mariadb: [MariaDialect],
-    sqlite: [SqliteDialect],
 };
-const SQLITE_DEPRECATION = 'SQLite through uql-orm/bunSql is deprecated; use Sqlite3QuerierPool from uql-orm/sqlite, which runs on bun:sqlite under Bun';
 export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
     config;
     sql;
     sqlDialectName;
-    sqliteConfigured;
-    /**
-     * @param config Bun's own `SQL.Options`, from which the engine is inferred. SQLite through here is
-     * deprecated: `Sqlite3QuerierPool` (`uql-orm/sqlite`) runs on `bun:sqlite` under Bun, and streams,
-     * loads extensions and prepares statements, none of which `bun:sql`'s SQLite adapter can.
-     */
+    /** @param config Bun's own `SQL.Options`, from which the engine is inferred. */
     constructor(config, extra) {
         const dialectName = inferDialectName(config);
         const [Dialect, driverCapabilities] = DialectMap[dialectName];
         super(new Dialect({ ...dialectOptionsFrom(extra), driverCapabilities }), extra);
         this.config = config;
         this.sqlDialectName = dialectName;
-        if (dialectName === 'sqlite') {
-            process.emitWarning(SQLITE_DEPRECATION, { type: 'DeprecationWarning', code: 'UQL_BUNSQL_SQLITE' });
-        }
-        const opts = normalizeBunOpts(config, dialectName);
-        this.sql = new SQL(opts);
+        this.sql = new SQL(normalizeBunOpts(config, dialectName));
     }
     /**
      * Provides a pg-compatible interface for libraries like connect-pg-simple.
@@ -65,25 +52,7 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
         };
     }
     async getQuerier() {
-        return new BunSqlQuerier(() => this.acquire(), this.dialect, this.extra);
-    }
-    /**
-     * Bun's SQLite adapter does not support connection reservation (it's unpooled), so the pool hands out
-     * its one handle, configured like every other local SQLite connection on the first acquisition, and
-     * a `release` that does nothing: the handle is the pool's, and outlives every querier over it.
-     */
-    async acquire() {
-        if (this.sqlDialectName !== 'sqlite') {
-            return this.sql.reserve();
-        }
-        this.sqliteConfigured ??= this.configureSqlite();
-        await this.sqliteConfigured;
-        return { unsafe: this.sql.unsafe.bind(this.sql), release: () => { } };
-    }
-    async configureSqlite() {
-        for (const pragma of SQLITE_PRAGMAS) {
-            await this.sql.unsafe(`PRAGMA ${pragma}`);
-        }
+        return new BunSqlQuerier(() => this.sql.reserve(), this.dialect, this.extra);
     }
     async end() {
         await this.sql.close();

package/dist/d1/d1Querier.d.ts

@@ -1,6 +1,6 @@
 import { AbstractSqliteQuerier } from '../sqlite/abstractSqliteQuerier.js';
 import type { SqliteDialect } from '../sqlite/sqliteDialect.js';
-import type { ExtraOptions } from '../type/index.js';
+import type { ExtraOptions, RawRow } from '../type/index.js';
 export interface D1Meta {
     duration?: number;
     size_after?: number;
@@ -25,6 +25,7 @@ export interface D1ExecResult {
 export interface D1PreparedStatement {
     bind(...values: unknown[]): D1PreparedStatement;
     first<T = unknown>(colName?: string): Promise<T | null>;
+    /** Documented by D1 as an alias of {@link all}: both answer the rows and `meta.changes`. */
     run<T = unknown>(): Promise<D1Result<T>>;
     all<T = unknown>(): Promise<D1Result<T>>;
     raw<T = unknown>(): Promise<T[]>;
@@ -35,12 +36,19 @@ export interface D1Database {
     batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
     exec(query: string): Promise<D1ExecResult>;
 }
-/** The only part of a D1 binding the querier uses; a full {@link D1Database} satisfies it. */
+/**
+ * The only part of a D1 binding the querier uses: what a {@link D1Database} and a session from
+ * `withSession()`, which a read-replicated database is read through, both have.
+ */
 export type D1Preparer = Pick<D1Database, 'prepare'>;
 export declare class D1Querier extends AbstractSqliteQuerier {
     readonly db: D1Preparer;
     readonly extra?: ExtraOptions | undefined;
     constructor(db: D1Preparer, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
-    internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
-    internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
+    protected execute(query: string, values?: unknown[]): Promise<{
+        rows: RawRow[];
+        changes: number;
+    }>;
+    /** D1 answers `BEGIN` with `D1_ERROR: not authorized`: a single statement is its only atomic unit. */
+    protected internalBegin(): Promise<void>;
 }

package/dist/d1/d1Querier.js

@@ -7,18 +7,13 @@ export class D1Querier extends AbstractSqliteQuerier {
         this.db = db;
         this.extra = extra;
     }
-    async internalAll(query, values) {
+    async execute(query, values) {
         const stmt = this.db.prepare(query);
-        const bound = values?.length ? stmt.bind(...values) : stmt;
-        const res = await bound.all();
-        return res.results;
+        const { results, meta } = await (values?.length ? stmt.bind(...values) : stmt).all();
+        return { rows: results, changes: meta.changes ?? 0 };
     }
-    async internalRun(query, values) {
-        const stmt = this.db.prepare(query);
-        const bound = values?.length ? stmt.bind(...values) : stmt;
-        const res = await bound.run();
-        const rows = res.results;
-        const changes = rows.length || res.meta?.changes || 0;
-        return this.buildUpdateResult({ rows, changes, id: res.meta?.last_row_id });
+    /** D1 answers `BEGIN` with `D1_ERROR: not authorized`: a single statement is its only atomic unit. */
+    async internalBegin() {
+        throw new TypeError('Cloudflare D1 has no transactions: write the changes as one statement, or idempotently');
     }
 }

package/dist/d1/d1QuerierPool.d.ts

@@ -1,10 +1,14 @@
 import { AbstractSqlQuerierPool } from '../querier/index.js';
 import type { ExtraOptions } from '../type/index.js';
-import { type D1Database, D1Querier } from './d1Querier.js';
+import { type D1Preparer, D1Querier } from './d1Querier.js';
 import { D1SqliteDialect } from './d1SqliteDialect.js';
+/**
+ * Pool for Cloudflare D1. It holds nothing: every querier runs on what it was given, `env.DB` or a
+ * session from `env.DB.withSession()`, the way a read-replicated database is read consistently.
+ */
 export declare class D1QuerierPool extends AbstractSqlQuerierPool<D1Querier, D1SqliteDialect> {
-    readonly db: D1Database;
-    constructor(db: D1Database, extra?: ExtraOptions);
+    readonly db: D1Preparer;
+    constructor(db: D1Preparer, extra?: ExtraOptions);
     getQuerier(): Promise<D1Querier>;
     end(): Promise<void>;
 }

package/dist/d1/d1QuerierPool.js

@@ -2,6 +2,10 @@ import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractSqlQuerierPool } from '../querier/index.js';
 import { D1Querier } from './d1Querier.js';
 import { D1SqliteDialect } from './d1SqliteDialect.js';
+/**
+ * Pool for Cloudflare D1. It holds nothing: every querier runs on what it was given, `env.DB` or a
+ * session from `env.DB.withSession()`, the way a read-replicated database is read consistently.
+ */
 export class D1QuerierPool extends AbstractSqlQuerierPool {
     db;
     constructor(db, extra) {
@@ -11,7 +15,5 @@ export class D1QuerierPool extends AbstractSqlQuerierPool {
     async getQuerier() {
         return new D1Querier(this.db, this.dialect, this.extra);
     }
-    async end() {
-        // no-op for D1 bindings
-    }
+    async end() { }
 }

package/dist/entity/decorator/entity.d.ts

@@ -1,4 +1,4 @@
-import type { EntityIndexOptions, EntityOptions, FieldKey, FilterOptions, IndexColumnInput, KeyMap, Type } from '../../type/index.js';
+import type { EntityIndexColumnInput, EntityIndexOptions, EntityOptions, FilterOptions, RefMap, Type } from '../../type/index.js';
 /**
  * Marks a class as an entity and finalizes its metadata.
  *
@@ -16,12 +16,8 @@ export declare function Entity<E>(opts?: EntityOptions<E>): (entity: Type<E>, co
  */
 export declare function Filter<E>(name: string, opts: FilterOptions<E>): (entity: Type<E>) => void;
 /**
- * Declares a composite index, its columns read off the key map. Stacks, so several may sit above one
- * class. `E` is inferred from the class the returned decorator is applied to, which is what types the
- * key map: `@Index((user) => [user.nope])` does not compile, and a rename reaches every column.
- *
- * @example `@Index((user) => [user.lastName, user.firstName], { name: 'users_fullname_idx' })`
- * @example `@Index((user) => [user.email], { unique: true })`
- * @example `@Index((user) => [user.email], { unique: true, where: { deletedAt: null } })`
+ * Declares a composite index, its columns read off the entity's refs, so `@Index((user) => [user.nope])`
+ * does not compile and a rename reaches every column. Stacks, so several may sit above one class.
+ * @example `@Index((user) => [user.lastName, raw`lower(${user.email})`], { unique: true })`
  */
-export declare function Index<E>(columns: (keys: KeyMap<E>) => readonly IndexColumnInput<FieldKey<E>, E>[], options?: EntityIndexOptions<E>): (entity: Type<E>) => void;
+export declare function Index<E>(columns: (refs: RefMap<E>) => readonly EntityIndexColumnInput<E>[], options?: EntityIndexOptions<E>): (entity: Type<E>) => void;

package/dist/entity/decorator/entity.js

@@ -28,13 +28,9 @@ export function Filter(name, opts) {
     };
 }
 /**
- * Declares a composite index, its columns read off the key map. Stacks, so several may sit above one
- * class. `E` is inferred from the class the returned decorator is applied to, which is what types the
- * key map: `@Index((user) => [user.nope])` does not compile, and a rename reaches every column.
- *
- * @example `@Index((user) => [user.lastName, user.firstName], { name: 'users_fullname_idx' })`
- * @example `@Index((user) => [user.email], { unique: true })`
- * @example `@Index((user) => [user.email], { unique: true, where: { deletedAt: null } })`
+ * Declares a composite index, its columns read off the entity's refs, so `@Index((user) => [user.nope])`
+ * does not compile and a rename reaches every column. Stacks, so several may sit above one class.
+ * @example `@Index((user) => [user.lastName, raw`lower(${user.email})`], { unique: true })`
  */
 export function Index(columns, options = {}) {
     return (entity) => {

package/dist/entity/metadata/definition.d.ts

@@ -11,8 +11,8 @@ export declare function defineRelation<E, T extends object>(entity: Type<E>, key
 export declare function relationRegistration<T extends object, O>({ mappedBy, references, ...opts }: RelationOptions<T, O>): RelationRegistration;
 export declare function defineHook<E>(entity: Type<E>, methodName: string, event: HookEvent): EntityMeta<E>;
 /**
- * Declares a composite index, its columns read off the key map. `unique` and the authored column sugar
- * are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
+ * Declares a composite index, its columns read off the entity's refs. `unique` and the authored column
+ * sugar are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
  */
 export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput<E>): EntityMeta<E>;
 export declare function defineFilter<E>(entity: Type<E>, name: string, opts: FilterOptions<E>): EntityMeta<E>;

package/dist/entity/metadata/definition.js

@@ -1,6 +1,6 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
 import { isInlinedExpression } from '../../util/field.util.js';
-import { entityName, entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, definedEntries, } from '../../util/index.js';
+import { entityName, entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, lowerFirst, memberRefs, normalizeIndexColumn, upperFirst, definedEntries, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 /**
  * A map held on `globalThis` through the global symbol registry, so a single one survives multiple
@@ -56,8 +56,8 @@ export function defineRelation(entity, key, opts) {
 export function relationRegistration({ mappedBy, references, ...opts }) {
     return {
         ...opts,
-        ...(mappedBy ? { mappedBy: mappedBy(keyMap()) } : {}),
-        ...(references ? { references: [...references(keyMap(), keyMap())] } : {}),
+        ...(mappedBy && { mappedBy: mappedBy(keyMap()) }),
+        ...(references && { references: [...references(keyMap(), keyMap())] }),
     };
 }
 /** Every entity's key map: a callback only reads one property off it, and that property is its own key. */
@@ -83,26 +83,22 @@ function addRelation(entity, key, registration) {
 }
 export function defineHook(entity, methodName, event) {
     const meta = ensureWritableMeta(entity);
-    if (!meta.hooks)
-        meta.hooks = {};
-    if (!meta.hooks[event])
-        meta.hooks[event] = [];
-    meta.hooks[event].push({ methodName });
+    ((meta.hooks ??= {})[event] ??= []).push({ methodName });
     return meta;
 }
 /**
- * Declares a composite index, its columns read off the key map. `unique` and the authored column sugar
- * are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
+ * Declares a composite index, its columns read off the entity's refs. `unique` and the authored column
+ * sugar are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
  */
 export function defineIndex(entity, index) {
     const meta = ensureWritableMeta(entity);
-    const keys = keyMap();
+    const refs = memberRefs();
     (meta.indexes ??= []).push({
         ...index,
         unique: index.unique ?? false,
         where: index.where && entityWhere(index.where),
-        columns: index.columns(keys).map(normalizeIndexColumn),
-        include: index.include?.(keys),
+        columns: index.columns(refs).map(normalizeIndexColumn),
+        include: index.include?.(refs).map((ref) => ref.key),
     });
     return meta;
 }
@@ -114,9 +110,7 @@ export function defineFilter(entity, name, opts) {
     if (opts.security && opts.onMissing === 'skip') {
         throw TypeError(`'${entity.name}' security filter '${name}' cannot use onMissing: 'skip' (it must fail closed)`);
     }
-    if (!meta.filters)
-        meta.filters = {};
-    meta.filters[name] = opts;
+    (meta.filters ??= {})[name] = opts;
     return meta;
 }
 /**
@@ -208,9 +202,7 @@ export function defineEntity(entity, opts = {}) {
     }
     if (softDeleteKeys.length) {
         meta.softDelete = softDeleteKeys[0];
-        if (!meta.filters)
-            meta.filters = {};
-        meta.filters[SOFT_DELETE_FILTER] = { where: { [meta.softDelete]: null }, default: true };
+        (meta.filters ??= {})[SOFT_DELETE_FILTER] = { where: { [meta.softDelete]: null }, default: true };
     }
     const ids = getIdKeys(meta);
     if (!ids.length) {
@@ -506,10 +498,9 @@ function extendMeta(target, source) {
     }
     // Merge hooks from parent entity (parent hooks execute first)
     if (source.hooks) {
-        if (!target.hooks)
-            target.hooks = {};
+        const hooks = (target.hooks ??= {});
         for (const [event, sourceList] of definedEntries(source.hooks)) {
-            target.hooks[event] = [...sourceList, ...(target.hooks[event] ?? [])];
+            hooks[event] = [...sourceList, ...(hooks[event] ?? [])];
         }
     }
 }

package/dist/libsql/libsqlDialect.d.ts

@@ -12,7 +12,7 @@ export declare class LibsqlDialect extends SqliteDialect {
      * functions this dialect would otherwise inherit are never present.
      *
      * @remarks `inner` and `l1` are left out: `vector_distance_dot` only exists in the newer Rust
-     * engine (see `TursoDialect`) and no libSQL build has an L1 metric. Both raise the same
+     * engine (see `TursoLocalDialect`) and no libSQL build has an L1 metric. Both raise the same
      * "does not support vector distance metric" error as any other unsupported metric.
      */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;

package/dist/libsql/libsqlDialect.js

@@ -11,7 +11,7 @@ export class LibsqlDialect extends SqliteDialect {
      * functions this dialect would otherwise inherit are never present.
      *
      * @remarks `inner` and `l1` are left out: `vector_distance_dot` only exists in the newer Rust
-     * engine (see `TursoDialect`) and no libSQL build has an L1 metric. Both raise the same
+     * engine (see `TursoLocalDialect`) and no libSQL build has an L1 metric. Both raise the same
      * "does not support vector distance metric" error as any other unsupported metric.
      */
     vectorMetrics = new Map([

package/dist/libsql/libsqlQuerierPool.d.ts

@@ -1,19 +1,28 @@
 import type { Config } from '@libsql/client';
+import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
 import { type HranaClient, HranaQuerier } from '../sqlite/hranaQuerier.js';
-import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
 import type { ExtraOptions } from '../type/index.js';
 import { LibsqlDialect } from './libsqlDialect.js';
-/** Embedded replica: local `file:` DB + `syncUrl` remote - DDL should run on the remote (sqld). */
-export declare function libsqlUseRemoteForMigrations(config: Pick<Config, 'url' | 'syncUrl'>): boolean;
-export declare class LibsqlQuerierPool extends AbstractHranaQuerierPool<LibsqlDialect> {
+/**
+ * Pool for libSQL. One client serves every querier, since Hrana keeps no per-connection state: a
+ * transaction takes its own session handle. The pool builds that client from `@libsql/client`'s
+ * `Config`, or shares one the caller built (`@libsql/client/web`, `@libsql/client-wasm`), which stays
+ * theirs to close.
+ */
+export declare class LibsqlQuerierPool extends AbstractSharedHandleQuerierPool<HranaClient, HranaQuerier, LibsqlDialect> {
     private readonly conf;
-    constructor(conf: Config, extra?: ExtraOptions);
-    protected openClient(): Promise<HranaClient>;
+    constructor(conf: Config | HranaClient, extra?: ExtraOptions);
+    protected openDb(): Promise<HranaClient>;
+    protected buildQuerier(client: HranaClient): HranaQuerier;
+    end(): Promise<void>;
     /**
-     * For embedded replicas (`file:` + `syncUrl`), returns a querier connected to `syncUrl` so migrations hit sqld.
-     * Otherwise same as `getQuerier`. The migrator calls this for `up`/`down`, `syncForce`, and `autoSync` DDL.
+     * For an embedded replica - a `file:` url with a `syncUrl` - a querier on the sync url, so migrations
+     * reach sqld, its client closing with it. Anything else migrates like any other querier.
      */
     getMigrationQuerier(): Promise<HranaQuerier>;
-    /** Imported on use, so `uql-orm/libsql` loads without the optional `@libsql/client` peer installed. */
+    /**
+     * Imported on use, so `uql-orm/libsql` loads without the optional `@libsql/client` peer installed.
+     * Integers read as `bigint` whatever the config asks, so the querier decodes one past 2^53 exactly.
+     */
     private createClient;
 }