uql-orm 0.22.0 → 0.24.0

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>;
 }

package/dist/sqlite/sqliteQuerierPool.js

@@ -1,34 +1,19 @@
-import { AbstractSqlQuerierPool } from '../querier/index.js';
-import { SqliteDialect } from './sqliteDialect.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 SqliteDialect({ 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 db = await this.openDriverDb(Object.keys(driverOpts).length > 0 ? driverOpts : undefined);
-        for (const extension of extensions ?? []) {
-            db.loadExtension(extension);
-        }
-        return db;
-    }
-    async openDriverDb(opts) {
+        const opts = Object.keys(driverOpts).length > 0 ? driverOpts : undefined;
         if (typeof Bun !== 'undefined') {
             const { Database: BunDatabase } = await import('bun:sqlite');
             const { adaptBunSqlite } = await import('./bunSqliteAdapter.bun.js');
@@ -41,8 +26,4 @@ export class Sqlite3QuerierPool extends AbstractSqlQuerierPool {
         db.pragma('journal_mode = WAL');
         return db;
     }
-    async end() {
-        await this.db?.close();
-        this.db = undefined;
-    }
 }

package/dist/type/entity.d.ts

@@ -175,14 +175,36 @@ export type JsonColumnType = 'json' | 'jsonb';
  * SQL binary/blob column types
  */
 export type BlobColumnType = 'blob' | 'bytea';
+/**
+ * SQL boolean column types
+ */
+export type BooleanColumnType = 'bool' | 'boolean';
+/**
+ * SQL vector column types
+ */
+export type VectorColumnType = 'vector' | 'halfvec' | 'sparsevec';
 /**
  * SQL column types supported by uql migrations
  */
-export type ColumnType = NumericColumnType | StringColumnType | DateColumnType | JsonColumnType | BlobColumnType | 'bool' | 'boolean' | 'vector' | 'halfvec' | 'sparsevec';
+export type ColumnType = NumericColumnType | StringColumnType | DateColumnType | JsonColumnType | BlobColumnType | BooleanColumnType | VectorColumnType;
 /**
  * Logical types for a field
  */
 export type FieldType = StringConstructor | NumberConstructor | BooleanConstructor | DateConstructor | BigIntConstructor | ColumnType;
+/**
+ * The {@link FieldType} values legal for a field declared as `V`.
+ *
+ * This is what makes an explicit `type` an improvement over the reflected one it replaces: the
+ * annotation is checked against the property's real TypeScript type, so `@Field({ type: String })` on
+ * a `number` no longer compiles into a silent TEXT column. `unknown` shapes fall through to the full
+ * {@link FieldType}, keeping genuinely untyped fields usable.
+ *
+ * JSON is matched on the `__json` brand rather than structurally, because {@link Json} intersects its
+ * payload (`Json<string>` really does extend `string`) and would otherwise land on the string arm.
+ * Both `Json<T>` and `Json<T>[]` have to be recognised, and the array check has to precede the scalar
+ * arms so a `number[]` vector is not read as a `number`.
+ */
+export type TypeFor<V, T = NonNullable<V>> = IsJson<T> extends true ? JsonColumnType : IsJson<NonNullable<Unpacked<T>>> extends true ? JsonColumnType : T extends readonly number[] ? VectorColumnType : T extends string ? StringConstructor | StringColumnType : T extends number ? NumberConstructor | NumericColumnType : T extends bigint ? BigIntConstructor | NumericColumnType : T extends boolean ? BooleanConstructor | BooleanColumnType : T extends Date ? DateConstructor | DateColumnType : T extends Uint8Array ? BlobColumnType : FieldType;
 /**
  * Configurable options for a field
  */
@@ -191,11 +213,13 @@ export type FieldOptions = {
     readonly isId?: true;
     readonly type?: FieldType;
     /**
-     * Set by `defineField` when `type` was inferred via reflection rather than
-     * given explicitly. Internal bookkeeping - do not set this from a decorator.
+     * Set by `defineField` when the field gave `references` but no `type`, so schema generation resolves
+     * the column from the referenced primary key rather than from whatever ended up in `type`. That is
+     * what keeps a `uuid` primary key from becoming TEXT on every foreign key pointing at it.
+     * Internal bookkeeping - do not set this from a decorator.
      * @internal
      */
-    readonly typeInferred?: boolean;
+    readonly typeFromReference?: boolean;
     /**
      * Dimensions for vector fields. Used in schema generation.
      * @example `@Field({ type: 'vector', dimensions: 1536 })`
@@ -270,6 +294,55 @@ export type FieldOptions = {
     readonly comment?: string;
 };
 export type OnFieldCallback = Scalar | QueryRaw | (() => Scalar | QueryRaw);
+/**
+ * The TypeScript types a field may be declared as, given the `type` it registers: the inverse of
+ * {@link TypeFor}.
+ *
+ * Both directions are needed because they are consumed at opposite ends. `defineEntity` keys its bulk
+ * `fields` by property name, so the property's type is already known and {@link TypeFor} narrows the
+ * `type` allowed. A decorator has it the other way round: `@Field({ type: String })` is checked before
+ * the class exists, so the only way to reach the property is to state what `type: String` implies and
+ * let the decorator's context position compare it against the real field. Neither can be derived from
+ * the other by inference, so `entityOptions.type-test.ts` asserts they agree instead.
+ */
+export type TsTypeOf<T> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BigIntConstructor ? bigint : T extends BooleanConstructor ? boolean : T extends DateConstructor ? Date : T extends StringColumnType ? string : T extends NumericColumnType ? number | bigint : T extends BooleanColumnType ? boolean : T extends DateColumnType ? Date : T extends JsonColumnType ? Json<unknown> | readonly Json<unknown>[] : T extends BlobColumnType ? Uint8Array : T extends VectorColumnType ? readonly number[] : unknown;
+/**
+ * {@link FieldOptions} for a field declared as `V`, with `type` required and checked by
+ * {@link TypeFor}.
+ *
+ * The second arm is load-bearing rather than a convenience: a foreign-key column may omit `type` so
+ * that schema generation resolves it from the referenced primary key instead, picking up that key's
+ * `columnType`, length and chained references. Forcing `type: Number` onto
+ * `@Field({ references: () => Company })` would silently downgrade a `uuid` key to TEXT on every
+ * column pointing at it.
+ */
+export type FieldOptionsFor<V> = (FieldOptions & {
+    readonly type: TypeFor<V>;
+}) | (FieldOptions & {
+    readonly references: EntityGetter;
+    readonly type?: TypeFor<V>;
+});
+/**
+ * The entity a relation field points at: `Company` for both `company?: Company` and
+ * `companies?: Company[]`.
+ */
+export type RelationTarget<V> = NonNullable<Unpacked<NonNullable<V>>>;
+/**
+ * {@link RelationOptions} for a relation field declared as `V`, with `entity` required and pinned to
+ * `V`'s own type, and the cardinality restricted to the ones that field shape can hold. Together those
+ * reject `@ManyToOne({ entity: () => Other })` on a `Company` field, and any to-many cardinality on a
+ * field that is not an array.
+ */
+export type RelationOptionsFor<V> = Omit<RelationOptions<RelationTarget<V>>, 'entity' | 'cardinality'> & {
+    readonly entity: EntityGetter<RelationTarget<V>>;
+    readonly cardinality: NonNullable<V> extends readonly unknown[] ? '1m' | 'mm' : '11' | 'm1';
+};
+/**
+ * The method names of an entity, so hook registrations name a method that exists.
+ */
+export type MethodKey<E> = {
+    readonly [K in keyof E]-?: NonNullable<E[K]> extends (...args: never[]) => unknown ? K : never;
+}[Key<E>];
 export type EntityGetter<E = any> = () => Type<E>;
 export type CascadeType = 'persist' | 'delete';
 export type RelationOptions<E = any> = {
@@ -299,20 +372,6 @@ export type RelationOneToOneOptions<E> = RelationOptionsOwner<E> | RelationOptio
 export type RelationOneToManyOptions<E> = RelationOptionsInverseSide<E> | RelationOptionsThroughOwner<E>;
 export type RelationManyToOneOptions<E> = RelationOptionsOwner<E>;
 export type RelationManyToManyOptions<E> = RelationOptionsThroughOwner<E> | RelationOptionsInverseSide<E>;
-/**
- * Wrapper type for relation type definitions in entities.
- * Used to circumvent ESM modules circular dependency issue caused by reflection metadata saving the type of the property.
- *
- * Usage example:
- * @Entity()
- * export default class User {
- *
- *     @OneToOne(() => Profile, profile => profile.user)
- *     profile: Relation<Profile>;
- *
- * }
- */
-export type Relation<T> = T;
 /**
  * Lifecycle hook event names.
  */
@@ -354,8 +413,12 @@ export type IndexTypeOptions = {
  * @Index([{ column: 'body', length: 64 }])                       // MySQL needs a prefix on TEXT
  * @Index(['data'], { type: 'gin' })                              // JSONB containment
  * ```
+ *
+ * `C` is the entity's `FieldKey` on the `@Index`/`defineEntity` paths, where the decorated class says
+ * which columns exist. It defaults to `string` for the migration builder's `table.index(...)`, which
+ * names raw table columns with no entity in scope.
  */
-export type IndexColumnInput = string | QueryRaw | IndexColumnOptions;
+export type IndexColumnInput<C extends string = string> = C | QueryRaw | IndexColumnOptions<C>;
 /**
  * What an index entry can carry besides the thing being indexed. Shared with the normalized
  * `IndexColumnSchema`, so the authored and internal shapes cannot drift apart.
@@ -373,9 +436,9 @@ export type IndexColumnModifiers = {
     /** Operator class, e.g. `jsonb_path_ops` for a smaller GIN index. Postgres only. */
     readonly opsClass?: string;
 };
-export type IndexColumnOptions = IndexColumnModifiers & {
+export type IndexColumnOptions<C extends string = string> = IndexColumnModifiers & {
     /** The column to index, or `raw(...)` for an expression. */
-    readonly column: string | QueryRaw;
+    readonly column: C | QueryRaw;
 };
 /**
  * One index entry, normalized: {@link IndexColumnInput}'s three authored shapes all reduce to this
@@ -439,11 +502,15 @@ export type EntityOptions<E = unknown> = {
     /** Named, default-on `$where` filters (soft-delete is auto-registered from `@Field({ softDelete })`). */
     readonly filters?: Record<string, FilterOptions<E>>;
     /** Scalar fields; use `isId: true` on exactly one field for the primary key. */
-    readonly fields?: Record<string, FieldOptions>;
-    readonly relations?: Record<string, RelationOptions>;
-    readonly indexes?: readonly EntityIndexInput[];
+    readonly fields?: {
+        readonly [K in FieldKey<E>]?: FieldOptionsFor<E[K]>;
+    };
+    readonly relations?: {
+        readonly [K in RelationKey<E>]?: RelationOptionsFor<E[K]>;
+    };
+    readonly indexes?: readonly EntityIndexInput<FieldKey<E>>[];
     /** Map hook events to method names on the entity class. */
-    readonly hooks?: Partial<Record<HookEvent, readonly string[]>>;
+    readonly hooks?: Partial<Record<HookEvent, readonly MethodKey<E>[]>>;
 };
 /**
  * Everything an index carries beyond its columns, shared by `@Index`, `defineEntity` and the
@@ -452,9 +519,9 @@ export type EntityOptions<E = unknown> = {
  */
 export type IndexOptions = DistributiveOmit<EntityIndexMeta, 'columns'>;
 /**
- * An index as authored, before {@link appendEntityIndex} normalizes its columns.
+ * An index as authored, before `defineIndex` normalizes its columns.
  */
-export type EntityIndexInput = IndexOptions & {
-    readonly columns: readonly IndexColumnInput[];
+export type EntityIndexInput<C extends string = string> = IndexOptions & {
+    readonly columns: readonly IndexColumnInput<C>[];
 };
 export {};

package/dist/type/querier.d.ts

@@ -1,11 +1,10 @@
 import type { Db } from 'mongodb';
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SqlDialectName } from './dialect.js';
-import type { HookEvent, IdValue, UpdatePayload } from './entity.js';
+import type { HookEvent } from './entity.js';
 import type { LoggingOptions } from './logger.js';
 import type { NamingStrategy } from './namingStrategy.js';
-import type { Query, QueryConflictPaths, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
-import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
+import type { Query, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
 import type { UniversalQuerier } from './universalQuerier.js';
 import type { Type } from './utility.js';
 /**
@@ -56,34 +55,6 @@ export interface Querier extends UniversalQuerier {
     count<E extends object>(q: QuerySearch<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
-    /**
-     * Insert a single record and return its ID (provided, `onInsert`-generated, or
-     * database-generated - see {@link Querier.insertMany} for the exact semantics).
-     * Returns `undefined` when the ID cannot be determined (e.g. MySQL/SQLite non-auto-increment
-     * keys in batches without explicit IDs).
-     */
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
-    /**
-     * Insert multiple records in a single statement (auto-chunked when the batch exceeds the
-     * dialect's bind-parameter limit) and return their IDs in payload order.
-     *
-     * Provided IDs and client-generated ones (`@Id({ onInsert })`) are always returned as-is.
-     * Database-generated IDs are exact on `'returning'` dialects (Postgres, MariaDB, MongoDB);
-     * on MySQL/SQLite they are inferred from the driver header, which is only reliable for
-     * auto-increment keys in batches without explicit IDs - otherwise those entries are
-     * `undefined` rather than potentially wrong values.
-     */
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
-    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
-     * entity has no soft-delete field.
-     */
-    restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;
-    restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
-    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
     /**
      * Delete many records (soft-deletes when the entity has a soft-delete field, else removes them).
      * Supports both entity-as-argument and entity-as-field patterns.
@@ -92,10 +63,6 @@ export interface Querier extends UniversalQuerier {
     deleteMany<E extends object>(q: QuerySearch<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
-    /**
-     * Run an aggregate query (GROUP BY with aggregate functions).
-     */
-    aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     /**
      * whether this querier is in a transaction or not.
      */
@@ -120,6 +87,12 @@ export interface Querier extends UniversalQuerier {
      * release the querier to the pool.
      */
     release(): Promise<void>;
+    /**
+     * Releases the querier when an `await using` binding goes out of scope, so a unit of work cannot
+     * leak a connection on an early return or a throw.
+     * @example `await using querier = await pool.getQuerier();`
+     */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 export interface SqlQuerier extends Querier {
     /**

package/dist/type/querierPool.d.ts

@@ -15,24 +15,25 @@ export interface PoolRunOptions {
 /**
  * Querier pool. Read the dialect id via `pool.dialect.dialectName` (see {@link AbstractDialect.dialectName}); queriers expose the same on `querier.dialect`.
  *
- * The read methods of {@link UniversalQuerier} are available directly on the pool. Each call
- * acquires its own querier, runs the single read, and releases it - so
- * `Promise.all([pool.findMany(A, {}), pool.count(B, {})])` runs on separate connections in
- * parallel, while the same calls inside one `withQuerier`/`transaction` callback share a pinned
- * connection and serialize. Single-connection backends (better-sqlite3, Bun sqlite, D1) stay
- * correct but always serialize on their one connection.
+ * A pool is a {@link UniversalQuerier} too, so a function that runs queries takes that type and the
+ * caller passes its own querier or the pool. `pool.op(...)` is exactly
+ * `pool.withQuerier((querier) => querier.op(...))`, so two pool calls are two units of work; when they
+ * must commit together, that is `transaction`.
  *
- * An enclosing `withContext` scopes the pool reads (`security` filters apply); one wrapper covers a
- * whole parallel fan-out, which is why the reads take no per-call `context` option (unlike
- * `withQuerier`/`transaction`).
+ * Acquiring per call is also what makes `Promise.all([pool.findMany(A, {}), pool.count(B, {})])` run on
+ * separate connections, while the same calls inside one `withQuerier`/`transaction` share a pinned
+ * connection and serialize. Single-connection backends (better-sqlite3, Bun sqlite, D1) stay correct
+ * but always serialize.
  *
- * Pool reads take the entity-as-argument form only. For the `{ $entity }` form, streaming, or
- * writes (they need a unit of work), use `withQuerier`/`transaction`.
+ * An enclosing `withContext` scopes pool calls (`security` filters apply), which is why they take no
+ * per-call `context` option (unlike `withQuerier`/`transaction`).
+ *
+ * Pool calls take the entity-as-argument form only; the `{ $entity }` form needs a querier.
  *
  * @typeParam Q - Querier implementation returned from the pool.
  * @typeParam D - Concrete dialect class held by the pool.
  */
-export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDialect = AbstractDialect> extends Pick<UniversalQuerier, 'findOneById' | 'findOne' | 'findMany' | 'findManyAndCount' | 'count' | 'aggregate'> {
+export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDialect = AbstractDialect> extends UniversalQuerier {
     /**
      * Database dialect instance (single source of truth for dialect id and SQL/NoSQL behavior).
      */