@lossless.org/client 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lossless.org/client",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "private": false,
   "description": "One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.",
   "exports": {
@@ -82,7 +82,7 @@
     "@aws-sdk/client-s3": "^3.1039.0",
     "@clickhouse/client": "1.23.1",
     "@git.zone/tsbuild": "5.0.0",
-    "@git.zone/tsrun": "3.0.1",
+    "@git.zone/tsrun": "3.0.2",
     "@git.zone/tstest": "6.3.2",
     "@lossless.org/nosqldb": "8.0.2",
     "@lossless.org/nosqldb-qualified": "npm:@lossless.org/nosqldb@10.7.2",

package/readme.md

@@ -108,6 +108,8 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Transactions ended by close | a `session.withTransaction()` whose session `db.close()` ends while it runs rejects with `SmartdataPersistenceError` code `unsupported_operation` — "nothing was committed" before the commit, "the commit outcome is unknown" during it — instead of resolving with the callback's result |
 | Transaction commit outcome | `SmartdataSession.getCommitOutcome(error)` states for every value a `session.withTransaction()` rejected with whether the transaction could have committed: `not_committed` (nothing was committed) or `unknown` (a commit was sent and never confirmed); the rejection itself keeps its identity |
 | Cancellation | `signal` on every exact call, `atomicDeleteMany()` and `session.withTransaction(callback, { signal })`, which interrupts the session's operation in flight, rolls the attempt back and never commits after an abort |
+| Nested array paths | `@svDb({ arrayPaths: [...] })` declares nested arrays below a persisted root; `$push`, `$addToSet` and `$pull` in `atomicUpdate()`, `atomicUpdateMany()`, `atomicFindOneAndUpdate()` and `atomicUpsertMany()` accept them, while undeclared and non-array nested paths stay refused with `invalid_argument` |
+| Grouped totals over nested paths | `getGroupedTotals()` / `getGroupedTotalsPage()` group by and sum nested paths declared through `atomicPaths` or `arrayPaths`, and `unwind: path` groups by each element of one declared array |
 | Query-plan inspection | `Model.inspectQueryPlan(db, { filter, sort?, projection?, limit?, timeoutMS?, signal? })` — the winning plan's stages (`stage`, `depth`, `indexName`, `direction`) and `nReturned`/`totalKeysExamined`/`totalDocsExamined`, read-only and bounded, so a consumer proves a model query uses its intended index without raw driver access |
 | Disposable test databases on a unix socket | `SmartdataTestDatabase.create({ connection: { socketPath } })` from `@lossless.org/client/testsupport` reaches an engine that listens only on a unix-domain socket, fault helpers included; the loopback `host`/`port` form is unchanged |
 
@@ -130,8 +132,8 @@ The document model runs on both NoSQLDB and MongoDB, but several APIs do not mea
 
 | Document API | On the NoSQLDB engine | On MongoDB |
 | --- | --- | --- |
-| `getGroupedTotals()` / `getGroupedTotalsPage()` with one `groupBy` field | exact, including `sums` | exact |
-| the same with **two** `groupBy` fields | exact, `sums` included, on an engine that identifies itself as NoSQLDB 10.5.0 or newer: that release evaluates the composite group key per document. Below it the call is refused with `unsupported_operation` naming both fields and the single-field form, because the engine leaves the composite group key unresolved and answers with a single row whose group values are the literal field paths (`'$owner'`) and whose count is the whole filtered collection; the refusal is the guard against that wrong number, not a fix for it | exact |
+| `getGroupedTotals()` / `getGroupedTotalsPage()` with one `groupBy` field | exact, including `sums`, declared nested paths and `unwind` of a declared array, on 8.0.2 and 10.7.2 alike | exact |
+| the same with **two** `groupBy` fields | exact, `sums`, nested paths and `unwind` included, on an engine that identifies itself as NoSQLDB 10.5.0 or newer: that release evaluates the composite group key per document. Below it the call is refused with `unsupported_operation` naming both fields and the single-field form, because the engine leaves the composite group key unresolved and answers with a single row whose group values are the literal field paths (`'$owner'`) and whose count is the whole filtered collection; the refusal is the guard against that wrong number, not a fix for it | exact |
 | guarded `$expr` atomic filters (`$add`, `$lte`, `$ifNull`) | exact on 10.6.0 and newer: the engine evaluates the client's fail-closed compilation (`$cond`, `$let`, `$isNumber`, `$type`), so the guard admits within the limit, refuses beyond it and never matches a stored value that is not a finite number. 8.0.2 rejects the compilation with `invalid argument: $cond` and leaves the document untouched | exact |
 | `watch()` change streams | unsupported. `NoSqlConnection` refuses with `unsupported_capability`, and so does a plain `SmartdataDb` whose engine identified itself; against an engine that answers no identity the refusal instead arrives from the engine as `CommandNotFound` once the change stream is read | supported on replica sets |
 | model-declared partial indexes (`partialFilterExpression`) | not expressible: the index-option type rejects it and the runtime refuses it with `invalid_configuration`. A client decision, not an engine limit on every release — 10.6.0 and newer create partial indexes, 8.0.2 refuses the option with `InvalidOptions` (72) — because one model declaration has to hold on every qualified backend. A migration may create one on 10.7.2; `toleratedIndexNames` accepts it and inspection reports its filter | not expressible, but a migration may own one; inspection reports its filter |

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@lossless.org/client',
-  version: '1.14.0',
+  version: '1.15.0',
   description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
 }

package/ts/nosqldb/classes.collection.ts

@@ -2498,13 +2498,21 @@ export class SmartdataCollection<T> {
    * Executes a bounded grouped-totals aggregation over already-validated
    * stages and never exposes the aggregation cursor. Prefer the validated
    * static `SmartDataDbDoc.getGroupedTotals()`, which owns input validation
-   * before this raw persistence boundary.
+   * before this raw persistence boundary. `unwindPath` names an already
+   * validated field path whose array is unwound between the match and the
+   * group stage.
    */
   public async aggregateGroupedTotals(
     matchArg: plugins.mongodb.Filter<plugins.mongodb.Document> | undefined,
     groupArg: plugins.mongodb.Document,
     limitArg: number,
-    opts?: { session?: TSmartdataOrdinarySession; maxTimeMS?: number; timeoutMS?: number; signal?: AbortSignal }
+    opts?: {
+      session?: TSmartdataOrdinarySession;
+      maxTimeMS?: number;
+      timeoutMS?: number;
+      signal?: AbortSignal;
+      unwindPath?: string;
+    }
   ): Promise<plugins.mongodb.Document[]> {
     return this.runWithOrdinarySession(
       opts?.session,
@@ -2515,6 +2523,9 @@ export class SmartdataCollection<T> {
         if (matchArg && Object.keys(matchArg).length > 0) {
           pipeline.push({ $match: matchArg });
         }
+        if (opts?.unwindPath !== undefined) {
+          pipeline.push({ $unwind: '$' + opts.unwindPath });
+        }
         pipeline.push({ $group: groupArg });
         pipeline.push({ $limit: limitArg });
         const cursor = this.mongoDbCollection.aggregate(pipeline, {