@proteinjs/db 1.37.0 → 1.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.37.0",
+  "version": "1.39.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": "cb0fda126d5d2bd5b17d1bc13e87c2373eb61f52"
+  "gitHead": "bc027111370f4391426dce2e8faf0b862664b3c5"
 }

package/src/Columns.ts

@@ -27,14 +27,17 @@ export class StringColumn<T = string> implements Column<T, string> {
     public options?: ColumnOptions,
     public maxLength: number | 'MAX' = 255
   ) {
-    this.options = Object.assign(
-      {
-        ui: {
-          hidden: maxLength === 'MAX',
-        },
-      },
-      options
-    );
+    /**
+     * Unbounded ('MAX') text columns are NOT default-hidden (founder ruling, admin round 3):
+     * the record FORM renders any length safely now (multiline field with the bounded preview
+     * + expand dialog past the inline bound), and a value like a migration's failure stack is
+     * exactly what the form gets opened to read. The record TABLE's default column pick still
+     * excludes unbounded text (a row can't afford one) — that exclusion lives with the pick
+     * (db-ui `defaultRecordTableColumns`), keyed on `maxLength`, not here. `ui.hidden` remains
+     * the author's explicit hide-everywhere; subclasses whose storage happens to be MAX but
+     * whose values aren't prose (Object/Array/Password/Uuid) declare their own ui defaults.
+     */
+    this.options = Object.assign({ ui: {} }, options);
   }
 }
 

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 & {});
   };
 };
 

package/src/encryption/DataEncryptionKeyTable.ts

@@ -27,7 +27,9 @@ export class DataEncryptionKeyTable extends Table<DataEncryptionKey> {
   public columns: Table<DataEncryptionKey>['columns'] = withRecordColumns<DataEncryptionKey>({
     owner: new StringColumn('owner', { nullable: false }, 36),
     version: new IntegerColumn('version', { nullable: false }),
-    wrappedKey: new StringColumn('wrapped_key', { nullable: false }, 'MAX'),
+    // Explicitly ui-hidden: unbounded TEXT columns render on record forms now (admin round 3),
+    // but this is wrapped key MATERIAL, not prose — it never renders in any UI.
+    wrappedKey: new StringColumn('wrapped_key', { nullable: false, ui: { hidden: true } }, 'MAX'),
     status: new StringColumn('status', { nullable: false }, 16),
   });
   /** (owner, version) is the identity an envelope names — the race loser on concurrent

package/test/StringColumnUiDefaults.test.ts

@@ -0,0 +1,42 @@
+/**
+ * StringColumn's ui defaults (founder ruling, admin round 3): an unbounded ('MAX') plain-text
+ * column is NOT default-hidden anymore — the record form renders any length safely (bounded
+ * preview + expand past the inline bound), so the old there-is-no-safe-rendering hide is
+ * obsolete. The record TABLE's default pick excludes unbounded text at the pick itself
+ * (db-ui), not via this layer. `ui.hidden` remains the author's explicit hide-everywhere,
+ * and the columns whose MAX storage isn't prose keep their own explicit ui defaults.
+ */
+// Table first: it anchors the src module cycle (Table → Record → Columns) the way every
+// sibling suite does — importing Columns first evaluates Record before UuidColumn exists.
+import '../src/Table';
+import { ArrayColumn, ObjectColumn, PasswordColumn, StringColumn, UuidColumn } from '../src/Columns';
+
+describe('StringColumn ui defaults', () => {
+  it('an unbounded column is not default-hidden', () => {
+    const column = new StringColumn('report', undefined, 'MAX');
+    expect(column.options?.ui?.hidden).toBeFalsy();
+  });
+
+  it('a bounded column stays not hidden', () => {
+    expect(new StringColumn('title').options?.ui?.hidden).toBeFalsy();
+    expect(new StringColumn('description', {}, 4000).options?.ui?.hidden).toBeFalsy();
+  });
+
+  it("an author's explicit ui.hidden survives on an unbounded column", () => {
+    const column = new StringColumn('transcript', { ui: { hidden: true } }, 'MAX');
+    expect(column.options?.ui?.hidden).toBe(true);
+  });
+
+  it('author options without ui still leave the column visible', () => {
+    const column = new StringColumn('notes', { defaultValue: async () => 'x' }, 'MAX');
+    expect(column.options?.ui?.hidden).toBeFalsy();
+    expect(column.options?.defaultValue).toBeDefined();
+  });
+
+  it('non-prose MAX-storage columns keep their own hidden defaults', () => {
+    expect(new ObjectColumn('payload').options?.ui?.hidden).toBe(true);
+    expect(new ArrayColumn('items').options?.ui?.hidden).toBe(true);
+    expect(new PasswordColumn('password').options?.ui?.hidden).toBe(true);
+    expect(new UuidColumn('token').options?.ui?.hidden).toBe(true);
+  });
+});