uql-orm 0.68.1 → 0.70.0

package/dist/entity/metadata/definition.js

@@ -1,4 +1,4 @@
-import { SOFT_DELETE_FILTER } from '../../type/index.js';
+import { RelationAggregate, SOFT_DELETE_FILTER } from '../../type/index.js';
 import { isInlinedExpression } from '../../util/field.util.js';
 import { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, memberRefs, normalizeIndexColumn, definedEntries, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
@@ -17,6 +17,14 @@ function globalMap(key) {
 const metas = globalMap('uql-orm/entity/metadata/v1');
 export function defineField(entity, key, opts = {}) {
     const meta = ensureWritableMeta(entity);
+    const { computed, ...rest } = opts;
+    const sql = computed === undefined ? undefined : entitySql(computed);
+    // A relation aggregate reads as a correlated subquery, which no engine accepts in a generated column:
+    // keeping one on the row takes the triggers a write fires, which are not built yet.
+    if (opts.stored && sql instanceof RelationAggregate) {
+        throw new TypeError(`'${entity.name}.${key}' cannot be 'stored': a relation aggregate reads as a subquery, which no ` +
+            "engine keeps in a generated column. Drop 'stored' to have it read on each query.");
+    }
     // A stored computed column is a real column and still needs a type; only an inlined one is exempt,
     // its expression being spliced in rather than declared.
     if (!opts.type && !opts.references && !isInlinedExpression(opts)) {
@@ -31,13 +39,12 @@ export function defineField(entity, key, opts = {}) {
     // Flagged when the author gave `references` but no `type`, so schema generation knows to resolve the
     // column from the referenced primary key (picking up its `columnType`, length and chained keys)
     // instead of treating whatever ends up in `type` as deliberate.
-    const { computed, ...rest } = opts;
     const resolved = rest.type ? rest : { ...rest, typeFromReference: true };
     meta.fields[fieldKey] = {
         ...meta.fields[fieldKey],
         name: key,
         ...resolved,
-        ...(computed && { computed: entitySql(computed) }),
+        ...(sql && { computed: sql }),
     };
     return meta;
 }

package/dist/migrate/codegen/entityCodeGenerator.js

@@ -156,9 +156,11 @@ export class EntityCodeGenerator {
             const fieldOptions = this.buildFieldOptions(col, propertyName);
             lines.push(`  @Field(${fieldOptions})`);
         }
-        // Property
+        // Property. A generated column is the database's to write, so it is `readonly`: a write payload
+        // leaves those out, and one naming it would be dropped rather than persisted.
         const nullable = col.nullable ? '?' : '';
-        lines.push(`  ${propertyName}${nullable}: ${tsType};`);
+        const written = col.generatedAs === undefined ? '' : 'readonly ';
+        lines.push(`  ${written}${propertyName}${nullable}: ${tsType};`);
         return lines.join('\n');
     }
     /**

package/dist/migrate/introspection/postgresIntrospector.d.ts

@@ -14,6 +14,12 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
     protected getTableNamesQuery(): string;
     protected tableExistsQuery(): string;
     protected parseTableExistsResult([row]: RawRow[]): boolean;
+    /**
+     * The comment reads through `to_regclass` rather than a `::regclass` cast: a name resolves against
+     * the live catalogue while `information_schema` answers from this statement's snapshot, so a table
+     * another connection has just dropped is still listed here and the cast would raise on it. Whole
+     * database scans meet that table every time something else is migrating.
+     */
     protected getColumnsQuery(_tableName: string): string;
     /**
      * `attname` where the entry is a column, `pg_get_indexdef` for that one position where it is an

package/dist/migrate/introspection/postgresIntrospector.js

@@ -37,6 +37,12 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     parseTableExistsResult([row]) {
         return row['exists'] === true;
     }
+    /**
+     * The comment reads through `to_regclass` rather than a `::regclass` cast: a name resolves against
+     * the live catalogue while `information_schema` answers from this statement's snapshot, so a table
+     * another connection has just dropped is still listed here and the cast would raise on it. Whole
+     * database scans meet that table every time something else is migrating.
+     */
     getColumnsQuery(_tableName) {
         return /*sql*/ `
       SELECT
@@ -68,7 +74,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
           HAVING COUNT(*) = 1 AND MIN(kcu.column_name) = c.column_name
         ) AS is_unique,
         pg_catalog.col_description(
-          (quote_ident(c.table_schema) || '.' || quote_ident(c.table_name))::regclass,
+          to_regclass(quote_ident(c.table_schema) || '.' || quote_ident(c.table_name)),
           c.ordinal_position
         ) AS column_comment
       FROM information_schema.columns c

package/dist/migrate/migrator.d.ts

@@ -49,7 +49,8 @@ export declare class Migrator {
     /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
     private runInOrder;
     /**
-     * Run a single migration, within a transaction where the dialect has one for it
+     * Run a single migration, in a transaction where the dialect has one for it and the migration has not
+     * declared `transaction: false` - the opt-out a statement an engine refuses inside one needs.
      */
     runMigration(migration: Migration<Querier>, direction: 'up' | 'down'): Promise<MigrationResult>;
     /**

package/dist/migrate/migrator.js

@@ -112,14 +112,15 @@ export class Migrator {
         return results;
     }
     /**
-     * Run a single migration, within a transaction where the dialect has one for it
+     * Run a single migration, in a transaction where the dialect has one for it and the migration has not
+     * declared `transaction: false` - the opt-out a statement an engine refuses inside one needs.
      */
     async runMigration(migration, direction) {
         const startTime = Date.now();
         return this.target.withSession(async ({ querier, transaction }) => {
             try {
                 this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
-                await transaction(async () => {
+                const work = async () => {
                     if (direction === 'up') {
                         await migration.up(querier);
                         await this.storage.logWithQuerier(querier, migration.name);
@@ -128,7 +129,8 @@ export class Migrator {
                         await migration.down(querier);
                         await this.storage.unlogWithQuerier(querier, migration.name);
                     }
-                });
+                };
+                await (migration.transaction === false ? work() : transaction(work));
                 const duration = Date.now() - startTime;
                 this.logger.logMigration(`Migration ${migration.name} ${direction === 'up' ? 'applied' : 'reverted'} in ${duration}ms`);
                 return {

package/dist/mongo/mongoDialect.d.ts

@@ -33,20 +33,15 @@ export declare class MongoDialect extends AbstractDialect {
     columnOf<E>(meta: EntityMeta<E>, key: string): string;
     where<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions): Filter<E>;
     /**
-     * A `$where` that may constrain relations, as the `$lookup` stages it needs and the `$match` reading
-     * them: each condition a lookup into a temporary field (`unset` names them), so `$or` keeps its meaning.
+     * The stages every pipeline starts with: the `$lookup` each relation condition needs, into a temporary
+     * field so `$or` keeps its meaning, the `$match` reading them, and the temporaries taken back out. Each
+     * relation aggregate the `$where` or `named` reads is left on the document, once, under its column.
      */
-    whereWithRelations<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions): {
-        readonly stages: MongoAggregationPipelineEntry<Document>[];
-        readonly filter: Filter<E>;
-        readonly unset: string[];
-    };
-    /** Whether a `$where` constrains any relation, and so needs the aggregation path rather than a cursor. */
-    constrainsRelations<E extends Document>(entity: Type<E>, where: QueryWhere<E> | undefined): boolean;
+    matchStages<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions, named?: readonly string[]): MongoAggregationPipelineEntry<Document>[];
     /**
      * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
-     * recursion). Relation keys need `$lookup` stages, so they are only accepted when `lookups` is
-     * given - a plain `find`/`updateMany` filter has nowhere to put them.
+     * recursion). A relation, or a relation aggregate, needs `$lookup` stages, so it is only accepted
+     * when `lookups` is given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
     protected renderFilter<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, lookups?: RelationLookups): Filter<E>;
     /**
@@ -139,9 +134,29 @@ export declare class MongoDialect extends AbstractDialect {
         readonly stages: MongoAggregationPipelineEntry<Document>[];
         readonly fields: string[];
     };
-    /** The correlated lookup counting a relation's rows, which `where` narrows, into `temp`. */
-    private tallyLookup;
-    /** The tally a lookup left in `temp`, which holds no row at all where nothing matched: a zero. */
+    /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
+    readsAggregates<E extends Document>(entity: Type<E>, q: Query<E>): boolean;
+    /** The relation aggregates a read projects or sorts by; its `$where` puts its own on the document. */
+    private aggregateKeys;
+    /**
+     * The relation aggregate `key` computes, put on the document under its column by the stages
+     * {@link aggregateStages} builds from the same spec SQL renders as a subquery. Once however many
+     * clauses read it; a key computing none adds nothing.
+     */
+    private appendAggregateField;
+    /**
+     * One relation aggregate on the document under `field`: the correlated lookup that reads the related
+     * rows - narrowed, ordered and capped as the spec says - ending in the tally or total it wants, and
+     * the `$addFields` reading that back, `0` or `null` where the lookup matched nothing.
+     *
+     * Every aggregate MongoDB answers is built here: a `$count` a query asks for, an ordering by one, and
+     * a field a `computed` declares, which is the same spec the SQL dialects render as one subquery.
+     */
+    private aggregateStages;
+    /**
+     * The value a lookup left in `temp`, which holds no row at all where nothing matched: `0` for the
+     * aggregates that count something, and `null` for the ones with no value to report.
+     */
     private tally;
     /**
      * The lookups reading each to-many a query populates, and the tally of each `$count`, onto the fields
@@ -232,13 +247,28 @@ export declare class MongoDialect extends AbstractDialect {
     /**
      * Build MongoDB aggregation pipeline stages from a QueryAggregate.
      */
-    buildAggregateStages<E extends Document, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Record<string, unknown>[];
+    buildAggregateStages<E extends Document, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): MongoAggregationPipelineEntry<Document>[];
     /**
-     * Resolve parsed group entries into the `_id` keys and accumulators of a `$group` stage.
-     * `distinctReducers` maps each DISTINCT alias (collected via `$addToSet`) to the `$project`
-     * operator that reduces its set: `$size` for `$count`, `$sum`/`$avg` for the numeric ops.
+     * Resolve parsed group entries into the `_id` keys and accumulators of a `$group` stage, and the
+     * `columns` its `$project` reads each result from: a group key out of `_id`, a DISTINCT set by its
+     * size, and a `$sum` as null where it read no value, as SQL answers it. `named` is every field it reads,
+     * filters included, so each relation aggregate among them is put on the document first.
      */
     private buildGroupSpec;
+    /** `1` where `ref` holds a value, `0` where it is null or missing, which an expression tells apart. */
+    private static countOf;
+    /** Whether `ref` is null or missing: an expression compares a missing field as neither. */
+    private static isNullExpr;
+    /** The field a grouped path reads, on the document or on the joined one its lookup unwound. */
+    private groupedPath;
+    /**
+     * An aggregate's own `$where` as the expression a `$cond` tests, which a query filter is not: the
+     * comparisons and the logical operators translate, anything else is refused by name. `named` gathers
+     * the fields it reads, so a relation aggregate among them is on the document first.
+     */
+    private whereExpression;
+    /** One field's condition as an expression: a value it equals, a list it is in, or a map of comparisons. */
+    private fieldExpression;
     private buildHavingFilter;
     /**
      * Separate vector sort entries from regular sort entries.
@@ -249,7 +279,7 @@ export declare class MongoDialect extends AbstractDialect {
      * Build a `$vectorSearch` aggregation pipeline stage.
      * Merges `$where` into `$vectorSearch.filter` for optimal pre-filtering.
      */
-    buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions, candidates?: number): Record<string, unknown>;
+    buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions, candidates?: number): MongoAggregationPipelineEntry<Document>;
 }
 export type MongoAggregationPipelineEntry<E extends Document> = {
     $lookup?: MongoAggregationLookup;