uql-orm 0.53.0 → 0.55.0

package/dist/postgres/pgQuerier.js

@@ -1,3 +1,30 @@
-import { AbstractPgQuerier } from './abstractPgQuerier.js';
-export class PgQuerier extends AbstractPgQuerier {
+import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
+/**
+ * Querier for every client with node-postgres' API: `pg` itself, for Postgres and CockroachDB, and
+ * Neon's serverless driver. Generic over the client alone - the dialect is whichever the pool built.
+ */
+export class PgQuerier extends AbstractPoolQuerier {
+    async internalAll(query, values) {
+        const res = await this.getConn().query(query, values);
+        return res.rows;
+    }
+    async internalRun(query, values) {
+        const res = await this.getConn().query(query, values);
+        return this.buildUpdateResult({ rows: res.rows, changes: res.rowCount ?? 0 });
+    }
+    async *internalStream(query, values) {
+        const { default: QueryStream } = await import('pg-query-stream');
+        const stream = this.getConn().query(new QueryStream(query, values));
+        try {
+            for await (const row of stream) {
+                yield row;
+            }
+        }
+        finally {
+            stream.destroy();
+        }
+    }
+    async releaseConn(conn, discard) {
+        await conn.release(discard);
+    }
 }

package/dist/postgres/pgQuerierPool.d.ts

@@ -1,10 +1,8 @@
 import { Pool, type PoolClient, type PoolConfig } from 'pg';
 import type { ExtraOptions } from '../type/index.js';
 import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
-import { PgDialect } from './pgDialect.js';
-import { PgQuerier } from './pgQuerier.js';
-export declare class PgQuerierPool extends AbstractPgQuerierPool<PoolClient, PgQuerier, PgDialect> {
+import { PostgresDialect } from './postgresDialect.js';
+export declare class PgQuerierPool extends AbstractPgQuerierPool<PoolClient, PostgresDialect> {
     readonly pool: Pool;
     constructor(opts: PoolConfig, extra?: ExtraOptions);
-    protected buildQuerier(connect: () => Promise<PoolClient>): PgQuerier;
 }

package/dist/postgres/pgQuerierPool.js

@@ -1,16 +1,12 @@
 import { Pool, types } from 'pg';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
-import { PgDialect } from './pgDialect.js';
 import { numericTypes } from './pgNumericTypes.js';
-import { PgQuerier } from './pgQuerier.js';
+import { PostgresDialect } from './postgresDialect.js';
 export class PgQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // keepAlive reduces (but can't eliminate) idle connections being silently
         // dropped by NATs/firewalls on long-lived remote connections.
-        super(new PgDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
-    }
-    buildQuerier(connect) {
-        return new PgQuerier(connect, this.dialect, this.extra);
+        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
     }
 }

package/dist/postgres/postgresDialect.d.ts

@@ -1,11 +1,11 @@
 import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
 import type { QueryConflictPaths, QueryContext, SqlDialectName, Type } from '../type/index.js';
 /**
- * PostgreSQL dialect. For node-pg use PgDialect. Neon, Bun SQL, and Cockroach use driver-specific
- * subclasses. 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 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.
  */
 export declare class PostgresDialect extends PgLikeSqlDialect {
     readonly dialectName: SqlDialectName;

package/dist/postgres/postgresDialect.js

@@ -2,11 +2,11 @@ import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 /**
- * PostgreSQL dialect. For node-pg use PgDialect. Neon, Bun SQL, and Cockroach use driver-specific
- * subclasses. 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 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.
  */
 export class PostgresDialect extends PgLikeSqlDialect {
     dialectName = 'postgres';

package/dist/postgres/postgresWireDriverCapabilities.d.ts

@@ -9,11 +9,11 @@
  *
  * The pair is one constant because it is one driver's shape, and `BunSqlQuerierPool` hands it to
  * `PostgresDialect`/`CockroachDialect` as their `driverCapabilities` rather than subclassing either:
- * Bun changes how a parameter binds, never the SQL. `PgDialect` uses neither, keeping the base
+ * Bun changes how a parameter binds, never the SQL. `PgQuerierPool` uses neither, keeping the base
  * {@link PgLikeSqlDialect} defaults, since node-`pg` needs no fix.
  *
  * @remarks Optional import for custom pools. Neon uses its own serverless driver (not `bun:sql`),
- * so `NeonDialect` is a separate, unverified case - do not assume it needs this without testing.
+ * so `NeonQuerierPool` is a separate, unverified case - do not assume it needs this without testing.
  */
 export declare const POSTGRES_WIRE_DRIVER_CAPABILITIES: {
     readonly nativeArrays: false;

package/dist/postgres/postgresWireDriverCapabilities.js

@@ -9,11 +9,11 @@
  *
  * The pair is one constant because it is one driver's shape, and `BunSqlQuerierPool` hands it to
  * `PostgresDialect`/`CockroachDialect` as their `driverCapabilities` rather than subclassing either:
- * Bun changes how a parameter binds, never the SQL. `PgDialect` uses neither, keeping the base
+ * Bun changes how a parameter binds, never the SQL. `PgQuerierPool` uses neither, keeping the base
  * {@link PgLikeSqlDialect} defaults, since node-`pg` needs no fix.
  *
  * @remarks Optional import for custom pools. Neon uses its own serverless driver (not `bun:sql`),
- * so `NeonDialect` is a separate, unverified case - do not assume it needs this without testing.
+ * so `NeonQuerierPool` is a separate, unverified case - do not assume it needs this without testing.
  */
 export const POSTGRES_WIRE_DRIVER_CAPABILITIES = {
     nativeArrays: false,

package/dist/querier/abstractPoolQuerier.d.ts

@@ -6,7 +6,7 @@ export declare abstract class AbstractPoolQuerier<C> extends AbstractSqlQuerier
     readonly extra?: ExtraOptions | undefined;
     protected conn: C | undefined;
     protected getConn(): C;
-    constructor(dialect: AbstractSqlDialect, connect: () => Promise<C>, extra?: ExtraOptions | undefined);
+    constructor(connect: () => Promise<C>, dialect: AbstractSqlDialect, extra?: ExtraOptions | undefined);
     protected lazyConnect(): Promise<void>;
     internalRelease(discard: boolean): Promise<void>;
     protected abstract releaseConn(conn: C, discard: boolean): Promise<void>;

package/dist/querier/abstractPoolQuerier.js

@@ -8,7 +8,7 @@ export class AbstractPoolQuerier extends AbstractSqlQuerier {
             throw new TypeError('pool querier not connected');
         return this.conn;
     }
-    constructor(dialect, connect, extra) {
+    constructor(connect, dialect, extra) {
         super(dialect, extra);
         this.connect = connect;
         this.extra = extra;

package/dist/querier/abstractQuerier.d.ts

@@ -1,5 +1,6 @@
-import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
 import { LoggerWrapper, type ParentJoin, type ParentPartition } from '../util/index.js';
+/** Base class for all database queriers. */
 export declare abstract class AbstractQuerier implements Querier {
     readonly extra?: ExtraOptions | undefined;
     /**
@@ -109,11 +110,12 @@ export declare abstract class AbstractQuerier implements Querier {
     abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
     /**
-     * A composite key is named here rather than by the statement: no column holds it, so no database
-     * reports one, but the caller wrote every column of it and the payload still carries them.
+     * The `onInsert` values are filled here, before the write, so the after hooks and the ids read the
+     * same rows the statement wrote.
      */
     insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
-    protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    /** 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>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
@@ -150,20 +152,9 @@ export declare abstract class AbstractQuerier implements Querier {
     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>;
     /**
-     * Insert or update, as the name has always promised - and now as one statement per kind rather
-     * than a guess.
-     *
-     * Whether a row names its key decides which statement it takes, never whether the row exists: an
-     * id the caller invented is not proof of anything, and a stale one used to issue an `UPDATE` that
-     * matched nothing and reported success. A named row upserts on its own key, so it is written
-     * either way and no read can go stale between deciding and writing. An unnamed one inserts, and
-     * the database assigns the key.
-     *
-     * A composite key is always supplied by the caller, so it always takes the upsert branch - which
-     * is why nothing here special-cases one, and why this is the method that stopped refusing them.
-     *
-     * The hooks follow the statement: a named row fires `beforeUpsert`/`afterUpsert`, never the
-     * update pair, because the database picks the branch as the statement runs.
+     * Whether a row names its key decides its statement, never whether the row exists: a named row
+     * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
+     * 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 fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
@@ -217,14 +208,18 @@ export declare abstract class AbstractQuerier implements Querier {
     /** Whether anything at all - a global listener or the entity itself - handles `event`. */
     private hasHook;
     /**
-     * Emit a lifecycle hook event for the given entity.
-     * Fires global listeners first, then entity-level hooks.
+     * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
+     * not report them in payload order. A row that no read row matches, or that two do, keeps
+     * `undefined`: a missing id is honest where a guessed one is not.
      */
+    protected idsByConflict<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, rows: EntityData<E>[]): Promise<(PrimaryKey | undefined)[]>;
     /**
-     * Runs `write` between the event's `before`/`after` pair. Every hooked write is this shape, and
-     * each one spelled out was a place the pair could drift - `upsert` had none at all for a release.
+     * Runs `write` between the event's `before`/`after` pair. The before hooks get the caller's rows, so
+     * what they assign is written; `write` and the after hooks get a copy, which by then carries what
+     * the write filled in - a generated key, an `onInsert` value - without it landing on the caller's.
      */
     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.

package/dist/querier/abstractQuerier.js

@@ -1,5 +1,5 @@
 import { assertSoleId, getMeta, idOf, namesKey, soleIdOf } from '../entity/index.js';
-import { asSelectMap, childrenOf, clone, dataKeyed, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, childrenOf, clone, dataKeyed, fillOnFields, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
@@ -41,22 +41,27 @@ function soleParentColumn(relOpts) {
     return parentJoins(relOpts, 1)[0].joined;
 }
 /**
- * Base class for all database queriers.
- * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
+ * The id each written row is named by, in payload order. Read off the rows as written, so a key the
+ * database generated or the ORM filled is there, and a composite is named by every column of it.
  */
+function writtenIds(meta, rows) {
+    return rows.map((row) => (namesKey(meta, row) ? idOf(meta, row) : undefined));
+}
 /**
- * The ids an upsert reports, payload-aligned so the result zips with the rows that were passed.
- *
- * A composite is named from the payload, as an insert's is: no column holds that key, so no
- * statement reports one. A sole key takes what the statement reported when it spoke for every row,
- * and otherwise falls back to the key the caller supplied - a `firstId` dialect reports nothing for
- * a batch, which is not the same as those rows having no id.
+ * Writes the key an upsert reported onto each row that named none - only the key, since an `onInsert`
+ * value was never written to a row the upsert updated. A report aligns with the rows only when it
+ * speaks for every one: a `firstId` dialect reports nothing for a batch.
  */
-function upsertIds(meta, payload, reported) {
-    return meta.ids.length === 1 && reported?.length === payload.length
-        ? reported
-        : payload.map((it) => (namesKey(meta, it) ? idOf(meta, it) : undefined));
+function adoptReportedIds(meta, rows, reported) {
+    if (meta.ids.length !== 1 || reported?.length !== rows.length) {
+        return;
+    }
+    const [idKey] = meta.ids;
+    for (let index = 0; index < rows.length; index++) {
+        rows[index][idKey] ??= reported[index];
+    }
 }
+/** Base class for all database queriers. */
 export class AbstractQuerier {
     extra;
     /**
@@ -182,15 +187,18 @@ export class AbstractQuerier {
         return id;
     }
     /**
-     * A composite key is named here rather than by the statement: no column holds it, so no database
-     * reports one, but the caller wrote every column of it and the payload still carries them.
+     * The `onInsert` values are filled here, before the write, so the after hooks and the ids read the
+     * same rows the statement wrote.
      */
     async insertMany(entity, payload) {
+        if (!payload?.length) {
+            return [];
+        }
         const meta = getMeta(entity);
-        return this.hooked(entity, 'Insert', payload, async () => {
-            const reported = await this.internalInsertMany(entity, payload);
-            // Neither branch can be shown to be `WrittenId` for an unresolved `E`; `idOf` narrows likewise.
-            return meta.ids.length === 1 ? reported : payload.map((it) => idOf(meta, it));
+        return this.hooked(entity, 'Insert', payload, async (rows) => {
+            fillOnFields(meta, rows, 'onInsert');
+            await this.internalInsertMany(entity, rows);
+            return writtenIds(meta, rows);
         });
     }
     async updateOneById(entity, id, payload, opts) {
@@ -198,7 +206,10 @@ export class AbstractQuerier {
         return this.updateMany(entity, { $where: whereIds(getMeta(entity), id) }, payload, opts);
     }
     async updateMany(entity, q, payload, opts) {
-        return this.hooked(entity, 'Update', [payload], () => this.internalUpdateMany(entity, q, payload, opts));
+        return this.hooked(entity, 'Update', [payload], ([row]) => {
+            fillOnFields(getMeta(entity), [row], 'onUpdate');
+            return this.internalUpdateMany(entity, q, row, opts);
+        });
     }
     async restoreOneById(entity, id) {
         assertIdValue(entity, id);
@@ -221,16 +232,20 @@ export class AbstractQuerier {
      * was how an `@Id({ onInsert })` or an audit trail silently skipped this path.
      */
     async upsertOne(entity, conflictPaths, payload) {
-        return this.hooked(entity, 'Upsert', [payload], async () => {
-            const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, payload);
-            const [id] = upsertIds(getMeta(entity), [payload], ids);
+        const meta = getMeta(entity);
+        return this.hooked(entity, 'Upsert', [payload], async (rows) => {
+            const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, rows[0]);
+            adoptReportedIds(meta, rows, ids);
+            const [id] = writtenIds(meta, rows);
             return { id, changes, created };
         });
     }
     async upsertMany(entity, conflictPaths, payload) {
-        return this.hooked(entity, 'Upsert', payload, async () => {
-            const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, payload);
-            return { ids: upsertIds(getMeta(entity), payload, ids), changes };
+        const meta = getMeta(entity);
+        return this.hooked(entity, 'Upsert', payload, async (rows) => {
+            const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, rows);
+            adoptReportedIds(meta, rows, ids);
+            return { ids: writtenIds(meta, rows), changes };
         });
     }
     async deleteOneById(entity, id, opts) {
@@ -278,20 +293,9 @@ export class AbstractQuerier {
         return id;
     }
     /**
-     * Insert or update, as the name has always promised - and now as one statement per kind rather
-     * than a guess.
-     *
-     * Whether a row names its key decides which statement it takes, never whether the row exists: an
-     * id the caller invented is not proof of anything, and a stale one used to issue an `UPDATE` that
-     * matched nothing and reported success. A named row upserts on its own key, so it is written
-     * either way and no read can go stale between deciding and writing. An unnamed one inserts, and
-     * the database assigns the key.
-     *
-     * A composite key is always supplied by the caller, so it always takes the upsert branch - which
-     * is why nothing here special-cases one, and why this is the method that stopped refusing them.
-     *
-     * The hooks follow the statement: a named row fires `beforeUpsert`/`afterUpsert`, never the
-     * update pair, because the database picks the branch as the statement runs.
+     * Whether a row names its key decides its statement, never whether the row exists: a named row
+     * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
+     * inserts. A composite is always named. The hooks follow the statement: a named row fires the upsert pair.
      */
     async saveMany(entity, payload) {
         const meta = getMeta(entity);
@@ -320,15 +324,15 @@ export class AbstractQuerier {
         const write = async () => {
             if (toInsert.length) {
                 const inserted = await this.insertMany(entity, toInsert.map((index) => payload[index]));
-                toInsert.forEach((index, position) => {
-                    ids[index] = inserted[position];
-                });
+                for (let position = 0; position < toInsert.length; position++) {
+                    ids[toInsert[position]] = inserted[position];
+                }
             }
             if (toUpsert.length) {
                 const conflictPaths = Object.fromEntries(meta.ids.map((key) => [key, true]));
-                await this.upsertMany(entity, conflictPaths, toUpsert.map((index) => payload[index]));
-                for (const index of toUpsert) {
-                    ids[index] = idOf(meta, payload[index]);
+                const { ids: upserted } = await this.upsertMany(entity, conflictPaths, toUpsert.map((index) => payload[index]));
+                for (let position = 0; position < toUpsert.length; position++) {
+                    ids[toUpsert[position]] = upserted[position];
                 }
             }
         };
@@ -519,16 +523,15 @@ export class AbstractQuerier {
         // unless this has run - and this method is `protected`, so a caller can arrive without them.
         assertSoleId(meta, 'saving a relation');
         const relEntity = relOpts.entity();
-        const relPayload = relValue;
         switch (relOpts.cardinality) {
             case '1m':
             case 'mm':
-                return this.saveToMany(relOpts, relEntity, ids, relPayload, isUpdate);
+                return this.saveToMany(relOpts, relEntity, ids, relValue, isUpdate);
             case '11':
-                return this.saveOneToOne(relEntity, relOpts, ids, relPayload, isUpdate);
+                return this.saveOneToOne(relEntity, relOpts, ids, relValue, isUpdate);
             case 'm1':
-                if (relPayload)
-                    return this.saveManyToOne(entity, relEntity, relOpts, ids, relPayload);
+                if (relValue)
+                    return this.saveManyToOne(entity, relEntity, relOpts, ids, relValue);
         }
     }
     async saveToMany(relOpts, relEntity, ids, relPayload, isUpdate) {
@@ -628,19 +631,39 @@ export class AbstractQuerier {
         return (this.extra?.listeners?.some((listener) => listener[event]) || (getMeta(entity).hooks?.[event]?.length ?? 0) > 0);
     }
     /**
-     * Emit a lifecycle hook event for the given entity.
-     * Fires global listeners first, then entity-level hooks.
+     * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
+     * not report them in payload order. A row that no read row matches, or that two do, keeps
+     * `undefined`: a missing id is honest where a guessed one is not.
      */
+    async idsByConflict(entity, conflictPaths, rows) {
+        const meta = getMeta(entity);
+        const [idKey] = meta.ids;
+        const keys = getKeys(conflictPaths);
+        const q = {
+            $select: Object.fromEntries([idKey, ...keys].map((key) => [key, true])),
+            $where: { $or: rows.map((row) => Object.fromEntries(keys.map((key) => [key, row[key]]))) },
+        };
+        const found = await this.internalFindMany(entity, q, { filters: withoutSoftDeleteFilter(undefined) });
+        const byConflict = new Map();
+        for (const row of found) {
+            const key = rowKey(row, keys);
+            byConflict.set(key, byConflict.has(key) ? undefined : row[idKey]);
+        }
+        return rows.map((row) => byConflict.get(rowKey(row, keys)));
+    }
     /**
-     * Runs `write` between the event's `before`/`after` pair. Every hooked write is this shape, and
-     * each one spelled out was a place the pair could drift - `upsert` had none at all for a release.
+     * Runs `write` between the event's `before`/`after` pair. The before hooks get the caller's rows, so
+     * what they assign is written; `write` and the after hooks get a copy, which by then carries what
+     * the write filled in - a generated key, an `onInsert` value - without it landing on the caller's.
      */
     async hooked(entity, event, payloads, write) {
         await this.emitHook(entity, `before${event}`, payloads);
-        const result = await write();
-        await this.emitHook(entity, `after${event}`, payloads);
+        const rows = clone(payloads);
+        const result = await write(rows);
+        await this.emitHook(entity, `after${event}`, rows);
         return result;
     }
+    /** Fires the global listeners first, then the entity's own hooks. */
     async emitHook(entity, event, payloads) {
         if (!this.hasHook(entity, event))
             return;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
-import type { EntityData, ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import { type ParentPartition } from '../util/index.js';
 import type { BuildUpdateResultPayload } from '../util/sql.util.js';
 import { AbstractQuerier } from './abstractQuerier.js';
@@ -71,6 +71,13 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * query, so neither can reach here.
      */
     protected internalFindManyPerParent<E extends object>(entity: Type<E>, q: Query<E>, partition: ParentPartition): Promise<E[]>;
+    /**
+     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
+     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
+     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
+     * pair outright. Both then cost a second statement; only the counting differs.
+     */
+    private countedSeparately;
     /**
      * One statement for both: the page carries its own unpaged total in an extra column. An empty page
      * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
@@ -82,13 +89,6 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
      * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
      */
-    /**
-     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
-     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
-     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
-     * pair outright. Both then cost a second statement; only the counting differs.
-     */
-    private countedSeparately;
     protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     private selectRows;
     private hydrateRows;
@@ -119,7 +119,7 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     protected internalCount<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
-    internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
     internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
     private settleIds;
@@ -129,14 +129,21 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     get hasOpenTransaction(): boolean;
     beginTransaction(opts?: TransactionOptions): Promise<void>;
+    /**
+     * Only an end that succeeded ends the transaction. A `COMMIT` that fails can leave it open (SQLite
+     * answers `SQLITE_BUSY` and keeps it), so the flag has to stay set for the `catch` in
+     * {@link AbstractQuerier.transaction} or {@link AbstractQuerier.release} to roll it back.
+     */
     commitTransaction(): Promise<void>;
     rollbackTransaction(): Promise<void>;
     /**
-     * Only a statement that succeeded ends the transaction. A `COMMIT` that fails can leave it open
-     * (SQLite answers `SQLITE_BUSY` and keeps it), so the flag has to stay set for the `catch` in
-     * {@link AbstractQuerier.transaction} or {@link AbstractQuerier.release} to roll it back.
+     * How this driver opens, commits and rolls back: the dialect's statements, unless its transactions
+     * are objects rather than statements - Hrana's session handle, `mssql`'s `Transaction` - in which
+     * case it overrides all three. The bookkeeping around them stays above, written once.
      */
-    private endTransactionWith;
+    protected internalBegin(opts?: TransactionOptions): Promise<void>;
+    protected internalCommit(): Promise<void>;
+    protected internalRollback(): Promise<void>;
     /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
     private runTransactionCommand;
 }