@procedures/mongo 0.2.2 → 0.3.0

package/src/procedures/documents.bulk.ts

@@ -0,0 +1,192 @@
+/**
+ * Procedure: mongo.documents.bulk (roadmap R44)
+ * Several writes in one request: insertOne, updateOne, updateMany, deleteOne and deleteMany
+ *
+ * The operations have the form of the `bulkWrite` of the driver, and run in order by default.
+ * In order, the first failure stops the rest. With `ordered: false`, the server runs each
+ * operation, and the error tells which ones failed.
+ *
+ * The rules of `update` and `delete` (deep dive DATA-4) apply to each operation: an empty filter
+ * of an update or a delete needs `confirm: true`, and an unknown field is an error.
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import type { AnyBulkWriteOperation, Document } from "mongodb";
+import { z } from "zod";
+import { collectionFor, copyScope, SCOPE_FIELDS, type ScopeInput } from "../scope.js";
+import { described, documentObject, scopeFields } from "./input-schemas.js";
+import type { BulkOperation, DocumentQuery, DocumentUpdate } from "../types.js";
+
+// Input/Output types
+interface BulkInput extends ScopeInput {
+  /** The writes, in order */
+  operations: BulkOperation[];
+  /** True (the default): the first failure stops the rest */
+  ordered?: boolean;
+  /** Set to true to use an empty filter in an update or a delete */
+  confirm?: boolean;
+}
+
+interface BulkOutput {
+  ok: boolean;
+  insertedCount: number;
+  matchedCount: number;
+  modifiedCount: number;
+  deletedCount: number;
+  upsertedCount: number;
+  /** The ids of the inserted documents, as text, by the index of their operation */
+  insertedIds: Record<string, string>;
+  /** The ids of the documents that an upsert made, as text, by the index of their operation */
+  upsertedIds: Record<string, string>;
+}
+
+const PROCEDURE = "mongo.documents.bulk";
+const INPUT_FIELDS = new Set<string>(["operations", "ordered", "confirm", ...SCOPE_FIELDS]);
+
+/** The fields of the body of each kind of operation, and the fields that it needs. */
+const KINDS: Record<string, { fields: readonly string[]; required: readonly string[] }> = {
+  insertOne: { fields: ["document"], required: ["document"] },
+  updateOne: { fields: ["filter", "update", "upsert"], required: ["filter", "update"] },
+  updateMany: { fields: ["filter", "update", "upsert"], required: ["filter", "update"] },
+  deleteOne: { fields: ["filter"], required: ["filter"] },
+  deleteMany: { fields: ["filter"], required: ["filter"] },
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** This function checks one operation, and gives it in the form of the driver. */
+function parseOperation(raw: unknown, index: number, confirm: boolean): BulkOperation {
+  const at = `${PROCEDURE}: operations[${index}]`;
+  if (!isPlainObject(raw) || Object.keys(raw).length !== 1) {
+    throw new Error(`${at} must be an object with one of the keys ${Object.keys(KINDS).join(", ")}`);
+  }
+  const kind = Object.keys(raw)[0]!;
+  const spec = KINDS[kind];
+  if (!spec) throw new Error(`${at}: unknown operation "${kind}". The operations are: ${Object.keys(KINDS).join(", ")}`);
+  const body = raw[kind];
+  if (!isPlainObject(body)) throw new Error(`${at}.${kind} must be an object`);
+  for (const key of Object.keys(body)) {
+    if (!spec.fields.includes(key)) throw new Error(`${at}.${kind}: unknown field "${key}". The fields are: ${spec.fields.join(", ")}`);
+  }
+  for (const key of spec.required) {
+    if (body[key] === undefined) throw new Error(`${at}.${kind}: ${key} is required`);
+  }
+  if (kind === "insertOne") {
+    if (!isPlainObject(body["document"])) throw new Error(`${at}.insertOne: document must be an object`);
+    return { insertOne: { document: body["document"] } };
+  }
+  const filter = body["filter"];
+  if (!isPlainObject(filter)) throw new Error(`${at}.${kind}: filter must be an object`);
+  if (Object.keys(filter).length === 0 && !confirm) {
+    throw new Error(`${at}.${kind}: an empty filter matches every document. Set confirm: true to use it.`);
+  }
+  if (kind === "deleteOne") return { deleteOne: { filter: filter as DocumentQuery } };
+  if (kind === "deleteMany") return { deleteMany: { filter: filter as DocumentQuery } };
+  const update = body["update"];
+  if (typeof update !== "object" || update === null) {
+    throw new Error(`${at}.${kind}: update must be an object (or a pipeline array)`);
+  }
+  const upsert = body["upsert"];
+  if (upsert !== undefined && typeof upsert !== "boolean") throw new Error(`${at}.${kind}: upsert must be a boolean`);
+  const operation = { filter: filter as DocumentQuery, update: update as DocumentUpdate, ...(upsert !== undefined ? { upsert } : {}) };
+  return kind === "updateOne" ? { updateOne: operation } : { updateMany: operation };
+}
+
+/** This function checks the input of a bulk write. */
+export function parseBulkInput(data: unknown): BulkInput {
+  if (!isPlainObject(data)) throw new Error(`${PROCEDURE}: input must be an object`);
+  for (const key of Object.keys(data)) {
+    if (!INPUT_FIELDS.has(key)) throw new Error(`${PROCEDURE}: unknown field "${key}". The fields are: ${[...INPUT_FIELDS].join(", ")}`);
+  }
+  for (const field of ["ordered", "confirm"]) {
+    if (data[field] !== undefined && typeof data[field] !== "boolean") throw new Error(`${PROCEDURE}: ${field} must be a boolean`);
+  }
+  const confirm = data["confirm"] === true;
+  const operations = data["operations"];
+  if (!Array.isArray(operations) || operations.length === 0) {
+    throw new Error(`${PROCEDURE}: operations must be a list with at least one operation`);
+  }
+  const result: BulkInput = { operations: operations.map((operation, index) => parseOperation(operation, index, confirm)) };
+  copyScope(data, result);
+  if (data["ordered"] !== undefined) result.ordered = data["ordered"] as boolean;
+  if (confirm) result.confirm = true;
+  return result;
+}
+
+/** The ids of a result, as text, by the index of their operation. */
+function idsAsText(ids: Record<number, unknown> | undefined): Record<string, string> {
+  return Object.fromEntries(Object.entries(ids ?? {}).map(([index, id]) => [index, String(id)]));
+}
+
+// Schemas
+const operationBody = (fields: Record<string, z.ZodType>) => z.object(fields);
+const filterField = documentObject().describe("The filter of the documents. An empty filter needs confirm: true.");
+const updateField = z
+  .union([documentObject(), z.array(documentObject())])
+  .describe('The update operations, for example { $set: { status: "done" } }, or a pipeline');
+const upsertField = z.boolean().optional().describe("Insert a document when none matches");
+
+const bulkInputSchema = described<BulkInput>(
+  parseBulkInput,
+  z.object({
+    ...scopeFields(),
+    operations: z
+      .array(
+        z.union([
+          z.object({ insertOne: operationBody({ document: documentObject().describe("The new document") }) }),
+          z.object({ updateOne: operationBody({ filter: filterField, update: updateField, upsert: upsertField }) }),
+          z.object({ updateMany: operationBody({ filter: filterField, update: updateField, upsert: upsertField }) }),
+          z.object({ deleteOne: operationBody({ filter: filterField }) }),
+          z.object({ deleteMany: operationBody({ filter: filterField }) }),
+        ])
+      )
+      .min(1)
+      .describe("The writes, in order: each one is { insertOne }, { updateOne }, { updateMany }, { deleteOne } or { deleteMany }"),
+    ordered: z.boolean().optional().describe("True (the default): the first failure stops the rest. False: the server tries each write."),
+    confirm: z.boolean().optional().describe("Set to true to use an empty filter, which matches every document, in an update or a delete"),
+  })
+);
+const bulkOutputSchema = zodAdapter<BulkOutput>(
+  z.looseObject({
+    ok: z.boolean().describe("True when the server confirmed the writes"),
+    insertedCount: z.number().describe("The number of inserted documents"),
+    matchedCount: z.number().describe("The number of documents that the updates matched"),
+    modifiedCount: z.number().describe("The number of documents that the updates changed"),
+    deletedCount: z.number().describe("The number of deleted documents"),
+    upsertedCount: z.number().describe("The number of documents that an upsert made"),
+    insertedIds: z.record(z.string(), z.string()).describe("The ids of the inserted documents, as text, by the index of their operation"),
+    upsertedIds: z.record(z.string(), z.string()).describe("The ids of the upserted documents, as text, by the index of their operation"),
+  })
+);
+
+export const bulkProcedure: Procedure<
+  BulkInput,
+  BulkOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "bulk"])
+  .input(bulkInputSchema)
+  .output(bulkOutputSchema)
+  .meta({
+    description: "Several writes in one request: insertOne, updateOne, updateMany, deleteOne and deleteMany, in order by default",
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"] },
+  })
+  .handler(async (input: BulkInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+    const result = await collection.bulkWrite(input.operations as AnyBulkWriteOperation<Document>[], { ordered: input.ordered ?? true });
+    return {
+      ok: result.ok === 1,
+      insertedCount: result.insertedCount,
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+      deletedCount: result.deletedCount,
+      upsertedCount: result.upsertedCount,
+      insertedIds: idsAsText(result.insertedIds),
+      upsertedIds: idsAsText(result.upsertedIds),
+    };
+  })
+  .build();
+
+export type { BulkInput, BulkOutput };

package/src/procedures/documents.distinct.ts

@@ -0,0 +1,57 @@
+/**
+ * Procedure: mongo.documents.distinct (roadmap R44)
+ * The distinct values of one field in the documents that match a filter
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { collectionFor, type ScopeInput } from "../scope.js";
+import { scopeFields, documentObject } from "./input-schemas.js";
+import { z } from "zod";
+import { type DocumentQuery } from "../types.js";
+
+// Input/Output types
+interface DistinctInput extends ScopeInput {
+  /** The field, with dots for an embedded field ("address.city") */
+  field: string;
+  /** The filter of the documents (default: all documents) */
+  query?: DocumentQuery | undefined;
+}
+
+interface DistinctOutput {
+  values: unknown[];
+}
+
+// Schemas
+const distinctInputSchema = zodAdapter<DistinctInput>(
+  z.object({
+    ...scopeFields(),
+    field: z.string().min(1).describe('The field, with dots for an embedded field (for example "address.city")'),
+    query: documentObject().optional().describe("The filter of the documents (default: all documents)"),
+  })
+);
+const distinctOutputSchema = zodAdapter<DistinctOutput>(
+  z.looseObject({
+    values: z.array(z.unknown()).describe("The distinct values of the field. An array field gives each of its elements."),
+  })
+);
+
+export const distinctProcedure: Procedure<
+  DistinctInput,
+  DistinctOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "distinct"])
+  .input(distinctInputSchema)
+  .output(distinctOutputSchema)
+  .meta({
+    description: "The distinct values of a field in the documents that match a filter",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: DistinctInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+    const values = await collection.distinct(input.field, input.query ?? {});
+    return { values };
+  })
+  .build();
+
+export type { DistinctInput, DistinctOutput };

package/src/procedures/documents.explain.ts

@@ -0,0 +1,144 @@
+/**
+ * Procedure: mongo.documents.explain (roadmap R44)
+ * The plan of a find or of an aggregation pipeline
+ *
+ * With `pipeline`, the procedure explains an aggregation. Else it explains a find with `query`
+ * (default: all documents). It refuses `$out` and `$merge`, as `documents.aggregate` does (R7):
+ * the verbosity `executionStats` runs the plan.
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import type { Document, ExplainVerbosityLike, FindOptions } from "mongodb";
+import { z } from "zod";
+import { collectionFor, copyScope, SCOPE_FIELDS, type ScopeInput } from "../scope.js";
+import { described, documentObject, scopeFields } from "./input-schemas.js";
+import { writingStage } from "./documents.aggregate.js";
+import type { AggregationStage, DocumentQuery, SortSpec } from "../types.js";
+
+/** How much the server tells: the plan only, or also the statistics of a run. */
+type Verbosity = "queryPlanner" | "executionStats" | "allPlansExecution";
+const VERBOSITIES: readonly Verbosity[] = ["queryPlanner", "executionStats", "allPlansExecution"];
+
+// Input/Output types
+interface ExplainInput extends ScopeInput {
+  /** The filter of a find (default: all documents). Not with `pipeline`. */
+  query?: DocumentQuery;
+  /** The fields of a find to give (1) or to leave out (0) */
+  projection?: Record<string, 0 | 1>;
+  /** The sort order of a find */
+  sort?: SortSpec;
+  /** The most documents of a find */
+  limit?: number;
+  /** An aggregation pipeline (not with `query`) */
+  pipeline?: AggregationStage[];
+  /** The verbosity (default: queryPlanner) */
+  verbosity?: Verbosity;
+}
+
+interface ExplainOutput {
+  /** "find" or "aggregate" */
+  operation: "find" | "aggregate";
+  /** The explain document of the server */
+  plan: Record<string, unknown>;
+}
+
+const PROCEDURE = "mongo.documents.explain";
+const INPUT_FIELDS = new Set<string>(["query", "projection", "sort", "limit", "pipeline", "verbosity", ...SCOPE_FIELDS]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** This function checks the input of an explain. */
+export function parseExplainInput(data: unknown): ExplainInput {
+  if (!isPlainObject(data)) throw new Error(`${PROCEDURE}: input must be an object`);
+  for (const key of Object.keys(data)) {
+    if (!INPUT_FIELDS.has(key)) throw new Error(`${PROCEDURE}: unknown field "${key}". The fields are: ${[...INPUT_FIELDS].join(", ")}`);
+  }
+  const result: ExplainInput = {};
+  copyScope(data, result);
+  const pipeline = data["pipeline"];
+  if (pipeline !== undefined) {
+    for (const field of ["query", "projection", "sort", "limit"]) {
+      if (data[field] !== undefined) throw new Error(`${PROCEDURE}: give a pipeline or the fields of a find (${field}), not both`);
+    }
+    if (!Array.isArray(pipeline) || !pipeline.every(isPlainObject)) throw new Error(`${PROCEDURE}: pipeline must be a list of stages`);
+    const stage = writingStage(pipeline);
+    if (stage) throw new Error(`${PROCEDURE} is read only: the stage ${stage} writes to a collection`);
+    result.pipeline = pipeline as AggregationStage[];
+  }
+  for (const field of ["query", "projection", "sort"] as const) {
+    const value = data[field];
+    if (value === undefined) continue;
+    if (!isPlainObject(value)) throw new Error(`${PROCEDURE}: ${field} must be an object`);
+    (result as Record<string, unknown>)[field] = value;
+  }
+  const limit = data["limit"];
+  if (limit !== undefined) {
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1) throw new Error(`${PROCEDURE}: limit must be an integer >= 1`);
+    result.limit = limit;
+  }
+  const verbosity = data["verbosity"];
+  if (verbosity !== undefined) {
+    if (!VERBOSITIES.includes(verbosity as Verbosity)) throw new Error(`${PROCEDURE}: verbosity must be ${VERBOSITIES.join(", ")}`);
+    result.verbosity = verbosity as Verbosity;
+  }
+  return result;
+}
+
+/** The explain document without the fields of the cluster time: they hold signatures, not the plan. */
+function planOf(explained: Document): Record<string, unknown> {
+  const { $clusterTime: _clusterTime, operationTime: _operationTime, ...plan } = explained;
+  return plan;
+}
+
+// Schemas
+const explainInputSchema = described<ExplainInput>(
+  parseExplainInput,
+  z.object({
+    ...scopeFields(),
+    query: documentObject().optional().describe("The filter of a find (default: all documents). Not with pipeline."),
+    projection: z.record(z.string(), z.union([z.literal(0), z.literal(1)])).optional().describe("The fields of a find to give (1) or to leave out (0)"),
+    sort: z.record(z.string(), z.unknown()).optional().describe("The sort order of a find: { field: 1 } ascending, { field: -1 } descending"),
+    limit: z.number().int().min(1).optional().describe("The most documents of a find"),
+    pipeline: z.array(documentObject()).optional().describe("An aggregation pipeline to explain, in place of a find. $out and $merge are refused."),
+    verbosity: z
+      .enum(["queryPlanner", "executionStats", "allPlansExecution"])
+      .optional()
+      .describe("queryPlanner (the default): the plan only. executionStats and allPlansExecution also run the plan."),
+  })
+);
+const explainOutputSchema = zodAdapter<ExplainOutput>(
+  z.looseObject({
+    operation: z.enum(["find", "aggregate"]).describe("The operation that the server explained"),
+    plan: z.record(z.string(), z.unknown()).describe("The explain document of the server (queryPlanner, and executionStats with that verbosity)"),
+  })
+);
+
+export const explainProcedure: Procedure<
+  ExplainInput,
+  ExplainOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "explain"])
+  .input(explainInputSchema)
+  .output(explainOutputSchema)
+  .meta({
+    description: "The plan of a find or an aggregation pipeline (read only: $out and $merge are refused)",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: ExplainInput, ctx: ProcedureContext): Promise<ExplainOutput> => {
+    const { collection } = await collectionFor(input, ctx);
+    const verbosity: ExplainVerbosityLike = input.verbosity ?? "queryPlanner";
+    if (input.pipeline) {
+      return { operation: "aggregate", plan: planOf(await collection.aggregate(input.pipeline).explain(verbosity)) };
+    }
+    const options: FindOptions = {};
+    if (input.projection) options.projection = input.projection;
+    if (input.sort) options.sort = input.sort;
+    if (input.limit !== undefined) options.limit = input.limit;
+    return { operation: "find", plan: planOf(await collection.find(input.query ?? {}, options).explain(verbosity)) };
+  })
+  .build();
+
+export type { ExplainInput, ExplainOutput };

package/src/procedures/index.ts

@@ -20,6 +20,12 @@ export { updateProcedure } from "./documents.update.js";
 export { deleteProcedure } from "./documents.delete.js";
 export { countProcedure } from "./documents.count.js";
 export { aggregateProcedure } from "./documents.aggregate.js";
+export { distinctProcedure } from "./documents.distinct.js";
+export { bulkProcedure } from "./documents.bulk.js";
+export { explainProcedure } from "./documents.explain.js";
+
+// Change streams
+export { watchProcedure } from "./watch.js";
 
 // Index procedures
 export { listIndexesProcedure } from "./indexes.list.js";

package/src/procedures/watch.ts

@@ -0,0 +1,184 @@
+/**
+ * Procedure: mongo.watch (roadmap R44)
+ * The changes of a collection or of a database, as a stream (a change stream)
+ *
+ * The stream has no end (`metadata.stream: { unbounded: true }`). It stops when the reader stops
+ * or the signal of the call aborts: the procedure then closes the change stream. A change stream
+ * needs a replica set or a sharded cluster: a server without one refuses it.
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import type { ChangeStream, ChangeStreamOptions, Document } from "mongodb";
+import { z } from "zod";
+import { collectionFor, databaseFor, copyScope, SCOPE_FIELDS, type ScopeInput } from "../scope.js";
+import { described, documentObject } from "./input-schemas.js";
+
+/** The stages that a change stream accepts after its own stage. */
+const CHANGE_STREAM_STAGES = ["$match", "$project", "$addFields", "$set", "$unset", "$replaceRoot", "$replaceWith", "$redact"];
+
+type FullDocument = "default" | "updateLookup" | "whenAvailable" | "required";
+const FULL_DOCUMENT: readonly FullDocument[] = ["default", "updateLookup", "whenAvailable", "required"];
+
+// Input/Output types
+interface WatchInput extends ScopeInput {
+  /** The stages after the change stream stage: $match, $project and the other stages it accepts */
+  pipeline?: Document[];
+  /** The full document of an update: "default" (none), "updateLookup", "whenAvailable" or "required" */
+  fullDocument?: FullDocument;
+  /** The resume token of an earlier change: the stream starts after it */
+  resumeAfter?: string;
+}
+
+/** One change: an item of the stream. */
+interface WatchChange {
+  /** insert, update, replace, delete, drop, rename, dropDatabase or invalidate */
+  operationType: string;
+  /** The database and the collection of the change */
+  ns?: { db: string; coll?: string | undefined } | undefined;
+  /** The _id of the changed document */
+  documentKey?: Record<string, unknown> | undefined;
+  /** The document of an insert or a replace (and of an update with fullDocument) */
+  fullDocument?: Record<string, unknown> | null | undefined;
+  /** The changed and removed fields of an update */
+  updateDescription?: Record<string, unknown> | undefined;
+  /** The time of the change on the server (ISO 8601), from MongoDB 6.0 */
+  wallTime?: string | undefined;
+  /** The resume token of the change: resumeAfter takes it */
+  resumeToken: string;
+}
+
+const PROCEDURE = "mongo.watch";
+const INPUT_FIELDS = new Set<string>(["pipeline", "fullDocument", "resumeAfter", ...SCOPE_FIELDS]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** This function checks the input of a watch. */
+export function parseWatchInput(data: unknown): WatchInput {
+  if (!isPlainObject(data)) throw new Error(`${PROCEDURE}: input must be an object`);
+  for (const key of Object.keys(data)) {
+    if (!INPUT_FIELDS.has(key)) throw new Error(`${PROCEDURE}: unknown field "${key}". The fields are: ${[...INPUT_FIELDS].join(", ")}`);
+  }
+  const result: WatchInput = {};
+  copyScope(data, result);
+  const pipeline = data["pipeline"];
+  if (pipeline !== undefined) {
+    if (!Array.isArray(pipeline)) throw new Error(`${PROCEDURE}: pipeline must be a list of stages`);
+    for (const [index, stage] of pipeline.entries()) {
+      const names = isPlainObject(stage) ? Object.keys(stage) : [];
+      if (names.length !== 1 || !CHANGE_STREAM_STAGES.includes(names[0]!)) {
+        throw new Error(`${PROCEDURE}: pipeline[${index}] must be one stage of ${CHANGE_STREAM_STAGES.join(", ")}`);
+      }
+    }
+    result.pipeline = pipeline as Document[];
+  }
+  const fullDocument = data["fullDocument"];
+  if (fullDocument !== undefined) {
+    if (!FULL_DOCUMENT.includes(fullDocument as FullDocument)) throw new Error(`${PROCEDURE}: fullDocument must be ${FULL_DOCUMENT.join(", ")}`);
+    result.fullDocument = fullDocument as FullDocument;
+  }
+  const resumeAfter = data["resumeAfter"];
+  if (resumeAfter !== undefined) {
+    if (typeof resumeAfter !== "string" || resumeAfter.length === 0) throw new Error(`${PROCEDURE}: resumeAfter must be a resume token (text)`);
+    result.resumeAfter = resumeAfter;
+  }
+  return result;
+}
+
+/** The item of one change event of the driver. */
+export function toWatchChange(event: Document): WatchChange {
+  const id = event["_id"] as { _data?: unknown } | undefined;
+  const change: WatchChange = {
+    operationType: String(event["operationType"]),
+    resumeToken: typeof id?._data === "string" ? id._data : JSON.stringify(id ?? null),
+  };
+  if (isPlainObject(event["ns"])) change.ns = event["ns"] as { db: string; coll?: string | undefined };
+  if (isPlainObject(event["documentKey"])) change.documentKey = event["documentKey"];
+  if (event["fullDocument"] !== undefined) change.fullDocument = event["fullDocument"] as Record<string, unknown> | null;
+  if (isPlainObject(event["updateDescription"])) change.updateDescription = event["updateDescription"];
+  if (event["wallTime"] instanceof Date) change.wallTime = event["wallTime"].toISOString();
+  return change;
+}
+
+/**
+ * The changes, as a stream. The change stream closes when the reader stops (the `finally` of the
+ * generator) or when the signal aborts (the close ends the wait for the next change).
+ */
+export async function* watchChanges(input: WatchInput, ctx: ProcedureContext): AsyncGenerator<WatchChange, void, undefined> {
+  const options: ChangeStreamOptions = {};
+  if (input.fullDocument) options.fullDocument = input.fullDocument;
+  if (input.resumeAfter) options.resumeAfter = { _data: input.resumeAfter };
+  const pipeline = input.pipeline ?? [];
+  const stream: ChangeStream =
+    input.collection !== undefined || ctx.metadata["collection"] !== undefined
+      ? (await collectionFor(input, ctx)).collection.watch(pipeline, options)
+      : (await databaseFor(input, ctx)).watch(pipeline, options);
+  const signal = ctx.signal;
+  // True when the signal closed the change stream. The driver also closes it before it throws a
+  // failure (a server without a replica set): that error goes to the reader.
+  let stopped = false;
+  const close = (): void => {
+    stopped = true;
+    stream.close().catch(() => undefined);
+  };
+  signal?.addEventListener("abort", close, { once: true });
+  try {
+    if (signal?.aborted) return;
+    for await (const event of stream) {
+      yield toWatchChange(event);
+    }
+  } catch (error) {
+    // The abort of the call ends the stream without an error
+    if (stopped) return;
+    throw error;
+  } finally {
+    signal?.removeEventListener("abort", close);
+    await stream.close().catch(() => undefined);
+  }
+}
+
+// Schemas
+const watchInputSchema = described<WatchInput>(
+  parseWatchInput,
+  z.object({
+    collection: z.string().min(1).optional().describe("The collection to watch. Without it, the stream gives the changes of the database."),
+    database: z.string().min(1).optional().describe("The database name (default: the database of the connection)"),
+    pipeline: z.array(documentObject()).optional().describe("Stages after the change stream stage: $match, $project, $addFields, $set, $unset, $replaceRoot, $replaceWith, $redact"),
+    fullDocument: z.enum(["default", "updateLookup", "whenAvailable", "required"]).optional().describe("The full document of an update: updateLookup reads it (default: none)"),
+    resumeAfter: z.string().min(1).optional().describe("The resume token of an earlier change: the stream starts after it"),
+  })
+);
+const watchOutputSchema = zodAdapter<WatchChange>(
+  z.looseObject({
+    operationType: z.string().describe("insert, update, replace, delete, drop, rename, dropDatabase or invalidate"),
+    ns: z.looseObject({ db: z.string(), coll: z.string().optional() }).optional().describe("The database and the collection of the change"),
+    documentKey: z.record(z.string(), z.unknown()).optional().describe("The _id of the changed document"),
+    fullDocument: z.record(z.string(), z.unknown()).nullable().optional().describe("The document of an insert or a replace, and of an update with fullDocument"),
+    updateDescription: z.record(z.string(), z.unknown()).optional().describe("The changed and removed fields of an update"),
+    wallTime: z.string().optional().describe("The time of the change on the server (ISO 8601), from MongoDB 6.0"),
+    resumeToken: z.string().describe("The resume token of the change: resumeAfter takes it"),
+  })
+);
+
+export const watchProcedure: Procedure<
+  WatchInput,
+  WatchChange,
+  { description: string; effects?: Effects; stream?: { unbounded?: boolean }; output?: string }
+> = createProcedure()
+  .path(["mongo", "watch"])
+  .input(watchInputSchema)
+  .output(watchOutputSchema)
+  .meta({
+    description: "The changes of a collection or a database, as a stream without an end (a change stream needs a replica set)",
+    effects: { reads: ["mongo", "network"], writes: [] },
+    // The stream has no end: it stops when the reader stops (roadmap R15)
+    stream: { unbounded: true },
+    output: "streaming",
+  })
+  // invokeProcedure reads a returned async iterable as a stream: the handler types of the core do
+  // not describe that case
+  .handler(((input: WatchInput, ctx: ProcedureContext) => watchChanges(input, ctx)) as never)
+  .build();
+
+export type { WatchInput, WatchChange };

package/src/procedures.types.ts

@@ -43,6 +43,10 @@ import type { UpdateInput, UpdateOutput } from "./procedures/documents.update.js
 import type { DeleteInput, DeleteOutput } from "./procedures/documents.delete.js";
 import type { CountInput, CountOutput } from "./procedures/documents.count.js";
 import type { AggregateInput, AggregateOutput } from "./procedures/documents.aggregate.js";
+import type { DistinctInput, DistinctOutput } from "./procedures/documents.distinct.js";
+import type { BulkInput, BulkOutput } from "./procedures/documents.bulk.js";
+import type { ExplainInput, ExplainOutput } from "./procedures/documents.explain.js";
+import type { WatchInput, WatchChange } from "./procedures/watch.js";
 import type { ListIndexesInput, ListIndexesOutput } from "./procedures/indexes.list.js";
 import type { CreateIndexInput, CreateIndexOutput } from "./procedures/indexes.create.js";
 import type { DropIndexInput, DropIndexOutput } from "./procedures/indexes.drop.js";
@@ -72,6 +76,14 @@ export type {
   CountOutput,
   AggregateInput,
   AggregateOutput,
+  DistinctInput,
+  DistinctOutput,
+  BulkInput,
+  BulkOutput,
+  ExplainInput,
+  ExplainOutput,
+  WatchInput,
+  WatchChange,
   ListIndexesInput,
   ListIndexesOutput,
   CreateIndexInput,
@@ -108,12 +120,17 @@ export interface MongoProcedures {
       delete: { input: DeleteInput; output: DeleteOutput };
       count: { input: CountInput; output: CountOutput };
       aggregate: { input: AggregateInput; output: AggregateOutput };
+      distinct: { input: DistinctInput; output: DistinctOutput };
+      bulk: { input: BulkInput; output: BulkOutput };
+      explain: { input: ExplainInput; output: ExplainOutput };
     };
     indexes: {
       list: { input: ListIndexesInput; output: ListIndexesOutput };
       create: { input: CreateIndexInput; output: CreateIndexOutput };
       drop: { input: DropIndexInput; output: DropIndexOutput };
     };
+    /** A stream: the output is the type of one item */
+    watch: { input: WatchInput; output: WatchChange };
   };
 }
 
@@ -134,9 +151,13 @@ export type ProcedureInput<P extends readonly string[]> =
   P extends ["mongo", "documents", "delete"] ? DeleteInput :
   P extends ["mongo", "documents", "count"] ? CountInput :
   P extends ["mongo", "documents", "aggregate"] ? AggregateInput :
+  P extends ["mongo", "documents", "distinct"] ? DistinctInput :
+  P extends ["mongo", "documents", "bulk"] ? BulkInput :
+  P extends ["mongo", "documents", "explain"] ? ExplainInput :
   P extends ["mongo", "indexes", "list"] ? ListIndexesInput :
   P extends ["mongo", "indexes", "create"] ? CreateIndexInput :
   P extends ["mongo", "indexes", "drop"] ? DropIndexInput :
+  P extends ["mongo", "watch"] ? WatchInput :
   never;
 
 /**
@@ -156,7 +177,11 @@ export type ProcedureOutput<P extends readonly string[]> =
   P extends ["mongo", "documents", "delete"] ? DeleteOutput :
   P extends ["mongo", "documents", "count"] ? CountOutput :
   P extends ["mongo", "documents", "aggregate"] ? AggregateOutput :
+  P extends ["mongo", "documents", "distinct"] ? DistinctOutput :
+  P extends ["mongo", "documents", "bulk"] ? BulkOutput :
+  P extends ["mongo", "documents", "explain"] ? ExplainOutput :
   P extends ["mongo", "indexes", "list"] ? ListIndexesOutput :
   P extends ["mongo", "indexes", "create"] ? CreateIndexOutput :
   P extends ["mongo", "indexes", "drop"] ? DropIndexOutput :
+  P extends ["mongo", "watch"] ? WatchChange :
   never;