{"owner":"mongodb","repo":"node-mongodb-native","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents (Claude Code, Codex, Copilot, Cursor, Aider, etc.) when working with code in this repository.\n\n## Project Overview\n\nThis 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.\n\n## Related Repositories\n\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n\n**Do not hand-edit**: `lib/` (build output), `mongodb.d.ts` (generated), `HISTORY.md` (release-please managed), `test/spec/` (vendored from specifications repo).\n\n## Common Commands\n\n### Building\n\n```bash\nnpm run build:ts          # Compile TypeScript to lib/\nnpm run check:ts          # Type-check without emitting\n```\n\n### Linting\n\n```bash\nnpm run check:eslint      # Run ESLint\nnpm run fix:eslint        # Auto-fix ESLint issues\n```\n\n### Testing\n\nIntegration tests require a running MongoDB instance (unit tests do not). To start one locally:\n\n```bash\ngit submodule update --init\nexport DRIVERS_TOOLS=$(pwd)/drivers-evergreen-tools\nVERSION='latest' TOPOLOGY='replica_set' bash .evergreen/run-orchestration.sh\nsource mo-expansion.sh\n```\n\n```bash\nnpm run check:unit        # Unit tests (no database required)\nnpm run check:test        # Integration tests (requires database)\nnpm test                  # Full check (lint + d.ts/tsd) + unit + integration\n\n# Run a single test by name pattern\nnpm run check:unit -- -g \"pattern\"\nnpm run check:test -- -g \"pattern\"\n```\n\nTests 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:\n\n```js\ndescribe(\n  'my test',\n  { metadata: { requires: { topology: ['replicaset'], mongodb: '>=6.0' } } },\n  function () {}\n);\n```\n\n## Architecture\n\n### Layered Design\n\n```\nPublic API (MongoClient, Db, Collection, Cursors)\n  → Operations (CRUD, Aggregation, Indexes, Bulk writes)\n    → Sessions & Transactions\n      → SDAM – Server Discovery And Monitoring (src/sdam/)\n        → CMAP – Connection Management And Pooling (src/cmap/)\n          → Wire Protocol & BSON serialization\n```\n\n### Key Source Directories\n\n- **`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.\n- **`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.\n- **`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).\n- **`src/cursor/`** — `AbstractCursor` base with lazy evaluation, async iteration, and streaming. Specialized cursors: `FindCursor`, `AggregationCursor`, `ChangeStreamCursor`, etc.\n- **`src/bulk/`** — Ordered and unordered bulk write operations.\n- **`src/client-side-encryption/`** — Auto-encryption and explicit encryption (CSFLE/Queryable Encryption).\n- **`src/gridfs/`** — GridFS file storage using upload/download streams.\n\n### How Operations Execute\n\n1. User calls a method (e.g., `collection.insertOne()`)\n2. An operation object is created (e.g., `InsertOperation`)\n3. `executeOperation()` handles: implicit session creation → server selection → connection checkout → command building → wire protocol send → response handling → retry on transient errors\n4. Connection returned to pool, session cleaned up\n\n### Test Structure\n\n- **`test/unit/`** — Mirrors `src/` structure. No database interaction, uses mocks.\n- **`test/integration/`** — Real database tests organized by feature area.\n- **`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.\n- **`test/mongodb.ts`** — Central re-export of all `src/` internals for test access. Tests import from `../../mongodb` (or appropriate depth), never directly from `src/`.\n\n## Code Conventions\n\n- **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.\n- **No `export default`** — All exports must be named.\n- **No TypeScript enums** — Use string unions or `as const` objects instead.\n- **`src/`: no `node:` import prefix** — In source files, use bare module names (e.g., `import { setTimeout } from 'timers'`). Tests may use `node:` imports where allowed by the repo config.\n- **`src/`: timer/process imports** — In source files, import `setTimeout`, `setInterval`, `clearTimeout`, `process`, etc. from their modules instead of using globals.\n- **No `Buffer`** — Use `Uint8Array` in source code.\n- **BSON imports** — Source code must import from `src/bson.ts`, not from the `bson` package directly.\n- **Null/undefined checks** — Use loose equality (`== null`) not strict (`=== null` or `=== undefined`).\n- **Type imports** — Use `import { type Foo }` (inline type imports).\n- **`return await`** — Required in `src/` (enforced by `@typescript-eslint/return-await: always`).\n- **Error messages** — Sentence case, no trailing period. Use driver-specific error types extending `MongoError`.\n- **Formatting** — Prettier with single quotes, 2-space indentation, 100-char width, no trailing commas.\n\n## Commit Messages\n\nFollow [Conventional Commits](https://www.conventionalcommits.org/): `<type>(NODE-XXXX): <subject>`\n\nTypes: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`\n\nBreaking changes use `!`: `feat(NODE-XXXX)!: description`\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents (Claude Code, Codex, Copilot, Cursor, Aider, etc.) when working with code in this repository.\n\n## Project Overview\n\nThis 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.\n\n## Related Repositories\n\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n\n**Do not hand-edit**: `lib/` (build output), `mongodb.d.ts` (generated), `HISTORY.md` (release-please managed), `test/spec/` (vendored from specifications repo).\n\n## Common Commands\n\n### Building\n\n```bash\nnpm run build:ts          # Compile TypeScript to lib/\nnpm run check:ts          # Type-check without emitting\n```\n\n### Linting\n\n```bash\nnpm run check:eslint      # Run ESLint\nnpm run fix:eslint        # Auto-fix ESLint issues\n```\n\n### Testing\n\nIntegration tests require a running MongoDB instance (unit tests do not). To start one locally:\n\n```bash\ngit submodule update --init\nexport DRIVERS_TOOLS=$(pwd)/drivers-evergreen-tools\nVERSION='latest' TOPOLOGY='replica_set' bash .evergreen/run-orchestration.sh\nsource mo-expansion.sh\n```\n\n```bash\nnpm run check:unit        # Unit tests (no database required)\nnpm run check:test        # Integration tests (requires database)\nnpm test                  # Full check (lint + d.ts/tsd) + unit + integration\n\n# Run a single test by name pattern\nnpm run check:unit -- -g \"pattern\"\nnpm run check:test -- -g \"pattern\"\n```\n\nTests 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:\n\n```js\ndescribe(\n  'my test',\n  { metadata: { requires: { topology: ['replicaset'], mongodb: '>=6.0' } } },\n  function () {}\n);\n```\n\n## Architecture\n\n### Layered Design\n\n```\nPublic API (MongoClient, Db, Collection, Cursors)\n  → Operations (CRUD, Aggregation, Indexes, Bulk writes)\n    → Sessions & Transactions\n      → SDAM – Server Discovery And Monitoring (src/sdam/)\n        → CMAP – Connection Management And Pooling (src/cmap/)\n          → Wire Protocol & BSON serialization\n```\n\n### Key Source Directories\n\n- **`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.\n- **`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.\n- **`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).\n- **`src/cursor/`** — `AbstractCursor` base with lazy evaluation, async iteration, and streaming. Specialized cursors: `FindCursor`, `AggregationCursor`, `ChangeStreamCursor`, etc.\n- **`src/bulk/`** — Ordered and unordered bulk write operations.\n- **`src/client-side-encryption/`** — Auto-encryption and explicit encryption (CSFLE/Queryable Encryption).\n- **`src/gridfs/`** — GridFS file storage using upload/download streams.\n\n### How Operations Execute\n\n1. User calls a method (e.g., `collection.insertOne()`)\n2. An operation object is created (e.g., `InsertOperation`)\n3. `executeOperation()` handles: implicit session creation → server selection → connection checkout → command building → wire protocol send → response handling → retry on transient errors\n4. Connection returned to pool, session cleaned up\n\n### Test Structure\n\n- **`test/unit/`** — Mirrors `src/` structure. No database interaction, uses mocks.\n- **`test/integration/`** — Real database tests organized by feature area.\n- **`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.\n- **`test/mongodb.ts`** — Central re-export of all `src/` internals for test access. Tests import from `../../mongodb` (or appropriate depth), never directly from `src/`.\n\n## Code Conventions\n\n- **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.\n- **No `export default`** — All exports must be named.\n- **No TypeScript enums** — Use string unions or `as const` objects instead.\n- **`src/`: no `node:` import prefix** — In source files, use bare module names (e.g., `import { setTimeout } from 'timers'`). Tests may use `node:` imports where allowed by the repo config.\n- **`src/`: timer/process imports** — In source files, import `setTimeout`, `setInterval`, `clearTimeout`, `process`, etc. from their modules instead of using globals.\n- **No `Buffer`** — Use `Uint8Array` in source code.\n- **BSON imports** — Source code must import from `src/bson.ts`, not from the `bson` package directly.\n- **Null/undefined checks** — Use loose equality (`== null`) not strict (`=== null` or `=== undefined`).\n- **Type imports** — Use `import { type Foo }` (inline type imports).\n- **`return await`** — Required in `src/` (enforced by `@typescript-eslint/return-await: always`).\n- **Error messages** — Sentence case, no trailing period. Use driver-specific error types extending `MongoError`.\n- **Formatting** — Prettier with single quotes, 2-space indentation, 100-char width, no trailing commas.\n\n## Commit Messages\n\nFollow [Conventional Commits](https://www.conventionalcommits.org/): `<type>(NODE-XXXX): <subject>`\n\nTypes: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`\n\nBreaking changes use `!`: `feat(NODE-XXXX)!: description`\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance to AI coding agents (Claude Code, Codex, Copilot, Cursor, Aider, etc.) when working with code in this repository.\n\n## Project Overview\n\nThis 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.\n\n## Related Repositories\n\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n\n**Do not hand-edit**: `lib/` (build output), `mongodb.d.ts` (generated), `HISTORY.md` (release-please managed), `test/spec/` (vendored from specifications repo).\n\n## Common Commands\n\n### Building\n\n```bash\nnpm run build:ts          # Compile TypeScript to lib/\nnpm run check:ts          # Type-check without emitting\n```\n\n### Linting\n\n```bash\nnpm run check:eslint      # Run ESLint\nnpm run fix:eslint        # Auto-fix ESLint issues\n```\n\n### Testing\n\nIntegration tests require a running MongoDB instance (unit tests do not). To start one locally:\n\n```bash\ngit submodule update --init\nexport DRIVERS_TOOLS=$(pwd)/drivers-evergreen-tools\nVERSION='latest' TOPOLOGY='replica_set' bash .evergreen/run-orchestration.sh\nsource mo-expansion.sh\n```\n\n```bash\nnpm run check:unit        # Unit tests (no database required)\nnpm run check:test        # Integration tests (requires database)\nnpm test                  # Full check (lint + d.ts/tsd) + unit + integration\n\n# Run a single test by name pattern\nnpm run check:unit -- -g \"pattern\"\nnpm run check:test -- -g \"pattern\"\n```\n\nTests 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:\n\n```js\ndescribe(\n  'my test',\n  { metadata: { requires: { topology: ['replicaset'], mongodb: '>=6.0' } } },\n  function () {}\n);\n```\n\n## Architecture\n\n### Layered Design\n\n```\nPublic API (MongoClient, Db, Collection, Cursors)\n  → Operations (CRUD, Aggregation, Indexes, Bulk writes)\n    → Sessions & Transactions\n      → SDAM – Server Discovery And Monitoring (src/sdam/)\n        → CMAP – Connection Management And Pooling (src/cmap/)\n          → Wire Protocol & BSON serialization\n```\n\n### Key Source Directories\n\n- **`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.\n- **`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.\n- **`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).\n- **`src/cursor/`** — `AbstractCursor` base with lazy evaluation, async iteration, and streaming. Specialized cursors: `FindCursor`, `AggregationCursor`, `ChangeStreamCursor`, etc.\n- **`src/bulk/`** — Ordered and unordered bulk write operations.\n- **`src/client-side-encryption/`** — Auto-encryption and explicit encryption (CSFLE/Queryable Encryption).\n- **`src/gridfs/`** — GridFS file storage using upload/download streams.\n\n### How Operations Execute\n\n1. User calls a method (e.g., `collection.insertOne()`)\n2. An operation object is created (e.g., `InsertOperation`)\n3. `executeOperation()` handles: implicit session creation → server selection → connection checkout → command building → wire protocol send → response handling → retry on transient errors\n4. Connection returned to pool, session cleaned up\n\n### Test Structure\n\n- **`test/unit/`** — Mirrors `src/` structure. No database interaction, uses mocks.\n- **`test/integration/`** — Real database tests organized by feature area.\n- **`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.\n- **`test/mongodb.ts`** — Central re-export of all `src/` internals for test access. Tests import from `../../mongodb` (or appropriate depth), never directly from `src/`.\n\n## Code Conventions\n\n- **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.\n- **No `export default`** — All exports must be named.\n- **No TypeScript enums** — Use string unions or `as const` objects instead.\n- **`src/`: no `node:` import prefix** — In source files, use bare module names (e.g., `import { setTimeout } from 'timers'`). Tests may use `node:` imports where allowed by the repo config.\n- **`src/`: timer/process imports** — In source files, import `setTimeout`, `setInterval`, `clearTimeout`, `process`, etc. from their modules instead of using globals.\n- **No `Buffer`** — Use `Uint8Array` in source code.\n- **BSON imports** — Source code must import from `src/bson.ts`, not from the `bson` package directly.\n- **Null/undefined checks** — Use loose equality (`== null`) not strict (`=== null` or `=== undefined`).\n- **Type imports** — Use `import { type Foo }` (inline type imports).\n- **`return await`** — Required in `src/` (enforced by `@typescript-eslint/return-await: always`).\n- **Error messages** — Sentence case, no trailing period. Use driver-specific error types extending `MongoError`.\n- **Formatting** — Prettier with single quotes, 2-space indentation, 100-char width, no trailing commas.\n\n## Commit Messages\n\nFollow [Conventional Commits](https://www.conventionalcommits.org/): `<type>(NODE-XXXX): <subject>`\n\nTypes: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`\n\nBreaking changes use `!`: `feat(NODE-XXXX)!: description`\n","category":"root","tokens":1813}]}