@procedures/mongo 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @procedures/mongo
 
+## 0.3.0
+
+### Minor Changes
+
+- c799cdd: `HybridStorage` cannot lose data (roadmap R2). A sync gets the ids of the remote items from the new `getEntries()` of a storage (the collection procedure `collections.<name>.entries`), or else from `keyOf`. A remote item without a key stops the sync with `MissingKeysError` before any change: before, such a list emptied the local cache. A write-through that the remote cannot take waits in the queue and throws `PendingWriteError`, and a timer sends the queue. A write that the remote refuses is undone in the local cache. A full queue refuses a write with `QueueFullError`: before, it dropped the oldest operation. A second try of a write replaces its queued operation. A write-through sends the older queued operations first. The reads wait for the first sync.
+- 3aa6495: Four procedures (roadmap R44). `mongo.documents.distinct` gives the distinct values of a field. `mongo.documents.bulk` sends `insertOne`, `updateOne`, `updateMany`, `deleteOne` and `deleteMany` operations in one request, in order by default. An empty filter of an update or a delete needs `confirm: true`. `mongo.documents.explain` gives the plan of a find or an aggregation, and refuses `$out` and `$merge`.
+  
+  `mongo.watch` gives the changes of a collection or a database as a stream without an end. The stream closes when the reader stops or the call aborts. A change stream needs a replica set. The type `BulkOperation` also has `BulkUpdateMany` and `BulkDeleteMany`.
+- 89d8a4a: Three procedures only read now (CAP-1, CAP-2, CAP-3, roadmap R7), so a read-only session (`mark mcp --read-only`) serves them. `db.query` refuses a statement that changes data (`PRAGMA query_only`), and the file keeps its bytes. `mongo.documents.aggregate` refuses `$out` and `$merge`, also in the pipelines of `$facet`, `$lookup` and `$unionWith`. `logs.query` gives no entries for a missing file or table, and does not make them.
+
+### Patch Changes
+
+- Updated dependencies [ddea529]
+- Updated dependencies [b2a3e3a]
+- Updated dependencies [a8c47f1]
+- Updated dependencies [381ce3a]
+- Updated dependencies [0c627f8]
+- Updated dependencies [ae7f05f]
+- Updated dependencies [7873940]
+- Updated dependencies [a70d445]
+- Updated dependencies [bc70357]
+- Updated dependencies [07cc998]
+- Updated dependencies [a6b01a9]
+- Updated dependencies [c799cdd]
+- Updated dependencies [540f8d9]
+- Updated dependencies [b6daaec]
+- Updated dependencies [5b9264e]
+- Updated dependencies [956e88b]
+- Updated dependencies [ff62281]
+- Updated dependencies [d81d0ed]
+- Updated dependencies [aa67cc7]
+- Updated dependencies [061fa22]
+- Updated dependencies [cfb9d69]
+- Updated dependencies [43f7de5]
+- Updated dependencies [b07bb50]
+- Updated dependencies [4a3bfa1]
+- Updated dependencies [bd0b626]
+- Updated dependencies [a6be873]
+- Updated dependencies [fb30718]
+- Updated dependencies [c5528e4]
+- Updated dependencies [fee5d9c]
+- Updated dependencies [21f7743]
+- Updated dependencies [31a0b46]
+  - @procedures/client@0.3.0
+  - @procedures/collections@0.3.0
+
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies [15e48cf]
+  - @procedures/client@0.2.3
+  - @procedures/collections@0.2.3
+
 ## 0.2.2
 
 ### Patch Changes

package/README.md

@@ -13,11 +13,12 @@ MongoDB client wrapper with client procedures for local or RPC access. Provides
 - **Local usage**: Direct MongoDB connection with native driver
 - **RPC usage**: Remote procedure calls via `client.call()`
 
-The package follows the client procedure pattern, with 16 procedures in 4 categories. Its register entry (`import "@procedures/mongo/register"`) registers them:
+The package follows the client procedure pattern, with 20 procedures in 5 categories. Its register entry (`import "@procedures/mongo/register"`) registers them:
 - **Database**: `ping`, `info`
 - **Collections**: `list`, `create`, `drop`, `stats`
-- **Documents**: `find`, `get`, `insert`, `update`, `delete`, `count`, `aggregate`
+- **Documents**: `find`, `get`, `insert`, `update`, `delete`, `count`, `aggregate`, `distinct`, `bulk`, `explain`
 - **Indexes**: `list`, `create`, `drop`
+- **Change streams**: `mongo.watch`
 
 ## Architecture
 
@@ -735,6 +736,52 @@ interface AggregateOutput {
 }
 ```
 
+##### `mongo.documents.distinct`
+
+The procedure gives the distinct values of one field in the documents that match `query`. The default `query` matches all documents. An array field gives each of its elements. Use dots for an embedded field, for example `address.city`.
+
+```typescript
+const { values } = await client.exec(
+  ["mongo", "documents", "distinct"],
+  { collection: "users", field: "country", query: { status: "active" } }
+);
+```
+
+##### `mongo.documents.bulk`
+
+The procedure sends several writes in one request. The operations have the form of the `bulkWrite` of the driver: `insertOne`, `updateOne`, `updateMany`, `deleteOne` and `deleteMany`. By default, the operations run in order, and the first failure stops the rest. With `ordered: false`, the server tries each operation, and the error tells which ones failed.
+
+The rules of `update` and `delete` apply to each operation. An empty filter of an update or a delete needs `confirm: true` on the call. An unknown operation or field is an error.
+
+```typescript
+const result = await client.exec(["mongo", "documents", "bulk"], {
+  collection: "users",
+  operations: [
+    { insertOne: { document: { name: "Di" } } },
+    { updateOne: { filter: { name: "Ann" }, update: { $set: { status: "active" } } } },
+    { updateMany: { filter: { status: "new" }, update: { $set: { status: "active" } } } },
+    { deleteOne: { filter: { name: "Bob" } } },
+    { deleteMany: { filter: { status: "deleted" } } },
+  ],
+});
+// result: { ok, insertedCount, matchedCount, modifiedCount, deletedCount, upsertedCount, insertedIds, upsertedIds }
+```
+
+The ids in `insertedIds` and `upsertedIds` are text, and their keys are the indexes of the operations.
+
+##### `mongo.documents.explain`
+
+The procedure gives the plan of a find or of an aggregation pipeline. With `pipeline`, it explains an aggregation. Without `pipeline`, it explains a find with `query`, `projection`, `sort` and `limit`. The verbosity `queryPlanner` (the default) gives the plan only. With the verbosities `executionStats` and `allPlansExecution`, the server also does the plan and gives its statistics. As `documents.aggregate` does, the procedure refuses `$out` and `$merge`.
+
+```typescript
+const { operation, plan } = await client.exec(["mongo", "documents", "explain"], {
+  collection: "users",
+  query: { email: "ann@example.com" },
+  verbosity: "executionStats",
+});
+console.log(plan.queryPlanner.winningPlan);
+```
+
 #### Index Procedures
 
 ##### `mongo.indexes.list`
@@ -856,6 +903,26 @@ interface DropIndexOutput {
 }
 ```
 
+#### Change Streams
+
+##### `mongo.watch`
+
+The procedure gives the changes of a collection as a stream. Without `collection`, it gives the changes of each collection of the database. The stream has no end (`metadata.stream: { unbounded: true }`). It stops when the reader stops or the call aborts, and the procedure then closes the change stream.
+
+A change stream needs a replica set or a sharded cluster. A standalone server refuses it, and the reader gets that error.
+
+```typescript
+for await (const change of client.execStream(["mongo", "watch"], {
+  collection: "orders",
+  pipeline: [{ $match: { operationType: { $in: ["insert", "update"] } } }],
+  fullDocument: "updateLookup",
+})) {
+  console.log(change.operationType, change.documentKey, change.resumeToken);
+}
+```
+
+Each item has the `operationType`, the namespace `ns`, the `documentKey` and the `resumeToken`. An insert gives the `fullDocument`, and an update gives the `updateDescription`. With `fullDocument: "updateLookup"`, an update also gives the current document. To continue after a stop, give the last `resumeToken` as `resumeAfter`. The `pipeline` accepts only the stages of a change stream: `$match`, `$project`, `$addFields`, `$set`, `$unset`, `$replaceRoot`, `$replaceWith` and `$redact`.
+
 ### Type Definitions
 
 #### Core Types
@@ -1278,9 +1345,13 @@ client-mongo/
 │   │   ├── documents.delete.ts
 │   │   ├── documents.count.ts
 │   │   ├── documents.aggregate.ts
+│   │   ├── documents.distinct.ts
+│   │   ├── documents.bulk.ts
+│   │   ├── documents.explain.ts
 │   │   ├── indexes.list.ts
 │   │   ├── indexes.create.ts
-│   │   └── indexes.drop.ts
+│   │   ├── indexes.drop.ts
+│   │   └── watch.ts            # mongo.watch
 ├── dist/                       # Compiled output
 ├── package.json
 ├── tsconfig.json