@lossless.org/client 1.13.0 → 1.15.0

package/ts/nosqldb/classes.doc.ts

@@ -16,6 +16,10 @@ import {
   type ISmartdataStoredInspectionOptions, type ISmartdataStoredInspection,
   type ISmartdataStoredEvidenceInspection,
 } from './classes.storedinspection.js';
+import {
+  inspectQueryPlan, requireQueryPlanOptions,
+  type ISmartdataQueryPlan, type ISmartdataQueryPlanOptions,
+} from './classes.queryplaninspection.js';
 import {
   getIdentityDocumentIdField,
   type IManager,
@@ -218,6 +222,13 @@ export interface SvDbOptions {
    * below this persisted field.
    */
   atomicPaths?: readonly string[];
+  /**
+   * Explicit relative nested paths below this persisted field that hold
+   * arrays. Each one is a declared nested path exactly like an `atomicPaths`
+   * entry, and in addition the array operators `$push`, `$addToSet` and
+   * `$pull` and the grouped-totals `unwind` may target it.
+   */
+  arrayPaths?: readonly string[];
   /**
    * Declares this persisted top-level field as numeric for strict atomic
    * expression references.
@@ -282,6 +293,13 @@ export function svDb(options?: SvDbOptions) {
                 : options.atomicPaths,
             }
           : {}),
+        ...(options.arrayPaths !== undefined
+          ? {
+              arrayPaths: Array.isArray(options.arrayPaths)
+                ? [...options.arrayPaths]
+                : options.arrayPaths,
+            }
+          : {}),
       }
     : undefined;
   return (value: undefined, context: ClassFieldDecoratorContext) => {
@@ -773,16 +791,48 @@ export interface ISmartdataAtomicNumericExpression<T> {
   ];
 }
 
-export interface ISmartdataGroupedTotalsOptions<T> {
+/**
+ * A path grouped totals may group by or sum: a declared top-level field or a
+ * nested path declared through `@svDb({ atomicPaths })` or
+ * `@svDb({ arrayPaths })`.
+ */
+export type TSmartdataGroupedTotalsPath<T> = TSmartdataAtomicDocumentPath<T>;
+
+/**
+ * A path grouped totals may unwind: a declared top-level array field or a
+ * nested path declared through `@svDb({ arrayPaths })`.
+ */
+export type TSmartdataGroupedTotalsUnwindPath<T> =
+  | TSmartdataAtomicArrayPath<T>
+  | TSmartdataAtomicNestedDocumentPath<T>;
+
+export interface ISmartdataGroupedTotalsOptions<
+  T,
+  TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never,
+> {
+  /**
+   * One or two distinct declared paths whose value combinations form the
+   * groups: declared top-level fields or nested paths declared through
+   * `@svDb({ atomicPaths })` or `@svDb({ arrayPaths })`.
+   */
+  groupBy: ReadonlyArray<TSmartdataGroupedTotalsPath<T>>;
   /**
-   * One or two declared top-level fields whose distinct value combinations
-   * form the groups.
+   * Groups by each element of one array instead of by the array: names
+   * exactly one `groupBy` path, which must be a declared top-level array
+   * field or a nested path declared through `@svDb({ arrayPaths })`. Every
+   * element forms its own row, so `count` counts elements and a document
+   * contributes its `sums` once per element; a document whose array is
+   * missing, null or empty contributes nothing. The `filter` still selects
+   * whole documents before the array is unwound.
    */
-  groupBy: ReadonlyArray<TSmartdataDocumentPath<T>>;
+  unwind?: TUnwind;
   /**
-   * Declared numeric top-level fields to sum per group.
+   * Declared numeric top-level fields, or declared nested paths holding
+   * numbers, to sum per group.
    */
-  sums?: ReadonlyArray<TSmartdataNumericDocumentPath<T>>;
+  sums?: ReadonlyArray<
+    TSmartdataNumericDocumentPath<T> | TSmartdataAtomicNestedDocumentPath<T>
+  >;
   filter?: MongoFilter<T>;
   /**
    * Required bound on the number of returned groups (1..10000). The group
@@ -803,18 +853,37 @@ export interface ISmartdataGroupedTotalsOptions<T> {
   session?: TSmartdataOrdinarySession;
 }
 
-export interface ISmartdataGroupedTotalsRow<T> {
+export interface ISmartdataGroupedTotalsRow<
+  T,
+  TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never,
+> {
   /**
-   * The group's key values. Documents missing a group field and documents
-   * holding an explicit null merge into one group reported as null.
+   * The group's key values, keyed by the `groupBy` paths as given. Documents
+   * missing a group path and documents holding an explicit null merge into
+   * one group reported as null. An unwound top-level array reports the
+   * element; nested paths report the stored value untyped.
    */
-  group: { [TKey in TSmartdataDocumentPath<T>]?: T[TKey] | null };
+  group:
+    & {
+      [TKey in TSmartdataDocumentPath<T>]?:
+        | (TKey extends TUnwind ? TSmartdataAtomicArrayElement<T[TKey]> : T[TKey])
+        | null;
+    }
+    & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, unknown>>;
   count: number;
-  sums: Partial<Record<TSmartdataNumericDocumentPath<T>, number>>;
+  sums: Partial<
+    Record<
+      TSmartdataNumericDocumentPath<T> | TSmartdataAtomicNestedDocumentPath<T>,
+      number
+    >
+  >;
 }
 
-export interface ISmartdataGroupedTotalsPage<T> {
-  rows: Array<ISmartdataGroupedTotalsRow<T>>;
+export interface ISmartdataGroupedTotalsPage<
+  T,
+  TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never,
+> {
+  rows: Array<ISmartdataGroupedTotalsRow<T, TUnwind>>;
   hasMore: boolean;
 }
 
@@ -826,12 +895,19 @@ export type TSmartdataAtomicArrayPath<T> = {
 type TSmartdataAtomicArrayElement<TValue> =
   NonNullable<TValue> extends ReadonlyArray<infer TElement> ? TElement : never;
 
-type TSmartdataAtomicArrayOperation<T> = Partial<{
-  [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicArrayElement<T[TKey]>;
-}>;
+/**
+ * Array operators take a declared top-level array field, typed by its element,
+ * or a nested path below a declared field. A nested path is accepted at run
+ * time only when the model declares it through `@svDb({ arrayPaths })`.
+ */
+type TSmartdataAtomicArrayOperation<T> =
+  & Partial<{
+    [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicArrayElement<T[TKey]>;
+  }>
+  & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, unknown>>;
 
-type TSmartdataAtomicPullScalar<TValue> = Extract<
-  TValue,
+/** The scalar equality operands `$pull` accepts. */
+type TSmartdataAtomicPullScalarValue =
   | string
   | number
   | boolean
@@ -843,14 +919,22 @@ type TSmartdataAtomicPullScalar<TValue> = Extract<
   | plugins.mongodb.Long
   | plugins.mongodb.Int32
   | plugins.mongodb.Double
-  | plugins.mongodb.Timestamp
+  | plugins.mongodb.Timestamp;
+
+type TSmartdataAtomicPullScalar<TValue> = Extract<
+  TValue,
+  TSmartdataAtomicPullScalarValue
 >;
 
-type TSmartdataAtomicArrayPullOperation<T> = Partial<{
-  [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicPullScalar<
-    TSmartdataAtomicArrayElement<T[TKey]>
+type TSmartdataAtomicArrayPullOperation<T> =
+  & Partial<{
+    [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicPullScalar<
+      TSmartdataAtomicArrayElement<T[TKey]>
+    >;
+  }>
+  & Partial<
+    Record<TSmartdataAtomicNestedDocumentPath<T>, TSmartdataAtomicPullScalarValue>
   >;
-}>;
 
 export interface ISmartdataAtomicUpdate<T> {
   $set?: TSmartdataAtomicSet<T>;
@@ -872,19 +956,21 @@ export interface ISmartdataAtomicUpdate<T> {
   $min?: TSmartdataAtomicMonotonic<T>;
   $setOnInsert?: TSmartdataAtomicSet<T>;
   /**
-   * Appends one element to a declared top-level array field. Modifier
-   * documents ($each, $position, $slice, $sort) are rejected.
+   * Appends one element to a declared top-level array field or a nested
+   * path declared through `@svDb({ arrayPaths })`. Modifier documents
+   * ($each, $position, $slice, $sort) are rejected.
    */
   $push?: TSmartdataAtomicArrayOperation<T>;
   /**
-   * Adds one element to a declared top-level array field unless an equal
-   * element is already present. Modifier documents are rejected.
+   * Adds one element to a declared top-level array field or a declared
+   * nested array path unless an equal element is already present. Modifier
+   * documents are rejected.
    */
   $addToSet?: TSmartdataAtomicArrayOperation<T>;
   /**
    * Removes every element equal to a scalar operand from a declared
-   * top-level array field. Operator documents, plain objects, arrays, and
-   * regular expressions are rejected.
+   * top-level array field or a declared nested array path. Operator
+   * documents, plain objects, arrays, and regular expressions are rejected.
    */
   $pull?: TSmartdataAtomicArrayPullOperation<T>;
 }
@@ -3047,6 +3133,8 @@ const normalizeAtomicUpdate = <T>(
   updateArg: ISmartdataAtomicUpdate<T>,
   declaredRootsArg: Set<string>,
   declaredNestedPathsArg: Set<string>,
+  /** Nested paths declared through `@svDb({ arrayPaths })`; array operators may target them. */
+  declaredArrayPathsArg: Set<string>,
   uniqueRootsArg: Set<string>,
   serializedRootsArg: Set<string>,
   /**
@@ -3160,10 +3248,13 @@ const normalizeAtomicUpdate = <T>(
       }
       occupiedPaths.push({ path, operator });
       if (arrayOperators.has(operator)) {
-        if (path !== root) {
+        if (path !== root && !declaredArrayPathsArg.has(path)) {
+          // The shape of a nested value is known only from its declaration, so
+          // a nested path that is not declared as an array is refused rather
+          // than left to fail on the stored value.
           throw new SmartdataPersistenceError(
             'invalid_argument',
-            `${operator} may only target declared top-level array fields; "${path}" is a nested path.`,
+            `${operator} may only target a declared top-level array field or a nested path declared through @svDb({ arrayPaths }); "${path}" is not a declared array path.`,
           );
         }
         if (value === undefined) {
@@ -3727,6 +3818,32 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     return inspectStoredDocumentEvidence(this, dbArg, optionsArg);
   }
 
+  /**
+   * Explains one model query with `executionStats` on `dbArg` and returns the
+   * winning plan's stages and execution totals, so a consumer can prove which
+   * index serves the query. Read-only: nothing is created, bound or hydrated.
+   */
+  public static async inspectQueryPlan<T>(
+    this: plugins.tsclass.typeFest.Class<T>,
+    dbArg: SmartdataDb,
+    optionsArg: ISmartdataQueryPlanOptions<T>,
+  ): Promise<ISmartdataQueryPlan> {
+    const model = this as unknown as typeof SmartDataDbDoc;
+    const options = requireQueryPlanOptions(optionsArg);
+    model.assertHydratedProjection(options.projection);
+    const declaredRoots = model.getDeclaredPersistedRoots();
+    const declaredQueryPaths = model.getDeclaredQueryPaths();
+    return inspectQueryPlan(dbArg, {
+      collectionName: getExpectedCollectionTopologyForModel(model).collectionName,
+      filter: model.normalizeReadFilter(options.filter),
+      sort: normalizeSort(options.sort, declaredRoots, declaredQueryPaths),
+      projection: normalizeProjection(options.projection, declaredRoots, declaredQueryPaths),
+      limit: options.limit,
+      timeoutMS: options.timeoutMS,
+      signal: options.signal,
+    });
+  }
+
   public static createInstanceFromMongoDbNativeDoc<T>(
     this: plugins.tsclass.typeFest.Class<T>,
     mongoDbNativeDocArg: any,
@@ -3873,21 +3990,41 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     return keySets;
   }
 
+  /**
+   * Every nested path the model declares below a persisted field, through
+   * `@svDb({ atomicPaths })` or `@svDb({ arrayPaths })`.
+   */
   private static getDeclaredAtomicPaths(): Set<string> {
+    return new Set([
+      ...(this as any).readDeclaredNestedPaths('atomicPaths') as Set<string>,
+      ...(this as any).readDeclaredNestedPaths('arrayPaths') as Set<string>,
+    ]);
+  }
+
+  /** The nested paths declared through `@svDb({ arrayPaths })` as holding arrays. */
+  private static getDeclaredArrayPaths(): Set<string> {
+    return (this as any).readDeclaredNestedPaths('arrayPaths') as Set<string>;
+  }
+
+  private static readDeclaredNestedPaths(
+    declarationArg: 'atomicPaths' | 'arrayPaths',
+  ): Set<string> {
     const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
     const uniqueRoots = (this as any).getDeclaredUniqueRoots() as Set<string>;
     const options = (this as any)._svDbOptions as
       | Record<string, SvDbOptions>
       | undefined;
-    const atomicPaths = new Set<string>();
+    const label = declarationArg === 'atomicPaths' ? 'Atomic' : 'Array';
+    const nestedPaths = new Set<string>();
     for (const [root, fieldOptions] of Object.entries(options || {})) {
-      if (fieldOptions.atomicPaths === undefined) {
+      const relativePaths = fieldOptions[declarationArg];
+      if (relativePaths === undefined) {
         continue;
       }
-      if (!Array.isArray(fieldOptions.atomicPaths)) {
+      if (!Array.isArray(relativePaths)) {
         throw new SmartdataPersistenceError(
           'invalid_configuration',
-          `Atomic paths for persisted field "${root}" must be an array.`,
+          `${label} paths for persisted field "${root}" must be an array.`,
         );
       }
       if (
@@ -3896,20 +4033,20 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       ) {
         throw new SmartdataPersistenceError(
           'invalid_configuration',
-          `Serialized persisted field "${root}" may not declare atomic nested paths.`,
+          `Serialized persisted field "${root}" may not declare ${label.toLowerCase()} nested paths.`,
         );
       }
       if (uniqueRoots.has(root)) {
         throw new SmartdataPersistenceError(
           'invalid_configuration',
-          `Immutable @unI() field "${root}" may not declare atomic nested paths.`,
+          `Immutable @unI() field "${root}" may not declare ${label.toLowerCase()} nested paths.`,
         );
       }
-      for (const relativePath of fieldOptions.atomicPaths) {
+      for (const relativePath of relativePaths) {
         if (typeof relativePath !== 'string' || relativePath.length === 0) {
           throw new SmartdataPersistenceError(
             'invalid_configuration',
-            `Atomic paths for persisted field "${root}" must be non-empty strings.`,
+            `${label} paths for persisted field "${root}" must be non-empty strings.`,
           );
         }
         const fullPath = `${root}.${relativePath}`;
@@ -3917,20 +4054,20 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
           requireDeclaredPath(
             fullPath,
             declaredRoots,
-            'Atomic path declaration',
+            `${label} path declaration`,
             new Set([fullPath]),
           );
         } catch (errorArg) {
           throw new SmartdataPersistenceError(
             'invalid_configuration',
-            `Atomic path declaration "${fullPath}" is invalid.`,
+            `${label} path declaration "${fullPath}" is invalid.`,
             { cause: errorArg },
           );
         }
-        atomicPaths.add(fullPath);
+        nestedPaths.add(fullPath);
       }
     }
-    return atomicPaths;
+    return nestedPaths;
   }
 
   private static getSerializedPersistedRoots(): Set<string> {
@@ -4267,6 +4404,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     }
     const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
     const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const declaredArrayPaths = (this as any).getDeclaredArrayPaths() as Set<string>;
     const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
       string,
       TSmartdataIdentityValueType
@@ -4302,6 +4440,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       updateArg,
       declaredRoots,
       declaredAtomicPaths,
+      declaredArrayPaths,
       uniqueRoots,
       serializedRoots,
       upserting ? { identityValueTypes } : undefined,
@@ -4377,6 +4516,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const policy = getOrdinaryPersistencePolicy(this);
     const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
     const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const declaredArrayPaths = (this as any).getDeclaredArrayPaths() as Set<string>;
     const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
       string,
       TSmartdataIdentityValueType
@@ -4403,6 +4543,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       updateArg,
       declaredRoots,
       declaredAtomicPaths,
+      declaredArrayPaths,
       uniqueRoots,
       serializedRoots,
       normalizedOptions.upsert ? { identityValueTypes } : undefined,
@@ -4733,6 +4874,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const timeoutMS = requireBoundedInteger(opts?.timeoutMS, 'Atomic update-many timeoutMS', 120_000);
     const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
     const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const declaredArrayPaths = (this as any).getDeclaredArrayPaths() as Set<string>;
     const uniqueRoots = (this as any).getDeclaredUniqueRoots() as Set<string>;
     const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
       string,
@@ -4753,6 +4895,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       updateArg,
       declaredRoots,
       declaredAtomicPaths,
+      declaredArrayPaths,
       uniqueRoots,
       serializedRoots,
     );
@@ -4843,6 +4986,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     );
     const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
     const declaredAtomicPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
+    const declaredArrayPaths = (this as any).getDeclaredArrayPaths() as Set<string>;
     const identityValueTypes = (this as any).getDeclaredIdentityValueTypes() as Map<
       string,
       TSmartdataIdentityValueType
@@ -4891,6 +5035,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         operation.update as ISmartdataAtomicUpdate<T>,
         declaredRoots,
         declaredAtomicPaths,
+        declaredArrayPaths,
         uniqueRoots,
         serializedRoots,
         { identityValueTypes },
@@ -4946,18 +5091,24 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
 
   /**
    * Computes bounded grouped counts and optional numeric sums server-side.
-   * Groups by one or two declared top-level fields, always returns a `count`
-   * per group, and sums only declared numeric fields. The `$limit` follows
-   * the group stage without a sort, so when more groups exist than the limit
-   * the returned subset is arbitrary. Use `getGroupedTotalsPage()` when the
-   * caller must detect overflow. The aggregation cursor never leaves SmartData.
+   * Groups by one or two declared paths — top-level fields or nested paths
+   * declared through `@svDb({ atomicPaths })` or `@svDb({ arrayPaths })` —
+   * optionally by each element of one declared array (`unwind`), always
+   * returns a `count` per group, and sums only declared numeric paths. The
+   * `$limit` follows the group stage without a sort, so when more groups
+   * exist than the limit the returned subset is arbitrary. Use
+   * `getGroupedTotalsPage()` when the caller must detect overflow. The
+   * aggregation cursor never leaves SmartData.
    */
-  public static async getGroupedTotals<T>(
+  public static async getGroupedTotals<
+    T,
+    TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never,
+  >(
     this: plugins.tsclass.typeFest.Class<T>,
-    optionsArg: ISmartdataGroupedTotalsOptions<T>,
-  ): Promise<Array<ISmartdataGroupedTotalsRow<T>>> {
+    optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>,
+  ): Promise<Array<ISmartdataGroupedTotalsRow<T, TUnwind>>> {
     const page = await (this as any).getGroupedTotalsPage(optionsArg) as
-      ISmartdataGroupedTotalsPage<T>;
+      ISmartdataGroupedTotalsPage<T, TUnwind>;
     return page.rows;
   }
 
@@ -4966,10 +5117,13 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
    * reports whether at least one additional group exists beyond the requested
    * row limit.
    */
-  public static async getGroupedTotalsPage<T>(
+  public static async getGroupedTotalsPage<
+    T,
+    TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never,
+  >(
     this: plugins.tsclass.typeFest.Class<T>,
-    optionsArg: ISmartdataGroupedTotalsOptions<T>,
-  ): Promise<ISmartdataGroupedTotalsPage<T>> {
+    optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>,
+  ): Promise<ISmartdataGroupedTotalsPage<T, TUnwind>> {
     if ((this as any)[exactPersistencePolicySymbol]) {
       throw new SmartdataPersistenceError(
         'unsupported_operation',
@@ -4989,6 +5143,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     }
     const allowedKeys = new Set([
       'groupBy',
+      'unwind',
       'sums',
       'filter',
       'limit',
@@ -5017,6 +5172,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       }
     }
     const groupByOption = optionsArg.groupBy;
+    const unwindOption = optionsArg.unwind;
     const sumsOption = optionsArg.sums;
     const filterOption = optionsArg.filter;
     const limitOption = optionsArg.limit;
@@ -5029,6 +5185,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     signalOption?.throwIfAborted();
     const sessionOption = optionsArg.session;
     const declaredRoots = (this as any).getDeclaredPersistedRoots() as Set<string>;
+    const declaredNestedPaths = (this as any).getDeclaredAtomicPaths() as Set<string>;
     const serializedRoots = (this as any).getSerializedPersistedRoots() as Set<string>;
     const requireDeclaredGroupField = (
       fieldArg: unknown,
@@ -5037,23 +5194,22 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       if (typeof fieldArg !== 'string') {
         throw new SmartdataPersistenceError(
           'invalid_argument',
-          `${labelArg} must name a declared top-level field.`,
-        );
-      }
-      const root = requireDeclaredPath(fieldArg, declaredRoots, labelArg);
-      if (root !== fieldArg) {
-        throw new SmartdataPersistenceError(
-          'invalid_argument',
-          `${labelArg} must name a declared top-level field, not a nested path.`,
+          `${labelArg} must name a declared top-level field or a declared nested path.`,
         );
       }
+      const root = requireDeclaredPath(
+        fieldArg,
+        declaredRoots,
+        labelArg,
+        declaredNestedPaths,
+      );
       if (serializedRoots.has(root)) {
         throw new SmartdataPersistenceError(
           'unsupported_operation',
           `${labelArg} cannot target serialized field "${root}".`,
         );
       }
-      return root;
+      return fieldArg;
     };
     if (
       !Array.isArray(groupByOption)
@@ -5071,11 +5227,14 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     if (
       groupByFields.length < 1
       || groupByFields.length > 2
-      || new Set(groupByFields).size !== groupByFields.length
+      || (
+        groupByFields.length === 2
+        && pathsConflict(groupByFields[0], groupByFields[1])
+      )
     ) {
       throw new SmartdataPersistenceError(
         'invalid_argument',
-        'Grouped totals groupBy fields must be one or two distinct fields.',
+        'Grouped totals groupBy fields must be one or two distinct fields, neither nested in the other.',
       );
     }
     if (sumsOption !== undefined && !Array.isArray(sumsOption)) {
@@ -5093,6 +5252,27 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         'Grouped totals sum fields must be distinct.',
       );
     }
+    let unwindField: string | undefined;
+    if (unwindOption !== undefined) {
+      if (typeof unwindOption !== 'string' || !groupByFields.includes(unwindOption)) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Grouped totals unwind must name one of the groupBy paths.',
+        );
+      }
+      if (
+        unwindOption.includes('.')
+        && !((this as any).getDeclaredArrayPaths() as Set<string>).has(unwindOption)
+      ) {
+        // A nested value's shape is known only from its declaration; unwinding
+        // a path not declared as an array would count scalars as elements.
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `Grouped totals unwind path "${unwindOption}" is not declared through @svDb({ arrayPaths }).`,
+        );
+      }
+      unwindField = unwindOption;
+    }
     const limit = requireBoundedInteger(
       limitOption,
       'Grouped totals limit',
@@ -5124,11 +5304,17 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         + `call, such as groupBy: ["${groupByFields[0]}"].`,
       );
     }
+    // A composite key names its members by position: a group path may be
+    // dotted, and an expression object's field names may not contain a dot.
+    const compositeKeyName = (indexArg: number): string => 'k' + indexArg;
     const groupStage: Record<string, unknown> = {
       _id: groupByFields.length === 1
         ? '$' + groupByFields[0]
         : Object.fromEntries(
-            groupByFields.map((fieldArg) => [fieldArg, '$' + fieldArg]),
+            groupByFields.map((fieldArg, indexArg) => [
+              compositeKeyName(indexArg),
+              '$' + fieldArg,
+            ]),
           ),
       __groupedTotalsCount: { $sum: 1 },
     };
@@ -5146,6 +5332,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         ...(maxTimeMS !== undefined ? { maxTimeMS } : {}),
         ...(timeoutMS !== undefined ? { timeoutMS } : {}),
         ...(signalOption !== undefined ? { signal: signalOption } : {}),
+        ...(unwindField !== undefined ? { unwindPath: unwindField } : {}),
       },
     );
     const hasMore = rows.length > limit;
@@ -5168,10 +5355,10 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         group[groupByFields[0]] = rowArg._id ?? null;
       } else {
         const compoundKey = (rowArg._id ?? {}) as Record<string, unknown>;
-        for (const fieldArg of groupByFields) {
+        for (const [index, fieldArg] of groupByFields.entries()) {
           // Missing and explicit-null values merge into one group that is
           // reported as null in both the single-field and compound shapes.
-          group[fieldArg] = compoundKey[fieldArg] ?? null;
+          group[fieldArg] = compoundKey[compositeKeyName(index)] ?? null;
         }
       }
       const sums: Record<string, number> = {};
@@ -5188,7 +5375,7 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
           'Grouped totals count',
         ),
         sums,
-      } as ISmartdataGroupedTotalsRow<T>;
+      } as ISmartdataGroupedTotalsRow<T, TUnwind>;
     });
     return {
       rows: mappedRows,