uql-orm 0.66.0 → 0.67.1

package/dist/mssql/mssqlWireTypes.d.ts

@@ -3,20 +3,8 @@ type ColumnTypes = Record<string, {
     readonly type: unknown;
 }>;
 /**
- * Decode `BIGINT` as a JS number, leaving every other type to the driver.
- *
- * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
- * `schema/canonicalType.ts`), and `tedious` hands that back as a string to protect the digits past
- * 2^53 - so without this a field declared `number` reads back as `'9'`, including every generated
- * primary key on every entity.
- *
- * At the wire, for the reason `pgNumericTypes` gives: everything crosses it exactly once - entity
- * reads, the ids an `OUTPUT` reports, raw SQL, counts, aggregates - where the ORM's own hydration
- * only ever sees entity reads.
- *
- * By the rule every driver here shares, `decodeWideNumber`: a number where one is exact, the driver's
- * exact text past 2^53. The lighter escape hatch for a column that big is the declaration -
- * `@Field({ type: String, columnType: 'bigint' })`.
+ * Decodes `BIGINT`, which `tedious` returns as text, by `decodeWideNumber`: `type: Number` maps to
+ * BIGINT, so otherwise every generated key reads back as a string. At the wire, which every result crosses.
  */
 export declare function decodeWireTypes<T>(rows: T[] | undefined, columns: ColumnTypes | undefined): T[];
 export {};

package/dist/mssql/mssqlWireTypes.js

@@ -1,19 +1,7 @@
 import { decodeWideNumber } from '../util/wideNumber.js';
 /**
- * Decode `BIGINT` as a JS number, leaving every other type to the driver.
- *
- * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
- * `schema/canonicalType.ts`), and `tedious` hands that back as a string to protect the digits past
- * 2^53 - so without this a field declared `number` reads back as `'9'`, including every generated
- * primary key on every entity.
- *
- * At the wire, for the reason `pgNumericTypes` gives: everything crosses it exactly once - entity
- * reads, the ids an `OUTPUT` reports, raw SQL, counts, aggregates - where the ORM's own hydration
- * only ever sees entity reads.
- *
- * By the rule every driver here shares, `decodeWideNumber`: a number where one is exact, the driver's
- * exact text past 2^53. The lighter escape hatch for a column that big is the declaration -
- * `@Field({ type: String, columnType: 'bigint' })`.
+ * Decodes `BIGINT`, which `tedious` returns as text, by `decodeWideNumber`: `type: Number` maps to
+ * BIGINT, so otherwise every generated key reads back as a string. At the wire, which every result crosses.
  */
 export function decodeWireTypes(rows, columns) {
     if (!rows?.length || !columns) {

package/dist/nestjs/uqlModule.js

@@ -43,13 +43,8 @@ import { UqlContextInterceptor } from './uqlContextInterceptor.js';
  */
 export const UQL_QUERIER_POOL = Symbol('UQL_QUERIER_POOL');
 /**
- * Ends the pool when Nest shuts down.
- *
- * @remarks A provider rather than a hook on the module class, and built through `useFactory` with an
- * `inject` list rather than constructor injection: Nest injects constructor parameters with a parameter
- * decorator, and the TC39 decorator spec has none, so `@Inject()` cannot appear in a file compiled
- * against it. Nest runs lifecycle hooks on providers too, so this keeps the pool that *this* module was
- * configured with instead of reaching for the global default.
+ * Ends the pool this module was configured with when Nest shuts down: a provider built by `useFactory`,
+ * since TC39 decorators have no parameter decorator for `@Inject()`.
  */
 class UqlPoolLifecycle {
     pool;

package/dist/pglite/pgliteQuerier.d.ts

@@ -1,15 +1,7 @@
 import type { PostgresDialect } from '../postgres/postgresDialect.js';
 import { AbstractSqlQuerier } from '../querier/index.js';
 import type { ExtraOptions } from '../type/index.js';
-/**
- * Structural subset of the `@electric-sql/pglite` API actually used here, declared locally so this
- * package does not couple its published types to a pre-1.0 dependency.
- *
- * @remarks This is what uql *consumes* from the driver, so it is two methods and stating them costs
- * nothing. `PglitePoolOptions` is the opposite case and imports PGlite's own type: those options are
- * the caller's input to the driver, so restating them would mean re-deriving its whole option surface
- * and then casting at the `PGlite.create` call.
- */
+/** The two methods uql uses of `@electric-sql/pglite`, stated so its published types do not depend on a pre-1.0 package. */
 export type PgliteDatabase = {
     query<T>(query: string, params?: unknown[]): Promise<{
         rows: T[];

package/dist/pglite/pgliteQuerierPool.d.ts

@@ -3,34 +3,12 @@ import { PostgresDialect } from '../postgres/postgresDialect.js';
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
 import type { ExtraOptions } from '../type/index.js';
 import { type PgliteDatabase, PgliteQuerier } from './pgliteQuerier.js';
-/**
- * The driver's own options, minus the `dataDir` this pool takes as its first argument.
- *
- * @remarks Imported rather than restated so extensions and the filesystem hooks keep their real types:
- * `extensions: { vector }` from `@electric-sql/pglite-pgvector` is how a vector column becomes usable,
- * mirroring `LocalSqlitePoolOptions.extensions` for `sqlite-vec`. Type-only, like the `pg` imports in
- * `abstractPgQuerierPool.ts`, so nothing here reaches a runtime without the peer installed.
- */
+/** PGlite's own options but `dataDir`, the pool's first argument; `extensions: { vector }` enables pgvector. Type-only. */
 export type PglitePoolOptions = Omit<PGliteOptions, 'dataDir'>;
 /**
- * Pool for PGlite, Postgres compiled to WASM and run in this process. No server, no container.
- *
- * PGlite is single connection, so the shared-handle lifecycle is {@link AbstractSharedHandleQuerierPool}'s.
- * Where PGlite differs from the two SQLite-family pools there is that it does not refuse a second
- * `BEGIN`: a querier that opens a transaction while another already has one silently joins it, and that
- * one's `ROLLBACK` then discards both queriers' writes. Nothing reports it, so a unit of work that needs
- * a transaction of its own needs its own pool, and therefore its own database.
- *
- * @remarks Transactions are plain `BEGIN`/`COMMIT` statements rather than `db.transaction()`, whose
- * callback holds PGlite's transaction mutex and would block every other querier's reads until commit.
- * The cost is that PGlite cannot see the transaction, so it flushes to the filesystem after each
- * statement within one: pass `relaxedDurability: true` on a persistent `dataDir` to skip waiting on
- * those flushes.
- *
- * The dialect is plain `PostgresDialect`, `dialectName` included: PGlite *is* Postgres, so the
- * introspector, schema generator and CLI resolve to Postgres's. Both driver capabilities hold as
- * they are - PGlite serializes every built-in array type itself, and the `$n::jsonb` cast is what
- * makes its `Describe` report JSONB and pick its JSON serializer; a bare `$n` binds `[object Object]`.
+ * A pool for PGlite, Postgres in WASM in this process, on one connection. A second `BEGIN` silently joins
+ * the open transaction, so a unit of work needing its own needs its own pool. Transactions are plain
+ * statements, so pass `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
  */
 export declare class PgliteQuerierPool extends AbstractSharedHandleQuerierPool<PgliteDatabase, PgliteQuerier, PostgresDialect> {
     readonly dataDir: string;

package/dist/pglite/pgliteQuerierPool.js

@@ -4,24 +4,9 @@ import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandle
 import { decodeWideNumber } from '../util/wideNumber.js';
 import { PgliteQuerier } from './pgliteQuerier.js';
 /**
- * Pool for PGlite, Postgres compiled to WASM and run in this process. No server, no container.
- *
- * PGlite is single connection, so the shared-handle lifecycle is {@link AbstractSharedHandleQuerierPool}'s.
- * Where PGlite differs from the two SQLite-family pools there is that it does not refuse a second
- * `BEGIN`: a querier that opens a transaction while another already has one silently joins it, and that
- * one's `ROLLBACK` then discards both queriers' writes. Nothing reports it, so a unit of work that needs
- * a transaction of its own needs its own pool, and therefore its own database.
- *
- * @remarks Transactions are plain `BEGIN`/`COMMIT` statements rather than `db.transaction()`, whose
- * callback holds PGlite's transaction mutex and would block every other querier's reads until commit.
- * The cost is that PGlite cannot see the transaction, so it flushes to the filesystem after each
- * statement within one: pass `relaxedDurability: true` on a persistent `dataDir` to skip waiting on
- * those flushes.
- *
- * The dialect is plain `PostgresDialect`, `dialectName` included: PGlite *is* Postgres, so the
- * introspector, schema generator and CLI resolve to Postgres's. Both driver capabilities hold as
- * they are - PGlite serializes every built-in array type itself, and the `$n::jsonb` cast is what
- * makes its `Describe` report JSONB and pick its JSON serializer; a bare `$n` binds `[object Object]`.
+ * A pool for PGlite, Postgres in WASM in this process, on one connection. A second `BEGIN` silently joins
+ * the open transaction, so a unit of work needing its own needs its own pool. Transactions are plain
+ * statements, so pass `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
  */
 export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
     dataDir;

package/dist/postgres/abstractPgQuerierPool.d.ts

@@ -7,14 +7,7 @@ export interface PgAnyPool<C extends PgAnyClient> extends ErrorEmittingPool {
     connect: () => Promise<C>;
     end: () => Promise<void>;
 }
-/**
- * Shared base class for Postgres-compatible querier pools. Each hands out a {@link PgQuerier} over its
- * driver's client, so a subclass supplies only the dialect and the driver's pool.
- *
- * Wires the crash-preventing error handler here, once, so a new pg-compatible pool subclass can't be
- * added without it - the constructor takes the already constructed pool and attaches the handler
- * unconditionally.
- */
+/** A Postgres-wire pool of {@link PgQuerier}s, attaching the error handler that keeps a dropped connection from crashing the process. */
 export declare abstract class AbstractPgQuerierPool<C extends PgAnyClient, D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<PgQuerier<C>, D> {
     readonly pool: PgAnyPool<C>;
     constructor(dialect: D, pool: PgAnyPool<C>, extra?: ExtraOptions);

package/dist/postgres/abstractPgQuerierPool.js

@@ -1,14 +1,7 @@
 import { AbstractSqlQuerierPool } from '../querier/index.js';
 import { attachPoolErrorHandler } from '../util/index.js';
 import { PgQuerier } from './pgQuerier.js';
-/**
- * Shared base class for Postgres-compatible querier pools. Each hands out a {@link PgQuerier} over its
- * driver's client, so a subclass supplies only the dialect and the driver's pool.
- *
- * Wires the crash-preventing error handler here, once, so a new pg-compatible pool subclass can't be
- * added without it - the constructor takes the already constructed pool and attaches the handler
- * unconditionally.
- */
+/** A Postgres-wire pool of {@link PgQuerier}s, attaching the error handler that keeps a dropped connection from crashing the process. */
 export class AbstractPgQuerierPool extends AbstractSqlQuerierPool {
     pool;
     constructor(dialect, pool, extra) {

package/dist/postgres/pgNumericTypes.d.ts

@@ -10,32 +10,9 @@ type PgTypes = {
     getTypeParser(oid: number, format?: 'text' | 'binary'): (value: string) => unknown;
 };
 /**
- * Decode `INT8` and `FLOAT8`, leaving every other type to the driver: an INT8 by `decodeWideNumber` - a
- * number where one is exact, its exact text past 2^53 - and a FLOAT8 as the float64 it already is.
- *
- * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
- * `schema/canonicalType.ts`), so without it a field declared `number` read back as `'9'` - including
- * every auto-increment primary key, on every entity. `FLOAT8` is a float64, which is exactly what a
- * JS number is, so decoding it loses nothing at all.
- *
- * At the driver because everything crosses the wire decoder exactly once - entity reads, `RETURNING
- * id`, raw SQL, counts, aggregates - while the ORM's hydration only ever sees entity reads. Which
- * types belong here and which need the entity's declaration is settled in `hydratableFields`.
- *
- * `NUMERIC` is deliberately absent, and decoded in hydration instead: `type: BigInt` also maps to
- * BIGINT, so a blanket decode here is already as far as a driver can go without the declaration. That
- * split also covers mysql2, which returns DECIMAL as text and has no equivalent hook.
- *
- * Per pool, never global, which is the whole reason this takes `types` as an argument. TypeORM does
- * the same job by assigning `postgres.defaults.parseInt8`, a module-wide flag every pool in the
- * process then shares; MikroORM passes a per-pool `TypeOverrides`, as here. Two globals of exactly
- * that shape have already been deleted from this repo - `test/pgTypeParsers.util.ts` and the
- * `types.setTypeParser` calls in `neon/neonQuerier.test.ts` - and both made the suite pass on
- * behaviour the library never shipped. Do not reintroduce one.
- *
- * A caller's own `types` in the pool options are spread after this one and therefore win. For a
- * decimal, the lighter escape hatch is the declaration itself: `@Field({ type: String, columnType:
- * 'decimal' })` keeps the column DECIMAL while leaving the value as the exact text the driver returned.
+ * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
+ * BIGINT. At the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field.
+ * Per pool, never a global parser, and a caller's own `types` win.
  */
 export declare function numericTypes(types: PgTypes): CustomTypesConfig;
 export {};

package/dist/postgres/pgNumericTypes.js

@@ -1,31 +1,8 @@
 import { decodeWideNumber } from '../util/wideNumber.js';
 /**
- * Decode `INT8` and `FLOAT8`, leaving every other type to the driver: an INT8 by `decodeWideNumber` - a
- * number where one is exact, its exact text past 2^53 - and a FLOAT8 as the float64 it already is.
- *
- * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
- * `schema/canonicalType.ts`), so without it a field declared `number` read back as `'9'` - including
- * every auto-increment primary key, on every entity. `FLOAT8` is a float64, which is exactly what a
- * JS number is, so decoding it loses nothing at all.
- *
- * At the driver because everything crosses the wire decoder exactly once - entity reads, `RETURNING
- * id`, raw SQL, counts, aggregates - while the ORM's hydration only ever sees entity reads. Which
- * types belong here and which need the entity's declaration is settled in `hydratableFields`.
- *
- * `NUMERIC` is deliberately absent, and decoded in hydration instead: `type: BigInt` also maps to
- * BIGINT, so a blanket decode here is already as far as a driver can go without the declaration. That
- * split also covers mysql2, which returns DECIMAL as text and has no equivalent hook.
- *
- * Per pool, never global, which is the whole reason this takes `types` as an argument. TypeORM does
- * the same job by assigning `postgres.defaults.parseInt8`, a module-wide flag every pool in the
- * process then shares; MikroORM passes a per-pool `TypeOverrides`, as here. Two globals of exactly
- * that shape have already been deleted from this repo - `test/pgTypeParsers.util.ts` and the
- * `types.setTypeParser` calls in `neon/neonQuerier.test.ts` - and both made the suite pass on
- * behaviour the library never shipped. Do not reintroduce one.
- *
- * A caller's own `types` in the pool options are spread after this one and therefore win. For a
- * decimal, the lighter escape hatch is the declaration itself: `@Field({ type: String, columnType:
- * 'decimal' })` keeps the column DECIMAL while leaving the value as the exact text the driver returned.
+ * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
+ * BIGINT. At the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field.
+ * Per pool, never a global parser, and a caller's own `types` win.
  */
 export function numericTypes(types) {
     // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.

package/dist/postgres/postgresDialect.d.ts

@@ -1,17 +1,11 @@
 import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
-import type { QueryConflictPaths, QueryContext, SqlDialectName, Type } from '../type/index.js';
-/**
- * PostgreSQL dialect, the same class under every Postgres driver - `pg`, Neon, PGlite, `bun:sql` -
- * where a driver that binds differently passes `driverCapabilities` rather than subclassing it.
- * Shared Postgres-wire AST/quoting/JSONB/full-text-search/vector-search logic (including BIGINT
- * IDENTITY PKs) lives in {@link PgLikeSqlDialect}; this class adds what's Postgres-only: the `vector`
- * extension requirement, pgvector's index syntax, and `xmax`-based upsert `created` detection.
- */
+import type { QueryConflictPaths, QueryContext, SqlDialectFeatures, SqlDialectName, Type } from '../type/index.js';
+/** PostgreSQL, under every driver: `pg`, Neon, PGlite, `bun:sql`. Adds pgvector and the `xmax` upsert `created`. */
 export declare class PostgresDialect extends PgLikeSqlDialect {
     readonly dialectName: SqlDialectName;
     readonly vectorExtension: string | undefined;
-    /** pgvector is the only engine with `halfvec` and `sparsevec`; every other maps them onto `vector`. */
-    protected readonly hasNarrowVectorTypes = true;
+    /** pgvector is the only engine with `halfvec` and `sparsevec`. */
+    readonly features: SqlDialectFeatures;
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     /**
      * `to_regclass` rather than a `::regclass` cast: it answers `NULL` for a table that does not exist

package/dist/postgres/postgresDialect.js

@@ -1,18 +1,12 @@
 import { COUNT_ALIAS } from '../dialect/aliases.js';
-import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
+import { PG_FEATURES, PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
-/**
- * PostgreSQL dialect, the same class under every Postgres driver - `pg`, Neon, PGlite, `bun:sql` -
- * where a driver that binds differently passes `driverCapabilities` rather than subclassing it.
- * Shared Postgres-wire AST/quoting/JSONB/full-text-search/vector-search logic (including BIGINT
- * IDENTITY PKs) lives in {@link PgLikeSqlDialect}; this class adds what's Postgres-only: the `vector`
- * extension requirement, pgvector's index syntax, and `xmax`-based upsert `created` detection.
- */
+/** PostgreSQL, under every driver: `pg`, Neon, PGlite, `bun:sql`. Adds pgvector and the `xmax` upsert `created`. */
 export class PostgresDialect extends PgLikeSqlDialect {
     dialectName = 'postgres';
     vectorExtension = 'vector';
-    /** pgvector is the only engine with `halfvec` and `sparsevec`; every other maps them onto `vector`. */
-    hasNarrowVectorTypes = true;
+    /** pgvector is the only engine with `halfvec` and `sparsevec`. */
+    features = { ...PG_FEATURES, narrowVectorTypes: true };
     upsert(ctx, entity, conflictPaths, payload) {
         // The xmax system column is 0 for a newly inserted row and non-zero for an updated one (MVCC).
         super.upsert(ctx, entity, conflictPaths, payload, `(xmax = 0) AS ${this.escapeId('_created')}`);

package/dist/querier/abstractQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 /** Base class for all database queriers. */
 export declare abstract class AbstractQuerier implements Querier {
@@ -18,28 +18,17 @@ export declare abstract class AbstractQuerier implements Querier {
     constructor(extra?: ExtraOptions | undefined);
     protected validateProjectionQuery<E extends object>(entity: Type<E>, q: Query<E>): void;
     private validateProjectionQueryRecursive;
-    /**
-     * Resolves `[entity, query, opts]` for the dual call pattern: `(entity, q, opts)` (entity argument)
-     * vs `(query, opts)` (entity via the query's `$entity` field). Generic in the query `Q` because it
-     * only ever reads `$entity`: pinning it to one statement's shape made every caller launder its own
-     * through a cast, which is how a read query's `$sort` used to reach a write's.
-     */
+    /** `[entity, query, opts]` from either call form, `(entity, q, opts)` or `({ $entity, ...q }, opts)`. */
     protected resolveEntityQuery<E extends object, Q extends object>(entityOrQuery: Type<E> | (Q & {
         $entity: Type<E>;
     }), maybeQueryOrOpts?: Q | QueryOptions, maybeOpts?: QueryOptions): [Type<E>, Q, QueryOptions | undefined];
     findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, id: EntityId<E>, q?: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
-    /**
-     * Find a single record matching the query.
-     * Supports both entity-as-argument and entity-as-field patterns.
-     */
+    /** Find one record, the entity passed first or as the query's `$entity`. */
     findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryOneProjected<E, S, V, X, P, C> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
     findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
-    /**
-     * Find multiple records matching the query.
-     * Supports both entity-as-argument and entity-as-field patterns.
-     */
+    /** Find many records, the entity passed first or as the query's `$entity`. */
     findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
@@ -49,20 +38,13 @@ export declare abstract class AbstractQuerier implements Querier {
      * or pipeline. [The design](../../../../architecture/relations-in-one-statement.md).
      */
     protected abstract internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
-    /**
-     * Stream records as an async iterable, in both the entity-as-argument and entity-as-field patterns.
-     * Each row streams with its populated relations and counts, read by the same statement or pipeline
-     * `findMany` runs. No `afterLoad` hooks on streamed rows.
-     */
+    /** Stream records with the relations and counts `findMany` reads, the entity passed first or as `$entity`. No hooks fire. */
     findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
     findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
     protected abstract internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncIterable<E>;
-    /**
-     * Find multiple records and return both the records and total count.
-     * Supports both entity-as-argument and entity-as-field patterns.
-     */
+    /** Find many records and count every match, the entity passed first or as the query's `$entity`. */
     findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
@@ -72,20 +54,14 @@ export declare abstract class AbstractQuerier implements Querier {
      * backend with no way to answer both at once is left with; SQL overrides it to answer from one.
      */
     protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
-    /**
-     * Count records matching the query, in both the entity-as-argument and entity-as-field patterns.
-     * A `$skip`/`$limit` settles the matching ids and counts those, rather than scanning every match;
-     * `$sort` never reaches that SELECT, since it changes which rows a page holds, never how many.
-     */
+    /** Count records matching the query, the entity passed first or as the query's `$entity`. */
     count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: QueryOptions): Promise<number>;
     count<E extends object>(q: QueryPage<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
-    protected abstract internalCount<E extends object>(entity: Type<E>, q: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * Whether anything matches, in both the entity-as-argument and entity-as-field patterns. A count
-     * capped at one row, so the engine stops at the first match instead of scanning every other one.
-     */
+    /** How many rows match, or how many of them a page takes: counted where they are, never read. */
+    protected abstract internalCount<E extends object>(entity: Type<E>, q: QueryPage<E>, opts?: QueryOptions): Promise<number>;
+    /** Whether anything matches, the entity passed first or as `$entity`: a count capped at one row. */
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;
     exists<E extends object>(q: QueryFilter<E> & {
         $entity: Type<E>;
@@ -106,38 +82,30 @@ export declare abstract class AbstractQuerier implements Querier {
     /** Writes `rows`, and onto each one the key the database generated for it, where it can tell. */
     protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
+    private updateColumns;
+    /** Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or delete. */
+    protected settlesWrite<E extends object>(_entity: Type<E>, q: QuerySearch<E>): boolean;
+    /** The ids `q` matches, in its own order and page. */
+    protected settleIds<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<EntityId<E>[]>;
+    /** Runs one UPDATE over `q`, which names its rows by id wherever {@link updateMany} settled them. */
     protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
     restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
-    /**
-     * `beforeUpsert`/`afterUpsert` rather than the insert's or the update's pair: the database decides
-     * which branch each row takes as the statement runs, so neither of those could be fired honestly -
-     * but the upsert itself is a fact known before and after, and a row written with no hook at all
-     * was how an `@Id({ onInsert })` or an audit trail silently skipped this path.
-     */
+    /** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
     protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * Delete records matching the query. Soft-deletes when the entity has a soft-delete field (unless
-     * `opts.hardDelete`), otherwise removes the rows. Supports both entity-as-argument and entity-as-field patterns.
-     */
+    /** Delete records matching the query, the entity passed first or as `$entity`; soft-deletes unless `opts.hardDelete`. */
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(q: QuerySearch<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
-    /**
-     * The rows a delete is about to take, loaded only when a hook or listener is there to receive
-     * them: the round trip is pure overhead for the (common) delete nobody is watching, and
-     * `internalDeleteMany` has its own fast path that never reads the rows at all.
-     *
-     * `undefined` means nobody was watching, which is not the same as the empty array meaning nothing
-     * matched - the caller deletes by `q` for the first and skips the statement entirely for the second.
-     */
-    private findDoomed;
+    /** Runs one DELETE (or soft-delete stamp) over `q`, which names its rows by id wherever {@link deleteMany} settled them. */
     protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
     /**
@@ -146,39 +114,21 @@ export declare abstract class AbstractQuerier implements Querier {
      * inserts. A composite is always named. The hooks follow the statement: a named row fires the upsert pair.
      */
     saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
-    protected insertRelations<E extends object>(entity: Type<E>, payload: E[]): Promise<void>;
-    protected updateRelations<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<void>;
+    /** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
+    protected insertRelations<E extends object>(entity: Type<E>, rows: E[]): Promise<void>;
+    /** `EntityId` because a settled composite row is an object, which {@link childrenOf} reads each foreign key column out of. */
+    private deleteRelations;
     /**
-     * `EntityId` because a settled set names composite rows as objects, which is also what the parent's
-     * own delete takes - and what {@link childrenOf} reads each child's foreign key columns out of.
+     * Writes each parent's value into one relation. The parent owns what it points at: an update replaces
+     * it, and a `null` only clears it.
      */
-    protected deleteRelations<E extends object>(entity: Type<E>, ids: EntityId<E>[], opts?: QueryOptions): Promise<void>;
-    /**
-     * Persists `relValue` against every id in `ids`, which an update hands the whole page of rows it
-     * settled: the value is the same for all of them, so the statements are per relation rather than per
-     * row wherever the cardinality allows it.
-     */
-    protected saveRelation<E extends object>(entity: Type<E>, ids: IdValue<E>[], relValue: unknown, relKey: RelationKey<E>, isUpdate?: boolean): Promise<void>;
-    private saveToMany;
-    private saveOneToOne;
+    private saveRelation;
+    /** Each parent gets its own referenced row, and its own column pointing at it. */
     private saveManyToOne;
     abstract readonly hasOpenTransaction: boolean;
     /**
-     * Runs `callback` in a transaction: begin, commit on success, roll back on failure.
-     *
-     * The single place that sequence is written; everything else delegates here, because both subtleties
-     * below were got wrong by code that hand-rolled it:
-     *
-     * - `beginTransaction` connects before it begins, so a refused connection lands in the catch with no
-     *   transaction open. `rollbackTransaction` is a no-op there rather than an error, which is why a
-     *   wrong password no longer surfaces as a transaction-state error.
-     * - A rollback that fails too is a consequence of the original failure, not news, so it must not
-     *   replace it either.
-     *
-     * The connection is **not** released here: whoever took it from the pool gives it back, through
-     * {@link QuerierPool.transaction}, {@link QuerierPool.withQuerier} or `await using`. Releasing a
-     * connection this method never acquired is what forced every caller to know whether it still owned
-     * one afterwards.
+     * Runs `callback` in a transaction, joining one already open. A rollback that fails is logged, never
+     * thrown over the original error, and the connection stays with whoever acquired it.
      */
     transaction<T>(callback: () => Promise<T>, opts?: TransactionOptions): Promise<T>;
     /** Whether anything at all - a global listener or the entity itself - handles `event`. */
@@ -205,23 +155,9 @@ export declare abstract class AbstractQuerier implements Querier {
     private hooked;
     /** Fires the global listeners first, then the entity's own hooks. */
     private emitHook;
-    /**
-     * Runs `task` after everything already queued on this querier, one at a time.
-     *
-     * @remarks Not re-entrant: only one task runs at a time, so a serialized method awaited from inside
-     * another one would wait for a task queued behind itself. Callers below keep their `serialize` calls
-     * sequential rather than nested.
-     */
+    /** Runs `task` after everything already queued, one at a time. Not re-entrant: never nest `serialize` calls. */
     protected serialize<T>(task: () => Promise<T>): Promise<T>;
-    /**
-     * Runs `task`, logs `query` with how long it took, and tags any error it throws with that query.
-     *
-     * A method rather than the `@Log()` decorator it replaces. A standard-spec method decorator works by
-     * returning a replacement function, and a replacement cannot carry the original's type parameters, so
-     * decorating `internalFindMany<E extends Document>` made its signature unresolvable. Most of the query
-     * surface is generic like that, and wrapping at the call site costs one line while keeping the
-     * signature intact.
-     */
+    /** Runs `task`, logs `query` with its duration, and tags a failure with it: a method, since a decorator would lose the generics. */
     protected timed<T>(query: string, values: unknown[] | undefined, task: () => Promise<T>): Promise<T>;
     abstract beginTransaction(opts?: TransactionOptions): Promise<void>;
     /** Strict: this is the check that catches a forgotten `beginTransaction`. */
@@ -232,12 +168,8 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     abstract rollbackTransaction(): Promise<void>;
     /**
-     * Rolls back an unfinished transaction, then hands the connection back.
-     *
-     * @remarks Refusing to release was the opposite of safe: the throw came *before* the connection went
-     * back, so it destroyed the error that got here and cost the pool a connection with a live `BEGIN` on
-     * it. It is also the only option `await using` can reach, which calls `Symbol.asyncDispose` with no
-     * arguments and discards what it returns.
+     * Rolls back an unfinished transaction, then hands the connection back, discarding it if the rollback
+     * failed. Never throws first, since `await using` has no other way to release.
      */
     release(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;