@probitas/client-mongodb

MongoDB client for Probitas scenario testing framework.

This package provides a MongoDB client designed for integration testing of applications using MongoDB.

Features

• CRUD Operations: find, findOne, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany
• Aggregations: Full aggregation pipeline support
• Sessions: Transaction support with sessions
• Type Safety: Generic type parameters for document types
• Resource Management: Implements AsyncDisposable for proper cleanup

Installation

deno add jsr:@probitas/client-mongodb

Quick Start

import { createMongoClient } from "@probitas/client-mongodb";

const client = await createMongoClient({
  url: "mongodb://localhost:27017",
  database: "testdb",
});

// Get a collection
const users = client.collection<{ name: string; email: string }>("users");

// Insert a document
const insertResult = await users.insertOne({ name: "Alice", email: "alice@example.com" });
console.log("Inserted ID:", insertResult.insertedId);

// Find documents
const findResult = await users.find({ name: "Alice" });
console.log("Found:", findResult.documents);

// Find one document
const user = await users.findOne({ name: "Alice" });
console.log("User:", user?.document);

await client.close();

Transactions

await client.withSession(async (session) => {
  session.startTransaction();
  try {
    const accounts = client.collection("accounts");
    await accounts.updateOne(
      { _id: "from" },
      { $inc: { balance: -100 } },
      { session }
    );
    await accounts.updateOne(
      { _id: "to" },
      { $inc: { balance: 100 } },
      { session }
    );
    await session.commitTransaction();
  } catch (error) {
    await session.abortTransaction();
    throw error;
  }
});

Using with using Statement

await using client = await createMongoClient({
  url: "mongodb://localhost:27017",
  database: "testdb",
});

const result = await client.collection("test").findOne({});
// Client automatically closed when block exits

Related Packages

Package	Description
@probitas/client	Core utilities and types

Links

• GitHub Repository
• Probitas Framework
• MongoDB

deno add jsr:@probitas/client-mongodb

class MongoConnectionError extends MongoError

new MongoConnectionError(message: string, options?: MongoErrorOptions)

class MongoDuplicateKeyError extends MongoError

new MongoDuplicateKeyError(message: string, keyPattern: Record<string, number>, keyValue: Record<string, unknown>, options?: MongoErrorOptions)

class MongoError extends ClientError

new MongoError(message: string, _: unknown, options?: MongoErrorOptions)

class MongoNotFoundError extends MongoError

new MongoNotFoundError(message: string, options?: MongoErrorOptions)

class MongoQueryError extends MongoError

new MongoQueryError(message: string, collection: string, options?: MongoErrorOptions)

class MongoValidationError extends MongoError

new MongoValidationError(message: string, validationErrors: readonly string[], options?: MongoErrorOptions)

class MongoWriteError extends MongoError

new MongoWriteError(message: string, writeErrors: readonly { index: number; code: number; message: string }[], options?: MongoErrorOptions)

interface MongoClient extends AsyncDisposable

collection<T extends Document = Document>(name: string): MongoCollection<T>

db(name: string): MongoClient

transaction<T>(fn: (session: MongoSession) => unknown): Promise<T>

close(): Promise<void>

interface MongoClientConfig extends CommonOptions

const config: MongoClientConfig = {
  url: "mongodb://localhost:27017",
  database: "testdb",
};

const config: MongoClientConfig = {
  url: {
    host: "localhost",
    port: 27017,
    username: "admin",
    password: "secret",
    authSource: "admin",
  },
  database: "testdb",
};

interface MongoCollection<T extends Document>

find(filter?: Filter, options?: MongoFindOptions): Promise<MongoFindResult<T>>

findOne(filter: Filter, options?: CommonOptions): Promise<MongoFindOneResult<T>>

insertOne(doc: Omit<T, "_id">, options?: CommonOptions): Promise<MongoInsertOneResult>

insertMany(docs: Omit<T, "_id">[], options?: CommonOptions): Promise<MongoInsertManyResult>

updateOne(filter: Filter, update: UpdateFilter, options?: MongoUpdateOptions): Promise<MongoUpdateResult>

updateMany(filter: Filter, update: UpdateFilter, options?: MongoUpdateOptions): Promise<MongoUpdateResult>

deleteOne(filter: Filter, options?: CommonOptions): Promise<MongoDeleteResult>

deleteMany(filter: Filter, options?: CommonOptions): Promise<MongoDeleteResult>

aggregate<R = T>(pipeline: Document[], options?: CommonOptions): Promise<MongoFindResult<R>>

countDocuments(filter?: Filter, options?: CommonOptions): Promise<MongoCountResult>

interface MongoConnectionConfig extends CommonConnectionConfig

interface MongoCountResult

interface MongoDeleteResult

interface MongoDocs<T> extends ReadonlyArray<T>

first(): T | undefined

firstOrThrow(): T

last(): T | undefined

lastOrThrow(): T

interface MongoErrorOptions extends ErrorOptions

interface MongoFindOneResult<T = Document>

interface MongoFindOptions extends CommonOptions

interface MongoFindResult<T = Document>

interface MongoInsertManyResult

interface MongoInsertOneResult

interface MongoSession

collection<T extends Document = Document>(name: string): MongoCollection<T>

interface MongoUpdateOptions extends CommonOptions

interface MongoUpdateResult

async function createMongoClient(config: MongoClientConfig): Promise<MongoClient>

const mongo = await createMongoClient({
  url: "mongodb://localhost:27017",
  database: "testdb",
});

const users = mongo.collection<{ name: string; age: number }>("users");
const result = await users.find({ age: { $gte: 18 } });
console.log(result.docs.first());

await mongo.close();

const mongo = await createMongoClient({
  url: {
    host: "localhost",
    port: 27017,
    username: "admin",
    password: "secret",
    authSource: "admin",
  },
  database: "testdb",
});

const users = mongo.collection<User>("users");

// Insert a document
const insertResult = await users.insertOne({ name: "Alice", age: 30 });
console.log("Inserted ID:", insertResult.insertedId);

// Find documents with projection and sorting
const findResult = await users.find(
  { age: { $gte: 25 } },
  { sort: { name: 1 }, limit: 10 }
);
console.log("Found:", findResult.documents.length);

await mongo.transaction(async (session) => {
  const users = session.collection<User>("users");
  await users.insertOne({ name: "Bob", age: 25 });
  await users.updateOne({ name: "Alice" }, { $inc: { age: 1 } });
});

const result = await users.aggregate<{ _id: string; avgAge: number }>([
  { $group: { _id: "$department", avgAge: { $avg: "$age" } } },
  { $sort: { avgAge: -1 } },
]);

await using mongo = await createMongoClient({
  url: "mongodb://localhost:27017",
  database: "testdb",
});

const result = await mongo.collection("users").find({});
// Client automatically closed when scope exits

function createMongoDocs<T>(items: T[]): MongoDocs<T>

type Document<T = any> = Record<string, T>

type Filter = Record<string, any>

type MongoResult<T = any> = MongoFindResult<T> | MongoInsertOneResult | MongoInsertManyResult | MongoUpdateResult | MongoDeleteResult | MongoFindOneResult<T> | MongoCountResult

type UpdateFilter = Record<string, any>