@procedures/mongo 0.0.0-stage → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * TypeScript types for client-mongo procedures
+ */
+import { ObjectId } from "mongodb";
+import type { Document, Filter, UpdateFilter } from "mongodb";
+/**
+ * Pagination input parameters
+ */
+export interface PaginationInput {
+    /** Page number (1-indexed, default: 1) */
+    page?: number;
+    /** Items per page (default: 20, max: 100) */
+    limit?: number;
+}
+/**
+ * Pagination output metadata
+ */
+export interface PaginationOutput {
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    limit: number;
+    /** Total number of items */
+    total: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Whether there is a next page */
+    hasNext: boolean;
+    /** Whether there is a previous page */
+    hasPrev: boolean;
+}
+/**
+ * Sort order for queries
+ */
+export type SortOrder = 1 | -1;
+/**
+ * Sort specification
+ */
+export type SortSpec = Record<string, SortOrder>;
+/**
+ * Document ID - can be string or ObjectId.
+ * MongoDB supports any type for _id, but string and ObjectId are most common.
+ */
+export type DocumentId = string | ObjectId;
+/**
+ * Base document type.
+ * Uses MongoDB's Document type which allows any _id via index signature.
+ */
+export type BaseDocument = Document;
+/**
+ * Generic document type - use BaseDocument for proper _id typing
+ */
+export type MongoDocument = BaseDocument;
+/**
+ * Document query filter.
+ * Uses Document for compatibility with MongoDB driver methods.
+ */
+export type DocumentQuery = Filter<Document>;
+/**
+ * Document update specification
+ */
+export type DocumentUpdate = UpdateFilter<Document>;
+/**
+ * How to interpret a string id when building an `_id` filter.
+ *
+ * - `"objectId"` — coerce to an ObjectId (falls back to the raw string when the
+ *   value is not a valid ObjectId).
+ * - `"string"` — match the raw string `_id` only.
+ * - `"auto"` (default) — when the id is a valid ObjectId, match EITHER an
+ *   ObjectId `_id` or the raw string `_id`, so documents stored with a
+ *   string `_id` that happens to be 24-hex (e.g. MongoStorage keys) stay
+ *   reachable. Otherwise match the string.
+ */
+export type IdType = "auto" | "objectId" | "string";
+/**
+ * Build an `_id` filter from a string id.
+ *
+ * MongoDB supports any `_id` type at runtime. Previously any string that parsed
+ * as an ObjectId was silently coerced, making 24-hex *string* `_id`s
+ * unreachable. The default `"auto"` mode now queries both forms via `$or` when
+ * the id is ambiguous, and `idType` provides an explicit escape hatch.
+ */
+export declare function buildIdFilter(id: string, idType?: IdType): Document;
+/**
+ * Base metadata for all procedures
+ */
+export interface BaseMeta extends Record<string, unknown> {
+    /** Override database name */
+    database?: string;
+}
+/**
+ * Metadata for collection-scoped procedures
+ */
+export interface CollectionMeta extends BaseMeta {
+    /** Collection name (required) */
+    collection: string;
+}
+/**
+ * Type guard to check if metadata has collection
+ */
+export declare function hasCollection(metadata: Record<string, unknown>): metadata is CollectionMeta;
+/**
+ * Type guard to get collection metadata, throws if missing
+ */
+export declare function requireCollection(metadata: Record<string, unknown>): CollectionMeta;
+/**
+ * Get base metadata (database override).
+ * BaseMeta extends Record<string, unknown> so this is type-safe.
+ */
+export declare function getBaseMeta(metadata: Record<string, unknown>): BaseMeta;
+/**
+ * Insert operation for bulk write
+ */
+export interface BulkInsertOne {
+    insertOne: {
+        document: Document;
+    };
+}
+/**
+ * Update operation for bulk write
+ */
+export interface BulkUpdateOne {
+    updateOne: {
+        filter: DocumentQuery;
+        update: DocumentUpdate;
+        upsert?: boolean;
+    };
+}
+/**
+ * Delete operation for bulk write
+ */
+export interface BulkDeleteOne {
+    deleteOne: {
+        filter: DocumentQuery;
+    };
+}
+/**
+ * Bulk operation union type
+ */
+export type BulkOperation = BulkInsertOne | BulkUpdateOne | BulkDeleteOne;
+/**
+ * Result of a bulk write operation
+ */
+export interface BulkWriteResult {
+    acknowledged: boolean;
+    insertedCount: number;
+    matchedCount: number;
+    modifiedCount: number;
+    deletedCount: number;
+    upsertedCount: number;
+}
+/**
+ * Index key specification
+ */
+export type IndexSpec = Record<string, 1 | -1 | "text" | "2dsphere">;
+/**
+ * Index creation options
+ */
+export interface IndexOptions {
+    /** Index name */
+    name?: string | undefined;
+    /** Unique index */
+    unique?: boolean | undefined;
+    /** Sparse index */
+    sparse?: boolean | undefined;
+    /** Build in background */
+    background?: boolean | undefined;
+    /** TTL in seconds */
+    expireAfterSeconds?: number | undefined;
+}
+/**
+ * Index information returned by listIndexes
+ */
+export interface IndexInfo {
+    name: string;
+    /** The fields of the index and their kind. The server also gives kinds that IndexSpec does not name ("hashed", "2d"). */
+    key: Record<string, number | string>;
+    unique?: boolean | undefined;
+    sparse?: boolean | undefined;
+}
+/**
+ * Collection creation options
+ */
+export interface CollectionOptions {
+    /** Create a capped collection */
+    capped?: boolean | undefined;
+    /** Max size in bytes (for capped) */
+    size?: number | undefined;
+    /** Max documents (for capped) */
+    max?: number | undefined;
+    /** JSON Schema validator */
+    validator?: Document | undefined;
+}
+/**
+ * Collection statistics
+ */
+export interface CollectionStats {
+    /** Number of documents */
+    count: number;
+    /** Size of documents in bytes */
+    size: number;
+    /** Average document size */
+    avgObjSize: number;
+    /** Total storage size */
+    storageSize: number;
+    /** Number of indexes */
+    nindexes: number;
+    /** Total index size */
+    totalIndexSize: number;
+}
+/**
+ * Database information
+ */
+export interface DatabaseInfo {
+    /** Database name */
+    name: string;
+    /** Number of collections */
+    collections: number;
+    /** Number of views */
+    views: number;
+    /** Size on disk in bytes */
+    sizeOnDisk: number;
+    /** Whether database is empty */
+    empty: boolean;
+}
+/**
+ * Aggregation pipeline stage
+ */
+export type AggregationStage = Document;
+/**
+ * Aggregation options
+ */
+export interface AggregationOptions {
+    /** Allow disk use for large operations */
+    allowDiskUse?: boolean | undefined;
+    /** Max execution time in ms */
+    maxTimeMS?: number | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,58 @@
+/**
+ * TypeScript types for client-mongo procedures
+ */
+import { ObjectId } from "mongodb";
+/**
+ * Build an `_id` filter from a string id.
+ *
+ * MongoDB supports any `_id` type at runtime. Previously any string that parsed
+ * as an ObjectId was silently coerced, making 24-hex *string* `_id`s
+ * unreachable. The default `"auto"` mode now queries both forms via `$or` when
+ * the id is ambiguous, and `idType` provides an explicit escape hatch.
+ */
+export function buildIdFilter(id, idType = "auto") {
+    if (idType === "string") {
+        return { _id: id };
+    }
+    let objectId = null;
+    try {
+        objectId = new ObjectId(id);
+    }
+    catch {
+        objectId = null;
+    }
+    if (idType === "objectId") {
+        return { _id: objectId ?? id };
+    }
+    // "auto": match both the ObjectId and the raw string when ambiguous.
+    if (objectId) {
+        return { $or: [{ _id: objectId }, { _id: id }] };
+    }
+    return { _id: id };
+}
+/**
+ * Type guard to check if metadata has collection
+ */
+export function hasCollection(metadata) {
+    return typeof metadata["collection"] === "string";
+}
+/**
+ * Type guard to get collection metadata, throws if missing
+ */
+export function requireCollection(metadata) {
+    if (!hasCollection(metadata)) {
+        throw new Error("collection is required in metadata");
+    }
+    if (metadata.collection.trim().length === 0) {
+        throw new Error("collection must be a non-empty string");
+    }
+    return metadata;
+}
+/**
+ * Get base metadata (database override).
+ * BaseMeta extends Record<string, unknown> so this is type-safe.
+ */
+export function getBaseMeta(metadata) {
+    return metadata;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0FnC;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,MAAM,GAAW,MAAM;IAC/D,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;IACrB,CAAC;IAED,IAAI,QAAQ,GAAoB,IAAI,CAAC;IACrC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1B,OAAO,EAAE,GAAG,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;IACjC,CAAC;IAED,qEAAqE;IACrE,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;AACrB,CAAC;AAsBD;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAiC;IAEjC,OAAO,OAAO,QAAQ,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAiC;IAEjC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,QAAiC;IAC3D,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,87 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/mongo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "MongoDB as typed procedures: documents, collections, indexes, aggregation and database info, with a lazy connection and safe update and delete targets.",
+  "keywords": [
+    "mongodb",
+    "mongo",
+    "database",
+    "crud",
+    "aggregation",
+    "procedures",
+    "rpc"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-mongo"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./procedures": {
+      "types": "./dist/procedures/index.d.ts",
+      "import": "./dist/procedures/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@mark1russell7/cue": "^1.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.0",
+    "@procedures/collections": "0.2.0",
+    "mongodb": "^7.0.0",
+    "zod": "^4.6.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/connection.ts

@@ -0,0 +1,198 @@
+/**
+ * MongoDB connection management for client-mongo
+ *
+ * Supports:
+ * - Environment variable configuration (MONGODB_URI, MONGODB_DATABASE)
+ * - Programmatic configuration
+ * - Singleton pattern for default connection
+ * - Multiple connections for multi-tenant scenarios
+ */
+
+import { MongoClient, Db, type MongoClientOptions } from "mongodb";
+
+/**
+ * Options for creating a MongoDB connection
+ */
+export interface MongoConnectionOptions {
+  /** MongoDB connection URI (default: MONGODB_URI env var or mongodb://localhost:27017) */
+  uri?: string;
+  /** Database name (default: MONGODB_DATABASE env var or "test") */
+  database?: string;
+  /** Additional MongoDB client options */
+  clientOptions?: MongoClientOptions;
+}
+
+/**
+ * MongoDB connection interface
+ */
+export interface MongoConnection {
+  /** Get the database instance */
+  getDb(): Db;
+  /** Get the underlying MongoClient */
+  getClient(): MongoClient;
+  /** Connect to the database (no-op if already connected) */
+  connect(): Promise<void>;
+  /** Disconnect from the database */
+  disconnect(): Promise<void>;
+  /** Check if connected */
+  isConnected(): boolean;
+}
+
+// Default connection singleton
+let defaultConnection: MongoConnection | null = null;
+
+/**
+ * Set the default connection used by procedures
+ */
+export function setDefaultConnection(conn: MongoConnection): void {
+  defaultConnection = conn;
+}
+
+/**
+ * Get the default connection
+ * @throws Error if no connection has been established
+ */
+export function getDefaultConnection(): MongoConnection {
+  if (!defaultConnection) {
+    throw new Error(
+      "MongoDB connection not initialized. Call connect() first."
+    );
+  }
+  return defaultConnection;
+}
+
+/**
+ * Check if a default connection exists
+ */
+export function hasDefaultConnection(): boolean {
+  return defaultConnection !== null;
+}
+
+/**
+ * Create and connect to MongoDB
+ *
+ * @example
+ * ```typescript
+ * // Using environment variables
+ * await connect();
+ *
+ * // With explicit options
+ * await connect({
+ *   uri: "mongodb://localhost:27017",
+ *   database: "myapp"
+ * });
+ * ```
+ */
+export async function connect(
+  options: MongoConnectionOptions = {}
+): Promise<MongoConnection> {
+  const uri =
+    options.uri ?? process.env["MONGODB_URI"] ?? "mongodb://localhost:27017";
+  const database =
+    options.database ?? process.env["MONGODB_DATABASE"] ?? "test";
+
+  const client = new MongoClient(uri, options.clientOptions);
+  await client.connect();
+
+  // Close any previous default connection before replacing it. Without this,
+  // the prior MongoClient (and its connection pool) is orphaned open and leaks
+  // on every call to connect() (e.g. repeated server.mongo.start invocations).
+  const previousConnection = defaultConnection;
+
+  let connected = true;
+
+  const connection: MongoConnection = {
+    getDb: () => {
+      if (!connected) {
+        throw new Error("Connection has been closed");
+      }
+      return client.db(database);
+    },
+    getClient: () => {
+      if (!connected) {
+        throw new Error("Connection has been closed");
+      }
+      return client;
+    },
+    connect: async () => {
+      // Already connected
+    },
+    disconnect: async () => {
+      if (connected) {
+        await client.close();
+        connected = false;
+      }
+    },
+    isConnected: () => connected,
+  };
+
+  setDefaultConnection(connection);
+
+  if (previousConnection && previousConnection !== connection) {
+    try {
+      await previousConnection.disconnect();
+    } catch {
+      // Best effort: ignore errors closing the stale connection so a failure
+      // to close the old client never breaks establishing the new one.
+    }
+  }
+
+  return connection;
+}
+
+// The options of the connection that ensureConnection() makes, and its attempt in progress
+let lazyOptions: MongoConnectionOptions = {};
+let pending: Promise<MongoConnection> | null = null;
+
+/**
+ * Set the options of the connection that the procedures make on their first call.
+ * The defaults are the `MONGODB_URI` and `MONGODB_DATABASE` environment variables.
+ */
+export function configure(options: MongoConnectionOptions): void {
+  lazyOptions = options;
+}
+
+/**
+ * Get the default connection, and connect first when there is no open one.
+ *
+ * The procedures call this function, so a host does not have to call `connect()`. (Before,
+ * nothing called `connect()`, and each `mongo.*` tool of the MCP server failed: deep dive DATA-5.)
+ * Concurrent first calls share one connection attempt.
+ */
+export function ensureConnection(): Promise<MongoConnection> {
+  if (defaultConnection?.isConnected()) {
+    return Promise.resolve(defaultConnection);
+  }
+  if (!pending) {
+    pending = connect(lazyOptions).finally(() => {
+      pending = null;
+    });
+  }
+  return pending;
+}
+
+/**
+ * Disconnect the default connection
+ */
+export async function disconnect(): Promise<void> {
+  if (defaultConnection) {
+    await defaultConnection.disconnect();
+    defaultConnection = null;
+  }
+}
+
+/**
+ * Get the database from the default connection
+ * Convenience function for procedure handlers
+ */
+export function getDb(): Db {
+  return getDefaultConnection().getDb();
+}
+
+/**
+ * Get the MongoClient from the default connection
+ * Convenience function for advanced operations
+ */
+export function getClient(): MongoClient {
+  return getDefaultConnection().getClient();
+}