@lossless.org/client 1.15.0 → 1.17.0

package/dist_ts/nosqldb/classes.doc.d.ts

@@ -287,15 +287,33 @@ export interface ISmartdataGroupedTotalsOptions<T, TUnwind extends TSmartdataGro
      */
     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.
@@ -303,12 +321,21 @@ export interface ISmartdataGroupedTotalsOptions<T, TUnwind extends TSmartdataGro
     sums?: ReadonlyArray<TSmartdataNumericDocumentPath<T> | TSmartdataAtomicNestedDocumentPath<T>>;
     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
@@ -336,7 +363,23 @@ export interface ISmartdataGroupedTotalsRow<T, TUnwind extends TSmartdataGrouped
 export interface ISmartdataGroupedTotalsPage<T, TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never> {
     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;
 }[TSmartdataDocumentPath<T>];
@@ -753,20 +796,47 @@ export declare class SmartDataDbDoc<T extends TImplements, TImplements, TManager
      * 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.
      */
     static getGroupedTotals<T, TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>): Promise<Array<ISmartdataGroupedTotalsRow<T, TUnwind>>>;
     /**
-     * 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.
      */
     static getGroupedTotalsPage<T, TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>): Promise<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.
+     */
+    static iterateGroupedTotals<T, TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>): AsyncGenerator<ISmartdataGroupedTotalsRow<T, TUnwind>, void, undefined>;
+    /**
+     * 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 readGroupedTotalsPage;
     /**
      * gets all instances as array
      * @param this