@procedures/mongo 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,159 @@
+/**
+ * @procedures/mongo
+ *
+ * MongoDB client wrapper with client procedures for RPC access.
+ * Use locally with direct MongoDB connection or remotely via client.call().
+ *
+ * @example
+ * ```typescript
+ * // Local usage: the first call connects (MONGODB_URI, or configure())
+ * import { configure } from "@procedures/mongo";
+ *
+ * configure({ uri: "mongodb://localhost:27017", database: "myapp" });
+ *
+ * // Via RPC client
+ * import { Client } from "client";
+ *
+ * const result = await client.call(
+ *   ["mongo", "documents", "find"],
+ *   { collection: "users", query: { status: "active" }, limit: 10 },
+ * );
+ * ```
+ */
+
+// =============================================================================
+// Connection Management
+// =============================================================================
+
+export {
+  connect,
+  configure,
+  ensureConnection,
+  disconnect,
+  getDb,
+  getClient,
+  getDefaultConnection,
+  setDefaultConnection,
+  hasDefaultConnection,
+} from "./connection.js";
+
+export type { MongoConnection, MongoConnectionOptions } from "./connection.js";
+export type { ScopeInput } from "./scope.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export {
+  // Type guards
+  hasCollection,
+  requireCollection,
+  getBaseMeta,
+} from "./types.js";
+
+// Typed procedures interface for autocomplete
+export type {
+  MongoProcedures,
+  ProcedureInput,
+  ProcedureOutput,
+  // Individual procedure types
+  PingInput,
+  PingOutput,
+  InfoInput,
+  ListCollectionsInput,
+  ListCollectionsOutput,
+  CreateCollectionInput,
+  CreateCollectionOutput,
+  DropCollectionInput,
+  DropCollectionOutput,
+  StatsInput,
+  FindInput,
+  FindOutput,
+  GetInput,
+  GetOutput,
+  InsertInput,
+  InsertOutput,
+  UpdateInput,
+  UpdateOutput,
+  DeleteInput,
+  DeleteOutput,
+  CountInput,
+  CountOutput,
+  AggregateInput,
+  AggregateOutput,
+  ListIndexesInput,
+  ListIndexesOutput,
+  CreateIndexInput,
+  CreateIndexOutput,
+  DropIndexInput,
+  DropIndexOutput,
+} from "./procedures.types.js";
+
+export type {
+  // Common
+  PaginationInput,
+  PaginationOutput,
+  SortOrder,
+  SortSpec,
+  // Documents
+  DocumentId,
+  BaseDocument,
+  MongoDocument,
+  DocumentQuery,
+  DocumentUpdate,
+  // Metadata
+  BaseMeta,
+  CollectionMeta,
+  // Bulk operations
+  BulkInsertOne,
+  BulkUpdateOne,
+  BulkDeleteOne,
+  BulkOperation,
+  BulkWriteResult,
+  // Indexes
+  IndexSpec,
+  IndexOptions,
+  IndexInfo,
+  // Collections
+  CollectionOptions,
+  CollectionStats,
+  // Database
+  DatabaseInfo,
+  // Aggregation
+  AggregationStage,
+  AggregationOptions,
+} from "./types.js";
+
+// =============================================================================
+// Storage (CollectionStorage implementation)
+// =============================================================================
+
+export { MongoStorage } from "./storage/index.js";
+export type { MongoStorageOptions } from "./storage/index.js";
+
+// =============================================================================
+// Procedure Registration
+// =============================================================================
+
+export { registerMongoProcedures, procedures } from "./module.js";
+
+// =============================================================================
+// Individual Procedures (for direct import if needed)
+// =============================================================================
+
+export * from "./procedures/index.js";
+
+// =============================================================================
+// Re-export mongodb types users may need
+// =============================================================================
+
+export type {
+  Db,
+  Collection,
+  Document,
+  ObjectId,
+  Filter,
+  UpdateFilter,
+  FindOptions,
+  AggregateOptions,
+} from "mongodb";

package/src/module.ts

@@ -0,0 +1,71 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration
+ *
+ * Registers MongoDB procedures with the client system.
+ * This file is referenced by package.json's client.procedures field.
+ */
+
+import { type AnyProcedure, defineModule, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+
+// Import all procedures
+import { pingProcedure } from "./procedures/database.ping.js";
+import { infoProcedure } from "./procedures/database.info.js";
+import { listProcedure } from "./procedures/collections.list.js";
+import { createCollectionProcedure } from "./procedures/collections.create.js";
+import { dropProcedure } from "./procedures/collections.drop.js";
+import { statsProcedure } from "./procedures/collections.stats.js";
+import { findProcedure } from "./procedures/documents.find.js";
+import { getProcedure } from "./procedures/documents.get.js";
+import { insertProcedure } from "./procedures/documents.insert.js";
+import { updateProcedure } from "./procedures/documents.update.js";
+import { deleteProcedure } from "./procedures/documents.delete.js";
+import { countProcedure } from "./procedures/documents.count.js";
+import { aggregateProcedure } from "./procedures/documents.aggregate.js";
+import { listIndexesProcedure } from "./procedures/indexes.list.js";
+import { createIndexProcedure } from "./procedures/indexes.create.js";
+import { dropIndexProcedure } from "./procedures/indexes.drop.js";
+
+/**
+ * All MongoDB procedures
+ */
+export const procedures: readonly AnyProcedure[] = [
+  // Database
+  pingProcedure,
+  infoProcedure,
+  // Collections
+  listProcedure,
+  createCollectionProcedure,
+  dropProcedure,
+  statsProcedure,
+  // Documents
+  findProcedure,
+  getProcedure,
+  insertProcedure,
+  updateProcedure,
+  deleteProcedure,
+  countProcedure,
+  aggregateProcedure,
+  // Indexes
+  listIndexesProcedure,
+  createIndexProcedure,
+  dropIndexProcedure,
+];
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const mongoModule: ProcedureModule = defineModule("@procedures/mongo", [...procedures]);
+
+export default mongoModule;
+
+/**
+ * This function registers the procedures of @procedures/mongo, and of the modules that it requires, in
+ * a registry. The default is the global registry. Importing this file registers nothing: the
+ * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerMongoProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [mongoModule]);
+}

package/src/procedures/collections.create.ts

@@ -0,0 +1,72 @@
+/**
+ * Procedure: mongo.collections.create
+ * Create a new collection
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { databaseFor, type ScopeInput } from "../scope.js";
+import { scopeFields, documentObject } from "./input-schemas.js";
+import { z } from "zod";
+import type { CreateCollectionOptions } from "mongodb";
+import { type CollectionOptions } from "../types.js";
+
+// Input/Output types
+interface CreateInput extends ScopeInput {
+  name: string;
+  options?: CollectionOptions | undefined;
+}
+
+interface CreateOutput {
+  acknowledged: boolean;
+  collectionName: string;
+}
+
+// Schemas
+const createInputSchema = zodAdapter<CreateInput>(
+  z.object({
+    ...scopeFields(),
+    name: z.string().min(1).describe("The name of the new collection"),
+    options: z
+      .looseObject({
+        capped: z.boolean().optional().describe("Make a capped collection"),
+        size: z.number().optional().describe("The maximum size in bytes (capped collections)"),
+        max: z.number().optional().describe("The maximum number of documents (capped collections)"),
+        validator: documentObject().optional().describe("A validator document (for example a $jsonSchema)"),
+      })
+      .optional()
+      .describe("The options of the collection"),
+  })
+);
+const createOutputSchema = zodAdapter<CreateOutput>(
+  z.looseObject({
+    acknowledged: z.boolean().describe("True when the server confirmed the write"),
+    collectionName: z.string().describe("The name of the new collection"),
+  })
+);
+
+export const createCollectionProcedure: Procedure<
+  CreateInput,
+  CreateOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "collections", "create"])
+  .input(createInputSchema)
+  .output(createOutputSchema)
+  .meta({
+    description: "Create a new collection",
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"], destructive: false },
+  })
+  .handler(async (input: CreateInput, ctx: ProcedureContext) => {
+    const db = await databaseFor(input, ctx);
+
+    // The schema leaves out an option that the input does not give: no option is undefined at run time
+    await db.createCollection(input.name, input.options as CreateCollectionOptions | undefined);
+
+    return {
+      acknowledged: true,
+      collectionName: input.name,
+    };
+  })
+  .build();
+
+export type { CreateInput, CreateOutput };

package/src/procedures/collections.drop.ts

@@ -0,0 +1,66 @@
+/**
+ * Procedure: mongo.collections.drop
+ * Drop (delete) a collection
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { collectionName, databaseFor, type ScopeInput } from "../scope.js";
+import { scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+
+// Input/Output types
+interface DropInput extends ScopeInput {
+  /** Confirmation required to prevent accidental drops */
+  confirm: boolean;
+}
+
+interface DropOutput {
+  acknowledged: boolean;
+  dropped: boolean;
+}
+
+// Schemas
+const dropInputSchema = zodAdapter<DropInput>(
+  z.object({
+    ...scopeFields(),
+    confirm: z.boolean().describe("Set to true to drop the collection and all of its documents"),
+  })
+);
+const dropOutputSchema = zodAdapter<DropOutput>(
+  z.looseObject({
+    acknowledged: z.boolean().describe("True when the server confirmed the write"),
+    dropped: z.boolean().describe("False when the collection did not exist"),
+  })
+);
+
+export const dropProcedure: Procedure<
+  DropInput,
+  DropOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "collections", "drop"])
+  .input(dropInputSchema)
+  .output(dropOutputSchema)
+  .meta({
+    description: "Drop (delete) a collection",
+    // The drop of a missing collection is not an error: it gives dropped: false
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"], idempotent: true },
+  })
+  .handler(async (input: DropInput, ctx: ProcedureContext) => {
+    const name = collectionName(input, ctx);
+
+    if (!input.confirm) {
+      throw new Error("confirm must be true to drop a collection");
+    }
+
+    const db = await databaseFor(input, ctx);
+    const dropped = await db.dropCollection(name);
+
+    return {
+      acknowledged: true,
+      dropped,
+    };
+  })
+  .build();
+
+export type { DropInput, DropOutput };

package/src/procedures/collections.list.ts

@@ -0,0 +1,56 @@
+/**
+ * Procedure: mongo.collections.list
+ * List all collections in the database
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { databaseFor, type ScopeInput } from "../scope.js";
+import { scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+
+// Input/Output types
+/** The input: only the scope fields. */
+type ListInput = ScopeInput;
+
+interface ListOutput {
+  collections: string[];
+}
+
+// Schemas
+const listInputSchema = zodAdapter<ListInput>(
+  z.object({ ...scopeFields() })
+);
+const listOutputSchema = zodAdapter<ListOutput>(
+  z.looseObject({
+    collections: z.array(z.string()).describe("The collection names of the database"),
+  })
+);
+
+export const listProcedure: Procedure<
+  ListInput,
+  ListOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "collections", "list"])
+  .input(listInputSchema)
+  .output(listOutputSchema)
+  .meta({
+    description: "List all collections in the database",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: ListInput, ctx: ProcedureContext) => {
+    const db = await databaseFor(input, ctx);
+
+    const collections = await db.listCollections().toArray();
+    const collectionNames = collections
+      .filter((c) => c.type === "collection")
+      .map((c) => c.name)
+      .sort();
+
+    return {
+      collections: collectionNames,
+    };
+  })
+  .build();
+
+export type { ListInput, ListOutput };

package/src/procedures/collections.stats.ts

@@ -0,0 +1,60 @@
+/**
+ * Procedure: mongo.collections.stats
+ * Get collection statistics
+ */
+
+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 { CollectionStats } from "../types.js";
+
+// Input/Output types
+/** The input: only the scope fields. */
+type StatsInput = ScopeInput;
+
+// Schemas
+const statsInputSchema = zodAdapter<StatsInput>(
+  z.object({ ...scopeFields() })
+);
+const statsOutputSchema = zodAdapter<CollectionStats>(
+  z.looseObject({
+    count: z.number().describe("The number of documents"),
+    size: z.number().describe("The size of the documents, in bytes"),
+    avgObjSize: z.number().describe("The average size of a document, in bytes"),
+    storageSize: z.number().describe("The storage size, in bytes"),
+    nindexes: z.number().describe("The number of indexes"),
+    totalIndexSize: z.number().describe("The size of the indexes, in bytes"),
+  })
+);
+
+export const statsProcedure: Procedure<
+  StatsInput,
+  CollectionStats,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "collections", "stats"])
+  .input(statsInputSchema)
+  .output(statsOutputSchema)
+  .meta({
+    description: "Get collection statistics",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: StatsInput, ctx: ProcedureContext) => {
+    const { db, name } = await collectionFor(input, ctx);
+    // Use collStats command since stats() is deprecated
+    const stats = await db.command({ collStats: name });
+
+    return {
+      count: (stats["count"] as number) ?? 0,
+      size: (stats["size"] as number) ?? 0,
+      avgObjSize: (stats["avgObjSize"] as number) ?? 0,
+      storageSize: (stats["storageSize"] as number) ?? 0,
+      nindexes: (stats["nindexes"] as number) ?? 0,
+      totalIndexSize: (stats["totalIndexSize"] as number) ?? 0,
+    };
+  })
+  .build();
+
+export type { StatsInput };
+export type StatsOutput = CollectionStats;

package/src/procedures/database.info.ts

@@ -0,0 +1,61 @@
+/**
+ * Procedure: mongo.database.info
+ * Get database information and statistics
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { databaseFor, type ScopeInput } from "../scope.js";
+import { scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+import { type DatabaseInfo } from "../types.js";
+
+// Input/Output types
+/** The input: only the scope fields. */
+type InfoInput = ScopeInput;
+
+// Schemas
+const infoInputSchema = zodAdapter<InfoInput>(
+  z.object({ ...scopeFields() })
+);
+const infoOutputSchema = zodAdapter<DatabaseInfo>(
+  z.looseObject({
+    name: z.string().describe("The database name"),
+    collections: z.number().describe("The number of collections (views not counted)"),
+    views: z.number().describe("The number of views"),
+    sizeOnDisk: z.number().describe("The data size, in bytes"),
+    empty: z.boolean().describe("True when the database has no collections"),
+  })
+);
+
+export const infoProcedure: Procedure<
+  InfoInput,
+  DatabaseInfo,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "database", "info"])
+  .input(infoInputSchema)
+  .output(infoOutputSchema)
+  .meta({
+    description: "Get database information and statistics",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: InfoInput, ctx: ProcedureContext) => {
+    const db = await databaseFor(input, ctx);
+
+    const stats = await db.stats();
+    const collections = await db.listCollections().toArray();
+
+    const views = collections.filter((c) => c.type === "view").length;
+
+    return {
+      name: db.databaseName,
+      collections: collections.length - views,
+      views,
+      sizeOnDisk: stats["dataSize"] ?? 0,
+      empty: collections.length === 0,
+    };
+  })
+  .build();
+
+export type { InfoInput };
+export type InfoOutput = DatabaseInfo;

package/src/procedures/database.ping.ts

@@ -0,0 +1,57 @@
+/**
+ * Procedure: mongo.database.ping
+ * Health check and connectivity test
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { databaseFor, type ScopeInput } from "../scope.js";
+import { scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+
+// Input/Output types
+/** The input: only the scope fields. */
+type PingInput = ScopeInput;
+
+interface PingOutput {
+  ok: boolean;
+  latencyMs: number;
+}
+
+// Schemas
+const pingInputSchema = zodAdapter<PingInput>(
+  z.object({ ...scopeFields() })
+);
+const pingOutputSchema = zodAdapter<PingOutput>(
+  z.looseObject({
+    ok: z.boolean().describe("True when the server answered"),
+    latencyMs: z.number().describe("The time of the ping, in milliseconds"),
+  })
+);
+
+export const pingProcedure: Procedure<
+  PingInput,
+  PingOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "database", "ping"])
+  .input(pingInputSchema)
+  .output(pingOutputSchema)
+  .meta({
+    description: "Health check and connectivity test",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: PingInput, ctx: ProcedureContext) => {
+    const db = await databaseFor(input, ctx);
+
+    const start = Date.now();
+    await db.command({ ping: 1 });
+    const latencyMs = Date.now() - start;
+
+    return {
+      ok: true,
+      latencyMs,
+    };
+  })
+  .build();
+
+export type { PingInput, PingOutput };

package/src/procedures/documents.aggregate.ts

@@ -0,0 +1,72 @@
+/**
+ * Procedure: mongo.documents.aggregate
+ * Run an aggregation pipeline
+ */
+
+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 { AggregateOptions } from "mongodb";
+import {
+  type AggregationStage,
+  type AggregationOptions,
+  type MongoDocument,
+} from "../types.js";
+
+// Input/Output types
+interface AggregateInput extends ScopeInput {
+  pipeline: AggregationStage[];
+  options?: AggregationOptions | undefined;
+}
+
+interface AggregateOutput {
+  results: MongoDocument[];
+}
+
+// Schemas
+const aggregateInputSchema = zodAdapter<AggregateInput>(
+  z.object({
+    ...scopeFields(),
+    pipeline: z.array(documentObject()).describe("The aggregation stages, in order (for example [{ $match: {...} }, { $group: {...} }])"),
+    options: z
+      .looseObject({
+        allowDiskUse: z.boolean().optional().describe("Allow the use of disk for large stages"),
+        maxTimeMS: z.number().optional().describe("The longest run time in milliseconds"),
+      })
+      .optional()
+      .describe("The options of the aggregation"),
+  })
+);
+const aggregateOutputSchema = zodAdapter<AggregateOutput>(
+  z.looseObject({
+    results: z.array(z.record(z.string(), z.unknown())).describe("The documents that the pipeline gave"),
+  })
+);
+
+export const aggregateProcedure: Procedure<
+  AggregateInput,
+  AggregateOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "documents", "aggregate"])
+  .input(aggregateInputSchema)
+  .output(aggregateOutputSchema)
+  .meta({
+    description: "Run an aggregation pipeline",
+    // A $out or $merge stage of the pipeline writes to a collection, and $out replaces it
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"] },
+  })
+  .handler(async (input: AggregateInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+
+    const results = await collection
+      // The schema leaves out an option that the input does not give
+      .aggregate(input.pipeline, input.options as AggregateOptions | undefined)
+      .toArray();
+
+    return { results };
+  })
+  .build();
+
+export type { AggregateInput, AggregateOutput };