uql-orm 0.66.0 → 0.67.0

package/dist/querier/abstractQuerier.js

@@ -1,15 +1,9 @@
-import { assertSoleId, getMeta, idOf, namesKey, relationOf, soleIdOf } from '../entity/index.js';
-import { childrenOf, clone, entityName, fillOnFields, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
+import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isPagedQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 /**
- * Rejects a nullish primary key before it reaches a statement. The by-id methods reduce to
- * `{ $where: { id } }`, and a key compared to `undefined` is *no filter*, so an unchecked one
- * addresses the whole table. An entity declares its id optional, which puts `undefined` inside
- * `IdValue<E>`, and the HTTP layer reaches these methods with parsed JSON regardless, so the guard
- * belongs at runtime.
- *
- * Its callers are all `async` so this surfaces as a rejection on every one of them: a guard that
- * threw synchronously from some and rejected from others would escape a caller's `.catch()`.
+ * Refuses a nullish id, which would reduce to no filter at all, and a composite id missing a column,
+ * which would address every row agreeing on the rest. Callers are `async`, so it always rejects.
  */
 function assertIdValue(entity, id) {
     if (id === undefined || id === null) {
@@ -29,13 +23,7 @@ function assertIdValue(entity, id) {
         throw new TypeError(`'${entity.name}' is addressed by an object carrying every key of its primary key (${ids.join(', ')}); missing ${missing.join(', ')}.`);
     }
 }
-/**
- * The one column a write path matches a parent's key against.
- *
- * Every caller reaches its parents through a sole id - `soleIdOf` refused a composite before any of
- * them - so the parent contributes exactly one column here, whether the relation goes through a
- * junction or straight to the child.
- */
+/** The column a write matches a parent's sole key against, on the junction or the child. */
 function soleParentColumn(relOpts) {
     return parentJoins(relOpts, 1)[0].joined;
 }
@@ -100,12 +88,7 @@ export class AbstractQuerier {
             }
         });
     }
-    /**
-     * 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)`. */
     resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         if (typeof entityOrQuery === 'function' && entityOrQuery.prototype) {
             return [entityOrQuery, maybeQueryOrOpts ?? {}, maybeOpts];
@@ -163,16 +146,11 @@ export class AbstractQuerier {
     }
     async count(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
-        if (q.$skip !== undefined || q.$limit !== undefined) {
-            const meta = getMeta(entity);
-            const rows = await this.internalFindMany(entity, idOnlyQuery(meta, { $where: q.$where, $skip: q.$skip, $limit: q.$limit }), opts);
-            return rows.length;
-        }
         return this.internalCount(entity, q, opts);
     }
     async exists(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
-        return (await this.count(entity, { $where: q.$where, $limit: 1 }, opts)) > 0;
+        return (await this.internalCount(entity, { $where: q.$where, $limit: 1 }, opts)) > 0;
     }
     /**
      * Run an aggregate query.
@@ -203,12 +181,41 @@ export class AbstractQuerier {
         assertIdValue(entity, id);
         return this.updateMany(entity, { $where: whereIds(getMeta(entity), id) }, payload, opts);
     }
+    /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     async updateMany(entity, q, payload, opts) {
-        return this.hooked(entity, 'Update', [payload], ([row]) => {
-            fillOnFields(getMeta(entity), [row], 'onUpdate');
-            return this.internalUpdateMany(entity, q, row, opts);
+        const meta = getMeta(entity);
+        return this.hooked(entity, 'Update', [payload], async ([row]) => {
+            fillOnFields(meta, [row], 'onUpdate');
+            const relKeys = filterPersistableRelationKeys(meta, row, 'persist');
+            if (!relKeys.length && !this.settlesWrite(entity, q)) {
+                return this.updateColumns(entity, q, row, opts, 0);
+            }
+            const ids = await this.settleIds(entity, q, opts);
+            if (!ids.length) {
+                return 0;
+            }
+            const changes = await this.updateColumns(entity, { $where: whereIds(meta, ids) }, row, opts, ids.length);
+            for (const relKey of relKeys) {
+                await this.saveRelation(entity, relKey, ids.map((id) => ({ id, value: row[relKey] })), true);
+            }
+            return changes;
         });
     }
+    /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
+    async updateColumns(entity, q, row, opts, unwritten) {
+        const writes = filterFieldKeys(getMeta(entity), row, 'onUpdate').length > 0;
+        return writes ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
+    }
+    /** Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or delete. */
+    settlesWrite(_entity, q) {
+        return isPagedQuery(q);
+    }
+    /** The ids `q` matches, in its own order and page. */
+    async settleIds(entity, q, opts) {
+        const meta = getMeta(entity);
+        const rows = await this.internalFindMany(entity, idOnlyQuery(meta, q), opts);
+        return rows.map((row) => idOf(meta, row));
+    }
     async restoreOneById(entity, id) {
         assertIdValue(entity, id);
         return this.restoreMany(entity, { $where: whereIds(getMeta(entity), id) });
@@ -223,12 +230,7 @@ export class AbstractQuerier {
             filters: { softDelete: false },
         });
     }
-    /**
-     * `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. */
     async upsertOne(entity, conflictPaths, payload) {
         const meta = getMeta(entity);
         return this.hooked(entity, 'Upsert', [payload], async (rows) => {
@@ -252,40 +254,29 @@ export class AbstractQuerier {
     }
     async deleteMany(entityOrQuery, qOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, qOrOpts, maybeOpts);
-        const doomed = await this.findDoomed(entity, q, opts);
-        if (doomed?.length === 0) {
+        const meta = getMeta(entity);
+        const cascades = cascadesOnDelete(meta);
+        const watched = this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
+        if (!watched && !cascades && !this.settlesWrite(entity, q)) {
+            return this.internalDeleteMany(entity, q, opts);
+        }
+        // A hard delete takes already-soft-deleted rows too, so reading them back has to see them.
+        const readOpts = opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
+        // A hook receives the rows themselves; the ids read off them name the same rows a second read might not.
+        const doomed = watched ? await this.internalFindMany(entity, q, readOpts) : [];
+        const ids = watched ? doomed.map((row) => idOf(meta, row)) : await this.settleIds(entity, q, readOpts);
+        if (!ids.length) {
             return 0;
         }
-        // Where a snapshot was taken, the statement names those rows rather than resolving `q` a second
-        // time. Two reads of one `$limit` with no total order are free to disagree, which would fire the
-        // hooks for one row and delete another; naming them also spares the second read.
-        let target = q;
-        if (doomed) {
-            const meta = getMeta(entity);
-            const ids = doomed.map((it) => idOf(meta, it));
-            target = { $where: whereIds(meta, ids) };
+        await this.emitHook(entity, 'beforeDelete', doomed);
+        // Children first: they hold the foreign key, which a schema without `ON DELETE CASCADE` enforces.
+        if (cascades) {
+            await this.deleteRelations(entity, ids, opts);
         }
-        await this.emitHook(entity, 'beforeDelete', doomed ?? []);
-        const changes = await this.internalDeleteMany(entity, target, opts);
-        await this.emitHook(entity, 'afterDelete', doomed ?? []);
+        const changes = await this.internalDeleteMany(entity, { $where: whereIds(meta, ids) }, opts);
+        await this.emitHook(entity, 'afterDelete', doomed);
         return changes;
     }
-    /**
-     * 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.
-     */
-    async findDoomed(entity, q, opts) {
-        if (!this.hasHook(entity, 'beforeDelete') && !this.hasHook(entity, 'afterDelete')) {
-            return undefined;
-        }
-        // A hard delete takes already-soft-deleted rows too, so reading them back has to see them.
-        const findOpts = opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
-        return this.internalFindMany(entity, q, findOpts);
-    }
     async saveOne(entity, payload) {
         const [id] = await this.saveMany(entity, [payload]);
         return id;
@@ -339,39 +330,18 @@ export class AbstractQuerier {
         await (toInsert.length && toUpsert.length ? this.transaction(write) : write());
         return ids;
     }
-    async insertRelations(entity, payload) {
-        const meta = getMeta(entity);
-        const entries = payload.reduce((acc, it) => {
-            const relKeys = filterPersistableRelationKeys(meta, it, 'persist');
-            if (relKeys.length > 0)
-                acc.push({ it, relKeys });
-            return acc;
-        }, []);
-        if (!entries.length)
-            return;
-        const idKey = soleIdOf(meta, 'saving a relation');
-        await Promise.all(entries.map(({ it, relKeys }) => Promise.all(relKeys.map((relKey) => this.saveRelation(entity, [it[idKey]], it[relKey], relKey)))));
-    }
-    async updateRelations(entity, q, payload, opts) {
+    /** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
+    async insertRelations(entity, rows) {
         const meta = getMeta(entity);
-        const relKeys = filterPersistableRelationKeys(meta, payload, 'persist');
-        if (!relKeys.length) {
-            return;
-        }
-        const idKey = soleIdOf(meta, 'saving a relation');
-        const founds = await this.findMany(entity, idOnlyQuery(meta, q), opts);
-        const ids = founds.map((found) => found[idKey]);
-        if (!ids.length) {
-            return;
-        }
-        for (const relKey of relKeys) {
-            await this.saveRelation(entity, ids, payload[relKey], relKey, true);
+        const [idKey] = meta.ids;
+        for (const relKey of filterPersistableRelationKeys(meta, meta.relations, 'persist')) {
+            const writes = rows.flatMap((row) => (row[relKey] == null ? [] : [{ id: row[idKey], value: row[relKey] }]));
+            if (writes.length) {
+                await this.saveRelation(entity, relKey, writes, false);
+            }
         }
     }
-    /**
-     * `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.
-     */
+    /** `EntityId` because a settled composite row is an object, which {@link childrenOf} reads each foreign key column out of. */
     async deleteRelations(entity, ids, opts) {
         const meta = getMeta(entity);
         const relKeys = filterPersistableRelationKeys(meta, meta.relations, 'delete');
@@ -385,101 +355,53 @@ export class AbstractQuerier {
         }
     }
     /**
-     * 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.
+     * 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.
      */
-    async saveRelation(entity, ids, relValue, relKey, isUpdate) {
+    async saveRelation(entity, relKey, writes, isUpdate) {
         const meta = getMeta(entity);
-        const relOpts = relationOf(meta, relKey);
-        // Here rather than only in the callers below: writing the parent's key into a child is one column
-        // per key, so a composite takes a statement per parent. `soleParentColumn` and the sole
-        // `targetKeyColumns` under it read the *first* pair, which is a real column of a wrong pairing
-        // unless this has run - and this method is `protected`, so a caller can arrive without them.
+        // Writing the parent's key into a child is one column per key, and the helpers below read the first pair.
         assertSoleId(meta, 'saving a relation');
+        const relOpts = relationOf(meta, relKey);
         const relEntity = relOpts.entity();
-        switch (relOpts.cardinality) {
-            case '1m':
-            case 'mm':
-                return this.saveToMany(relOpts, relEntity, ids, relValue, isUpdate);
-            case '11':
-                return this.saveOneToOne(relEntity, relOpts, ids, relValue, isUpdate);
-            case 'm1':
-                if (relValue)
-                    return this.saveManyToOne(entity, relEntity, relOpts, ids, relValue);
+        if (relOpts.cardinality === 'm1') {
+            return this.saveManyToOne(entity, relEntity, relOpts.references[0].local, writes);
         }
-    }
-    async saveToMany(relOpts, relEntity, ids, relPayload, isUpdate) {
-        const { through } = relOpts;
-        if (through) {
-            const localField = soleParentColumn(relOpts);
-            const [targetColumn] = targetKeyColumns(relOpts, 1);
-            const throughEntity = through();
-            if (isUpdate) {
-                await this.deleteMany(throughEntity, { $where: { [localField]: ids } });
-            }
-            if (relPayload) {
-                // Saved per parent on purpose: each one owns its copies of the children, and saving them once
-                // would link every parent to a single shared row instead.
-                for (const id of ids) {
-                    const savedIds = await this.saveMany(relEntity, relPayload);
-                    // A link needs the target's id, and a driver that cannot report one (a MySQL batch mixing
-                    // supplied and generated keys) would otherwise write a row pointing at `undefined`.
-                    if (savedIds.some((relId) => relId === undefined)) {
-                        throw new TypeError(`'${relEntity.name}' rows saved through '${throughEntity.name}' reported no id, so they cannot be linked. ` +
-                            'Insert them with their own ids, or save the relation in its own statement.');
-                    }
-                    await this.insertMany(throughEntity, savedIds.map((relId) => ({ [localField]: id, [targetColumn]: relId })));
-                }
-            }
+        const holder = relOpts.through ? relOpts.through() : relEntity;
+        const parentColumn = soleParentColumn(relOpts);
+        if (isUpdate) {
+            const ids = writes.map(({ id }) => id);
+            await this.deleteMany(holder, { $where: { [parentColumn]: ids } });
+        }
+        // Each parent gets its own copies, so a row listed for two parents is written twice.
+        const children = writes.flatMap(({ id, value }) => [value ?? []].flat().map((row) => ({ id, row })));
+        if (!children.length) {
             return;
         }
-        const foreignField = soleParentColumn(relOpts);
-        if (isUpdate) {
-            await this.deleteMany(relEntity, { $where: { [foreignField]: ids } });
+        if (!relOpts.through) {
+            await this.saveMany(relEntity, children.map(({ id, row }) => ({ ...row, [parentColumn]: id })));
+            return;
         }
-        if (relPayload) {
-            await this.saveMany(relEntity, ids.flatMap((id) => relPayload.map((it) => ({ ...it, [foreignField]: id }))));
+        const savedIds = await this.saveMany(relEntity, children.map(({ row }) => row));
+        // A link needs the target's id, which a MySQL batch mixing supplied and generated keys cannot report.
+        if (savedIds.includes(undefined)) {
+            throw new TypeError(`'${relEntity.name}' rows saved through '${holder.name}' reported no id, so they cannot be linked. ` +
+                'Insert them with their own ids, or save the relation in its own statement.');
         }
+        const [targetColumn] = targetKeyColumns(relOpts, 1);
+        await this.insertMany(holder, children.map(({ id }, index) => ({ [parentColumn]: id, [targetColumn]: savedIds[index] })));
     }
-    async saveOneToOne(relEntity, relOpts, ids, relPayload, isUpdate) {
-        const foreignField = soleParentColumn(relOpts);
-        // The same rule a to-many follows: the parent owns its child, so an update replaces it. Without
-        // this the old row stayed behind and a one-to-one `$populate` had two rows to choose from.
-        if (relPayload === null || isUpdate) {
-            await this.deleteMany(relEntity, { $where: { [foreignField]: ids } });
-            if (relPayload === null) {
-                return;
-            }
-        }
-        await this.saveMany(relEntity, ids.map((id) => ({ ...relPayload, [foreignField]: id })));
-    }
-    async saveManyToOne(entity, relEntity, relOpts, ids, relPayload) {
-        // Not `soleParentColumn`: a many-to-one points the other way, so this is the *parent's* own column
-        // holding the child's id - the one place `references[0].local` does not name a key of the parent.
-        const localField = relOpts.references[0].local;
-        // Per parent: each gets its own reference row, so each `SET` carries a different value.
-        for (const id of ids) {
-            const referenceId = await this.insertOne(relEntity, relPayload);
-            await this.updateOneById(entity, id, { [localField]: referenceId });
+    /** Each parent gets its own referenced row, and its own column pointing at it. */
+    async saveManyToOne(entity, relEntity, localColumn, writes) {
+        const pointing = writes.filter(({ value }) => value);
+        const referenceIds = await this.insertMany(relEntity, pointing.map(({ value }) => value));
+        for (const [index, { id }] of pointing.entries()) {
+            await this.updateOneById(entity, id, { [localColumn]: referenceIds[index] });
         }
     }
     /**
-     * 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.
      */
     async transaction(callback, opts) {
         if (this.hasOpenTransaction) {
@@ -578,27 +500,13 @@ export class AbstractQuerier {
         }
         await runHooks(entity, event, payloads, { querier: this });
     }
-    /**
-     * 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. */
     serialize(task) {
         const res = this.taskQueue.then(task);
         this.taskQueue = res.catch(() => { });
         return res;
     }
-    /**
-     * 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. */
     async timed(query, values, task) {
         const startTime = performance.now();
         try {
@@ -612,12 +520,8 @@ export class AbstractQuerier {
         }
     }
     /**
-     * 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.
      */
     async release() {
         let discard = false;

package/dist/querier/abstractSharedHandleQuerierPool.d.ts

@@ -2,23 +2,9 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SqlQuerier } from '../type/index.js';
 import { AbstractSqlQuerierPool } from './abstractSqlQuerierPool.js';
 /**
- * Base pool for a handle opened once and kept for the pool's lifetime: the one connection every local
- * SQLite driver, the embedded Turso engine and PGlite give per database, or libSQL's client.
- *
- * The handle is shared, but each acquisition gets its own querier, so transaction state stays per unit
- * of work. On a single connection that state is not *isolated*, which is the one way these differ from
- * a real pool: two queriers cannot hold independent transactions, and a unit of work that needs one needs
- * its own pool and therefore its own database. libSQL's client opens a session per transaction instead.
- *
- * What a second `BEGIN` then does is the engine's, not this class's: SQLite and the embedded Turso
- * engine both refuse it ("cannot start a transaction within a transaction"), while PGlite accepts it
- * into the transaction already open - see {@link PgliteQuerierPool}, which is why that one is worth
- * saying out loud.
- *
- * Subclasses supply only how to open the handle and how to wrap it.
- *
- * @remarks Deliberately not re-exported from `querier/index.ts`, which the root entry point re-exports:
- * only the driver entries that open a single handle need this, and each imports it by path.
+ * A pool over one handle kept for its lifetime: a local SQLite file, the embedded Turso engine, PGlite, or a
+ * libSQL client. Each acquisition gets its own querier, but on one connection two cannot hold separate
+ * transactions: a unit of work needing its own needs its own pool. Imported by path, not from `querier/index.ts`.
  */
 export declare abstract class AbstractSharedHandleQuerierPool<DB extends {
     close(): unknown;

package/dist/querier/abstractSharedHandleQuerierPool.js

@@ -1,22 +1,8 @@
 import { AbstractSqlQuerierPool } from './abstractSqlQuerierPool.js';
 /**
- * Base pool for a handle opened once and kept for the pool's lifetime: the one connection every local
- * SQLite driver, the embedded Turso engine and PGlite give per database, or libSQL's client.
- *
- * The handle is shared, but each acquisition gets its own querier, so transaction state stays per unit
- * of work. On a single connection that state is not *isolated*, which is the one way these differ from
- * a real pool: two queriers cannot hold independent transactions, and a unit of work that needs one needs
- * its own pool and therefore its own database. libSQL's client opens a session per transaction instead.
- *
- * What a second `BEGIN` then does is the engine's, not this class's: SQLite and the embedded Turso
- * engine both refuse it ("cannot start a transaction within a transaction"), while PGlite accepts it
- * into the transaction already open - see {@link PgliteQuerierPool}, which is why that one is worth
- * saying out loud.
- *
- * Subclasses supply only how to open the handle and how to wrap it.
- *
- * @remarks Deliberately not re-exported from `querier/index.ts`, which the root entry point re-exports:
- * only the driver entries that open a single handle need this, and each imports it by path.
+ * A pool over one handle kept for its lifetime: a local SQLite file, the embedded Turso engine, PGlite, or a
+ * libSQL client. Each acquisition gets its own querier, but on one connection two cannot hold separate
+ * transactions: a unit of work needing its own needs its own pool. Imported by path, not from `querier/index.ts`.
  */
 export class AbstractSharedHandleQuerierPool extends AbstractSqlQuerierPool {
     /**

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/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 { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryPage, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import type { BuildUpdateResultPayload } from '../util/sql.util.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
@@ -34,46 +34,27 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     protected lazyConnect(): Promise<void>;
     all<T>(query: string, values?: unknown[]): Promise<T[]>;
     run(query: string, values?: unknown[]): Promise<QueryUpdateResult>;
+    /** The rows of a statement the dialect builds. */
+    private query;
+    /** Runs a statement the dialect builds. */
+    private exec;
     /**
-     * `$lock` outside a transaction is always a bug, and a silent one. Every engine accepts
-     * `SELECT ... FOR UPDATE` in autocommit and then releases the lock as the statement commits,
-     * before the caller has seen a row: the SQL is correct, nothing is omitted, and no layer below
-     * this one can tell. The dialect cannot check it either, being stateless and shared by every
-     * connection of the pool, so this is the only place it can be caught.
-     *
-     * The capability check runs first on purpose: "this engine has no row locks" is the more
-     * actionable answer, and on SQLite it is the answer either way.
+     * Refuses a `$lock` the engine lacks, then one outside a transaction, where the lock would drop as the
+     * statement commits; only the querier knows whether one is open.
      */
     protected assertLockable<E>(entity: Type<E>, q: Query<E>): void;
     /**
-     * Run the `SET`s that tune an ANN index for this query, and refuse the ones that would not apply.
-     *
-     * Same shape as {@link assertLockable} and for the same reason: a `SET LOCAL` outside a transaction
-     * is accepted, applies to nothing, and leaves the query running at the engine's default recall -
-     * correct SQL, silently untuned. Only the querier knows whether a transaction is open.
-     *
-     * The statements go through `internalRun`, sharing this querier's single connection with the query
-     * they precede; `SET LOCAL` then expires with the transaction, so nothing is left behind.
+     * Runs the `SET`s tuning an ANN index for the query on its connection, refusing where they would apply to
+     * nothing: a `SET LOCAL` outside a transaction.
      */
     private applyVectorTuning;
     protected internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
+    /** Every row `q` matches past its page, deduplicated where it reads `$distinct`. */
+    private countUnpaged;
     /**
-     * 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
-     * the end, or a filter nothing matched.
-     *
-     * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
-     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
-     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
-     * 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}.
+     * The page and its unpaged total in one statement, a window column on each row, and a count of its own for
+     * an empty page. A window counts before `DISTINCT`, and the Postgres family refuses one beside a `$lock`,
+     * so those count apart.
      */
     protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     private selectRows;
@@ -104,13 +85,11 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * a catalog that does not know the table answers with no row, which is nothing counted.
      */
     private runCount;
-    protected internalCount<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
+    protected internalCount<E extends object>(entity: Type<E>, q: QueryPage<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>, 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;
     protected internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     private runUpsert;