@lossless.org/client 1.13.0 → 1.15.0

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

@@ -4,6 +4,7 @@ import { SmartdataDbCursor } from './classes.cursor.js';
 import { type ISmartdataBootstrapRecordOptions, type ISmartdataBootstrapRecordResult } from './classes.bootstraprecord.js';
 import { type ISmartdataCollectionPreparationOptions } from './classes.collectionpreparation.js';
 import { type ISmartdataStoredInspectionOptions, type ISmartdataStoredInspection, type ISmartdataStoredEvidenceInspection } from './classes.storedinspection.js';
+import { type ISmartdataQueryPlan, type ISmartdataQueryPlanOptions } from './classes.queryplaninspection.js';
 import { type IManager, type ISmartdataIndexInfo, SmartdataCollection } from './classes.collection.js';
 import { SmartdataDbWatcher } from './classes.watcher.js';
 import { type TSmartdataOrdinarySession } from './classes.session.js';
@@ -61,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.
@@ -260,16 +268,39 @@ 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 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
@@ -289,32 +320,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>>;
@@ -333,19 +373,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>;
 }
@@ -534,6 +576,12 @@ export declare class SmartDataDbDoc<T extends TImplements, TImplements, TManager
     static inspectStoredDocuments(dbArg: SmartdataDb, optionsArg?: ISmartdataStoredInspectionOptions): Promise<ISmartdataStoredInspection>;
     /** Diagnose stored BSON with explicit ordinary validation evidence, without hydration. */
     static inspectStoredDocumentEvidence(dbArg: SmartdataDb, optionsArg?: ISmartdataStoredInspectionOptions): Promise<ISmartdataStoredEvidenceInspection>;
+    /**
+     * 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.
+     */
+    static inspectQueryPlan<T>(this: plugins.tsclass.typeFest.Class<T>, dbArg: SmartdataDb, optionsArg: ISmartdataQueryPlanOptions<T>): Promise<ISmartdataQueryPlan>;
     static createInstanceFromMongoDbNativeDoc<T>(this: plugins.tsclass.typeFest.Class<T>, mongoDbNativeDocArg: any): T;
     private static getDeclaredPersistedRoots;
     private static getDeclaredUniqueRoots;
@@ -558,7 +606,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;
@@ -696,19 +751,22 @@ 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.
+     * 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.
      */
-    static getGroupedTotals<T>(this: plugins.tsclass.typeFest.Class<T>, optionsArg: ISmartdataGroupedTotalsOptions<T>): Promise<Array<ISmartdataGroupedTotalsRow<T>>>;
+    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