uql-orm 0.65.1 → 0.67.0

package/dist/type/entity.js

@@ -1,11 +1,28 @@
-/**
- * Allow to customize the name of the property that identifies an entity
- */
+/** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export const idKey = Symbol('idKey');
-/**
- * The one filter name uql registers itself, from `@Field({ softDelete })`. Four ends have to agree on
- * it and none would fail if they drifted: the field that registers it, the decorator that reserves
- * the name against a user's own filter, the hard delete that switches it off, and the bypass check
- * that lets it through on an entity which never declared one.
- */
+/** The filter `@Field({ softDelete })` registers, a name reserved against an entity's own filters. */
 export const SOFT_DELETE_FILTER = 'softDelete';
+/** Every SQL column type a field may declare, by family: the unions below and `columnFamily` both read it. */
+export const COLUMN_TYPES = {
+    numeric: [
+        'int',
+        'integer',
+        'tinyint',
+        'smallint',
+        'bigint',
+        'float',
+        'float4',
+        'float8',
+        'double',
+        'double precision',
+        'decimal',
+        'numeric',
+        'real',
+    ],
+    string: ['char', 'varchar', 'text', 'uuid'],
+    date: ['date', 'time', 'datetime', 'timestamp', 'timestamptz'],
+    json: ['json', 'jsonb'],
+    blob: ['blob', 'bytea'],
+    boolean: ['bool', 'boolean'],
+    vector: ['vector', 'halfvec', 'sparsevec'],
+};

package/dist/type/logger.d.ts

@@ -13,13 +13,7 @@ export interface Logger {
      * @param duration - The time it took to execute the query in milliseconds.
      */
     logQuery?(query: string, values?: unknown[], duration?: number): void;
-    /**
-     * Logs a slow query.
-     * @param query - The SQL query string.
-     * @param values - The parameters passed to the query (already redacted to `undefined`
-     * upstream, per `ExtraOptions.logValues`, when values shouldn't be logged).
-     * @param duration - The time it took to execute the query in milliseconds.
-     */
+    /** Logs a query that took longer than the threshold, its values `undefined` unless `logValues` is on. */
     logSlowQuery?(query: string, values?: unknown[], duration?: number): void;
     /**
      * Logs a warning.
@@ -50,11 +44,5 @@ export interface Logger {
  * Function type for backward compatibility with simple loggers.
  */
 export type LoggerFunction = (message: unknown, ...args: unknown[]) => void;
-/**
- * Options for configuring ORM logging.
- * - boolean: true to enable all logs with DefaultLogger, false to disable.
- * - LogLevel[]: enable specific log levels with DefaultLogger.
- * - Logger: use a custom logger implementation.
- * - LoggerFunction: use a custom function (backward compatibility).
- */
+/** How logging is configured: on or off, the levels to log, or a logger of your own. */
 export type LoggingOptions = boolean | LogLevel[] | Logger | LoggerFunction;

package/dist/type/migration.d.ts

@@ -94,21 +94,11 @@ export interface MigrationResult {
     readonly success: boolean;
     readonly error?: Error;
 }
-/**
- * A column as a statement describes one: {@link ColumnNode} with the engine's type spelling in place
- * of the canonical one, and without the graph links.
- *
- * Derived so a field the node gains reaches every path that renders a column. Listed field by field,
- * this dropped `enum` and then `generatedAs`, and a column added to an existing table arrived without
- * the constraint or the expression the entity declared.
- */
+/** A column as a statement renders one: a {@link ColumnNode} with the engine's type spelling and no graph links. */
 export interface ColumnSchema extends Omit<ColumnNode, 'type' | 'table' | 'referencedBy' | 'references'> {
     /**
-     * The engine's own type spelling, as introspection read it (`tinyint(1)`, `DATETIME`, `VARCHAR`).
-     * Deliberately not a {@link CanonicalType}: the diff has to compare what the engine would *store*,
-     * and several canonical types share one storage type per engine - an entity `boolean` is `TINYINT(1)`
-     * on MySQL and `INTEGER` on SQLite. Comparing canonical categories instead reports an alteration on
-     * every sync for those columns. Use `sqlToCanonical` to interpret it.
+     * The engine's own type spelling, `TINYINT(1)`, compared as stored: canonical types would differ where
+     * the engine stores them alike. `sqlToCanonical` reads it.
      */
     readonly type: string;
     /** Bounds introspection reports beside the type, where the engine states them separately. */
@@ -193,11 +183,8 @@ export interface SchemaDiff {
     readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
     /**
-     * The key the table has against the key the entity declares, set only when they differ.
-     *
-     * Compared by columns, never by name: the engine named the existing one, so requiring a derived
-     * name to match would rewrite the primary key of every table on the first migration after
-     * upgrading. `fromName` is what the database reported, and the only name a `DROP` can use.
+     * The table's key against the entity's, where their columns differ; `fromName` is the name the
+     * database reported, which is what a `DROP` needs.
      */
     readonly primaryKey?: {
         readonly from: string[];
@@ -259,13 +246,7 @@ export interface DropSchemaOptions {
  * Interface for generating DDL statements from entity metadata
  */
 export interface SchemaGenerator {
-    /**
-     * The whole schema for `entities`: every table, then the foreign keys between them.
-     *
-     * There is deliberately no per-entity counterpart. One entity means an AST holding one table, so every
-     * cross-entity foreign key has nothing to resolve against and is dropped: all three call sites that
-     * used to work that way emitted schemas with no referential integrity.
-     */
+    /** The whole schema for `entities`, tables then the foreign keys between them, which need every entity at once. */
     generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
     /**
      * Every `DROP TABLE` for `entities`, dependents first. The inverse of {@link generateCreateSchema},
@@ -307,21 +288,11 @@ export interface SchemaGenerator {
      */
     compileIndexPredicate(where: EntityWhereMeta<object>, entity: Type<object>, indexName: string): string;
     /**
-     * Compare an entity with a database table node and return the differences.
-     *
-     * `desiredAst` is the entity side, from {@link buildAST}, and must span every entity a foreign key
-     * on this table points at: a relation whose target is absent resolves to nothing, so the constraint
-     * reads as missing from both sides, which is a match and no statement. Defaults to this entity
-     * alone, which is right only where it has no relations.
+     * An entity's differences from its table. `desiredAst`, from {@link buildAST}, has to span every entity
+     * a foreign key here points at, or those keys read as matching.
      */
     diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
-    /**
-     * The entity side as an AST, to hand to every {@link diffSchema} of one run - building it per
-     * entity instead is quadratic in the number of entities.
-     *
-     * Optional because not every generator compares one: MongoDB has no foreign keys and diffs only
-     * indexes, so it neither implements this nor reads the argument.
-     */
+    /** The entities as one AST, built once per run for every {@link diffSchema}. Absent on MongoDB, which diffs only indexes. */
     buildAST?(entities: readonly Type<object>[]): SchemaAST;
     /**
      * The table's key: {@link resolveTableAlias} behind {@link resolveSchema}, which is how a

package/dist/type/querier.d.ts

@@ -16,11 +16,8 @@ export type IsolationLevel = 'read uncommitted' | 'read committed' | 'repeatable
  */
 export type TransactionOptions = {
     /**
-     * Applies to this transaction only.
-     *
-     * @remarks MySQL and MariaDB set it as a statement of its own ahead of `START TRANSACTION`, so a
-     * `START TRANSACTION` that then fails leaves the level applied to whatever the pooled connection
-     * runs next. Set it per transaction that needs it rather than relying on what a connection carries.
+     * Applies to this transaction only. The MySQL family sets it ahead of `START TRANSACTION`, where a
+     * failed start leaves it on the connection: set it per transaction that needs it.
      */
     readonly isolationLevel?: IsolationLevel;
 };
@@ -32,53 +29,37 @@ export type DialectName = SqlDialectName | 'mongodb';
  * what makes a typo'd query key report as itself rather than as a missing `$entity`.
  */
 export interface Querier extends UniversalQuerier {
-    /**
-     * Find one record. 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 many records. 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>[]>;
     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>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
-    /**
-     * Stream records as an async iterable, in both patterns, each with the relations and counts
-     * `findMany` reads. Fires no lifecycle hooks.
-     */
+    /** 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>>;
-    /**
-     * Find many records and count. Supports both 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]>;
     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>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
-    /**
-     * Count records. Supports both patterns.
-     */
+    /** Count records, the entity passed first or as the query's `$entity`. */
     count<E extends object>(q: QueryPage<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
     count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * Whether anything matches. Supports both patterns.
-     */
+    /** Whether anything matches, the entity passed first or as the query's `$entity`. */
     exists<E extends object>(q: QueryFilter<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<boolean>;
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;
-    /**
-     * Delete many records (soft-deletes when the entity has a soft-delete field, else removes them).
-     * Supports both entity-as-argument and entity-as-field patterns.
-     */
+    /** Delete many records, the entity passed first or as `$entity`; soft-deletes where the entity has a soft-delete field. */
     deleteMany<E extends object>(q: QuerySearch<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;

package/dist/type/querierPool.d.ts

@@ -13,25 +13,9 @@ export interface PoolRunOptions {
     readonly context?: UqlContext;
 }
 /**
- * Querier pool. Read the dialect id via `pool.dialect.dialectName` (see {@link AbstractDialect.dialectName}); queriers expose the same on `querier.dialect`.
- *
- * A pool is a {@link UniversalQuerier} too, so a function that runs queries takes that type and the
- * caller passes its own querier or the pool. `pool.op(...)` is exactly
- * `pool.withQuerier((querier) => querier.op(...))`, so two pool calls are two units of work; when they
- * must commit together, that is `transaction`.
- *
- * Acquiring per call is also what makes `Promise.all([pool.findMany(A, {}), pool.count(B, {})])` run on
- * separate connections, while the same calls inside one `withQuerier`/`transaction` share a pinned
- * connection and serialize. Single-connection backends (better-sqlite3, Bun sqlite, D1) stay correct
- * but always serialize.
- *
- * An enclosing `withContext` scopes pool calls (`security` filters apply), which is why they take no
- * per-call `context` option (unlike `withQuerier`/`transaction`).
- *
- * Pool calls take the entity-as-argument form only; the `{ $entity }` form needs a querier.
- *
- * @typeParam Q - Querier implementation returned from the pool.
- * @typeParam D - Concrete dialect class held by the pool.
+ * A pool of queriers, and a {@link UniversalQuerier} itself: each call runs on a querier of its own, so
+ * two calls are two units of work (use `transaction` to join them) and run in parallel where the backend
+ * has more than one connection. An enclosing `withContext` scopes its calls. The `{ $entity }` form needs a querier.
  */
 export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDialect = AbstractDialect> extends UniversalQuerier {
     /**
@@ -66,13 +50,7 @@ export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDial
      */
     end(): Promise<void>;
 }
-/**
- * SQL pool surface: adds the raw-SQL executors of {@link SqlQuerier} (`all`/`run`), with the same
- * connection-per-call semantics as the {@link QuerierPool} read helpers (see that doc for the
- * parallelism model and its single-connection caveat).
- *
- * Raw `all`/`run` bypass query generation, so they are **not** scoped by `security` filters/context.
- */
+/** A SQL pool, adding raw `all`/`run`, which no `security` filter scopes. */
 export interface SqlQuerierPool<Q extends SqlQuerier = SqlQuerier, D extends AbstractSqlDialect = AbstractSqlDialect> extends QuerierPool<Q, D>, Pick<SqlQuerier, 'all' | 'run'> {
 }
 /**

package/dist/type/query.d.ts

@@ -73,15 +73,8 @@ export type QueryPopulateRelationOptions<V> = IsMany<V> extends true ? RelationQ
     $required?: boolean;
 };
 /**
- * Ambient per-request context (e.g. `{ tenantId, userId, roles }`) resolved by parameterized
- * filters. Set with `withContext(ctx, cb)`. It's an `interface` (not a type alias) so you can type
- * your keys once via declaration merging and get them typed wherever context is read:
- *
- * ```ts
- * declare module 'uql-orm' {
- *   interface UqlContext { tenantId: number; userId: string }
- * }
- * ```
+ * The per-request context parameterized filters read, set with `withContext(ctx, cb)`. An interface,
+ * so its keys can be typed once: `declare module 'uql-orm' { interface UqlContext { tenantId: number } }`.
  */
 export interface UqlContext {
     [key: string]: unknown;
@@ -103,14 +96,18 @@ export type FilterOptions<E = unknown> = {
     readonly where: FilterWhere<E>;
     /** Applied to every query unless bypassed via `QueryOptions.filters`. Defaults to `true`. */
     readonly default?: boolean;
+} & ({
+    readonly security?: false;
+    /** What to do when {@link FilterOptions.where} returns `undefined`. Defaults to `skip`. */
+    readonly onMissing?: FilterOnMissing;
+} | {
     /**
      * Row-level-security filter: always applied (ignores `QueryOptions.filters` bypass) and
-     * AND-merged so a client `$where` on the same field can't override it.
+     * AND-merged so a client `$where` on the same field can't override it. It fails closed.
      */
-    readonly security?: boolean;
-    /** What to do when {@link where} returns `undefined`. Defaults to `skip`, or `throw` for `security`. */
-    readonly onMissing?: FilterOnMissing;
-};
+    readonly security: true;
+    readonly onMissing?: 'throw';
+});
 /**
  * direction for the sort.
  */
@@ -136,16 +133,9 @@ export type QuerySortByCount = {
     $count: QuerySortDirection;
 };
 /**
- * sort by map - supports field keys, JSON dot-notation paths (restricted to real JSON fields,
- * like `QueryWhere`), relation sort via nested objects, and vector similarity search on
- * `number[]` fields. `Vector` is what confines a vector search to the level the statement ranks:
- * the queried entity. A relation of it is joined in one row at a time, so there is nothing to rank
- * there - the SQL dialects throw, and MongoDB would quietly drop it, so this is its only guard.
- *
- * One mapped type over the three key sets rather than three intersected. The sets are disjoint - a
- * JSON path is dotted, and a field key cannot also be a relation key - and an assignability check
- * against an intersection is repeated per constituent, which made this the single most expensive
- * type in the package to check.
+ * A sort by fields, JSON paths, a to-one relation's fields, a to-many's `$count`, or a vector distance,
+ * which `Vector` confines to the queried entity. One mapped type over the key sets: an intersection is
+ * checked once per member, which made this the costliest type to check.
  */
 export type QuerySortMap<E, Vector extends boolean = true, K extends keyof E = FieldKey<E> | RelationKey<E>> = {
     [P in K]?: P extends RelationKey<E> ? IsMany<E[P]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[P]>, false> : Vector extends true ? NonNullable<E[P]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection;
@@ -225,25 +215,13 @@ export type Query<E> = {
      */
     $distinct?: boolean;
     /**
-     * take a row-level lock on the rows this query returns (`SELECT ... FOR UPDATE`). Needs an open
-     * transaction: outside one the statement commits and drops the lock before the caller can act on
-     * the rows, so it is rejected rather than emitted. Locks only the queried entity, never anything
-     * reached through `$populate`. SQL only; MongoDB and the SQLite family reject it.
-     *
-     * Declared here rather than on {@link QuerySearch}, which `update`/`delete` take: that placement
-     * is what keeps the clause off those statements at the type level.
+     * Lock the rows this query returns, `SELECT ... FOR UPDATE`, inside an open transaction: outside one
+     * it is refused, since the lock would drop before the rows are used. SQL only, and not the SQLite family.
      */
     $lock?: QueryLock;
     /**
-     * how many candidates an approximate-nearest-neighbour index explores before ranking, for a vector
-     * search. Higher trades speed for recall; the default is whatever the engine's own is, which is
-     * tuned for speed. Ignored where the search is exact (SQLite, libSQL and Turso scan every row) and
-     * where the field carries no ANN index, since there is nothing to widen.
-     *
-     * The units are the index's, not UQL's, so the number is not comparable across index types: it
-     * becomes `hnsw.ef_search` or `ivfflat.probes` on Postgres, `mhnsw_ef_search` on MariaDB, and
-     * `numCandidates` on MongoDB Atlas. On Postgres it needs an open transaction, since a `SET LOCAL`
-     * outside one applies to nothing.
+     * How many candidates an ANN index explores before ranking a vector search, in that index's own units
+     * (`hnsw.ef_search`, `numCandidates`...); ignored where the search is exact. Postgres needs a transaction.
      */
     $candidates?: number;
     /**
@@ -260,13 +238,8 @@ export type Query<E> = {
     $limit?: number;
 };
 /**
- * `Query`'s clauses grouped by the shape of their value - what a parser reading one off the wire and
- * a validator checking a relation's own query both need, and what each used to enumerate for itself.
- * Declared beside the type they describe so the two cannot drift, and `satisfies` fails the build
- * rather than the runtime if a clause is ever renamed.
- *
- * `$lock` is only in {@link QUERY_STATEMENT_CLAUSES}: neither a wire query nor a relation's query
- * accepts it.
+ * `Query`'s clauses grouped by the shape of their value, for the wire parser and the relation query
+ * check alike; `satisfies` keeps them in step with `Query`.
  */
 export declare const QUERY_OBJECT_CLAUSES: readonly ["$select", "$populate", "$exclude", "$where", "$sort"];
 /**
@@ -301,16 +274,8 @@ export type QueryOne<E> = Except<Query<E>, '$limit'>;
  */
 export type QueryUnique<E> = Pick<QueryOne<E>, '$select' | '$exclude' | '$populate' | '$where'>;
 /**
- * The clauses that decide a row's shape, captured from the query as written: the field names
- * `$select` and `$exclude` list, the value those maps carry (a falsy one subtracts instead of
- * selecting, as it does at runtime, and a widened map is how a projection that is not statically
- * known announces itself), and the relation names `$populate` lists.
- *
- * Each is captured as a *key set* rather than as the map itself, which is what keeps the checks
- * intact: TypeScript skips excess-property checking on a naked type parameter, so a captured map
- * would take a typo'd key without a word, while a captured key set makes that typo fail its own
- * `FieldKey<E>` / `RelationKey<E>` constraint. Every other clause - `$where`, `$sort`, and each
- * populated relation's own query - stays the concrete {@link Query} it is today.
+ * The clauses that shape a row, captured as key sets rather than maps: a naked type parameter skips
+ * excess-property checks, while a key set fails its own constraint on a typo.
  * @internal
  */
 type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = {
@@ -328,10 +293,8 @@ export type QueryProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P
  */
 export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never> = QueryOne<E> & QueryProjection<E, S, V, X, P, C>;
 /**
- * The keys a query comes back with, mirroring what the runtime projects: the fields a positive
- * `$select` names, or every field minus what a falsy `$select` entry or a truthy `$exclude` entry
- * subtracts, plus the relations `$populate` asked for. A positive `$select` wins outright, which is
- * why `$exclude` is only read on the branch where there is none.
+ * The keys a query comes back with, as the runtime projects them: a positive `$select`'s, or every
+ * field minus what `$select` or `$exclude` subtracts, plus the populated relations.
  * @internal
  */
 type ProjectedKeys<E, S, V, X, P> = ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S) | P;
@@ -341,16 +304,9 @@ type ProjectedKeys<E, S, V, X, P> = ([V] extends [false | 0] ? Exclude<FieldKey<
  */
 type IsUniform<V> = [V] extends [true | 1] ? true : [V] extends [false | 0] ? true : false;
 /**
- * A row of a find result: the entity narrowed to the fields the query projected, plus the relations
- * it populated - reading anything the query left out is a compile error rather than a silent
- * `undefined`. Modifiers are preserved, so an optional field stays optional. Name a projected row
- * with it where a helper has to take one: `QueryFindResult<User, 'id' | 'name'>`.
- *
- * The entity itself when the query projects nothing, when it uses a raw-projection array (columns,
- * not fields), and when the projection is not uniform - a `Query<E>` built elsewhere, or a map
- * mixing selected and subtracted entries, whose positive keys inference cannot recover. Relations
- * keep their declared type: narrowing them means capturing their queries as maps, which costs those
- * queries their own checks.
+ * A find's row: the entity narrowed to what the query projected and populated, so reading anything
+ * else does not compile. The entity itself where the projection is raw, absent or not uniform.
+ * @example `QueryFindResult<User, 'id' | 'name'>`
  */
 export type QueryFindResult<E, S extends FieldKey<E> = never, V = true, X extends FieldKey<E> = never, P extends RelationKey<E> = never, C extends RelationKey<E> = never> = QueryProjectedRow<E, S, V, X, P, C> & CountedRelations<C>;
 /**
@@ -375,13 +331,7 @@ type PopulatedToMany<E, P> = Extract<P, ToManyRelationKey<E>>;
 export type QueryStringified = {
     [K in keyof Query<unknown>]?: string;
 };
-/**
- * What upserting one row reports, against the entity rather than the driver.
- *
- * `created` is here and not on {@link QueryUpsertManyResult} because it is only ever knowable for a
- * single statement: a batch's `affectedRows` is a weighted sum on the dialects that report one at
- * all, and a batch of mixed shapes is several statements.
- */
+/** What upserting one row reports. `created` is only knowable for a single statement, so a batch has none. */
 export type QueryUpsertOneResult<E> = {
     readonly id?: WrittenId<E>;
     readonly changes?: number;

package/dist/type/query.js

@@ -4,13 +4,8 @@
  */
 export const COUNT_RESULT_KEY = '_count';
 /**
- * `Query`'s clauses grouped by the shape of their value - what a parser reading one off the wire and
- * a validator checking a relation's own query both need, and what each used to enumerate for itself.
- * Declared beside the type they describe so the two cannot drift, and `satisfies` fails the build
- * rather than the runtime if a clause is ever renamed.
- *
- * `$lock` is only in {@link QUERY_STATEMENT_CLAUSES}: neither a wire query nor a relation's query
- * accepts it.
+ * `Query`'s clauses grouped by the shape of their value, for the wire parser and the relation query
+ * check alike; `satisfies` keeps them in step with `Query`.
  */
 export const QUERY_OBJECT_CLAUSES = [
     '$select',

package/dist/type/queryAggregate.d.ts

@@ -1,21 +1,8 @@
 import type { FieldKey } from './entity.js';
 import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
 import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
-/**
- * Maps the offending keys to `never`, turning an excess key into a compile error; resolves to
- * `unknown` (an inert intersection member) when there are none. Needed because `$group`/`$select` are
- * captured as whole maps, and TypeScript skips excess-property checking on a naked type parameter.
- * A find captures key sets instead, where an unknown key fails the capture's own constraint.
- * @internal
- */
-type Reject<K> = [K] extends [never] ? unknown : Record<K & string, never>;
-/**
- * The columns `$group` actually names: keys whose value is literally `true`, not `keyof G`.
- * Wherever `G` cannot be inferred - `$group` omitted, hoisted, or annotated - it *is* its own
- * constraint, whose every value is `true | undefined`, and keying off values yields `never` there
- * rather than every field of the entity.
- * @internal
- */
+import type { RejectKeys } from './utility.js';
+/** The columns `$group` names by a literal `true`, so an uninferred `$group`, its own constraint, names none. */
 type GroupedKeys<G> = {
     [K in keyof G]: G[K] extends true ? K : never;
 }[keyof G];
@@ -95,15 +82,8 @@ type TotallingOp = OpsOf<'$sum' | '$avg' | '$sumDistinct' | '$avgDistinct'>;
  */
 type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, QueryFieldRef<E, NumericFieldKey<E>>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, QueryFieldRef<E>>;
 /**
- * An aggregate function applied to a field. Exactly one operation per entry (a second op is a
- * compile error). Only `$count` accepts `'*'` (i.e. `COUNT(*)`); every other op requires a field.
- * DISTINCT variants are flat ops (`$countDistinct`/`$sumDistinct`/`$avgDistinct`) taking a field.
- *
- * @example { $count: '*' }                    -> COUNT(*)
- * @example { $countDistinct: { id: true } }   -> COUNT(DISTINCT "id")
- * @example { $sum: { amount: true } }         -> SUM("amount")
- * @example { $sumDistinct: { amount: true } } -> SUM(DISTINCT "amount")
- * @example { $avg: { age: true } }            -> AVG("age")
+ * An aggregate over one field, exactly one op per entry: `{ $sum: { amount: true } }` is `SUM("amount")`,
+ * `{ $countDistinct: { id: true } }` is `COUNT(DISTINCT "id")`, and only `$count` takes `'*'`.
  */
 export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>>;
 /** A single-key `{ [op]: unknown }` shape for each op in `Ops`, matched to infer that op's result. */
@@ -114,44 +94,17 @@ type FnWithOp<Ops extends string> = {
 }[Ops];
 /** Ops that count rows. Alone among the ops they answer `0`, never NULL, over an empty group. */
 type CountingOp = OpsOf<'$count' | '$countDistinct'>;
-/**
- * Group-by columns: an object mapping entity field keys to `true`, exactly like {@link QuerySelect}.
- * Typed against the entity, so a typo'd column is a compile error. Compute aggregate columns with
- * {@link QueryAggMap} (the `$select` key), not here.
- *
- * @example
- * ```ts
- * { status: true } // -> GROUP BY "status"
- * ```
- */
+/** The columns to group by, `{ status: true }`, typed against the entity like `$select`. */
 export type QueryGroupMap<E> = Readonly<QuerySelect<E, FieldKey<E>, true>>;
-/**
- * Computed aggregate columns: an object mapping your chosen output alias to an aggregate function.
- * Alias names are free (you are naming new columns); the aggregated field reference inside each
- * function is typed against the entity.
- *
- * @example
- * ```ts
- * { count: { $count: '*' }, avgAge: { $avg: { age: true } } }
- * // -> COUNT(*) AS "count", AVG("age") AS "avgAge"
- * ```
- */
+/** Computed columns by the alias each is read back under: `{ count: { $count: '*' }, avgAge: { $avg: { age: true } } }`. */
 export type QueryAggMap<E> = {
     readonly [alias: string]: QueryAggregateFn<E>;
 };
 /** The entity type of an aggregated field reference `F`, or `unknown` if it is not a known field. */
 type FieldValueType<E, F> = F extends keyof E ? E[F] : unknown;
 /**
- * Resolves a single computed column's type from its aggregate function: `$count` is always
- * `number`; `$sum`/`$avg` total to a `number` or to `null`; `$min`/`$max` keep the aggregated
- * field's own type, likewise or `null`.
- *
- * Everything but `$count` is nullable: an aggregate over zero rows is NULL, and an ungrouped one
- * still returns a row, so a `$where` matching nothing hands back a row of NULLs.
- *
- * `$sum`/`$avg` are exact to 2^53: Postgres widens a sum over BIGINT to NUMERIC, and decoding that
- * text to satisfy this `number` drops the digits past that bound. Use `raw()` for a wider total.
- * @internal
+ * A computed column's type: a count is a `number`; every other aggregate is `null` over no rows, a
+ * total a `number` (exact to 2^53, `raw` beyond) and `$min`/`$max` the field's own type.
  */
 type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number : Fn extends FnWithOp<TotallingOp> ? number | null : Fn extends {
     readonly $min: infer F;
@@ -165,40 +118,17 @@ type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number :
 type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
-/**
- * Infers the aggregated result row: grouped columns (`G`) keep their entity type; computed columns
- * (`A`) resolve from their aggregate function via {@link QueryAggregateFnResult}.
- *
- * Grouped columns come from {@link GroupedKeys}, not `keyof G`, so a `$group` the compiler could
- * not read contributes none rather than all of them.
- */
+/** An aggregate's row: each grouped column with its entity type, each computed one with its aggregate's. */
 export type QueryAggregateResult<E, G, A> = Simplify<Pick<E, GroupedKeys<G> & FieldKey<E>> & {
     -readonly [K in keyof A]: QueryAggregateFnResult<E, A[K]>;
 }>;
-/**
- * Erased runtime shape of a HAVING clause (alias -> comparison), consumed by the dialect builders.
- * Values are `unknown` because the SQL is built generically; the typed, per-column value checking
- * lives in {@link QueryAggregate.$having}.
- *
- * @example { count: { $gt: 5 } }   -> HAVING COUNT(*) > 5
- */
+/** A `HAVING` as the dialects read it, erased; {@link QueryAggregate.$having} is where it is typed. `{ count: { $gt: 5 } }` */
 export type QueryHavingMap = {
     readonly [alias: string]: QueryWhereFieldValue<unknown> | undefined;
 };
 /**
- * Aggregate query - separate from `Query<E>` to keep return types honest.
- * Used exclusively with `querier.aggregate()`.
- *
- * @example
- * ```ts
- * querier.aggregate(User, {
- *   $where: { deletedAt: { $isNull: true } },
- *   $group: { status: true },
- *   $select: { count: { $count: '*' }, avgAge: { $avg: { age: true } } },
- *   $having: { count: { $gt: 5 } },
- *   $sort: { count: -1 },
- * });
- * ```
+ * An aggregate query, apart from `Query` so its row type stays honest:
+ * `aggregate(User, { $group: { status: true }, $select: { n: { $count: '*' } }, $having: { n: { $gt: 5 } } })`.
  */
 export type QueryAggregate<E, G extends QueryGroupMap<E> = QueryGroupMap<E>, A extends QueryAggMap<E> = QueryAggMap<E>> = {
     /**
@@ -207,29 +137,19 @@ export type QueryAggregate<E, G extends QueryGroupMap<E> = QueryGroupMap<E>, A e
     readonly $where?: QueryWhere<E>;
     /**
      * Columns to group by - `{ status: true }`, typed against the entity like `$select`. A computed
-     * aggregate wrongly placed here (it belongs in `$select`) is rejected via {@link Reject}, since
+     * aggregate wrongly placed here (it belongs in `$select`) is rejected via {@link RejectKeys}, since
      * `$group` is captured as a generic and a bare generic skips excess-property checking. The captured
      * map meets its schema, {@link QueryGroupMap}, so each key keeps its link to the entity property.
      */
-    readonly $group?: G & QueryGroupMap<E> & Reject<Exclude<keyof G, FieldKey<E>>>;
+    readonly $group?: G & QueryGroupMap<E> & RejectKeys<Exclude<keyof G, FieldKey<E>>>;
     /**
-     * Computed aggregate columns - `{ count: { $count: '*' }, avgAge: { $avg: { age: true } } }`. The
-     * captured map meets its schema over the same aliases, as `$group` does, so field keys stay linked
-     * (a `Record<keyof A, ...>` spelling of the same type breaks the inference of `A`).
-     *
-     * An alias repeating a `$group` column is rejected: both would be emitted under that one name,
-     * leaving the driver to keep whichever it read last.
+     * The computed columns by alias, the captured map meeting its schema so field keys stay linked. An alias
+     * repeating a `$group` column is refused, since both would come back under one name.
      */
     readonly $select?: A & {
         readonly [K in keyof A]: QueryAggregateFn<E>;
-    } & Reject<NamedKeys<A> & GroupedKeys<G>>;
-    /**
-     * Post-aggregation filtering, applied after grouping (SQL `HAVING`, MongoDB post-group `$match`).
-     * Keyed by the result columns (grouped columns + computed aliases), and each value is typed to that
-     * column's result type - a `$min`/`$max` over a `Date` field compares against a `Date`, a grouped
-     * column against its own type - reusing {@link QueryAggregateResult}. A name that is neither is a
-     * compile error.
-     */
+    } & RejectKeys<NamedKeys<A> & GroupedKeys<G>>;
+    /** Filtering after grouping, by a result column, each value typed as that column is. */
     readonly $having?: {
         readonly [K in keyof QueryAggregateResult<E, G, A>]?: QueryWhereFieldValue<QueryAggregateResult<E, G, A>[K]>;
     };