@lossless.org/client 1.14.0 → 1.16.0

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

@@ -62,6 +62,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.
@@ -261,16 +268,43 @@ export interface ISmartdataAtomicNumericExpression<T> {
         TSmartdataAtomicNumericExpressionOperand<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 declared top-level fields whose distinct value combinations
-     * form the groups.
+     * 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<TSmartdataDocumentPath<T>>;
+    groupBy: ReadonlyArray<TSmartdataGroupedTotalsPath<T>>;
     /**
-     * Declared numeric top-level fields to sum per group.
+     * 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.
      */
-    sums?: ReadonlyArray<TSmartdataNumericDocumentPath<T>>;
+    unwind?: TUnwind;
+    /**
+     * Declared numeric top-level fields, or declared nested paths holding
+     * numbers, to sum per group.
+     */
+    sums?: ReadonlyArray<TSmartdataNumericDocumentPath<T> | TSmartdataAtomicNestedDocumentPath<T>>;
     filter?: MongoFilter<T>;
     /**
      * Required bound on the number of returned groups (1..10000). The group
@@ -290,32 +324,41 @@ export interface ISmartdataGroupedTotalsOptions<T> {
     signal?: AbortSignal;
     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;
-    };
+        [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;
 }
 export type TSmartdataAtomicArrayPath<T> = {
     [TKey in TSmartdataDocumentPath<T>]: NonNullable<T[TKey]> extends ReadonlyArray<unknown> ? TKey : never;
 }[TSmartdataDocumentPath<T>];
 type TSmartdataAtomicArrayElement<TValue> = NonNullable<TValue> extends ReadonlyArray<infer TElement> ? TElement : never;
+/**
+ * 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]>;
-}>;
-type TSmartdataAtomicPullScalar<TValue> = Extract<TValue, string | number | boolean | null | Date | plugins.mongodb.ObjectId | plugins.mongodb.Binary | plugins.mongodb.Decimal128 | plugins.mongodb.Long | plugins.mongodb.Int32 | plugins.mongodb.Double | plugins.mongodb.Timestamp>;
+}> & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, unknown>>;
+/** The scalar equality operands `$pull` accepts. */
+type TSmartdataAtomicPullScalarValue = string | number | boolean | null | Date | plugins.mongodb.ObjectId | plugins.mongodb.Binary | plugins.mongodb.Decimal128 | plugins.mongodb.Long | plugins.mongodb.Int32 | plugins.mongodb.Double | plugins.mongodb.Timestamp;
+type TSmartdataAtomicPullScalar<TValue> = Extract<TValue, TSmartdataAtomicPullScalarValue>;
 type TSmartdataAtomicArrayPullOperation<T> = Partial<{
     [TKey in TSmartdataAtomicArrayPath<T>]: TSmartdataAtomicPullScalar<TSmartdataAtomicArrayElement<T[TKey]>>;
-}>;
+}> & Partial<Record<TSmartdataAtomicNestedDocumentPath<T>, TSmartdataAtomicPullScalarValue>>;
 export interface ISmartdataAtomicUpdate<T> {
     $set?: TSmartdataAtomicSet<T>;
     $unset?: Partial<Record<TSmartdataAtomicDocumentPath<T>, '' | true | 1>>;
@@ -334,19 +377,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>;
 }
@@ -565,7 +610,14 @@ export declare class SmartDataDbDoc<T extends TImplements, TImplements, TManager
      * guarantee at most one matching document for an equality filter.
      */
     private static getGloballyConstrainingKeySets;
+    /**
+     * Every nested path the model declares below a persisted field, through
+     * `@svDb({ atomicPaths })` or `@svDb({ arrayPaths })`.
+     */
     private static getDeclaredAtomicPaths;
+    /** The nested paths declared through `@svDb({ arrayPaths })` as holding arrays. */
+    private static getDeclaredArrayPaths;
+    private static readDeclaredNestedPaths;
     private static getSerializedPersistedRoots;
     private static getDeclaredQueryPaths;
     private static assertHydratedProjection;
@@ -703,19 +755,23 @@ export declare class SmartDataDbDoc<T extends TImplements, TImplements, TManager
     static atomicUpsertMany<T>(this: plugins.tsclass.typeFest.Class<T>, operationsArg: ReadonlyArray<ISmartdataAtomicUpsertManyOperation<T>>, opts?: ISmartdataAtomicUpsertManyOptions): Promise<ISmartdataAtomicUpsertManyResult>;
     /**
      * 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.
-     */
-    static getGroupedTotals<T>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T>): Promise<Array<ISmartdataGroupedTotalsRow<T>>>;
+     * Groups by one or two declared paths — top-level fields or nested paths
+     * declared through `@svDb({ atomicPaths })` or `@svDb({ arrayPaths })` —
+     * optionally per element of one declared array (`unwind`), whose element
+     * fields `groupBy` and `sums` may then name, 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.
+     */
+    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.
      */
-    static getGroupedTotalsPage<T>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T>): Promise<ISmartdataGroupedTotalsPage<T>>;
+    static getGroupedTotalsPage<T, TUnwind extends TSmartdataGroupedTotalsUnwindPath<T> = never>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T, TUnwind>): Promise<ISmartdataGroupedTotalsPage<T, TUnwind>>;
     /**
      * gets all instances as array
      * @param this