From 24dde0660a5e2ec86c71756489c845d31978b250 Mon Sep 17 00:00:00 2001 From: Sergey Zelenov Date: Mon, 27 Apr 2026 17:07:33 +0200 Subject: [PATCH 1/4] chore(NODE-7481): add AGENTS.md for cross-tool agent guidance --- AGENTS.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..54277e966c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,113 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (Claude Code, Codex, Copilot, Cursor, Aider, etc.) when working with code in this repository. + +## Project Overview + +This is the official MongoDB Node.js driver (`mongodb` npm package). It provides a TypeScript/JavaScript interface for applications to interact with MongoDB deployments. The driver implements the cross-driver MongoDB specifications. + +## Common Commands + +### Building + +```bash +npm run build:ts # Compile TypeScript to lib/ +npm run check:ts # Type-check without emitting +``` + +### Linting + +```bash +npm run check:eslint # Run ESLint +npm run fix:eslint # Auto-fix ESLint issues +``` + +### Testing + +Tests require a running MongoDB instance. To start one locally: + +```bash +git submodule update --init +export DRIVERS_TOOLS=$(pwd)/drivers-evergreen-tools +VERSION='latest' TOPOLOGY='replica_set' bash .evergreen/run-orchestration.sh +source mo-expansion.sh +``` + +```bash +npm run check:unit # Unit tests (no database required) +npm run check:test # Integration tests (requires database) +npm test # Lint + unit + integration + +# Run a single test by name pattern +npm run check:unit -- -g "pattern" +npm run check:test -- -g "pattern" +``` + +Tests use Mocha with 60-second timeout. Integration tests use a custom metadata UI that supports test filtering by topology, MongoDB version, auth, etc. via metadata: + +```js +describe( + 'my test', + { metadata: { requires: { topology: ['replicaset'], mongodb: '>=6.0' } } }, + function () {} +); +``` + +## Architecture + +### Layered Design + +``` +Public API (MongoClient, Db, Collection, Cursors) + → Operations (CRUD, Aggregation, Indexes, Bulk writes) + → Sessions & Transactions + → SDAM – Server Discovery And Monitoring (src/sdam/) + → CMAP – Connection Management And Pooling (src/cmap/) + → Wire Protocol & BSON serialization +``` + +### Key Source Directories + +- **`src/operations/`** — Each database command is an `AbstractOperation` subclass. Operations declare aspects (retryable, read/write, explainable) via Symbols. `execute_operation.ts` is the central execution engine handling retries, sessions, server selection. +- **`src/sdam/`** — Topology discovery and monitoring. `topology.ts` manages servers, `server_selection.ts` picks the best server based on read preference and latency, `monitor.ts` sends periodic heartbeats. +- **`src/cmap/`** — Connection pooling per server, wire protocol encoding/decoding, authentication handshakes. `auth/` contains implementations for each auth mechanism (SCRAM, X.509, AWS, OIDC, Kerberos, PLAIN). +- **`src/cursor/`** — `AbstractCursor` base with lazy evaluation, async iteration, and streaming. Specialized cursors: `FindCursor`, `AggregationCursor`, `ChangeStreamCursor`, etc. +- **`src/bulk/`** — Ordered and unordered bulk write operations. +- **`src/client-side-encryption/`** — Auto-encryption and explicit encryption (CSFLE/Queryable Encryption). +- **`src/gridfs/`** — GridFS file storage using upload/download streams. + +### How Operations Execute + +1. User calls a method (e.g., `collection.insertOne()`) +2. An operation object is created (e.g., `InsertOperation`) +3. `executeOperation()` handles: implicit session creation → server selection → connection checkout → command building → wire protocol send → response handling → retry on transient errors +4. Connection returned to pool, session cleaned up + +### Test Structure + +- **`test/unit/`** — Mirrors `src/` structure. No database interaction, uses mocks. +- **`test/integration/`** — Real database tests organized by feature area. +- **`test/spec/`** — YAML/JSON test specifications from the cross-driver specs. Implemented by spec runners in integration tests. Files named `*.spec.test.ts` use standardized runners; `*.prose.test.ts` are hand-written prose test implementations. +- **`test/mongodb.ts`** — Central re-export of all `src/` internals for test access. Tests import from `../../mongodb` (or appropriate depth), never directly from `src/`. + +## Code Conventions + +- **No `export default`** — All exports must be named. +- **No TypeScript enums** — Use string unions or `as const` objects instead. +- **No `node:` import prefix** — Use bare module names (e.g., `import { setTimeout } from 'timers'`). +- **Timer/process imports** — Must import `setTimeout`, `setInterval`, `clearTimeout`, `process`, etc. from their modules, not use globals. +- **No `Buffer`** — Use `Uint8Array` in source code. +- **BSON imports** — Source code must import from `src/bson.ts`, not from the `bson` package directly. +- **Null/undefined checks** — Use loose equality (`== null`) not strict (`=== null` or `=== undefined`). +- **Type imports** — Use `import { type Foo }` (inline type imports). +- **`return await`** — Required in `src/` (enforced by `@typescript-eslint/return-await: always`). +- **Error messages** — Sentence case, no trailing period. Use driver-specific error types extending `MongoError`. +- **Formatting** — Prettier with single quotes, 2-space tabs, 100-char width, no trailing commas. + +## Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/): `(NODE-XXXX): ` + +Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore` + +Breaking changes use `!`: `feat(NODE-XXXX)!: description` From 12bf280678659eef867b3aec20cee8ab2cb85350 Mon Sep 17 00:00:00 2001 From: Sergey Zelenov Date: Tue, 28 Apr 2026 16:43:11 +0200 Subject: [PATCH 2/4] address copilot comments --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 54277e966c..4f103b0ae1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ npm run fix:eslint # Auto-fix ESLint issues ### Testing -Tests require a running MongoDB instance. To start one locally: +Integration tests require a running MongoDB instance (unit tests do not). To start one locally: ```bash git submodule update --init @@ -36,7 +36,7 @@ source mo-expansion.sh ```bash npm run check:unit # Unit tests (no database required) npm run check:test # Integration tests (requires database) -npm test # Lint + unit + integration +npm test # Full check (lint + d.ts/tsd) + unit + integration # Run a single test by name pattern npm run check:unit -- -g "pattern" @@ -102,7 +102,7 @@ Public API (MongoClient, Db, Collection, Cursors) - **Type imports** — Use `import { type Foo }` (inline type imports). - **`return await`** — Required in `src/` (enforced by `@typescript-eslint/return-await: always`). - **Error messages** — Sentence case, no trailing period. Use driver-specific error types extending `MongoError`. -- **Formatting** — Prettier with single quotes, 2-space tabs, 100-char width, no trailing commas. +- **Formatting** — Prettier with single quotes, 2-space indentation, 100-char width, no trailing commas. ## Commit Messages From 00b4fa6f548ddb6843a186842c7a1ae25ec9210c Mon Sep 17 00:00:00 2001 From: Sergey Zelenov Date: Thu, 30 Apr 2026 14:04:50 +0200 Subject: [PATCH 3/4] chore(NODE-7481): added related repos --- AGENTS.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4f103b0ae1..850229a9c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,14 @@ This file provides guidance to AI coding agents (Claude Code, Codex, Copilot, Cu This is the official MongoDB Node.js driver (`mongodb` npm package). It provides a TypeScript/JavaScript interface for applications to interact with MongoDB deployments. The driver implements the cross-driver MongoDB specifications. +## Related Repositories + +- **[mongodb/specifications](https://github.com/mongodb/specifications)** — Cross-driver MongoDB specifications. **This is the source of truth** for behavior the driver must implement (CRUD, SDAM, CMAP, retryable reads/writes, sessions, transactions, change streams, CSFLE, etc.). Spec test fixtures (YAML/JSON) are vendored under `test/spec/`. When behavior is ambiguous, the spec wins; do not change behavior away from the spec without raising it there first. +- **[mongodb/js-bson](https://github.com/mongodb/js-bson)** — BSON serialization (`bson` npm package). Owned by this team. Bug reports and changes that touch BSON encoding/decoding belong there. +- **[mongodb-js/kerberos](https://github.com/mongodb-js/kerberos)** — Native Kerberos bindings (`kerberos` npm package, optional dependency). Owned by this team. GSSAPI auth issues are typically fixed there, not in the driver. +- **[mongodb-js/mongodb-client-encryption](https://github.com/mongodb-js/mongodb-client-encryption)** — Native bindings to `libmongocrypt` for CSFLE/Queryable Encryption (`mongodb-client-encryption` npm package). Owned by this team. +- **[mongodb-js/zstd](https://github.com/mongodb-js/zstd)** and **[mongodb-js/saslprep](https://github.com/mongodb-js/saslprep)** — Compression and SCRAM SASLprep helpers, also team-owned. + ## Common Commands ### Building From 49601856d052147b90002a17ffb9b1d970f1f2ef Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Thu, 30 Apr 2026 14:21:33 -0400 Subject: [PATCH 4/4] docs: claude suggestions --- AGENTS.md | 53 +++++++++++++++++++++-------------------------------- 1 file changed, 21 insertions(+), 32 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 850229a9c5..50947f85e3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This file provides guidance to AI coding agents (Claude Code, Codex, Copilot, Cursor, Aider, etc.) when working with code in this repository. +Guidance for AI coding agents working in this repository. ## Project Overview @@ -8,11 +8,17 @@ This is the official MongoDB Node.js driver (`mongodb` npm package). It provides ## Related Repositories -- **[mongodb/specifications](https://github.com/mongodb/specifications)** — Cross-driver MongoDB specifications. **This is the source of truth** for behavior the driver must implement (CRUD, SDAM, CMAP, retryable reads/writes, sessions, transactions, change streams, CSFLE, etc.). Spec test fixtures (YAML/JSON) are vendored under `test/spec/`. When behavior is ambiguous, the spec wins; do not change behavior away from the spec without raising it there first. -- **[mongodb/js-bson](https://github.com/mongodb/js-bson)** — BSON serialization (`bson` npm package). Owned by this team. Bug reports and changes that touch BSON encoding/decoding belong there. -- **[mongodb-js/kerberos](https://github.com/mongodb-js/kerberos)** — Native Kerberos bindings (`kerberos` npm package, optional dependency). Owned by this team. GSSAPI auth issues are typically fixed there, not in the driver. -- **[mongodb-js/mongodb-client-encryption](https://github.com/mongodb-js/mongodb-client-encryption)** — Native bindings to `libmongocrypt` for CSFLE/Queryable Encryption (`mongodb-client-encryption` npm package). Owned by this team. -- **[mongodb-js/zstd](https://github.com/mongodb-js/zstd)** and **[mongodb-js/saslprep](https://github.com/mongodb-js/saslprep)** — Compression and SCRAM SASLprep helpers, also team-owned. +- **[mongodb/specifications](https://github.com/mongodb/specifications)** — Cross-driver MongoDB specifications. **This is the source of truth** for behavior the driver must implement (CRUD, SDAM, CMAP, retryable reads/writes, sessions, transactions, change streams, CSFLE, etc.). Spec test fixtures (YAML/JSON) under `test/spec/` are copied from this repo and must not be hand-edited. When behavior is ambiguous, the spec wins; do not change behavior away from the spec without raising it there first. +- **[mongodb/js-bson](https://github.com/mongodb/js-bson)** — BSON serialization (`bson` npm package). Bug reports and changes that touch BSON encoding/decoding belong there. +- **Team-owned native/optional packages**: [`kerberos`](https://github.com/mongodb-js/kerberos) (GSSAPI), [`mongodb-client-encryption`](https://github.com/mongodb-js/mongodb-client-encryption) (libmongocrypt/CSFLE), [`zstd`](https://github.com/mongodb-js/zstd), [`saslprep`](https://github.com/mongodb-js/saslprep). Auth, encryption, and compression bugs are usually fixed in these repos, not the driver. + +## Pointers + +- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — developer setup, VS Code config, PR process. +- **[test/readme.md](./test/readme.md)** — full testing guide (this file only covers the basics). +- **Jira: `NODE-XXXX`** — tickets live at [jira.mongodb.org/browse/NODE](https://jira.mongodb.org/browse/NODE). Used as the commit scope. +- **Node.js**: minimum supported version is in `package.json` `engines.node` (currently `>=20.19.0`). +- **Do not hand-edit**: `lib/` (build output), `mongodb.d.ts` (generated), `HISTORY.md` (release-please managed), `test/spec/` (vendored from specifications repo). ## Common Commands @@ -32,26 +38,17 @@ npm run fix:eslint # Auto-fix ESLint issues ### Testing -Integration tests require a running MongoDB instance (unit tests do not). To start one locally: +See [test/readme.md](./test/readme.md) for the full guide. Quick reference: ```bash -git submodule update --init -export DRIVERS_TOOLS=$(pwd)/drivers-evergreen-tools -VERSION='latest' TOPOLOGY='replica_set' bash .evergreen/run-orchestration.sh -source mo-expansion.sh +npm run check:unit # Unit tests (no database) +npm run check:test # Integration tests (requires running MongoDB) +npm run check:unit -- -g "pattern" # Filter by name pattern ``` -```bash -npm run check:unit # Unit tests (no database required) -npm run check:test # Integration tests (requires database) -npm test # Full check (lint + d.ts/tsd) + unit + integration - -# Run a single test by name pattern -npm run check:unit -- -g "pattern" -npm run check:test -- -g "pattern" -``` +Integration tests need a local MongoDB; spin one up via `git submodule update --init` followed by `.evergreen/run-orchestration.sh` (see test README for env vars). -Tests use Mocha with 60-second timeout. Integration tests use a custom metadata UI that supports test filtering by topology, MongoDB version, auth, etc. via metadata: +Mocha runs with a 60-second timeout. Integration tests use a custom metadata UI for filtering by topology, MongoDB version, auth, etc.: ```js describe( @@ -84,13 +81,6 @@ Public API (MongoClient, Db, Collection, Cursors) - **`src/client-side-encryption/`** — Auto-encryption and explicit encryption (CSFLE/Queryable Encryption). - **`src/gridfs/`** — GridFS file storage using upload/download streams. -### How Operations Execute - -1. User calls a method (e.g., `collection.insertOne()`) -2. An operation object is created (e.g., `InsertOperation`) -3. `executeOperation()` handles: implicit session creation → server selection → connection checkout → command building → wire protocol send → response handling → retry on transient errors -4. Connection returned to pool, session cleaned up - ### Test Structure - **`test/unit/`** — Mirrors `src/` structure. No database interaction, uses mocks. @@ -100,6 +90,7 @@ Public API (MongoClient, Db, Collection, Cursors) ## Code Conventions +- **Public API stability** — Anything exported from `src/index.ts` flows into the published `mongodb.d.ts` via api-extractor. Renaming, removing, or narrowing exported types/signatures is a breaking change; confirm with a maintainer before doing so. - **No `export default`** — All exports must be named. - **No TypeScript enums** — Use string unions or `as const` objects instead. - **No `node:` import prefix** — Use bare module names (e.g., `import { setTimeout } from 'timers'`). @@ -114,8 +105,6 @@ Public API (MongoClient, Db, Collection, Cursors) ## Commit Messages -Follow [Conventional Commits](https://www.conventionalcommits.org/): `(NODE-XXXX): ` - -Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore` +Follow [Conventional Commits](https://www.conventionalcommits.org/): `(NODE-XXXX): `, where `NODE-XXXX` is the Jira ticket. -Breaking changes use `!`: `feat(NODE-XXXX)!: description` +Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`. Breaking changes use `!`: `feat(NODE-XXXX)!: description`.