uql-orm 0.50.0 → 0.52.0

package/dist/mssql/mssqlQuerierPool.js

@@ -0,0 +1,32 @@
+import { ConnectionPool } from 'mssql';
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
+import { AbstractSqlQuerierPool } from '../querier/index.js';
+import { MsSqlDialect } from './mssqlDialect.js';
+import { MsSqlQuerier } from './mssqlQuerier.js';
+export class MsSqlQuerierPool extends AbstractSqlQuerierPool {
+    pool;
+    #connected;
+    constructor(opts, extra) {
+        super(new MsSqlDialect(dialectOptionsFrom(extra)), extra);
+        this.pool = new ConnectionPool(opts);
+    }
+    /**
+     * `mssql` connects the pool as a whole rather than per checkout, so the promise is shared. A
+     * failed one is dropped rather than kept: memoized, a single transient failure would be handed to
+     * every later caller for the life of the pool.
+     */
+    async getQuerier() {
+        return new MsSqlQuerier(() => this.#connect(), this.dialect, this.extra);
+    }
+    #connect() {
+        this.#connected ??= this.pool.connect().catch((err) => {
+            this.#connected = undefined;
+            throw err;
+        });
+        return this.#connected;
+    }
+    async end() {
+        this.#connected = undefined;
+        await this.pool.close();
+    }
+}

package/dist/mssql/mssqlWireTypes.d.ts

@@ -0,0 +1,23 @@
+/** The column metadata `tedious` reports beside a recordset, narrowed to the one field read here. */
+type ColumnTypes = Record<string, {
+    readonly type: unknown;
+}>;
+/**
+ * Decode `BIGINT` as a JS number, leaving every other type to the driver.
+ *
+ * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
+ * `schema/canonicalType.ts`), and `tedious` hands that back as a string to protect the digits past
+ * 2^53 - so without this a field declared `number` reads back as `'9'`, including every generated
+ * primary key on every entity.
+ *
+ * At the wire, for the reason `pgNumericTypes` gives: everything crosses it exactly once - entity
+ * reads, the ids an `OUTPUT` reports, raw SQL, counts, aggregates - where the ORM's own hydration
+ * only ever sees entity reads.
+ *
+ * Exact to 2^53, which covers any generated id. A value past it keeps the string the driver gave,
+ * because a number could no longer represent it: that is the one case where handing back the exact
+ * text is more useful than handing back the type that was asked for. The lighter escape hatch for a
+ * column that big is the declaration - `@Field({ type: String, columnType: 'bigint' })`.
+ */
+export declare function decodeWireTypes<T>(rows: T[] | undefined, columns: ColumnTypes | undefined): T[];
+export {};

package/dist/mssql/mssqlWireTypes.js

@@ -0,0 +1,44 @@
+/**
+ * Decode `BIGINT` as a JS number, leaving every other type to the driver.
+ *
+ * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
+ * `schema/canonicalType.ts`), and `tedious` hands that back as a string to protect the digits past
+ * 2^53 - so without this a field declared `number` reads back as `'9'`, including every generated
+ * primary key on every entity.
+ *
+ * At the wire, for the reason `pgNumericTypes` gives: everything crosses it exactly once - entity
+ * reads, the ids an `OUTPUT` reports, raw SQL, counts, aggregates - where the ORM's own hydration
+ * only ever sees entity reads.
+ *
+ * Exact to 2^53, which covers any generated id. A value past it keeps the string the driver gave,
+ * because a number could no longer represent it: that is the one case where handing back the exact
+ * text is more useful than handing back the type that was asked for. The lighter escape hatch for a
+ * column that big is the declaration - `@Field({ type: String, columnType: 'bigint' })`.
+ */
+export function decodeWireTypes(rows, columns) {
+    if (!rows?.length || !columns) {
+        return rows ?? [];
+    }
+    const wide = Object.keys(columns).filter((name) => typeName(columns[name]?.type) === 'BigInt');
+    if (!wide.length) {
+        // The overwhelmingly common case, so an ordinary read copies nothing.
+        return rows;
+    }
+    return rows.map((row) => {
+        const decoded = { ...row };
+        for (const name of wide) {
+            const value = decoded[name];
+            if (typeof value === 'string') {
+                const asNumber = Number(value);
+                if (Number.isSafeInteger(asNumber)) {
+                    decoded[name] = asNumber;
+                }
+            }
+        }
+        return decoded;
+    });
+}
+/** `tedious` reports a column's type as its factory function, whose `name` is the type's own. */
+function typeName(type) {
+    return typeof type === 'function' ? type.name : undefined;
+}

package/dist/pglite/pgliteQuerier.d.ts

@@ -21,8 +21,8 @@ export type PgliteDatabase = {
  * 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
+ * hands a `pg-query-stream` object to `query()`, which PGlite's client has no equivalent of - so
+ * streaming pages the rows in SQL instead. `BEGIN`/`COMMIT` are plain statements on the single
  * connection, leaving transactions to the base class.
  */
 export declare class PgliteQuerier extends AbstractSqlQuerier {
@@ -31,6 +31,8 @@ export declare class PgliteQuerier extends AbstractSqlQuerier {
     constructor(db: PgliteDatabase, dialect: PgliteDialect, extra?: ExtraOptions | undefined);
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
+    /** Postgres compiled to WASM is still Postgres: `DECLARE`/`FETCH` streams what the client cannot. */
+    protected internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, any>;
     /** The handle belongs to the pool, which hands out one querier per unit of work over it. */
     internalRelease(): Promise<void>;
 }

package/dist/pglite/pgliteQuerier.js

@@ -1,10 +1,11 @@
+import { streamViaCursor } from '../postgres/pgCursorStream.js';
 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
+ * hands a `pg-query-stream` object to `query()`, which PGlite's client has no equivalent of - so
+ * streaming pages the rows in SQL instead. `BEGIN`/`COMMIT` are plain statements on the single
  * connection, leaving transactions to the base class.
  */
 export class PgliteQuerier extends AbstractSqlQuerier {
@@ -25,6 +26,10 @@ export class PgliteQuerier extends AbstractSqlQuerier {
         // 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 });
     }
+    /** Postgres compiled to WASM is still Postgres: `DECLARE`/`FETCH` streams what the client cannot. */
+    async *internalStream(query, values) {
+        yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, this.hasOpenTransaction);
+    }
     /** The handle belongs to the pool, which hands out one querier per unit of work over it. */
     async internalRelease() { }
 }

package/dist/postgres/pgCursorStream.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Runs one statement of the cursor protocol. `internalAll` for every caller so far: the cursor holds
+ * a connection's session state, so it must be the querier's own connection, and it must not go
+ * through `all()`, whose `serialize` is not re-entrant.
+ */
+export type CursorExecutor<T> = (query: string, values?: unknown[]) => Promise<T[]>;
+/**
+ * Stream a Postgres-wire result through a server-side cursor, for a driver whose client exposes none:
+ * `bun:sql` (no cursor API at all, [oven-sh/bun#17181](https://github.com/oven-sh/bun/issues/17181))
+ * and PGlite. `pg` has `pg-query-stream` and keeps using it.
+ *
+ * `DECLARE` is only legal inside a transaction, so one is opened here when the caller has none - and
+ * then committed, or rolled back if the stream failed. That `BEGIN` goes straight to the connection
+ * rather than through `beginTransaction`, so the querier's own transaction state stays untouched:
+ * this one is the generator's, and ends with it.
+ *
+ * The cleanup lives in `finally` because a consumer that stops early (`break`, a `throw` downstream)
+ * ends the generator there and nowhere else, and an abandoned cursor holds its transaction open.
+ */
+export declare function streamViaCursor<T>(exec: CursorExecutor<T>, query: string, values?: unknown[], inTransaction?: boolean): AsyncIterable<T>;

package/dist/postgres/pgCursorStream.js

@@ -0,0 +1,49 @@
+/** The cursor a stream declares. Suffixed per call, so two streams on one connection cannot collide. */
+const CURSOR_ALIAS = '_uql_cursor';
+/** Rows per round trip, matching `pg-query-stream`'s own default so both paths read the same. */
+const FETCH_SIZE = 100;
+let cursorSeq = 0;
+/**
+ * Stream a Postgres-wire result through a server-side cursor, for a driver whose client exposes none:
+ * `bun:sql` (no cursor API at all, [oven-sh/bun#17181](https://github.com/oven-sh/bun/issues/17181))
+ * and PGlite. `pg` has `pg-query-stream` and keeps using it.
+ *
+ * `DECLARE` is only legal inside a transaction, so one is opened here when the caller has none - and
+ * then committed, or rolled back if the stream failed. That `BEGIN` goes straight to the connection
+ * rather than through `beginTransaction`, so the querier's own transaction state stays untouched:
+ * this one is the generator's, and ends with it.
+ *
+ * The cleanup lives in `finally` because a consumer that stops early (`break`, a `throw` downstream)
+ * ends the generator there and nowhere else, and an abandoned cursor holds its transaction open.
+ */
+export async function* streamViaCursor(exec, query, values, inTransaction = false) {
+    const cursor = `${CURSOR_ALIAS}_${++cursorSeq}`;
+    const ownsTransaction = !inTransaction;
+    if (ownsTransaction) {
+        await exec('BEGIN');
+    }
+    let failed = false;
+    try {
+        await exec(`DECLARE ${cursor} CURSOR FOR ${query}`, values);
+        for (;;) {
+            const rows = await exec(`FETCH FORWARD ${FETCH_SIZE} FROM ${cursor}`);
+            yield* rows;
+            if (rows.length < FETCH_SIZE) {
+                return;
+            }
+        }
+    }
+    catch (err) {
+        failed = true;
+        throw err;
+    }
+    finally {
+        // Best-effort once the stream has failed: an error raised here would replace the one that brought
+        // us here, which is the one worth reporting, and the rollback discards the cursor either way.
+        const end = failed ? (sql) => exec(sql).catch(() => []) : exec;
+        await end(`CLOSE ${cursor}`);
+        if (ownsTransaction) {
+            await end(failed ? 'ROLLBACK' : 'COMMIT');
+        }
+    }
+}

package/dist/postgres/pgDialect.d.ts

@@ -4,7 +4,7 @@ import { PostgresDialect } from './postgresDialect.js';
  *
  * @remarks Uses base {@link PostgresDialect} capabilities: native JS arrays for `ANY` / `ALL`
  * (`nativeArrays: true`) and `$n::jsonb` without a text re-cast. Bun SQL Postgres needs
- * `BunSqlPostgresDialect` from `uql-orm/bunSql` instead (wire array literals + text json cast).
+ * `BunSqlQuerierPool` from `uql-orm/bunSql` instead (wire array literals + text json cast).
  */
 export declare class PgDialect extends PostgresDialect {
 }

package/dist/postgres/pgDialect.js

@@ -4,7 +4,7 @@ import { PostgresDialect } from './postgresDialect.js';
  *
  * @remarks Uses base {@link PostgresDialect} capabilities: native JS arrays for `ANY` / `ALL`
  * (`nativeArrays: true`) and `$n::jsonb` without a text re-cast. Bun SQL Postgres needs
- * `BunSqlPostgresDialect` from `uql-orm/bunSql` instead (wire array literals + text json cast).
+ * `BunSqlQuerierPool` from `uql-orm/bunSql` instead (wire array literals + text json cast).
  */
 export class PgDialect extends PostgresDialect {
 }

package/dist/postgres/postgresWireDriverCapabilities.d.ts

@@ -1,19 +1,21 @@
 /**
- * Wire-style parameter shaping for **Bun SQL** (and similar clients) on any Postgres-wire dialect:
- * arrays are sent as string literals (`nativeArrays: false`) via {@link PgLikeSqlDialect}'s
- * `toPgArray` path.
+ * Driver-shaped parameter handling for **Bun SQL** (and any client like it) on a Postgres-wire
+ * dialect: arrays go as string literals (`nativeArrays: false`, {@link PgLikeSqlDialect}'s `toPgArray`
+ * path) and a JSON bind is re-cast through text (`explicitJsonCast: true`). Both are measured, on a
+ * live server: `bun:sql` binds neither `sql.array(...)` nor a plain JS array through `unsafe()`
+ * (verified again on Bun 1.4.2), and without the text re-cast a `$set`/`$push` on a JSONB column
+ * silently writes the wrong value or throws - on Postgres and, identically, on CockroachDB, which
+ * `bun:sql` reaches through its own Postgres wire implementation.
  *
- * `PgDialect` does **not** use this constant - it keeps base {@link PgLikeSqlDialect} defaults
- * (`nativeArrays: true`, `explicitJsonCast: false`), since node-`pg` doesn't need the fix.
- * `BunSqlPostgresDialect` and `BunSqlCockroachDialect` both spread this and set
- * `explicitJsonCast: true` - `bun:sql` routes CockroachDB through its own Postgres wire-protocol
- * implementation (see `bunSql.util.ts#normalizeBunOpts`), so it needs the identical fix: verified
- * directly that without it, `$set`/`$push` on a JSONB column silently produce the wrong value
- * or throw on a live CockroachDB instance.
+ * 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
+ * {@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.
  */
 export declare const POSTGRES_WIRE_DRIVER_CAPABILITIES: {
     readonly nativeArrays: false;
+    readonly explicitJsonCast: true;
 };

package/dist/postgres/postgresWireDriverCapabilities.js

@@ -1,19 +1,21 @@
 /**
- * Wire-style parameter shaping for **Bun SQL** (and similar clients) on any Postgres-wire dialect:
- * arrays are sent as string literals (`nativeArrays: false`) via {@link PgLikeSqlDialect}'s
- * `toPgArray` path.
+ * Driver-shaped parameter handling for **Bun SQL** (and any client like it) on a Postgres-wire
+ * dialect: arrays go as string literals (`nativeArrays: false`, {@link PgLikeSqlDialect}'s `toPgArray`
+ * path) and a JSON bind is re-cast through text (`explicitJsonCast: true`). Both are measured, on a
+ * live server: `bun:sql` binds neither `sql.array(...)` nor a plain JS array through `unsafe()`
+ * (verified again on Bun 1.4.2), and without the text re-cast a `$set`/`$push` on a JSONB column
+ * silently writes the wrong value or throws - on Postgres and, identically, on CockroachDB, which
+ * `bun:sql` reaches through its own Postgres wire implementation.
  *
- * `PgDialect` does **not** use this constant - it keeps base {@link PgLikeSqlDialect} defaults
- * (`nativeArrays: true`, `explicitJsonCast: false`), since node-`pg` doesn't need the fix.
- * `BunSqlPostgresDialect` and `BunSqlCockroachDialect` both spread this and set
- * `explicitJsonCast: true` - `bun:sql` routes CockroachDB through its own Postgres wire-protocol
- * implementation (see `bunSql.util.ts#normalizeBunOpts`), so it needs the identical fix: verified
- * directly that without it, `$set`/`$push` on a JSONB column silently produce the wrong value
- * or throw on a live CockroachDB instance.
+ * 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
+ * {@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.
  */
 export const POSTGRES_WIRE_DRIVER_CAPABILITIES = {
     nativeArrays: false,
+    explicitJsonCast: true,
 };

package/dist/querier/abstractQuerier.d.ts

@@ -1,9 +1,5 @@
-import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, 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, 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.
- * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
- */
 export declare abstract class AbstractQuerier implements Querier {
     readonly extra?: ExtraOptions | undefined;
     /**
@@ -129,8 +125,8 @@ export declare abstract class AbstractQuerier implements Querier {
      * 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.
      */
-    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>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
     protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;

package/dist/querier/abstractQuerier.js

@@ -43,6 +43,19 @@ function soleParentColumn(relOpts) {
  * Base class for all database queriers.
  * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
  */
+/**
+ * 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.
+ */
+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));
+}
 export class AbstractQuerier {
     extra;
     /**
@@ -207,10 +220,17 @@ 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], () => this.internalUpsertOne(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);
+            return { id, changes, created };
+        });
     }
     async upsertMany(entity, conflictPaths, payload) {
-        return this.hooked(entity, 'Upsert', payload, () => this.internalUpsertMany(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 };
+        });
     }
     async deleteOneById(entity, id, opts) {
         assertIdValue(entity, id);

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -41,8 +41,8 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     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>;
-    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>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
     saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
     saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;