@procedures/mongo 0.0.0-stage → 0.2.0

package/src/procedures/documents.count.ts

@@ -0,0 +1,55 @@
+/**
+ * Procedure: mongo.documents.count
+ * Count documents matching 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 CountInput extends ScopeInput {
+  query?: DocumentQuery | undefined;
+}
+
+interface CountOutput {
+  count: number;
+}
+
+// Schemas
+const countInputSchema = zodAdapter<CountInput>(
+  z.object({
+    ...scopeFields(),
+    query: documentObject().optional().describe("The filter of the documents to count (default: all documents)"),
+  })
+);
+const countOutputSchema = zodAdapter<CountOutput>(
+  z.looseObject({
+    count: z.number().describe("The number of documents that match"),
+  })
+);
+
+export const countProcedure: Procedure<
+  CountInput,
+  CountOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "count"])
+  .input(countInputSchema)
+  .output(countOutputSchema)
+  .meta({
+    description: "Count documents matching a filter",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: CountInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+
+    const count = await collection.countDocuments(input.query ?? {});
+
+    return { count };
+  })
+  .build();
+
+export type { CountInput, CountOutput };

package/src/procedures/documents.delete.ts

@@ -0,0 +1,57 @@
+/**
+ * Procedure: mongo.documents.delete
+ * Delete documents matching a filter
+ */
+
+import { createProcedure, type Effects, type Procedure, type ProcedureContext, zodAdapter } from "@procedures/client";
+import { collectionFor } from "../scope.js";
+import { described, scopeFields, targetFields } from "./input-schemas.js";
+import { z } from "zod";
+import { parseTarget, targetFilter, type TargetInput } from "./target.js";
+
+// Input/Output types
+/** The input: exactly one of `id` or `filter`, and the scope fields. */
+type DeleteInput = TargetInput;
+
+interface DeleteOutput {
+  acknowledged: boolean;
+  deletedCount: number;
+}
+
+// Schemas
+const deleteInputSchema = described<DeleteInput>(
+  (data: unknown) => parseTarget("mongo.documents.delete", data).target,
+  z.object({ ...scopeFields(), ...targetFields() })
+);
+const deleteOutputSchema = zodAdapter<DeleteOutput>(
+  z.looseObject({
+    acknowledged: z.boolean().describe("True when the server confirmed the write"),
+    deletedCount: z.number().describe("The number of deleted documents"),
+  })
+);
+
+export const deleteProcedure: Procedure<
+  DeleteInput,
+  DeleteOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "delete"])
+  .input(deleteInputSchema)
+  .output(deleteOutputSchema)
+  .meta({
+    description: "Delete documents matching a filter",
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"] },
+  })
+  .handler(async (input: DeleteInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+    const filter = targetFilter(input);
+
+    const result = input.multi ? await collection.deleteMany(filter) : await collection.deleteOne(filter);
+    return {
+      acknowledged: result.acknowledged,
+      deletedCount: result.deletedCount,
+    };
+  })
+  .build();
+
+export type { DeleteInput, DeleteOutput };

package/src/procedures/documents.find.ts

@@ -0,0 +1,151 @@
+/**
+ * Procedure: mongo.documents.find
+ * Find documents with pagination and filtering
+ */
+
+import {
+  createProcedure,
+  type Effects,
+  type Procedure,
+  type ProcedureContext,
+  zodAdapter,
+} from "@procedures/client";
+import { collectionFor, copyScope, type ScopeInput } from "../scope.js";
+import { described, documentObject, scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+import {
+  type PaginationOutput,
+  type DocumentQuery,
+  type SortSpec,
+  type MongoDocument,
+} from "../types.js";
+
+// Input/Output types
+interface FindInput extends ScopeInput {
+  query?: DocumentQuery;
+  projection?: Record<string, 0 | 1>;
+  sort?: SortSpec;
+  page?: number;
+  limit?: number;
+}
+
+interface FindOutput {
+  documents: MongoDocument[];
+  pagination: PaginationOutput;
+}
+
+/**
+ * Validate find input. Enforces `page`/`limit` as integers >= 1 so a `page: 0`
+ * (which produced a negative `skip`) or a string `limit` (which produced a
+ * `NaN` limit) can no longer reach the driver. Other fields pass through.
+ */
+function parseFindInput(data: unknown): FindInput {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("mongo.documents.find: input must be an object");
+  }
+  const raw = data as Record<string, unknown>;
+  const result: FindInput = {};
+  copyScope(raw, result);
+
+  if (raw["query"] !== undefined) {
+    result.query = raw["query"] as DocumentQuery;
+  }
+  if (raw["projection"] !== undefined) {
+    result.projection = raw["projection"] as Record<string, 0 | 1>;
+  }
+  if (raw["sort"] !== undefined) {
+    result.sort = raw["sort"] as SortSpec;
+  }
+  if (raw["page"] !== undefined) {
+    const page = raw["page"];
+    if (typeof page !== "number" || !Number.isInteger(page) || page < 1) {
+      throw new Error("mongo.documents.find: page must be an integer >= 1");
+    }
+    result.page = page;
+  }
+  if (raw["limit"] !== undefined) {
+    const limit = raw["limit"];
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1) {
+      throw new Error("mongo.documents.find: limit must be an integer >= 1");
+    }
+    result.limit = limit;
+  }
+
+  return result;
+}
+
+// Schemas
+const findInputSchema = described<FindInput>(
+  parseFindInput,
+  z.object({
+    ...scopeFields(),
+    query: documentObject().optional().describe("The filter of the documents (default: all documents)"),
+    projection: z.record(z.string(), z.union([z.literal(0), z.literal(1)])).optional().describe("The fields to give (1) or to leave out (0)"),
+    sort: z.record(z.string(), z.unknown()).optional().describe("The sort order: { field: 1 } ascending, { field: -1 } descending"),
+    page: z.number().int().min(1).optional().describe("The page to give, from 1"),
+    limit: z.number().int().min(1).optional().describe("The number of documents on a page"),
+  })
+);
+const findOutputSchema = zodAdapter<FindOutput>(
+  z.looseObject({
+    documents: z.array(z.record(z.string(), z.unknown())).describe("The documents of the page"),
+    pagination: z.looseObject({
+      page: z.number().describe("The page, from 1"),
+      limit: z.number().describe("The number of documents on a page"),
+      total: z.number().describe("The number of documents that match"),
+      totalPages: z.number().describe("The number of pages"),
+      hasNext: z.boolean().describe("True when a next page exists"),
+      hasPrev: z.boolean().describe("True when a previous page exists"),
+    }).describe("The page of the result"),
+  })
+);
+
+export const findProcedure: Procedure<
+  FindInput,
+  FindOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "find"])
+  .input(findInputSchema)
+  .output(findOutputSchema)
+  .meta({
+    description: "Find documents with pagination and filtering",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: FindInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+
+    const query = input.query ?? {};
+    const page = input.page ?? 1;
+    const limit = Math.min(input.limit ?? 20, 100); // Cap at 100
+    const skip = (page - 1) * limit;
+
+    // Execute query and count in parallel
+    const [documents, total] = await Promise.all([
+      collection
+        .find(query)
+        .project(input.projection ?? {})
+        .sort(input.sort ?? {})
+        .skip(skip)
+        .limit(limit)
+        .toArray(),
+      collection.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+
+    return {
+      documents,
+      pagination: {
+        page,
+        limit,
+        total,
+        totalPages,
+        hasNext: page < totalPages,
+        hasPrev: page > 1,
+      },
+    };
+  })
+  .build();
+
+export type { FindInput, FindOutput };

package/src/procedures/documents.get.ts

@@ -0,0 +1,102 @@
+/**
+ * Procedure: mongo.documents.get
+ * Get a single document by ID
+ */
+
+import {
+  createProcedure,
+  type Effects,
+  type Procedure,
+  type ProcedureContext,
+  zodAdapter,
+} from "@procedures/client";
+import { collectionFor, copyScope, type ScopeInput } from "../scope.js";
+import { described, idTypeField, scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+import {
+  buildIdFilter,
+  type IdType,
+  type MongoDocument,
+} from "../types.js";
+
+// Input/Output types
+interface GetInput extends ScopeInput {
+  id: string;
+  /** How to interpret the id (default: "auto" — matches ObjectId or string) */
+  idType?: IdType;
+}
+
+interface GetOutput {
+  document: MongoDocument | null;
+}
+
+/**
+ * Validate get input: `id` must be a non-empty string, and `idType`, when
+ * present, must be one of the supported modes.
+ */
+function parseGetInput(data: unknown): GetInput {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("mongo.documents.get: input must be an object");
+  }
+  const raw = data as Record<string, unknown>;
+
+  const id = raw["id"];
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error("mongo.documents.get: id must be a non-empty string");
+  }
+
+  const result: GetInput = { id };
+  copyScope(raw, result);
+
+  const idType = raw["idType"];
+  if (idType !== undefined) {
+    if (idType !== "auto" && idType !== "objectId" && idType !== "string") {
+      throw new Error(
+        'mongo.documents.get: idType must be "auto", "objectId", or "string"'
+      );
+    }
+    result.idType = idType;
+  }
+
+  return result;
+}
+
+// Schemas
+const getInputSchema = described<GetInput>(
+  parseGetInput,
+  z.object({
+    ...scopeFields(),
+    id: z.string().min(1).describe("The id of the document"),
+    idType: idTypeField(),
+  })
+);
+const getOutputSchema = zodAdapter<GetOutput>(
+  z.looseObject({
+    document: z.record(z.string(), z.unknown()).nullable().describe("The document, or null when no document has the id"),
+  })
+);
+
+export const getProcedure: Procedure<
+  GetInput,
+  GetOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "get"])
+  .input(getInputSchema)
+  .output(getOutputSchema)
+  .meta({
+    description: "Get a single document by ID",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: GetInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+
+    const document = await collection.findOne(
+      buildIdFilter(input.id, input.idType)
+    );
+
+    return { document };
+  })
+  .build();
+
+export type { GetInput, GetOutput };

package/src/procedures/documents.insert.ts

@@ -0,0 +1,86 @@
+/**
+ * Procedure: mongo.documents.insert
+ * Insert one or more documents
+ */
+
+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 MongoDocument } from "../types.js";
+
+// Input/Output types
+interface InsertInput extends ScopeInput {
+  /** Single document or array of documents */
+  documents: MongoDocument | MongoDocument[];
+}
+
+interface InsertOutput {
+  acknowledged: boolean;
+  insertedIds: string[];
+  insertedCount: number;
+}
+
+// Schemas
+const insertInputSchema = zodAdapter<InsertInput>(
+  z.object({
+    ...scopeFields(),
+    documents: z
+      .union([documentObject(), z.array(documentObject())])
+      .describe("One document, or a list of documents"),
+  })
+);
+const insertOutputSchema = zodAdapter<InsertOutput>(
+  z.looseObject({
+    acknowledged: z.boolean().describe("True when the server confirmed the write"),
+    insertedIds: z.array(z.string()).describe("The ids of the new documents, as text"),
+    insertedCount: z.number().describe("The number of new documents"),
+  })
+);
+
+export const insertProcedure: Procedure<
+  InsertInput,
+  InsertOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "insert"])
+  .input(insertInputSchema)
+  .output(insertOutputSchema)
+  .meta({
+    description: "Insert one or more documents",
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"], destructive: false },
+  })
+  .handler(async (input: InsertInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+
+    const docs = Array.isArray(input.documents)
+      ? input.documents
+      : [input.documents];
+
+    if (docs.length === 0) {
+      return {
+        acknowledged: true,
+        insertedIds: [],
+        insertedCount: 0,
+      };
+    }
+
+    if (docs.length === 1) {
+      const result = await collection.insertOne(docs[0]!);
+      return {
+        acknowledged: result.acknowledged,
+        insertedIds: [String(result.insertedId)],
+        insertedCount: result.acknowledged ? 1 : 0,
+      };
+    }
+
+    const result = await collection.insertMany(docs);
+    return {
+      acknowledged: result.acknowledged,
+      insertedIds: Object.values(result.insertedIds).map(String),
+      insertedCount: result.insertedCount,
+    };
+  })
+  .build();
+
+export type { InsertInput, InsertOutput };

package/src/procedures/documents.update.ts

@@ -0,0 +1,96 @@
+/**
+ * Procedure: mongo.documents.update
+ * Update documents matching a filter
+ */
+
+import { createProcedure, type Effects, type Procedure, type ProcedureContext, zodAdapter } from "@procedures/client";
+import { collectionFor } from "../scope.js";
+import { described, documentObject, scopeFields, targetFields } from "./input-schemas.js";
+import { z } from "zod";
+import type { DocumentUpdate } from "../types.js";
+import { parseTarget, targetFilter, upsertFilter, type TargetInput } from "./target.js";
+
+// Input/Output types
+/** The input: exactly one of `id` or `filter`, the update, and the scope fields. */
+interface UpdateInput extends TargetInput {
+  /** Update operations */
+  update: DocumentUpdate;
+  /** Insert if not found */
+  upsert?: boolean;
+}
+
+interface UpdateOutput {
+  acknowledged: boolean;
+  matchedCount: number;
+  modifiedCount: number;
+  upsertedId: string | null;
+  upsertedCount: number;
+}
+
+function parseUpdateInput(data: unknown): UpdateInput {
+  const procedure = "mongo.documents.update";
+  const { target, raw } = parseTarget(procedure, data, ["update", "upsert"]);
+  const update = raw["update"];
+  if (typeof update !== "object" || update === null) {
+    throw new Error(`${procedure}: update must be an object (or a pipeline array)`);
+  }
+  const result: UpdateInput = { ...target, update: update as DocumentUpdate };
+  const upsert = raw["upsert"];
+  if (upsert !== undefined) {
+    if (typeof upsert !== "boolean") throw new Error(`${procedure}: upsert must be a boolean`);
+    result.upsert = upsert;
+  }
+  return result;
+}
+
+// Schemas
+const updateInputSchema = described<UpdateInput>(
+  parseUpdateInput,
+  z.object({
+    ...scopeFields(),
+    ...targetFields(),
+    update: documentObject().describe("The update operations, for example { $set: { status: \"done\" } }"),
+    upsert: z.boolean().optional().describe("Insert a document when none matches"),
+  })
+);
+const updateOutputSchema = zodAdapter<UpdateOutput>(
+  z.looseObject({
+    acknowledged: z.boolean().describe("True when the server confirmed the write"),
+    matchedCount: z.number().describe("The number of documents that matched"),
+    modifiedCount: z.number().describe("The number of documents that changed"),
+    upsertedId: z.string().nullable().describe("The id of the new document of an upsert, as text, or null"),
+    upsertedCount: z.number().describe("The number of documents that an upsert made"),
+  })
+);
+
+export const updateProcedure: Procedure<
+  UpdateInput,
+  UpdateOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "update"])
+  .input(updateInputSchema)
+  .output(updateOutputSchema)
+  .meta({
+    description: "Update documents matching a filter",
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"] },
+  })
+  .handler(async (input: UpdateInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+    const upsert = input.upsert ?? false;
+    const filter = upsert ? await upsertFilter(collection, input) : targetFilter(input);
+
+    const result = input.multi
+      ? await collection.updateMany(filter, input.update, { upsert })
+      : await collection.updateOne(filter, input.update, { upsert });
+    return {
+      acknowledged: result.acknowledged,
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+      upsertedId: result.upsertedId ? String(result.upsertedId) : null,
+      upsertedCount: result.upsertedCount,
+    };
+  })
+  .build();
+
+export type { UpdateInput, UpdateOutput };

package/src/procedures/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Procedure Barrel Export
+ */
+
+// Database procedures
+export { pingProcedure } from "./database.ping.js";
+export { infoProcedure } from "./database.info.js";
+
+// Collection procedures
+export { listProcedure } from "./collections.list.js";
+export { createCollectionProcedure } from "./collections.create.js";
+export { dropProcedure } from "./collections.drop.js";
+export { statsProcedure } from "./collections.stats.js";
+
+// Document procedures
+export { findProcedure } from "./documents.find.js";
+export { getProcedure } from "./documents.get.js";
+export { insertProcedure } from "./documents.insert.js";
+export { updateProcedure } from "./documents.update.js";
+export { deleteProcedure } from "./documents.delete.js";
+export { countProcedure } from "./documents.count.js";
+export { aggregateProcedure } from "./documents.aggregate.js";
+
+// Index procedures
+export { listIndexesProcedure } from "./indexes.list.js";
+export { createIndexProcedure } from "./indexes.create.js";
+export { dropIndexProcedure } from "./indexes.drop.js";
+
+// Schema helper
+export { schema } from "./schema.js";

package/src/procedures/indexes.create.ts

@@ -0,0 +1,74 @@
+/**
+ * Procedure: mongo.indexes.create
+ * Create an index on a collection
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { collectionFor, type ScopeInput } from "../scope.js";
+import { scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+import type { CreateIndexesOptions } from "mongodb";
+import { type IndexSpec, type IndexOptions } from "../types.js";
+
+// Input/Output types
+interface CreateIndexInput extends ScopeInput {
+  keys: IndexSpec;
+  options?: IndexOptions | undefined;
+}
+
+interface CreateIndexOutput {
+  acknowledged: boolean;
+  indexName: string;
+}
+
+// Schemas
+const createIndexInputSchema = zodAdapter<CreateIndexInput>(
+  z.object({
+    ...scopeFields(),
+    keys: z
+      .record(z.string(), z.union([z.literal(1), z.literal(-1), z.literal("text"), z.literal("2dsphere")]))
+      .describe('The fields of the index and their order: 1, -1, "text" or "2dsphere"'),
+    options: z
+      .looseObject({
+        name: z.string().optional().describe("The name of the index"),
+        unique: z.boolean().optional().describe("A unique index"),
+        sparse: z.boolean().optional().describe("A sparse index"),
+      })
+      .optional()
+      .describe("The options of the index"),
+  })
+);
+const createIndexOutputSchema = zodAdapter<CreateIndexOutput>(
+  z.looseObject({
+    acknowledged: z.boolean().describe("True when the server confirmed the write"),
+    indexName: z.string().describe("The name of the new index"),
+  })
+);
+
+export const createIndexProcedure: Procedure<
+  CreateIndexInput,
+  CreateIndexOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "indexes", "create"])
+  .input(createIndexInputSchema)
+  .output(createIndexOutputSchema)
+  .meta({
+    description: "Create an index on a collection",
+    // A second call with the same keys and options keeps the existing index
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"], destructive: false, idempotent: true },
+  })
+  .handler(async (input: CreateIndexInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+
+    // The schema leaves out an option that the input does not give: no option is undefined at run time
+    const indexName = await collection.createIndex(input.keys, input.options as CreateIndexesOptions | undefined);
+
+    return {
+      acknowledged: true,
+      indexName,
+    };
+  })
+  .build();
+
+export type { CreateIndexInput, CreateIndexOutput };