uql-orm 0.65.1 → 0.67.0

package/dist/querier/abstractQuerier.d.ts

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