MongoDB Adapter

[palcarazm]

Short Description of the Feature

Implement a MongoDB adapter (MongoBatchEntityReader and MongoBatchEntityWriter) for BatchJS-Data. This is the first NoSQL adapter and establishes the pattern for NoSQL implementations: database-specific query syntax, flexible pagination, and no transactions.

Expected Benefits

• Most popular NoSQL database: MongoDB support expands the user base significantly.
• Document flexibility: Users can work with nested JSON documents easily.
• Native patterns: Uses MongoDB-native filters ({ age: { $gt: 18 } }) and operations (insertMany(), bulkWrite()).

Acceptance Criteria

• src/mongodb/classes/MongoBatchEntityReader.ts implements AbstractNoSQLBatchEntityReaderStream using the official MongoDB Node.js driver.
• src/mongodb/classes/MongoBatchEntityWriter.ts implements AbstractNoSQLBatchEntityWriterStream using the official MongoDB Node.js driver.
• Query filter is a JSON object (MongoDB filter syntax).
• Pagination uses skip(offset).limit(size).
• Connection is managed via MongoClient passed in options.
• Batch writes use collection.insertMany() or collection.bulkWrite().
• No transaction support (documented limitation).
• mongodb is an optional peer dependency in package.json (>=5.x || >=6.x).
• MongoBatchEntityReaderOptions<T> and MongoBatchEntityWriterOptions<T> interfaces exist.
• The adapter is exported from src/mongodb/index.ts.
• JSDoc documentation covers all classes, methods, and options.
• npm run docs:mongodb generates docs/mongodb-api.md.
• Test coverage >=80% (unit + integration tests using testcontainers for MongoDB).
• README.md includes a MongoDB usage example.
• TypeScript types are published correctly for batchjs-data/mongodb.

Documentation

API Design

MongoBatchEntityReader

export interface MongoBatchEntityReaderOptions<T> {
  client: MongoClient;           // MongoDB client instance
  database: string;              // Database name
  collection: string;            // Collection name
  filter: Filter<T>;             // MongoDB filter JSON (e.g., { age: { $gt: 18 } })
  rowToEntity: (doc: any) => T;  // Convert MongoDB document to entity
  batchSize: number;             // Batch size
}

export class MongoBatchEntityReader<T> extends AbstractNoSQLBatchEntityReaderStream<T> {
  constructor(options: MongoBatchEntityReaderOptions<T>);
}

MongoBatchEntityWriter

export interface MongoBatchEntityWriterOptions<T> {
  client: MongoClient;           // MongoDB client instance
  database: string;              // Database name
  collection: string;            // Collection name
  entityToDocument: (entity: T) => any; // Convert entity to MongoDB document
  batchSize: number;             // Batch size
}

export class MongoBatchEntityWriter<T> extends AbstractNoSQLBatchEntityWriterStream<T> {
  constructor(options: MongoBatchEntityWriterOptions<T>);
}

Usage Example

import { MongoClient } from "mongodb";
import { MongoBatchEntityReader, MongoBatchEntityWriter } from "batchjs-data/mongodb";

const client = new MongoClient("mongodb://localhost:27017");

class UserBatchReader extends MongoBatchEntityReader<UserDTO> {
  constructor(batchSize: number) {
    super({
      batchSize,
      client,
      database: "myapp",
      collection: "users",
      filter: { age: { $gt: 18 } },
      rowToEntity: (doc) => ({ id: doc._id.toString(), username: doc.name, age: doc.age })
    });
  }
}

class UserBatchWriter extends MongoBatchEntityWriter<UserDTO> {
  constructor(batchSize: number) {
    super({
      batchSize,
      client,
      database: "myapp",
      collection: "users",
      entityToDocument: (entity) => ({ _id: entity.id, name: entity.username, age: entity.age })
    });
  }
}

Pagination Implementation

await collection
  .find(this.filter)
  .skip(this.entitiesRead)
  .limit(size)
  .toArray()

Batch Write Implementation

await collection.insertMany(chunk.map(this.entityToDocument));

Driver Compatibility

• mongodb version: ^5.0.0 || ^6.0.0
• MongoDB versions: 4.4, 5.0, 6.0, 7.0 (as supported by driver)
• Connection handling: Uses client.db(database).collection(collection) pattern

Additional Comments

• MongoDB documents have _id fields. Users should handle this in rowToEntity/entityToDocument.
• skip()/limit() pagination becomes inefficient for large offsets. Consider using cursor-based pagination as an alternative in future versions.
• No transaction support — insertMany() is not transactional in stand-alone mode (only in replica sets with transactions enabled). The adapter documents this as best-effort batch write.

Feature Request Checklist

• Confirm that you agree to follow the project's code of conduct.
• Confirm that you have reviewed open and rejected feature requests to ensure novelty.