uql-orm 0.29.0 → 0.31.0

package/dist/pglite/pgliteQuerier.js

@@ -0,0 +1,30 @@
+import { AbstractSqlQuerier } from '../querier/index.js';
+/**
+ * Querier for PGlite, Postgres compiled to WASM and run in this process.
+ *
+ * @remarks Extends {@link AbstractSqlQuerier} rather than `AbstractPgQuerier`, whose `internalStream`
+ * hands a `pg-query-stream` object to `query()`: PGlite has no cursor API, so streaming falls back to
+ * the base class buffering the whole result. `BEGIN`/`COMMIT` are plain statements on the single
+ * connection, leaving transactions to the base class.
+ */
+export class PgliteQuerier extends AbstractSqlQuerier {
+    db;
+    extra;
+    constructor(db, dialect, extra) {
+        super(dialect, extra);
+        this.db = db;
+        this.extra = extra;
+    }
+    async internalAll(query, values) {
+        const res = await this.db.query(query, values);
+        return res.rows;
+    }
+    async internalRun(query, values) {
+        const res = await this.db.query(query, values);
+        // `affectedRows`, not `rowCount`: PGlite derives the former from the command tag of a write only,
+        // where the latter also counts a `SELECT`'s rows and is absent altogether from a DDL tag.
+        return this.buildUpdateResult({ rows: res.rows, changes: res.affectedRows ?? 0 });
+    }
+    /** The handle belongs to the pool, which hands out one querier per unit of work over it. */
+    async internalRelease() { }
+}

package/dist/pglite/pgliteQuerierPool.d.ts

@@ -0,0 +1,36 @@
+import type { PGliteOptions } from '@electric-sql/pglite';
+import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
+import type { ExtraOptions } from '../type/index.js';
+import { PgliteDialect } from './pgliteDialect.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.
+ */
+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.
+ */
+export declare class PgliteQuerierPool extends AbstractSharedHandleQuerierPool<PgliteDatabase, PgliteQuerier, PgliteDialect> {
+    readonly dataDir: string;
+    readonly opts?: PglitePoolOptions | undefined;
+    constructor(dataDir?: string, opts?: PglitePoolOptions | undefined, extra?: ExtraOptions);
+    protected openDb(): Promise<PgliteDatabase>;
+    protected buildQuerier(db: PgliteDatabase): PgliteQuerier;
+}

package/dist/pglite/pgliteQuerierPool.js

@@ -0,0 +1,36 @@
+import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
+import { PgliteDialect } from './pgliteDialect.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.
+ */
+export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
+    dataDir;
+    opts;
+    constructor(dataDir = 'memory://', opts, extra) {
+        super(new PgliteDialect({ namingStrategy: extra?.namingStrategy }), extra);
+        this.dataDir = dataDir;
+        this.opts = opts;
+    }
+    async openDb() {
+        const { PGlite } = await import('@electric-sql/pglite');
+        // The declared return type is what checks {@link PgliteDatabase} against the real driver, so no
+        // cast is needed here or anywhere below it.
+        return PGlite.create(this.dataDir, this.opts);
+    }
+    buildQuerier(db) {
+        return new PgliteQuerier(db, this.dialect, this.extra);
+    }
+}

package/dist/querier/abstractQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { ExtraOptions, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QueryPopulate, QuerySearch, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QueryPopulate, QuerySearch, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 /**
  * Base class for all database queriers.
@@ -85,16 +85,16 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     protected abstract 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>[]>;
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
-    protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
+    protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     updateOneById<E extends object>(entity: Type<E>, id: IdValue<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>;
     restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;
     restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
-    abstract upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    abstract upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    abstract upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    abstract upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Delete records matching the query. Soft-deletes when the entity has a soft-delete field (unless
@@ -104,9 +104,18 @@ export declare abstract class AbstractQuerier implements Querier {
     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;
     protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-    saveOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E>>;
-    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E>>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     protected fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
     private fillToManyThroughRelation;
     private fillToManyOneToMany;
@@ -137,6 +146,8 @@ export declare abstract class AbstractQuerier implements Querier {
      * one afterwards.
      */
     transaction<T>(callback: () => Promise<T>, opts?: TransactionOptions): Promise<T>;
+    /** 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.

package/dist/querier/abstractQuerier.js

@@ -1,6 +1,20 @@
 import { getMeta } from '../entity/index.js';
-import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, LoggerWrapper, parseRelationAtKey, parseRelationQueryValue, runHooks, } from '../util/index.js';
+import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, LoggerWrapper, parseRelationAtKey, parseRelationQueryValue, runHooks, 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 nullish `$where` 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()`.
+ */
+function assertIdValue(entity, id) {
+    if (id === undefined || id === null) {
+        throw new TypeError(`'${entity.name}' was addressed by id, but the id is ${String(id)}`);
+    }
+}
 /**
  * Base class for all database queriers.
  * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
@@ -65,6 +79,7 @@ export class AbstractQuerier {
         return [$entity, query, maybeQueryOrOpts];
     }
     async findOneById(entity, id, q = {}, opts) {
+        assertIdValue(entity, id);
         return this.findOne(entity, { ...q, $where: augmentWhere(getMeta(entity), q.$where, id) }, opts);
     }
     async findOne(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
@@ -115,7 +130,8 @@ export class AbstractQuerier {
         await this.emitHook(entity, 'afterInsert', payload);
         return ids;
     }
-    updateOneById(entity, id, payload, opts) {
+    async updateOneById(entity, id, payload, opts) {
+        assertIdValue(entity, id);
         return this.updateMany(entity, { $where: id }, payload, opts);
     }
     async updateMany(entity, q, payload, opts) {
@@ -124,7 +140,8 @@ export class AbstractQuerier {
         await this.emitHook(entity, 'afterUpdate', [payload]);
         return changes;
     }
-    restoreOneById(entity, id) {
+    async restoreOneById(entity, id) {
+        assertIdValue(entity, id);
         return this.restoreMany(entity, { $where: id });
     }
     async restoreMany(entity, q) {
@@ -137,16 +154,41 @@ export class AbstractQuerier {
             filters: { softDelete: false },
         });
     }
-    deleteOneById(entity, id, opts) {
+    async deleteOneById(entity, id, opts) {
+        assertIdValue(entity, id);
         return this.deleteMany(entity, { $where: id }, opts);
     }
     async deleteMany(entityOrQuery, qOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, qOrOpts, maybeOpts);
-        await this.emitHook(entity, 'beforeDelete', []);
-        const changes = await this.internalDeleteMany(entity, q, opts);
-        await this.emitHook(entity, 'afterDelete', []);
+        const doomed = await this.findDoomed(entity, q, opts);
+        if (doomed?.length === 0) {
+            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.
+        const target = doomed ? { $where: doomed.map((it) => it[getMeta(entity).id]) } : q;
+        await this.emitHook(entity, 'beforeDelete', doomed ?? []);
+        const changes = await this.internalDeleteMany(entity, target, 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;
@@ -400,32 +442,26 @@ export class AbstractQuerier {
             throw err;
         }
     }
+    /** Whether anything at all - a global listener or the entity itself - handles `event`. */
+    hasHook(entity, event) {
+        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.
      */
     async emitHook(entity, event, payloads) {
-        const listeners = this.extra?.listeners;
-        const meta = getMeta(entity);
-        const registrations = meta.hooks?.[event];
-        // Fast bail-out: skip if no listeners and no entity hooks
-        if (!listeners?.length && !registrations?.length)
+        if (!this.hasHook(entity, event))
             return;
-        // Fire global listeners first
-        if (listeners?.length) {
-            for (const listener of listeners) {
-                const fn = listener[event];
-                if (fn) {
-                    const result = fn({ entity, querier: this, payloads, event });
-                    if (result instanceof Promise)
-                        await result;
-                }
+        for (const listener of this.extra?.listeners ?? []) {
+            const fn = listener[event];
+            if (fn) {
+                const result = fn({ entity, querier: this, payloads, event });
+                if (result instanceof Promise)
+                    await result;
             }
         }
-        // Fire entity-level hooks
-        if (registrations?.length) {
-            await runHooks(entity, event, payloads, { querier: this });
-        }
+        await runHooks(entity, event, payloads, { querier: this });
     }
     /**
      * Runs `task` after everything already queued on this querier, one at a time.

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { ExtraOptions, IdValue, PoolRunOptions, Querier, QuerierPool, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, PoolRunOptions, Querier, QuerierPool, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -35,14 +35,14 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     findManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     updateOneById<E extends object>(entity: Type<E>, id: IdValue<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>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
-    saveOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E>>;
-    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E>>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;

package/dist/querier/abstractSharedHandleQuerierPool.d.ts

@@ -0,0 +1,42 @@
+import type { AbstractSqlDialect } from '../dialect/index.js';
+import type { SqlQuerier } from '../type/index.js';
+import { AbstractSqlQuerierPool } from './abstractSqlQuerierPool.js';
+/**
+ * Base pool for an engine that gives one connection per database and keeps it open for the pool's
+ * lifetime: every local SQLite driver, the embedded Turso engine, and PGlite.
+ *
+ * The handle is shared, but each acquisition gets its own querier, so transaction state stays per unit
+ * of work. That state is not *isolated*, which is the one way these differ from a real pool: there is a
+ * single connection under every querier, so two of them cannot hold independent transactions, and a
+ * unit of work that needs one needs its own pool and therefore its own database.
+ *
+ * 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, the way {@link AbstractPgQuerierPool}
+ * takes `buildQuerier` alone. The lazy open and the close were written out once per pool before, along
+ * with three partial copies of the paragraph above.
+ *
+ * @remarks Deliberately not re-exported from `querier/index.ts`, which the root entry point re-exports:
+ * only the three driver entries need this, and each imports it by path, as `postgres/abstractPgQuerier.ts`
+ * is imported.
+ */
+export declare abstract class AbstractSharedHandleQuerierPool<DB extends {
+    close(): unknown;
+}, Q extends SqlQuerier, D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<Q, D> {
+    /**
+     * The open, not the handle: `db ??= await openDb()` reads before the await and assigns after, so
+     * callers arriving while the first open is in flight each start one of their own. The extra handles
+     * are then unreachable and never closed, and on an in-memory database they are separate databases,
+     * so a querier built on one writes where nothing else will ever read.
+     */
+    private opening?;
+    /** Opens the one connection. Called on the first acquisition, and again after an {@link end}. */
+    protected abstract openDb(): Promise<DB>;
+    /** Wraps the shared handle in a querier: the only thing that varies between these pools. */
+    protected abstract buildQuerier(db: DB): Q;
+    getQuerier(): Promise<Q>;
+    end(): Promise<void>;
+}

package/dist/querier/abstractSharedHandleQuerierPool.js

@@ -0,0 +1,48 @@
+import { AbstractSqlQuerierPool } from './abstractSqlQuerierPool.js';
+/**
+ * Base pool for an engine that gives one connection per database and keeps it open for the pool's
+ * lifetime: every local SQLite driver, the embedded Turso engine, and PGlite.
+ *
+ * The handle is shared, but each acquisition gets its own querier, so transaction state stays per unit
+ * of work. That state is not *isolated*, which is the one way these differ from a real pool: there is a
+ * single connection under every querier, so two of them cannot hold independent transactions, and a
+ * unit of work that needs one needs its own pool and therefore its own database.
+ *
+ * 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, the way {@link AbstractPgQuerierPool}
+ * takes `buildQuerier` alone. The lazy open and the close were written out once per pool before, along
+ * with three partial copies of the paragraph above.
+ *
+ * @remarks Deliberately not re-exported from `querier/index.ts`, which the root entry point re-exports:
+ * only the three driver entries need this, and each imports it by path, as `postgres/abstractPgQuerier.ts`
+ * is imported.
+ */
+export class AbstractSharedHandleQuerierPool extends AbstractSqlQuerierPool {
+    /**
+     * The open, not the handle: `db ??= await openDb()` reads before the await and assigns after, so
+     * callers arriving while the first open is in flight each start one of their own. The extra handles
+     * are then unreachable and never closed, and on an in-memory database they are separate databases,
+     * so a querier built on one writes where nothing else will ever read.
+     */
+    opening;
+    async getQuerier() {
+        // Cleared on failure, so a driver that could not start once is retried rather than refused forever.
+        this.opening ??= this.openDb().catch((err) => {
+            this.opening = undefined;
+            throw err;
+        });
+        return this.buildQuerier(await this.opening);
+    }
+    async end() {
+        const opening = this.opening;
+        this.opening = undefined;
+        // An open still in flight is awaited rather than abandoned: closing is what releases its file or port.
+        // One that failed leaves nothing to close, and `getQuerier` already reported it to its own caller.
+        const db = await opening?.catch(() => undefined);
+        await db?.close();
+    }
+}

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
-import type { ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, 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 {
@@ -64,10 +64,12 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     private hydrateFields;
     protected internalCount<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): 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: E[]): Promise<IdValue<E>[]>;
+    internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
+    private settleIds;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     get hasOpenTransaction(): boolean;
     beginTransaction(opts?: TransactionOptions): Promise<void>;

package/dist/querier/abstractSqlQuerier.js

@@ -3,6 +3,14 @@ import { getMeta } from '../entity/index.js';
 import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, getRelationRequestSummary, isAutoIncrement, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
+/**
+ * Whether `q` picks a specific slice of the matching rows rather than all of them. A write that
+ * does has to settle those rows and name them: `ORDER BY`/`LIMIT` on an UPDATE or DELETE is MySQL's
+ * alone.
+ */
+function isPaged(q) {
+    return q.$sort !== undefined || q.$limit !== undefined || q.$skip !== undefined;
+}
 export class AbstractSqlQuerier extends AbstractQuerier {
     dialect;
     extra;
@@ -219,12 +227,30 @@ export class AbstractSqlQuerier extends AbstractQuerier {
     }
     async internalUpdateMany(entity, q, payload, opts) {
         payload = clone(payload);
+        // Settled first for the reason `internalDeleteMany` settles: `ORDER BY`/`LIMIT` on an UPDATE is
+        // MySQL's alone, so a paged update has to name the rows it picked.
+        let target = q;
+        if (isPaged(q)) {
+            const ids = await this.settleIds(entity, q, opts);
+            if (!ids.length) {
+                return 0;
+            }
+            target = { $where: ids };
+        }
         const ctx = this.dialect.createContext();
-        this.dialect.update(ctx, entity, q, payload, opts);
+        this.dialect.update(ctx, entity, target, payload, opts);
         const { changes = 0 } = await this.run(ctx.sql, ctx.values);
-        await this.updateRelations(entity, q, payload, opts);
+        await this.updateRelations(entity, target, payload, opts);
         return changes;
     }
+    /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
+    async settleIds(entity, q, opts) {
+        const meta = getMeta(entity);
+        const ctx = this.dialect.createContext();
+        this.dialect.find(ctx, entity, { ...q, $select: { [meta.id]: true } }, opts);
+        const founds = await this.all(ctx.sql, ctx.values);
+        return founds.map((it) => it[meta.id]);
+    }
     async upsertOne(entity, conflictPaths, payload) {
         return this.upsertMany(entity, conflictPaths, [payload]);
     }
@@ -252,8 +278,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         // parents' ids to find their children, and no engine but MySQL accepts `ORDER BY`/`LIMIT` on a
         // DELETE, so a paged delete has to name the rows it settled on. A plain predicate needs neither,
         // and there the round trip buys nothing: the statement can say what the caller already said.
-        const hasPagination = q.$sort !== undefined || q.$limit !== undefined || q.$skip !== undefined;
-        if (!hasPagination && !cascadesOnDelete(meta)) {
+        if (!isPaged(q) && !cascadesOnDelete(meta)) {
             const ctx = this.dialect.createContext();
             this.dialect.delete(ctx, entity, q, opts);
             const { changes = 0 } = await this.run(ctx.sql, ctx.values);
@@ -261,13 +286,10 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         // A hard delete also targets already-soft-deleted rows, so drop the soft-delete filter when finding ids.
         const findOpts = opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
-        const findCtx = this.dialect.createContext();
-        this.dialect.find(findCtx, entity, { ...q, $select: { [meta.id]: true } }, findOpts);
-        const founds = await this.all(findCtx.sql, findCtx.values);
-        if (!founds.length) {
+        const ids = await this.settleIds(entity, q, findOpts);
+        if (!ids.length) {
             return 0;
         }
-        const ids = founds.map((it) => it[meta.id]);
         // Children first: they hold the foreign key, so deleting the parent ahead of them is rejected
         // outright by any schema that declares the constraint without `ON DELETE CASCADE`.
         await this.deleteRelations(entity, ids, opts);

package/dist/sqlite/localSqliteQuerierPool.d.ts

@@ -1,4 +1,4 @@
-import { AbstractSqlQuerierPool } from '../querier/index.js';
+import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
 import type { ExtraOptions } from '../type/index.js';
 import { SqliteDialect } from './sqliteDialect.js';
 import { type SqliteDatabase, SqliteQuerier } from './sqliteQuerier.js';
@@ -12,20 +12,17 @@ export type LocalSqlitePoolOptions = {
     extensions?: readonly string[];
 };
 /**
- * Pool for a SQLite database opened in this process, whichever driver provides it.
+ * Pool for a SQLite database opened in this process, whichever driver provides it. SQLite gives one
+ * connection per file, so the shared-handle lifecycle is {@link AbstractSharedHandleQuerierPool}'s.
  *
- * The handle is shared - SQLite gives one connection per file - but each acquisition gets its own
- * querier, so transaction state stays per unit of work. Subclasses supply only {@link createDb}: the
- * lifecycle, and loading the extensions on the way up, are the same for `better-sqlite3`, `bun:sqlite`
- * and `node:sqlite`, and were written out once per pool before.
+ * Subclasses supply only {@link createDb}: loading the extensions on the way up is the same for
+ * `better-sqlite3`, `bun:sqlite` and `node:sqlite`, and was written out once per pool before.
  */
-export declare abstract class AbstractLocalSqliteQuerierPool<O extends LocalSqlitePoolOptions> extends AbstractSqlQuerierPool<SqliteQuerier, SqliteDialect> {
+export declare abstract class AbstractLocalSqliteQuerierPool<O extends LocalSqlitePoolOptions> extends AbstractSharedHandleQuerierPool<SqliteDatabase, SqliteQuerier, SqliteDialect> {
     readonly opts?: O | undefined;
-    private db?;
     constructor(opts?: O | undefined, extra?: ExtraOptions);
     /** Opens the driver's database. Extensions are loaded by the caller, not here. */
     protected abstract createDb(): Promise<SqliteDatabase>;
-    getQuerier(): Promise<SqliteQuerier>;
-    private openDb;
-    end(): Promise<void>;
+    protected openDb(): Promise<SqliteDatabase>;
+    protected buildQuerier(db: SqliteDatabase): SqliteQuerier;
 }

package/dist/sqlite/localSqliteQuerierPool.js

@@ -1,25 +1,19 @@
-import { AbstractSqlQuerierPool } from '../querier/index.js';
+import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
 import { SqliteDialect } from './sqliteDialect.js';
 import { SqliteQuerier } from './sqliteQuerier.js';
 /**
- * Pool for a SQLite database opened in this process, whichever driver provides it.
+ * Pool for a SQLite database opened in this process, whichever driver provides it. SQLite gives one
+ * connection per file, so the shared-handle lifecycle is {@link AbstractSharedHandleQuerierPool}'s.
  *
- * The handle is shared - SQLite gives one connection per file - but each acquisition gets its own
- * querier, so transaction state stays per unit of work. Subclasses supply only {@link createDb}: the
- * lifecycle, and loading the extensions on the way up, are the same for `better-sqlite3`, `bun:sqlite`
- * and `node:sqlite`, and were written out once per pool before.
+ * Subclasses supply only {@link createDb}: loading the extensions on the way up is the same for
+ * `better-sqlite3`, `bun:sqlite` and `node:sqlite`, and was written out once per pool before.
  */
-export class AbstractLocalSqliteQuerierPool extends AbstractSqlQuerierPool {
+export class AbstractLocalSqliteQuerierPool extends AbstractSharedHandleQuerierPool {
     opts;
-    db;
     constructor(opts, extra) {
         super(new SqliteDialect({ namingStrategy: extra?.namingStrategy }), extra);
         this.opts = opts;
     }
-    async getQuerier() {
-        this.db ??= await this.openDb();
-        return new SqliteQuerier(this.db, this.dialect, this.extra);
-    }
     async openDb() {
         const db = await this.createDb();
         for (const extension of this.opts?.extensions ?? []) {
@@ -27,8 +21,7 @@ export class AbstractLocalSqliteQuerierPool extends AbstractSqlQuerierPool {
         }
         return db;
     }
-    async end() {
-        await this.db?.close();
-        this.db = undefined;
+    buildQuerier(db) {
+        return new SqliteQuerier(db, this.dialect, this.extra);
     }
 }