@lossless.org/client 1.15.0 → 1.17.0

package/ts/nosqldb/classes.doc.ts

@@ -817,15 +817,33 @@ export interface ISmartdataGroupedTotalsOptions<
    */
   groupBy: ReadonlyArray<TSmartdataGroupedTotalsPath<T>>;
   /**
-   * 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.
+   * Aggregates per element of one array instead of per document: names a
+   * declared top-level array field or a nested path declared through
+   * `@svDb({ arrayPaths })`, which is itself a `groupBy` or `sums` path or
+   * holds the element fields that `groupBy` and `sums` paths name below it
+   * (`lines.accountNumber` below `unwind: 'lines'`). Element fields are
+   * declared nested paths like any other, through `@svDb({ atomicPaths })`
+   * on the array's field. Every element contributes on its own, 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,
+   * and no `groupBy` or `sums` path may contain the unwound array; use
+   * `elementFilter` to select elements.
    */
   unwind?: TUnwind;
+  /**
+   * Selects the unwound elements that contribute, applied after the array is
+   * unwound and before grouping: only an element that matches is counted and
+   * summed. Requires `unwind`. Every path is the unwound array itself (its
+   * scalar element) or a declared nested path below it
+   * (`lines.accountNumber` below `unwind: 'lines'`), combined through
+   * `$and`, `$or` and `$nor`, with the operators of atomic filters: `$eq`,
+   * `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$type`,
+   * `$regex` with `$options`, and `$not`. Any other path or operator is
+   * refused with `invalid_argument`. The document `filter` can carry the same
+   * condition to preselect documents through an index.
+   */
+  elementFilter?: TSmartdataGroupedTotalsElementFilter<NoInfer<TUnwind>>;
   /**
    * Declared numeric top-level fields, or declared nested paths holding
    * numbers, to sum per group.
@@ -835,12 +853,21 @@ export interface ISmartdataGroupedTotalsOptions<
   >;
   filter?: MongoFilter<T>;
   /**
-   * Required bound on the number of returned groups (1..10000). The group
-   * stage is not sorted, so when more groups exist than the limit the
-   * returned subset is arbitrary. Use `getGroupedTotalsPage()` when the
-   * caller must detect overflow at the 10000-group boundary.
+   * Required bound on the number of returned groups (1..10000). Groups are
+   * ordered by their key — the `groupBy` values in the given order — and the
+   * first `limit` groups in that order are returned. Use
+   * `getGroupedTotalsPage()` to detect more groups and read them through
+   * `nextCursor`, or `iterateGroupedTotals()` to read every group.
    */
   limit: number;
+  /**
+   * Continues after the last group of an earlier page: the `nextCursor` that
+   * `getGroupedTotalsPage()` returned for the same `groupBy`, `unwind`,
+   * `sums`, `filter` and `elementFilter`. The page holds the groups whose key
+   * sorts after that group's key. A cursor that does not decode, or that
+   * another query shape produced, is refused with `invalid_argument`.
+   */
+  cursor?: string;
   maxTimeMS?: number;
   /**
    * Client-side deadline for the aggregation cursor up to its last reply. More
@@ -885,8 +912,32 @@ export interface ISmartdataGroupedTotalsPage<
 > {
   rows: Array<ISmartdataGroupedTotalsRow<T, TUnwind>>;
   hasMore: boolean;
+  /**
+   * Present exactly when `hasMore` is true: pass it back as `cursor`, with the
+   * same query, to read the next page. Opaque; it carries the query's shape
+   * and the last group's key.
+   */
+  nextCursor?: string;
 }
 
+/**
+ * The `elementFilter` of grouped totals: conditions on the unwound array
+ * `TUnwind` itself or on paths below it, in the shape of atomic filter
+ * conditions, combined through `$and`, `$or` and `$nor`.
+ */
+export type TSmartdataGroupedTotalsElementFilter<TUnwind extends string> =
+  & Partial<
+    Record<
+      TUnwind | `${TUnwind}.${string}`,
+      TSmartdataAtomicFilterCondition<unknown>
+    >
+  >
+  & {
+    $and?: Array<TSmartdataGroupedTotalsElementFilter<TUnwind>>;
+    $or?: Array<TSmartdataGroupedTotalsElementFilter<TUnwind>>;
+    $nor?: Array<TSmartdataGroupedTotalsElementFilter<TUnwind>>;
+  };
+
 export type TSmartdataAtomicArrayPath<T> = {
   [TKey in TSmartdataDocumentPath<T>]:
     NonNullable<T[TKey]> extends ReadonlyArray<unknown> ? TKey : never;
@@ -2809,6 +2860,50 @@ const normalizeAtomicNumericExpression = (
     : guardedComparison;
 };
 
+/** Requires a non-empty, ordinary, inert array of plain filter objects for `$and`, `$or` or `$nor`. */
+const requireInertLogicalFilterArray: (
+  valueArg: unknown,
+  labelArg: string,
+) => asserts valueArg is Array<Record<string, unknown>> = (
+  valueArg,
+  labelArg,
+) => {
+  if (
+    !Array.isArray(valueArg)
+    || plugins.nodeUtil.types.isProxy(valueArg)
+    || Object.getPrototypeOf(valueArg) !== Array.prototype
+    || valueArg.length === 0
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${labelArg} must be a non-empty ordinary array of filters.`,
+    );
+  }
+  assertOnlyDataProperties(valueArg, labelArg, true);
+  for (let index = 0; index < valueArg.length; index++) {
+    if (!Object.prototype.hasOwnProperty.call(valueArg, index)) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} may not contain sparse array positions.`,
+      );
+    }
+    const entry = valueArg[index];
+    if (
+      typeof entry !== 'object'
+      || entry === null
+      || Array.isArray(entry)
+      || plugins.nodeUtil.types.isProxy(entry)
+      || !isPlainObject(entry)
+    ) {
+      throw new SmartdataPersistenceError(
+        'invalid_argument',
+        `${labelArg} entries must be plain filter objects.`,
+      );
+    }
+    assertOnlyDataProperties(entry, `${labelArg} entry`, false);
+  }
+};
+
 const normalizeStrictFilter = (
   filterArg: Record<string, unknown>,
   declaredRootsArg: Set<string>,
@@ -2845,48 +2940,6 @@ const normalizeStrictFilter = (
     `${operationLabelArg} filter`,
     false,
   );
-  const requireInertLogicalFilterArray: (
-    valueArg: unknown,
-    labelArg: string,
-  ) => asserts valueArg is Array<Record<string, unknown>> = (
-    valueArg,
-    labelArg,
-  ) => {
-    if (
-      !Array.isArray(valueArg)
-      || plugins.nodeUtil.types.isProxy(valueArg)
-      || Object.getPrototypeOf(valueArg) !== Array.prototype
-      || valueArg.length === 0
-    ) {
-      throw new SmartdataPersistenceError(
-        'invalid_argument',
-        `${labelArg} must be a non-empty ordinary array of filters.`,
-      );
-    }
-    assertOnlyDataProperties(valueArg, labelArg, true);
-    for (let index = 0; index < valueArg.length; index++) {
-      if (!Object.prototype.hasOwnProperty.call(valueArg, index)) {
-        throw new SmartdataPersistenceError(
-          'invalid_argument',
-          `${labelArg} may not contain sparse array positions.`,
-        );
-      }
-      const entry = valueArg[index];
-      if (
-        typeof entry !== 'object'
-        || entry === null
-        || Array.isArray(entry)
-        || plugins.nodeUtil.types.isProxy(entry)
-        || !isPlainObject(entry)
-      ) {
-        throw new SmartdataPersistenceError(
-          'invalid_argument',
-          `${labelArg} entries must be plain filter objects.`,
-        );
-      }
-      assertOnlyDataProperties(entry, `${labelArg} entry`, false);
-    }
-  };
   /**
    * Plural intent is explicit in the plural method names, so an explicitly
    * enumerated, non-empty `$in` over equality scalars anchors those filters as
@@ -3124,6 +3177,341 @@ const normalizeStrictFilter = (
   ) as plugins.mongodb.Filter<plugins.mongodb.Document>;
 };
 
+/**
+ * Validates the `elementFilter` of grouped totals, which runs after `$unwind`:
+ * every path is the unwound array itself or a declared nested path below it,
+ * and every condition uses the operator subset of atomic filters.
+ */
+const normalizeGroupedTotalsElementFilter = (
+  filterArg: unknown,
+  unwindPathArg: string,
+  declaredRootsArg: Set<string>,
+  declaredNestedPathsArg: Set<string>,
+): plugins.mongodb.Filter<plugins.mongodb.Document> => {
+  const label = 'Grouped totals elementFilter';
+  if (
+    typeof filterArg !== 'object'
+    || filterArg === null
+    || Array.isArray(filterArg)
+    || plugins.nodeUtil.types.isProxy(filterArg)
+    || !isPlainObject(filterArg)
+    || Object.keys(filterArg).length === 0
+  ) {
+    throw new SmartdataPersistenceError(
+      'invalid_argument',
+      `${label} must be a non-empty plain filter object.`,
+    );
+  }
+  const normalizeFilterObject = (
+    filterObjectArg: Record<string, unknown>,
+  ): Record<string, unknown> => {
+    assertOnlyDataProperties(filterObjectArg, label, false);
+    const normalized: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(filterObjectArg)) {
+      if (key === '$and' || key === '$or' || key === '$nor') {
+        requireInertLogicalFilterArray(value, `${label} ${key}`);
+        normalized[key] = value.map((entryArg) => {
+          if (Object.keys(entryArg).length === 0) {
+            throw new SmartdataPersistenceError(
+              'invalid_argument',
+              `${label} ${key} entries must be non-empty filter objects.`,
+            );
+          }
+          return normalizeFilterObject(entryArg);
+        });
+        continue;
+      }
+      if (key.startsWith('$')) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${label} uses unsupported operator "${key}".`,
+        );
+      }
+      if (key !== unwindPathArg && !key.startsWith(unwindPathArg + '.')) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          `${label} path "${key}" is not an element path of the unwound array "${unwindPathArg}".`,
+        );
+      }
+      requireDeclaredPath(key, declaredRootsArg, label, declaredNestedPathsArg);
+      normalized[key] = normalizeAtomicFilterCondition(
+        value,
+        `${label} path "${key}"`,
+      );
+    }
+    return normalized;
+  };
+  return normalizeFilterObject(
+    filterArg as Record<string, unknown>,
+  ) as plugins.mongodb.Filter<plugins.mongodb.Document>;
+};
+
+/**
+ * The group value types grouped-totals paging orders, ascending. Missing values
+ * merge into null; numbers compare by value across int, long and double;
+ * strings compare by their UTF-8 bytes; ObjectIds by their bytes; false sorts
+ * before true. NoSQLDB and MongoDB order these types identically, and their
+ * range operators compare within each type the same way.
+ */
+const groupedTotalsOrderedTypes = ['null', 'number', 'string', 'objectId', 'bool', 'date'] as const;
+
+type TGroupedTotalsOrderedType = typeof groupedTotalsOrderedTypes[number];
+
+/** A group value paging can order, or undefined for any other value. */
+const groupedTotalsOrderedTypeOf = (
+  valueArg: unknown,
+): TGroupedTotalsOrderedType | undefined => {
+  if (valueArg === null) {
+    return 'null';
+  }
+  if (typeof valueArg === 'number') {
+    // NaN sorts below every number on both engines, but a range operator
+    // matches it on NoSQLDB and not on MongoDB.
+    return Number.isNaN(valueArg) ? undefined : 'number';
+  }
+  if (typeof valueArg === 'string') {
+    return 'string';
+  }
+  if (typeof valueArg === 'boolean') {
+    return 'bool';
+  }
+  if (valueArg instanceof plugins.mongodb.Long) {
+    return 'number';
+  }
+  if (valueArg instanceof plugins.mongodb.ObjectId) {
+    return 'objectId';
+  }
+  if (valueArg instanceof Date) {
+    return Number.isNaN(valueArg.getTime()) ? undefined : 'date';
+  }
+  return undefined;
+};
+
+const groupedTotalsExactNumber = (
+  valueArg: number | plugins.mongodb.Long,
+): number | bigint => typeof valueArg === 'number' ? valueArg : BigInt(valueArg.toString());
+
+/** Compares a finite or infinite double with an exact integer. */
+const compareGroupedTotalsDoubleWithInteger = (doubleArg: number, integerArg: bigint): number => {
+  if (!Number.isFinite(doubleArg)) {
+    return doubleArg > 0 ? 1 : -1;
+  }
+  const floor = Math.floor(doubleArg);
+  const floorInteger = BigInt(floor);
+  if (floorInteger !== integerArg) {
+    return floorInteger < integerArg ? -1 : 1;
+  }
+  return doubleArg === floor ? 0 : 1;
+};
+
+const compareGroupedTotalsNumbers = (
+  leftArg: number | plugins.mongodb.Long,
+  rightArg: number | plugins.mongodb.Long,
+): number => {
+  const left = groupedTotalsExactNumber(leftArg);
+  const right = groupedTotalsExactNumber(rightArg);
+  if (typeof left === 'number' && typeof right === 'number') {
+    return left < right ? -1 : left > right ? 1 : 0;
+  }
+  if (typeof left === 'bigint' && typeof right === 'bigint') {
+    return left < right ? -1 : left > right ? 1 : 0;
+  }
+  return typeof left === 'number'
+    ? compareGroupedTotalsDoubleWithInteger(left, right as bigint)
+    : -compareGroupedTotalsDoubleWithInteger(right as number, left);
+};
+
+/** Compares two ordered group values in the documented order. */
+const compareGroupedTotalsValues = (leftArg: unknown, rightArg: unknown): number => {
+  const leftType = groupedTotalsOrderedTypeOf(leftArg)!;
+  const rightType = groupedTotalsOrderedTypeOf(rightArg)!;
+  if (leftType !== rightType) {
+    return groupedTotalsOrderedTypes.indexOf(leftType) - groupedTotalsOrderedTypes.indexOf(rightType);
+  }
+  switch (leftType) {
+    case 'null':
+      return 0;
+    case 'number':
+      return compareGroupedTotalsNumbers(
+        leftArg as number | plugins.mongodb.Long,
+        rightArg as number | plugins.mongodb.Long,
+      );
+    case 'string':
+      return Buffer.compare(Buffer.from(leftArg as string, 'utf8'), Buffer.from(rightArg as string, 'utf8'));
+    case 'objectId':
+      return Buffer.compare(
+        Buffer.from((leftArg as plugins.mongodb.ObjectId).toHexString(), 'hex'),
+        Buffer.from((rightArg as plugins.mongodb.ObjectId).toHexString(), 'hex'),
+      );
+    case 'bool':
+      return Number(leftArg) - Number(rightArg);
+    case 'date':
+      return Math.sign((leftArg as Date).getTime() - (rightArg as Date).getTime());
+  }
+};
+
+/** Compares two group keys member by member. */
+const compareGroupedTotalsKeys = (
+  leftArg: readonly unknown[],
+  rightArg: readonly unknown[],
+): number => {
+  for (const [index, leftValue] of leftArg.entries()) {
+    const order = compareGroupedTotalsValues(leftValue, rightArg[index]);
+    if (order !== 0) {
+      return order;
+    }
+  }
+  return 0;
+};
+
+const groupedTotalsTypeClause = (
+  pathArg: string,
+  typeArg: TGroupedTotalsOrderedType,
+): plugins.mongodb.Document =>
+  typeArg === 'null' ? { [pathArg]: null } : { [pathArg]: { $type: typeArg } };
+
+/**
+ * Clauses matching a group key member that sorts before `valueArg`, or at it
+ * when `inclusiveArg` is set. A range operator only compares within one type,
+ * so every lower type is matched by its `$type`.
+ */
+const groupedTotalsBelowClauses = (
+  pathArg: string,
+  valueArg: unknown,
+  inclusiveArg: boolean,
+): plugins.mongodb.Document[] => {
+  const type = groupedTotalsOrderedTypeOf(valueArg)!;
+  const clauses = groupedTotalsOrderedTypes
+    .slice(0, groupedTotalsOrderedTypes.indexOf(type))
+    .map((typeArg) => groupedTotalsTypeClause(pathArg, typeArg));
+  if (type === 'null') {
+    if (inclusiveArg) {
+      clauses.push({ [pathArg]: null });
+    }
+  } else {
+    clauses.push({ [pathArg]: { [inclusiveArg ? '$lte' : '$lt']: valueArg } });
+  }
+  return clauses;
+};
+
+/**
+ * Clauses matching a group key at or before `afterArg` in lexicographic order
+ * over the members: a lower first member, or an equal first member and the
+ * rest at or before the rest of `afterArg`.
+ */
+const groupedTotalsAtOrBeforeClauses = (
+  memberPathsArg: readonly string[],
+  afterArg: readonly unknown[],
+): plugins.mongodb.Document[] => {
+  const [path, ...restPaths] = memberPathsArg;
+  const [value, ...restValues] = afterArg;
+  if (restPaths.length === 0) {
+    return groupedTotalsBelowClauses(path, value, true);
+  }
+  return [
+    ...groupedTotalsBelowClauses(path, value, false),
+    {
+      $and: [
+        value === null ? { [path]: null } : { [path]: { $eq: value } },
+        { $or: groupedTotalsAtOrBeforeClauses(restPaths, restValues) },
+      ],
+    },
+  ];
+};
+
+/**
+ * Clauses matching a group key member paging cannot order: an array, a
+ * document, a Decimal128, NaN or any type outside the ordered types. Such a
+ * group always stays a candidate for the next page, so the page that reaches
+ * it refuses it instead of skipping it silently.
+ */
+const groupedTotalsUnorderedClauses = (pathArg: string): plugins.mongodb.Document[] => [
+  { [pathArg]: { $type: 'array' } },
+  { [pathArg]: { $type: 'object' } },
+  { [pathArg]: { $type: 'decimal' } },
+  { [pathArg]: Number.NaN },
+  { $nor: groupedTotalsOrderedTypes.map((typeArg) => groupedTotalsTypeClause(pathArg, typeArg)) },
+];
+
+/** The post-group `$match` that keeps the groups whose key sorts after `afterArg`. */
+const groupedTotalsAfterFilter = (
+  memberPathsArg: readonly string[],
+  afterArg: readonly unknown[],
+): plugins.mongodb.Document => ({
+  $or: [
+    ...memberPathsArg.flatMap((pathArg) => groupedTotalsUnorderedClauses(pathArg)),
+    { $nor: groupedTotalsAtOrBeforeClauses(memberPathsArg, afterArg) },
+  ],
+});
+
+/** Bounds a decoded grouped-totals cursor; a group key is at most two values. */
+const groupedTotalsCursorMaximumLength = 65_536;
+
+const encodeGroupedTotalsCursor = (
+  shapeArg: string,
+  afterArg: readonly unknown[],
+): string => Buffer.from(
+  plugins.mongodb.BSON.EJSON.stringify({ shape: shapeArg, after: afterArg }, { relaxed: false }),
+  'utf8',
+).toString('base64url');
+
+/**
+ * Decodes a grouped-totals cursor for the query shape `shapeArg`. The cursor
+ * grants nothing a caller could not ask for directly — every page still applies
+ * the caller's filters — so it is checked, not signed: it must decode, carry
+ * this query's shape and one ordered value per group key member.
+ */
+const decodeGroupedTotalsCursor = (
+  cursorArg: unknown,
+  shapeArg: string,
+  memberCountArg: number,
+): unknown[] => {
+  const invalid = (reasonArg: string): SmartdataPersistenceError =>
+    new SmartdataPersistenceError('invalid_argument', `Grouped totals cursor ${reasonArg}.`);
+  if (
+    typeof cursorArg !== 'string'
+    || cursorArg.length === 0
+    || cursorArg.length > groupedTotalsCursorMaximumLength
+    || !/^[A-Za-z0-9_-]+$/.test(cursorArg)
+  ) {
+    throw invalid('must be a nextCursor returned by getGroupedTotalsPage()');
+  }
+  let decoded: unknown;
+  try {
+    decoded = plugins.mongodb.BSON.EJSON.parse(
+      Buffer.from(cursorArg, 'base64url').toString('utf8'),
+      { relaxed: false },
+    );
+  } catch {
+    throw invalid('does not decode');
+  }
+  if (
+    !isPlainObject(decoded)
+    || Object.keys(decoded).length !== 2
+    || typeof decoded.shape !== 'string'
+    || !Array.isArray(decoded.after)
+  ) {
+    throw invalid('does not decode');
+  }
+  if (decoded.shape !== shapeArg) {
+    throw invalid(
+      'belongs to another query: groupBy, unwind, sums, filter and elementFilter must match the page that returned it',
+    );
+  }
+  if (decoded.after.length !== memberCountArg) {
+    throw invalid('does not hold one value per groupBy path');
+  }
+  return decoded.after.map((valueArg: unknown) => {
+    const value = valueArg instanceof plugins.mongodb.Int32 || valueArg instanceof plugins.mongodb.Double
+      ? valueArg.valueOf()
+      : valueArg;
+    if (groupedTotalsOrderedTypeOf(value) === undefined) {
+      throw invalid('holds a group value paging does not order');
+    }
+    return value;
+  });
+};
+
 const pathsConflict = (leftArg: string, rightArg: string): boolean =>
   leftArg === rightArg ||
   leftArg.startsWith(`${rightArg}.`) ||
@@ -5093,12 +5481,13 @@ 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 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.
+   * optionally per element of one declared array (`unwind`), whose element
+   * fields `groupBy` and `sums` may then name and `elementFilter` may select,
+   * always returns a `count` per group, and sums only declared numeric paths.
+   * Rows come ordered by group key, and the first `limit` groups in that
+   * order are returned. Use `getGroupedTotalsPage()` when the caller must
+   * detect or read further groups. The aggregation cursor never leaves
+   * SmartData.
    */
   public static async getGroupedTotals<
     T,
@@ -5107,15 +5496,27 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     this: plugins.tsclass.typeFest.Class<T>,
     optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>,
   ): Promise<Array<ISmartdataGroupedTotalsRow<T, TUnwind>>> {
-    const page = await (this as any).getGroupedTotalsPage(optionsArg) as
+    const page = await (this as any).readGroupedTotalsPage(optionsArg, false) as
       ISmartdataGroupedTotalsPage<T, TUnwind>;
     return page.rows;
   }
 
   /**
-   * Computes the same bounded grouped totals as `getGroupedTotals()` and
-   * reports whether at least one additional group exists beyond the requested
-   * row limit.
+   * Computes the same grouped totals as `getGroupedTotals()`, reports whether
+   * at least one further group exists beyond the requested row limit and, when
+   * one does, returns `nextCursor` to read the next page through `cursor`.
+   * Pages follow the group key order, so reading them to the end reports
+   * every group exactly once while the data does not change. Under concurrent
+   * writes every page reads the data as it is at that page's read: the cursor
+   * only moves forward, so no group is reported twice, but a group created
+   * with a key before the cursor is not reported, and totals on different
+   * pages can reflect different moments. A caller that needs one consistent
+   * view reads every page inside one transaction session, as far as the
+   * engine's transaction isolation provides one. Paging orders group values that are null or missing,
+   * numbers, strings, ObjectIds, booleans and dates; a page that returns a
+   * cursor or continues one refuses any other group value — an array, a
+   * document, a Decimal128, NaN — with `unsupported_operation` instead of
+   * skipping it.
    */
   public static async getGroupedTotalsPage<
     T,
@@ -5123,6 +5524,53 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
   >(
     this: plugins.tsclass.typeFest.Class<T>,
     optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>,
+  ): Promise<ISmartdataGroupedTotalsPage<T, TUnwind>> {
+    return await (this as any).readGroupedTotalsPage(optionsArg, true) as
+      ISmartdataGroupedTotalsPage<T, TUnwind>;
+  }
+
+  /**
+   * Reads every group of a grouped-totals query in group key order, one page
+   * of `limit` groups per database round trip through
+   * `getGroupedTotalsPage()`, with the same exactness, ordering and
+   * concurrency rules. `cursor` resumes after an earlier page; `signal`,
+   * `timeoutMS` and `maxTimeMS` apply to each page.
+   */
+  public static async *iterateGroupedTotals<
+    T,
+    TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never,
+  >(
+    this: plugins.tsclass.typeFest.Class<T>,
+    optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>,
+  ): AsyncGenerator<ISmartdataGroupedTotalsRow<T, TUnwind>, void, undefined> {
+    // The first page validates the caller's options, so every later page
+    // copies an inert plain object.
+    let page = await (this as any).readGroupedTotalsPage(optionsArg, true) as
+      ISmartdataGroupedTotalsPage<T, TUnwind>;
+    while (true) {
+      yield* page.rows;
+      if (page.nextCursor === undefined) {
+        return;
+      }
+      page = await (this as any).readGroupedTotalsPage(
+        { ...optionsArg, cursor: page.nextCursor },
+        true,
+      ) as ISmartdataGroupedTotalsPage<T, TUnwind>;
+    }
+  }
+
+  /**
+   * Validates grouped-totals options and reads one page. `mintCursorArg` is
+   * false for `getGroupedTotals()`, which returns rows only and so never
+   * needs the next page's cursor.
+   */
+  private static async readGroupedTotalsPage<
+    T,
+    TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never,
+  >(
+    this: plugins.tsclass.typeFest.Class<T>,
+    optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>,
+    mintCursorArg: boolean,
   ): Promise<ISmartdataGroupedTotalsPage<T, TUnwind>> {
     if ((this as any)[exactPersistencePolicySymbol]) {
       throw new SmartdataPersistenceError(
@@ -5144,9 +5592,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     const allowedKeys = new Set([
       'groupBy',
       'unwind',
+      'elementFilter',
       'sums',
       'filter',
       'limit',
+      'cursor',
       'maxTimeMS',
       'timeoutMS',
       'signal',
@@ -5173,9 +5623,11 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     }
     const groupByOption = optionsArg.groupBy;
     const unwindOption = optionsArg.unwind;
+    const elementFilterOption = optionsArg.elementFilter;
     const sumsOption = optionsArg.sums;
     const filterOption = optionsArg.filter;
     const limitOption = optionsArg.limit;
+    const cursorOption = optionsArg.cursor;
     const maxTimeMSOption = optionsArg.maxTimeMS;
     const timeoutMSOption = optionsArg.timeoutMS;
     const signalOption = optionsArg.signal;
@@ -5254,10 +5706,36 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     }
     let unwindField: string | undefined;
     if (unwindOption !== undefined) {
-      if (typeof unwindOption !== 'string' || !groupByFields.includes(unwindOption)) {
+      if (typeof unwindOption !== 'string') {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Grouped totals unwind must name a declared array path.',
+        );
+      }
+      requireDeclaredGroupField(unwindOption, 'Grouped totals unwind path');
+      const aggregatedFields = [...groupByFields, ...sumFields];
+      // The unwound array either is a groupBy or sum path, or holds the
+      // element fields a groupBy or sum path names below it.
+      if (
+        !aggregatedFields.some((fieldArg) =>
+          fieldArg === unwindOption || fieldArg.startsWith(unwindOption + '.'),
+        )
+      ) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Grouped totals unwind must name a groupBy or sum path, or the array holding one of them.',
+        );
+      }
+      // A path that contains the unwound array would read a document whose
+      // array has been replaced by one element: neither the document's value
+      // nor the element's.
+      const containingField = aggregatedFields.find((fieldArg) =>
+        unwindOption.startsWith(fieldArg + '.'),
+      );
+      if (containingField !== undefined) {
         throw new SmartdataPersistenceError(
           'invalid_argument',
-          'Grouped totals unwind must name one of the groupBy paths.',
+          `Grouped totals path "${containingField}" contains the unwound array "${unwindOption}".`,
         );
       }
       if (
@@ -5273,6 +5751,21 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       }
       unwindField = unwindOption;
     }
+    let elementMatch: plugins.mongodb.Filter<plugins.mongodb.Document> | undefined;
+    if (elementFilterOption !== undefined) {
+      if (unwindField === undefined) {
+        throw new SmartdataPersistenceError(
+          'invalid_argument',
+          'Grouped totals elementFilter requires unwind: it selects elements of the unwound array.',
+        );
+      }
+      elementMatch = normalizeGroupedTotalsElementFilter(
+        elementFilterOption,
+        unwindField,
+        declaredRoots,
+        declaredNestedPaths,
+      );
+    }
     const limit = requireBoundedInteger(
       limitOption,
       'Grouped totals limit',
@@ -5307,13 +5800,20 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     // 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;
+    // MongoDB omits a missing member from a composite key, which would split
+    // missing and null into two groups reported alike; NoSQLDB evaluates a
+    // missing member as null. `$ifNull` merges them on MongoDB as well.
+    const compositeMember = (fieldArg: string): unknown =>
+      collection.smartdataDb.capabilities?.backend === 'mongodb'
+        ? { $ifNull: ['$' + fieldArg, null] }
+        : '$' + fieldArg;
     const groupStage: Record<string, unknown> = {
       _id: groupByFields.length === 1
         ? '$' + groupByFields[0]
         : Object.fromEntries(
             groupByFields.map((fieldArg, indexArg) => [
               compositeKeyName(indexArg),
-              '$' + fieldArg,
+              compositeMember(fieldArg),
             ]),
           ),
       __groupedTotalsCount: { $sum: 1 },
@@ -5321,10 +5821,38 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     for (const [index, sumField] of sumFields.entries()) {
       groupStage['__groupedTotalsSum' + index] = { $sum: '$' + sumField };
     }
+    const normalizedFilter = filterOption !== undefined
+      ? (this as any).normalizeReadFilter(filterOption) as plugins.mongodb.Filter<plugins.mongodb.Document>
+      : undefined;
+    // The group key's members as the post-group stages address them.
+    const keyMemberPaths = groupByFields.length === 1
+      ? ['_id']
+      : groupByFields.map((_fieldArg, indexArg) => '_id.' + compositeKeyName(indexArg));
+    const readKeyMembers = (rowArg: plugins.mongodb.Document): unknown[] => {
+      if (groupByFields.length === 1) {
+        return [rowArg._id ?? null];
+      }
+      const compoundKey = (rowArg._id ?? {}) as Record<string, unknown>;
+      return groupByFields.map((_fieldArg, indexArg) => compoundKey[compositeKeyName(indexArg)] ?? null);
+    };
+    // Binds a cursor to the query it continues. The limit may change between
+    // pages; everything that decides which groups exist may not.
+    const queryShape = (): string => plugins.nodeCrypto
+      .createHash('sha256')
+      .update(plugins.mongodb.BSON.EJSON.stringify({
+        collection: collection.collectionName,
+        groupBy: groupByFields,
+        unwind: unwindField ?? null,
+        sums: sumFields,
+        filter: normalizedFilter ?? null,
+        elementFilter: elementMatch ?? null,
+      }, { relaxed: false }))
+      .digest('base64url');
+    const after = cursorOption !== undefined
+      ? decodeGroupedTotalsCursor(cursorOption, queryShape(), keyMemberPaths.length)
+      : undefined;
     const rows = await collection.aggregateGroupedTotals(
-      filterOption !== undefined
-        ? (this as any).normalizeReadFilter(filterOption)
-        : undefined,
+      normalizedFilter,
       groupStage,
       limit + 1,
       {
@@ -5333,10 +5861,43 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
         ...(timeoutMS !== undefined ? { timeoutMS } : {}),
         ...(signalOption !== undefined ? { signal: signalOption } : {}),
         ...(unwindField !== undefined ? { unwindPath: unwindField } : {}),
+        ...(elementMatch !== undefined ? { elementMatch } : {}),
+        ...(after !== undefined
+          ? { groupMatch: groupedTotalsAfterFilter(keyMemberPaths, after) }
+          : {}),
+        sort: Object.fromEntries(keyMemberPaths.map((pathArg) => [pathArg, 1])),
       },
     );
     const hasMore = rows.length > limit;
     const returnedRows = rows.slice(0, limit);
+    const mintsCursor = mintCursorArg && hasMore;
+    let lastKey: unknown[] | undefined;
+    if (mintsCursor || after !== undefined) {
+      // A page that continues or is continued claims exact paging, so every
+      // key on it must be an ordered value, and the engine must have returned
+      // the keys strictly ascending after the cursor.
+      let previousKey = after;
+      for (const row of returnedRows) {
+        const key = readKeyMembers(row);
+        for (const [index, value] of key.entries()) {
+          if (groupedTotalsOrderedTypeOf(value) === undefined) {
+            throw new SmartdataPersistenceError(
+              'unsupported_operation',
+              `Grouped totals cannot page over group values of "${groupByFields[index]}" that are not `
+              + 'null, numbers, strings, ObjectIds, booleans or dates.',
+            );
+          }
+        }
+        if (previousKey !== undefined && compareGroupedTotalsKeys(previousKey, key) >= 0) {
+          throw new SmartdataPersistenceError(
+            'unsupported_operation',
+            'Grouped totals paging received groups out of group key order from this backend.',
+          );
+        }
+        previousKey = key;
+      }
+      lastKey = previousKey;
+    }
     const requireFiniteNumber = (
       valueArg: unknown,
       labelArg: string,
@@ -5380,6 +5941,9 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     return {
       rows: mappedRows,
       hasMore,
+      ...(mintsCursor && lastKey !== undefined
+        ? { nextCursor: encodeGroupedTotalsCursor(queryShape(), lastKey) }
+        : {}),
     };
   }