@proteinjs/db 1.36.0 → 1.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,7 +41,7 @@
     "test": "jest --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db-query": "^1.8.0",
+    "@proteinjs/db-query": "^1.9.0",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/serializer": "^1.1.10",
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "b25c88ae26fffd1c784b4c7b1174825b52751987"
+  "gitHead": "7c4ebb2ab218d48a276940140161979f0aa31730"
 }

package/src/Columns.ts

@@ -294,9 +294,13 @@ export class ReferenceColumn<T extends Record> extends StringColumn<Reference<T>
     name: string,
     public referenceTable: string,
     public cascadeDelete: boolean,
-    options?: ReferenceColumnOptions
+    options?: ReferenceColumnOptions & {
+      /** Id-column width (default 36, uuid). Pass the EXISTING width when adopting a column
+       *  that predates the reference type — Spanner cannot narrow a STRING in place. */
+      maxLength?: number;
+    }
   ) {
-    super(name, options, 36);
+    super(name, options, options?.maxLength ?? 36);
     this.reverseCascadeDelete = !!options?.reverseCascadeDelete;
   }
 

package/src/Db.ts

@@ -58,6 +58,8 @@ export type DbDriverQueryStatementConfig = ParameterizationConfig & {
   prefixTablesWithDb?: boolean;
   getDriverColumnType?: (tableName: string, columnName: string) => string;
   handleCaseSensitivity: (tableName: string, columnName: string, caseSensitive: boolean) => string;
+  /** Driver SQL for truncating a datetime column to a bucket unit (`QueryBuilder.timeBucket`). */
+  dateTruncExpression?: (resolvedColumnName: string, unit: 'day' | 'hour') => string;
 };
 
 export type DbDriverDmlStatementConfig = ParameterizationConfig & {
@@ -708,6 +710,29 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return result[0]['count'];
   }
 
+  /**
+   * Run a grouped-aggregation query and return the RAW result rows — one object per group,
+   * carrying the selected group fields (keyed by their DRIVER COLUMN names), any
+   * `timeBucket` dimension (keyed by its `resultProp`), and the aggregate values (keyed by
+   * their `resultProp`s). This is the scalable read for reporting rollups (SUM/COUNT per
+   * model/day/owner AT the database) — the alternative, `query()` + summing in memory, loads
+   * every underlying row and does not survive real data volumes.
+   *
+   * Rides the same authority as `query()`: table read auth unless run as system, and column
+   * queries (e.g. scope pre-filtering) are applied — a scoped caller aggregates only rows it
+   * could read. No record deserialization happens: aggregate rows are not records.
+   */
+  async queryAggregates<T extends R>(table: Table<T>, qb: QueryBuilder<T>): Promise<{ [key: string]: unknown }[]> {
+    if (!this.runAsSystem) {
+      this.auth.canQuery(table);
+    }
+
+    await this.addColumnQueries(table, qb);
+    const generateQuery = (config: DbDriverQueryStatementConfig) =>
+      qb.toSql(this.statementConfigFactory.getStatementConfig(config));
+    return await this.dbDriver.runQuery(generateQuery, this.transactionForDriver());
+  }
+
   private async addColumnQueries<T extends R>(
     table: Table<T>,
     qb: QueryBuilder<T>,

package/src/StatementConfigFactory.ts

@@ -34,7 +34,10 @@ export class StatementConfigFactory {
       useNamedParams: config.useNamedParams,
       getColumnType: this.getColumnType(),
       getDriverColumnType: config.getDriverColumnType,
-      ...(this.isQueryConfig(config) && { handleCaseSensitivity: config.handleCaseSensitivity }),
+      ...(this.isQueryConfig(config) && {
+        handleCaseSensitivity: config.handleCaseSensitivity,
+        dateTruncExpression: config.dateTruncExpression,
+      }),
     };
   }
 

package/src/Table.ts

@@ -311,6 +311,15 @@ export type ColumnOptions = {
   ) => Promise<void>;
   ui?: {
     hidden?: boolean;
+    /**
+     * Which section of the record form this column belongs to. The form derives a sane
+     * section from the column's type and name (identity strings up top, long text and
+     * structured values under Content, everything else under Details, server-managed meta
+     * under System); this hint overrides the derivation. Known values map to the canonical
+     * sections ('identity' | 'content' | 'details' | 'system'); any other string becomes its
+     * own titled section, ordered after Details.
+     */
+    formGroup?: 'identity' | 'content' | 'details' | 'system' | (string & {});
   };
 };