From 01e89e774ad84b119d53fcb65aaf5c5b7868fdc1 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Wed, 4 Feb 2026 16:26:11 -0500 Subject: [PATCH 01/12] docs(NODE-7396): document experimental features --- EXPERIMENTAL_FEATURES.md | 359 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 EXPERIMENTAL_FEATURES.md diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md new file mode 100644 index 00000000000..e6c75f87620 --- /dev/null +++ b/EXPERIMENTAL_FEATURES.md @@ -0,0 +1,359 @@ +# MongoDB Node.js Driver - Experimental Featuress + +This report documents all experimental features in the MongoDB Node.js Driver version 7.1.0. The driver contains **31 experimental annotations** across 9 major feature categories. These features are marked as experimental because they may undergo breaking changes in future releases, even in minor or patch versions. + +--- + +## Summary + +| Feature | Description | Introduced in | Status | +|---------|-------------|---------------|--------| +| [Explicit Resource Management](#explicit-resource-management) | Automatic cleanup using `Symbol.asyncDispose` | v6.9.0 | ⚠️ Experimental | +| [AbortSignal Support](#abortsignal-support) | Cancel operations using `AbortController` | v6.13.0 | ⚠️ Experimental | +| [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | ⚠️ Experimental | +| [Cursor Timeout Modes](#cursor-timeout-modes) | Configure how timeouts apply to cursors | v6.11.0 | ⚠️ Experimental | +| [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | ⚠️ Experimental | +| [Client-Side Encryption Features](#client-side-encryption-features) | Custom key material and rewrap APIs | v6.0.0 | ⚠️ Experimental | +| [Queryable Encryption Text Search](#queryable-encryption-text-search) | Text search on encrypted fields | v6.19.0 | ⚠️ Public Technical Preview | +| [Encrypted Fields](#encrypted-fields) | Schema for encrypted collections | v4.6.0 | ⚠️ Experimental | +| [GridFS Timeout Support](#gridfs-timeout-support) | Timeout options for GridFS streams | v6.6.0 | ⚠️ Experimental | + +--- + +## Feature Descriptions + +### Explicit Resource Management + +**Status**: ⚠️ Experimental (until TC39 proposal completion) + +**Description**: Native support for JavaScript's explicit resource management using `Symbol.asyncDispose`. This feature enables automatic cleanup of resources using the `await using` syntax. + +**Available On**: +- `MongoClient` - [src/mongo_client.ts:466](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_client.ts#L466) +- `ClientSession` - [src/sessions.ts:293](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L293) +- `ChangeStream` - [src/change_stream.ts:576](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/change_stream.ts#L576) +- All cursor types (`AbstractCursor`, `FindCursor`, `AggregationCursor`, etc.) - [src/cursor/abstract_cursor.ts:433](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/abstract_cursor.ts#L433) + +**Example**: +```typescript +// Automatic cleanup when scope exits +await using client = new MongoClient(url); +await using session = client.startSession(); +// No need to call client.close() or session.endSession() +``` + +**References**: +- [TC39 Explicit Resource Management Proposal](https://github.com/tc39/proposal-explicit-resource-management) +- Driver upgrade notes: `etc/notes/CHANGES_7.0.0.md` + +**Stability Note**: Will remain experimental until the TC39 proposal is finalized. + +--- + +### AbortSignal Support + +**Status**: ⚠️ Experimental + +**Type**: `Abortable` +**Source**: [src/mongo_types.ts:488](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L488) + +**Description**: Allows using `AbortController` to abort asynchronous operations. The `signal.reason` value is used as the error thrown. + +**Example**: +```typescript +const controller = new AbortController(); +const { signal } = controller; + +// Abort operation after 5 seconds +setTimeout(() => controller.abort(new Error('Operation timeout')), 5000); + +await collection.find({}, { signal }).toArray(); +``` + +**⚠️ Important Warning**: +If an abort signal aborts an operation while the driver is writing to the underlying socket or reading the response from the server, the socket will be closed. If signals are aborted at a high rate during socket read/writes, this can lead to a high rate of connection reestablishment. + +--- + +### Timeout Management + +**Status**: ⚠️ Experimental + +**Option**: `timeoutMS` + +**Description**: Specifies the time (in milliseconds) an operation will run until it throws a timeout error. + +**Available On**: +- `CommandOperationOptions` - [src/db.ts:97](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/db.ts#L97) +- `ClientSessionOptions` - [src/sessions.ts:141](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L141) +- `ClientSessionStartOptions.defaultTimeoutMS` - [src/sessions.ts:63](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L63) +- `ClientEncryptionOptions` - [src/client-side-encryption/client_encryption.ts:942](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L942) +- `MongoClientOptions` - [src/mongo_client.ts:145](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_client.ts#L145) +- `RunCommandOptions` - [src/operations/run_command.ts:19](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/run_command.ts#L19) +- `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts:23](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/run_command_cursor.ts#L23) +- `CollectionOptions` - [src/collection.ts:123](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/collection.ts#L123) +- `OperationOptions` - [src/operations/operation.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/operation.ts#L42) +- `GridFSBucketReadStreamOptions` - [src/gridfs/index.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/index.ts#L42) +- `GridFSBucketWriteStreamOptions` - [src/gridfs/upload.ts:36](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/upload.ts#L36) +- Various database and collection operation options + +**Example**: +```typescript +// Set timeout at client level +const client = new MongoClient(url, { timeoutMS: 10000 }); + +// Set timeout at operation level +await collection.find({}, { timeoutMS: 5000 }).toArray(); + +// Set timeout for session +const session = client.startSession({ timeoutMS: 30000 }); +``` + +--- + +### Cursor Timeout Modes + +**Status**: ⚠️ Experimental + +**Type**: `CursorTimeoutMode` +**Source**: +- Constant definition - [src/cursor/abstract_cursor.ts:70](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/abstract_cursor.ts#L70) +- Type definition - [src/cursor/abstract_cursor.ts:104](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/abstract_cursor.ts#L104) +- Option in `AbstractCursorOptions` - [src/cursor/abstract_cursor.ts:155](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/abstract_cursor.ts#L155) +- Option in `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts:31](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/run_command_cursor.ts#L31) + +**Values**: +- `'cursorLifetime'` - Timeout applies to the entire cursor lifetime +- `'iteration'` - Timeout applies to each `cursor.next()` call + +**Description**: Specifies how `timeoutMS` is applied to cursors. + +**Default Behavior**: +- **Non-tailable cursors**: `'cursorLifetime'` +- **Tailable cursors**: `'iteration'` (since tailable cursors can have arbitrarily long lifetimes) + +**Examples**: +```typescript +// Iteration mode: Each next() call must complete within 100ms +const cursor1 = collection.find({}, { + timeoutMS: 100, + timeoutMode: 'iteration' +}); +for await (const doc of cursor1) { + // Process doc - each iteration has 100ms timeout +} + +// Cursor lifetime mode: Entire operation must complete within 1000ms +const cursor2 = collection.find({}, { + timeoutMS: 1000, + timeoutMode: 'cursorLifetime' +}); +const docs = await cursor2.toArray(); // Must complete in 1000ms total +``` + +--- + +### Strict TypeScript Types + +**Status**: ⚠️ Experimental + +**Description**: Provides stricter type checking for MongoDB operations with better TypeScript inference for nested paths and type safety. + +**Types**: + +#### `StrictFilter` +**Source**: [src/mongo_types.ts:622](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L622) + +Provides strict type checking for filter predicates with proper nested path support. + +#### `StrictMatchKeysAndValues` +**Source**: [src/mongo_types.ts:664](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L664) + +Ensures type-safe matching of keys and values in update operations. + +#### `StrictUpdateFilter` +**Source**: [src/mongo_types.ts:634](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L634) + +Provides strict typing for update operators (`$set`, `$inc`, `$push`, etc.). + +**Example**: +```typescript +interface User { + name: string; + age: number; + address: { + city: string; + zip: number; + }; +} + +const collection: Collection = db.collection('users'); + +// Type-safe filter with nested paths +const filter: StrictFilter = { + 'address.city': 'New York' // ✓ Valid + // 'address.city': 123 // ✗ Compile error: number not assignable to string +}; + +// Type-safe update +const update: StrictUpdateFilter = { + $set: { age: 30 }, // ✓ Valid + // $set: { age: 'thirty' } // ✗ Compile error +}; +``` + +**⚠️ Production Warning**: As experimental features, these types can change at any time and are not recommended for production settings. + +--- + +### Client-Side Encryption Features + +**Status**: ⚠️ Experimental + +**Description**: Advanced client-side encryption capabilities for enhanced data security. + +#### Custom Key Material + +**Option**: `keyMaterial` +**Type**: `Buffer | Binary` +**Location**: `ClientEncryptionCreateDataKeyProviderOptions` +**Source**: [src/client-side-encryption/client_encryption.ts:1099](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L1099) + +**Description**: Allows providing custom key material when creating data keys, giving more control over the encryption key generation process. + +**Example**: +```typescript +const encryption = new ClientEncryption(client, { + keyVaultNamespace: 'encryption.__keyVault', + kmsProviders: { local: { key: localMasterKey } } +}); + +const dataKeyId = await encryption.createDataKey('local', { + keyMaterial: customKeyBuffer // Experimental option +}); +``` + +#### RewrapManyDataKey API + +**Interfaces**: +- `ClientEncryptionRewrapManyDataKeyProviderOptions` - [src/client-side-encryption/client_encryption.ts:889](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L889) +- `ClientEncryptionRewrapManyDataKeyResult` - [src/client-side-encryption/client_encryption.ts:1108](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L1108) + +**Description**: Experimental API for rewrapping multiple data keys in a single operation, useful for key rotation scenarios. + +**Interface Definition**: +```typescript +interface ClientEncryptionRewrapManyDataKeyProviderOptions { + provider: ClientEncryptionDataKeyProvider; + masterKey?: AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | + GCPEncryptionKeyOptions | KMIPEncryptionKeyOptions | undefined; +} + +interface ClientEncryptionRewrapManyDataKeyResult { + /** The result of rewrapping data keys. If unset, no keys matched the filter. */ + bulkWriteResult?: BulkWriteResult; +} +``` + +--- + +### Queryable Encryption Text Search + +**Status**: ⚠️ Public Technical Preview (may break at any time) + +**Option**: `textOptions` +**Type**: `TextQueryOptions` +**Location**: `ClientEncryptionEncryptOptions` +**Source**: +- Option in `ClientEncryptionEncryptOptions` - [src/client-side-encryption/client_encryption.ts:846](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L846) +- Interface `TextQueryOptions` - [src/client-side-encryption/client_encryption.ts:855](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L855) + +**Description**: Options for Queryable Encryption fields supporting text queries. Only valid when the encryption algorithm is set to `TextPreview`. + +**Example**: +```typescript +const encrypted = await encryption.encrypt(value, { + algorithm: 'TextPreview', + keyId: dataKeyId, + textOptions: { + // Text search configuration options + } +}); +``` + +**⚠️ Critical Warning**: This is a Public Technical Preview feature. The `textPreview` algorithm and related options are experimental and may break at any time. Not recommended for production use. + +--- + +### Encrypted Fields + +**Status**: ⚠️ Experimental + +**Option**: `encryptedFields` +**Type**: `Document` + +**Available On**: +- `CreateCollectionOptions` - [src/operations/create_collection.ts:98](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/create_collection.ts#L98) +- `DropCollectionOptions` - [src/operations/drop.ts:15](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/drop.ts#L15) + +**Description**: Specifies the schema for encrypted fields in a collection, used with Queryable Encryption. + +**Example**: +```typescript +// Create collection with encrypted fields +await db.createCollection('users', { + encryptedFields: { + fields: [ + { + path: 'ssn', + bsonType: 'string', + keyId: dataKeyId + } + ] + } +}); + +// Drop collection with encrypted fields +await db.dropCollection('users', { + encryptedFields: encryptedFieldsConfig +}); +``` + +--- + +### GridFS Timeout Support + +**Status**: ⚠️ Experimental + +**Description**: Timeout support for GridFS read and write streams. + +#### GridFS Read Stream Timeout + +**Option**: `timeoutMS` in `GridFSBucketReadStreamOptions` +**Source**: [src/gridfs/index.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/index.ts#L42) + +**Description**: Specifies the lifetime duration of a GridFS read stream. If any async operations are in progress when this timeout expires, the stream will throw a timeout error. + +**Example**: +```typescript +const bucket = new GridFSBucket(db); +const downloadStream = bucket.openDownloadStream(fileId, { + timeoutMS: 30000 // 30 second timeout for the entire download +}); +``` + +#### GridFS Write Stream Timeout + +**Option**: `timeoutMS` in `GridFSBucketWriteStreamOptions` +**Source**: [src/gridfs/upload.ts:36](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/upload.ts#L36) + +**Description**: Specifies the time an upload operation will run until it throws a timeout error. + +**Example**: +```typescript +const bucket = new GridFSBucket(db); +const uploadStream = bucket.openUploadStream('filename.txt', { + timeoutMS: 60000 // 60 second timeout for the entire upload +}); +``` + From 05d1489c54c0f77235a5dbff2cdb6744124a023c Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Tue, 12 May 2026 15:18:37 -0400 Subject: [PATCH 02/12] docs: update Experimental features and add reference in Readme --- EXPERIMENTAL_FEATURES.md | 119 ++++++++++++++++++++++++++------------- README.md | 6 ++ 2 files changed, 86 insertions(+), 39 deletions(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index e6c75f87620..cc54ae3c35a 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -1,6 +1,6 @@ -# MongoDB Node.js Driver - Experimental Featuress +# MongoDB Node.js Driver - Experimental Features -This report documents all experimental features in the MongoDB Node.js Driver version 7.1.0. The driver contains **31 experimental annotations** across 9 major feature categories. These features are marked as experimental because they may undergo breaking changes in future releases, even in minor or patch versions. +This report documents all experimental features in the MongoDB Node.js Driver. The driver contains **34 experimental annotations** across 10 major feature categories. These features are marked as experimental because they may undergo breaking changes in future releases, even in minor or patch versions. --- @@ -8,15 +8,16 @@ This report documents all experimental features in the MongoDB Node.js Driver ve | Feature | Description | Introduced in | Status | |---------|-------------|---------------|--------| -| [Explicit Resource Management](#explicit-resource-management) | Automatic cleanup using `Symbol.asyncDispose` | v6.9.0 | ⚠️ Experimental | +| [Runtime Adapters](#runtime-adapters) | Custom runtime module implementations | v7.2.0 | ⚠️ Experimental | +| [Queryable Encryption Text Search](#queryable-encryption-text-search) | Text search on encrypted fields | v6.19.0 | ⚠️ Public Technical Preview | | [AbortSignal Support](#abortsignal-support) | Cancel operations using `AbortController` | v6.13.0 | ⚠️ Experimental | -| [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | ⚠️ Experimental | | [Cursor Timeout Modes](#cursor-timeout-modes) | Configure how timeouts apply to cursors | v6.11.0 | ⚠️ Experimental | -| [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | ⚠️ Experimental | +| [Explicit Resource Management](#explicit-resource-management) | Automatic cleanup using `Symbol.asyncDispose` | v6.9.0 | ⚠️ Experimental | +| [GridFS Timeout Support](#gridfs-timeout-support) | Timeout options for GridFS streams | v6.6.0 | ⚠️ Experimental | +| [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | ⚠️ Experimental | | [Client-Side Encryption Features](#client-side-encryption-features) | Custom key material and rewrap APIs | v6.0.0 | ⚠️ Experimental | -| [Queryable Encryption Text Search](#queryable-encryption-text-search) | Text search on encrypted fields | v6.19.0 | ⚠️ Public Technical Preview | +| [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | ⚠️ Experimental | | [Encrypted Fields](#encrypted-fields) | Schema for encrypted collections | v4.6.0 | ⚠️ Experimental | -| [GridFS Timeout Support](#gridfs-timeout-support) | Timeout options for GridFS streams | v6.6.0 | ⚠️ Experimental | --- @@ -29,10 +30,10 @@ This report documents all experimental features in the MongoDB Node.js Driver ve **Description**: Native support for JavaScript's explicit resource management using `Symbol.asyncDispose`. This feature enables automatic cleanup of resources using the `await using` syntax. **Available On**: -- `MongoClient` - [src/mongo_client.ts:466](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_client.ts#L466) -- `ClientSession` - [src/sessions.ts:293](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L293) -- `ChangeStream` - [src/change_stream.ts:576](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/change_stream.ts#L576) -- All cursor types (`AbstractCursor`, `FindCursor`, `AggregationCursor`, etc.) - [src/cursor/abstract_cursor.ts:433](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/abstract_cursor.ts#L433) +- `MongoClient` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_client.ts) +- `ClientSession` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/sessions.ts) +- `ChangeStream` - [src/change_stream.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/change_stream.ts) +- All cursor types (`AbstractCursor`, `FindCursor`, `AggregationCursor`, etc.) - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) **Example**: ```typescript @@ -55,7 +56,7 @@ await using session = client.startSession(); **Status**: ⚠️ Experimental **Type**: `Abortable` -**Source**: [src/mongo_types.ts:488](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L488) +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) **Description**: Allows using `AbortController` to abort asynchronous operations. The `signal.reason` value is used as the error thrown. @@ -84,17 +85,17 @@ If an abort signal aborts an operation while the driver is writing to the underl **Description**: Specifies the time (in milliseconds) an operation will run until it throws a timeout error. **Available On**: -- `CommandOperationOptions` - [src/db.ts:97](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/db.ts#L97) -- `ClientSessionOptions` - [src/sessions.ts:141](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L141) -- `ClientSessionStartOptions.defaultTimeoutMS` - [src/sessions.ts:63](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L63) -- `ClientEncryptionOptions` - [src/client-side-encryption/client_encryption.ts:942](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L942) -- `MongoClientOptions` - [src/mongo_client.ts:145](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_client.ts#L145) -- `RunCommandOptions` - [src/operations/run_command.ts:19](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/run_command.ts#L19) -- `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts:23](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/run_command_cursor.ts#L23) -- `CollectionOptions` - [src/collection.ts:123](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/collection.ts#L123) -- `OperationOptions` - [src/operations/operation.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/operation.ts#L42) -- `GridFSBucketReadStreamOptions` - [src/gridfs/index.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/index.ts#L42) -- `GridFSBucketWriteStreamOptions` - [src/gridfs/upload.ts:36](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/upload.ts#L36) +- `CommandOperationOptions` - [src/db.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/db.ts) +- `ClientSessionOptions` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/sessions.ts) +- `ClientSessionStartOptions.defaultTimeoutMS` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/sessions.ts) +- `ClientEncryptionOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) +- `MongoClientOptions` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_client.ts) +- `RunCommandOptions` - [src/operations/run_command.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/operations/run_command.ts) +- `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/run_command_cursor.ts) +- `CollectionOptions` - [src/collection.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/collection.ts) +- `OperationOptions` - [src/operations/operation.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/operations/operation.ts) +- `GridFSBucketReadStreamOptions` - [src/gridfs/index.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/index.ts) +- `GridFSBucketWriteStreamOptions` - [src/gridfs/upload.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/upload.ts) - Various database and collection operation options **Example**: @@ -117,10 +118,10 @@ const session = client.startSession({ timeoutMS: 30000 }); **Type**: `CursorTimeoutMode` **Source**: -- Constant definition - [src/cursor/abstract_cursor.ts:70](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/abstract_cursor.ts#L70) -- Type definition - [src/cursor/abstract_cursor.ts:104](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/abstract_cursor.ts#L104) -- Option in `AbstractCursorOptions` - [src/cursor/abstract_cursor.ts:155](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/abstract_cursor.ts#L155) -- Option in `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts:31](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/cursor/run_command_cursor.ts#L31) +- Constant definition - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) +- Type definition - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) +- Option in `AbstractCursorOptions` - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) +- Option in `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/run_command_cursor.ts) **Values**: - `'cursorLifetime'` - Timeout applies to the entire cursor lifetime @@ -162,17 +163,17 @@ const docs = await cursor2.toArray(); // Must complete in 1000ms total **Types**: #### `StrictFilter` -**Source**: [src/mongo_types.ts:622](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L622) +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) Provides strict type checking for filter predicates with proper nested path support. #### `StrictMatchKeysAndValues` -**Source**: [src/mongo_types.ts:664](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L664) +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) Ensures type-safe matching of keys and values in update operations. #### `StrictUpdateFilter` -**Source**: [src/mongo_types.ts:634](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L634) +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) Provides strict typing for update operators (`$set`, `$inc`, `$push`, etc.). @@ -206,6 +207,46 @@ const update: StrictUpdateFilter = { --- +### Runtime Adapters + +**Status**: ⚠️ Experimental + +**Description**: Allows providing custom implementations of Node.js runtime modules to the driver. This enables the driver to work in non-Node.js JavaScript environments or with alternative module implementations. + +**Types**: + +#### `RuntimeAdapters` +**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/runtime_adapters.ts) + +Interface for providing custom runtime module implementations. + +#### `OsAdapter` +**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/runtime_adapters.ts) + +Represents the required functionality from the Node.js `os` module. + +**Available On**: +- `MongoClientOptions.runtimeAdapters` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_client.ts) + +**Example**: +```typescript +// Provide custom OS module implementation +const client = new MongoClient(url, { + runtimeAdapters: { + os: { + release: () => 'custom-release', + platform: () => 'linux', + arch: () => 'x64', + type: () => 'Linux' + } + } +}); +``` + +**⚠️ Important Warning**: This feature is experimental and primarily intended for running the driver in non-Node.js JavaScript runtimes. The API may change in future versions. + +--- + ### Client-Side Encryption Features **Status**: ⚠️ Experimental @@ -217,7 +258,7 @@ const update: StrictUpdateFilter = { **Option**: `keyMaterial` **Type**: `Buffer | Binary` **Location**: `ClientEncryptionCreateDataKeyProviderOptions` -**Source**: [src/client-side-encryption/client_encryption.ts:1099](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L1099) +**Source**: [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) **Description**: Allows providing custom key material when creating data keys, giving more control over the encryption key generation process. @@ -236,8 +277,8 @@ const dataKeyId = await encryption.createDataKey('local', { #### RewrapManyDataKey API **Interfaces**: -- `ClientEncryptionRewrapManyDataKeyProviderOptions` - [src/client-side-encryption/client_encryption.ts:889](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L889) -- `ClientEncryptionRewrapManyDataKeyResult` - [src/client-side-encryption/client_encryption.ts:1108](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L1108) +- `ClientEncryptionRewrapManyDataKeyProviderOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) +- `ClientEncryptionRewrapManyDataKeyResult` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) **Description**: Experimental API for rewrapping multiple data keys in a single operation, useful for key rotation scenarios. @@ -265,8 +306,8 @@ interface ClientEncryptionRewrapManyDataKeyResult { **Type**: `TextQueryOptions` **Location**: `ClientEncryptionEncryptOptions` **Source**: -- Option in `ClientEncryptionEncryptOptions` - [src/client-side-encryption/client_encryption.ts:846](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L846) -- Interface `TextQueryOptions` - [src/client-side-encryption/client_encryption.ts:855](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/client-side-encryption/client_encryption.ts#L855) +- Option in `ClientEncryptionEncryptOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) +- Interface `TextQueryOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) **Description**: Options for Queryable Encryption fields supporting text queries. Only valid when the encryption algorithm is set to `TextPreview`. @@ -293,8 +334,8 @@ const encrypted = await encryption.encrypt(value, { **Type**: `Document` **Available On**: -- `CreateCollectionOptions` - [src/operations/create_collection.ts:98](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/create_collection.ts#L98) -- `DropCollectionOptions` - [src/operations/drop.ts:15](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/drop.ts#L15) +- `CreateCollectionOptions` - [src/operations/create_collection.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/operations/create_collection.ts) +- `DropCollectionOptions` - [src/operations/drop.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/operations/drop.ts) **Description**: Specifies the schema for encrypted fields in a collection, used with Queryable Encryption. @@ -330,7 +371,7 @@ await db.dropCollection('users', { #### GridFS Read Stream Timeout **Option**: `timeoutMS` in `GridFSBucketReadStreamOptions` -**Source**: [src/gridfs/index.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/index.ts#L42) +**Source**: [src/gridfs/index.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/index.ts) **Description**: Specifies the lifetime duration of a GridFS read stream. If any async operations are in progress when this timeout expires, the stream will throw a timeout error. @@ -345,7 +386,7 @@ const downloadStream = bucket.openDownloadStream(fileId, { #### GridFS Write Stream Timeout **Option**: `timeoutMS` in `GridFSBucketWriteStreamOptions` -**Source**: [src/gridfs/upload.ts:36](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/upload.ts#L36) +**Source**: [src/gridfs/upload.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/upload.ts) **Description**: Specifies the time an upload operation will run until it throws a timeout error. diff --git a/README.md b/README.md index bf10fe6dac0..785cb4c22a1 100644 --- a/README.md +++ b/README.md @@ -351,6 +351,12 @@ Nightly versions are published regardless of testing outcome. This means there could be semantic breakages or partially implemented features. The nightly build is not suitable for production use. +## Experimental Features + +The MongoDB Node.js driver offers cutting-edge experimental features that give you early access to new capabilities and APIs. These features are marked with `@experimental` tags and are great for exploring new functionality and providing feedback. They may evolve in future releases. + +Explore the full list of experimental features, complete with descriptions and usage examples, in [EXPERIMENTAL_FEATURES.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/EXPERIMENTAL_FEATURES.md). + ## Next Steps - [MongoDB Documentation](https://www.mongodb.com/docs/manual/) From e9ec56a1ed04cee7bf4a58587077853175a99a4f Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Tue, 12 May 2026 15:24:21 -0400 Subject: [PATCH 03/12] docs(releasing): add instructions to maintain experimental feature docs --- etc/notes/releasing.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/etc/notes/releasing.md b/etc/notes/releasing.md index cacd46bcf28..757bfb22494 100644 --- a/etc/notes/releasing.md +++ b/etc/notes/releasing.md @@ -76,6 +76,13 @@ The MongoDB driver can now generate a cup of joe. 1. On slack notify `#node-driver-docs`, `#nodejs-devtools`, and `#mongoose` that we intend to publish a release. - You may skip this step if you are releasing a package other than the driver. +1. **If there are new or changed experimental features**, update `EXPERIMENTAL_FEATURES.md` + - Update the version number in the document header + - Update the count of experimental annotations (grep for `@experimental` in `src/`) + - Add descriptions for any new `@experimental` features + - Remove or update entries for features that are no longer experimental + - Ensure all source file references omit line numbers (links should point to files, not specific lines) + - Commit and push these changes to the release branch before running release notes 1. Comment "`run release_notes`" on the release PR. - This will kick off the action that reads the notes from each PR going into the release. - Double check the result looks logically organized From fe7cbb8080172dfe453ff4f76de6a2d6b956c448 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Wed, 27 May 2026 11:12:54 -0400 Subject: [PATCH 04/12] docs: remove repetitive warnings --- EXPERIMENTAL_FEATURES.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index cc54ae3c35a..7c8843c9ce8 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -1,6 +1,9 @@ # MongoDB Node.js Driver - Experimental Features -This report documents all experimental features in the MongoDB Node.js Driver. The driver contains **34 experimental annotations** across 10 major feature categories. These features are marked as experimental because they may undergo breaking changes in future releases, even in minor or patch versions. +This report documents all experimental features in the MongoDB Node.js Driver. The driver contains **34 experimental annotations** across 10 major feature categories. + +> [!WARNING] +> Experimental features may change in any release, including patches and minors, and are not covered by the driver's semver guarantees. Updates can change runtime behavior or break TypeScript compilation, and may require source changes before you can upgrade. --- @@ -71,8 +74,8 @@ setTimeout(() => controller.abort(new Error('Operation timeout')), 5000); await collection.find({}, { signal }).toArray(); ``` -**⚠️ Important Warning**: -If an abort signal aborts an operation while the driver is writing to the underlying socket or reading the response from the server, the socket will be closed. If signals are aborted at a high rate during socket read/writes, this can lead to a high rate of connection reestablishment. +> [!WARNING] +> If an abort signal aborts an operation while the driver is writing to the underlying socket or reading the response from the server, the socket will be closed. If signals are aborted at a high rate during socket read/writes, this can lead to a high rate of connection reestablishment. --- @@ -203,8 +206,6 @@ const update: StrictUpdateFilter = { }; ``` -**⚠️ Production Warning**: As experimental features, these types can change at any time and are not recommended for production settings. - --- ### Runtime Adapters @@ -243,8 +244,6 @@ const client = new MongoClient(url, { }); ``` -**⚠️ Important Warning**: This feature is experimental and primarily intended for running the driver in non-Node.js JavaScript runtimes. The API may change in future versions. - --- ### Client-Side Encryption Features @@ -322,8 +321,6 @@ const encrypted = await encryption.encrypt(value, { }); ``` -**⚠️ Critical Warning**: This is a Public Technical Preview feature. The `textPreview` algorithm and related options are experimental and may break at any time. Not recommended for production use. - --- ### Encrypted Fields From 0309cbb49d7f4ca8b809885f3444bdf2a3d2a523 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Wed, 27 May 2026 11:21:23 -0400 Subject: [PATCH 05/12] docs: enhance warning for AbortSignal usage and connection pool implications --- EXPERIMENTAL_FEATURES.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index 7c8843c9ce8..93cc8f948db 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -75,7 +75,9 @@ await collection.find({}, { signal }).toArray(); ``` > [!WARNING] -> If an abort signal aborts an operation while the driver is writing to the underlying socket or reading the response from the server, the socket will be closed. If signals are aborted at a high rate during socket read/writes, this can lead to a high rate of connection reestablishment. +> If an abort signal aborts an operation while the driver is writing to the underlying socket or reading the response from the server, the socket will be closed. If signals are aborted at a high rate during socket read/writes, this can lead to a high rate of connection reestablishment — programmatically aborting hundreds of operations can empty the driver's connection pool. +> +> `AbortSignal` is best suited for human-interactive interruption (e.g., Ctrl-C) where the cancellation frequency is reasonably low. Mitigation of this limitation is tracked in [NODE-6062](https://jira.mongodb.org/browse/NODE-6062) (`timeoutMS` expiration has the same limitation). --- From b5e24c53b0a1e021ca1ce159c8ff488ee20229e4 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Wed, 27 May 2026 13:47:52 -0400 Subject: [PATCH 06/12] docs: remove repetitive *status* notes from every section --- EXPERIMENTAL_FEATURES.md | 46 ++++++++++++++-------------------------- 1 file changed, 16 insertions(+), 30 deletions(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index 93cc8f948db..4f1e5b4f86b 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -9,18 +9,18 @@ This report documents all experimental features in the MongoDB Node.js Driver. T ## Summary -| Feature | Description | Introduced in | Status | -|---------|-------------|---------------|--------| -| [Runtime Adapters](#runtime-adapters) | Custom runtime module implementations | v7.2.0 | ⚠️ Experimental | -| [Queryable Encryption Text Search](#queryable-encryption-text-search) | Text search on encrypted fields | v6.19.0 | ⚠️ Public Technical Preview | -| [AbortSignal Support](#abortsignal-support) | Cancel operations using `AbortController` | v6.13.0 | ⚠️ Experimental | -| [Cursor Timeout Modes](#cursor-timeout-modes) | Configure how timeouts apply to cursors | v6.11.0 | ⚠️ Experimental | -| [Explicit Resource Management](#explicit-resource-management) | Automatic cleanup using `Symbol.asyncDispose` | v6.9.0 | ⚠️ Experimental | -| [GridFS Timeout Support](#gridfs-timeout-support) | Timeout options for GridFS streams | v6.6.0 | ⚠️ Experimental | -| [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | ⚠️ Experimental | -| [Client-Side Encryption Features](#client-side-encryption-features) | Custom key material and rewrap APIs | v6.0.0 | ⚠️ Experimental | -| [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | ⚠️ Experimental | -| [Encrypted Fields](#encrypted-fields) | Schema for encrypted collections | v4.6.0 | ⚠️ Experimental | +| Feature | Description | Introduced in | +|---------|-------------|---------------| +| [Runtime Adapters](#runtime-adapters) | Custom runtime module implementations | v7.2.0 | +| [Queryable Encryption Text Search](#queryable-encryption-text-search) | Text search on encrypted fields | v6.19.0 | +| [AbortSignal Support](#abortsignal-support) | Cancel operations using `AbortController` | v6.13.0 | +| [Cursor Timeout Modes](#cursor-timeout-modes) | Configure how timeouts apply to cursors | v6.11.0 | +| [Explicit Resource Management](#explicit-resource-management) | Automatic cleanup using `Symbol.asyncDispose` | v6.9.0 | +| [GridFS Timeout Support](#gridfs-timeout-support) | Timeout options for GridFS streams | v6.6.0 | +| [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | +| [Client-Side Encryption Features](#client-side-encryption-features) | Custom key material and rewrap APIs | v6.0.0 | +| [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | +| [Encrypted Fields](#encrypted-fields) | Schema for encrypted collections | v4.6.0 | --- @@ -28,7 +28,8 @@ This report documents all experimental features in the MongoDB Node.js Driver. T ### Explicit Resource Management -**Status**: ⚠️ Experimental (until TC39 proposal completion) +> [!WARNING] +> Experimental until TC39 proposal completion **Description**: Native support for JavaScript's explicit resource management using `Symbol.asyncDispose`. This feature enables automatic cleanup of resources using the `await using` syntax. @@ -56,8 +57,6 @@ await using session = client.startSession(); ### AbortSignal Support -**Status**: ⚠️ Experimental - **Type**: `Abortable` **Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) @@ -83,8 +82,6 @@ await collection.find({}, { signal }).toArray(); ### Timeout Management -**Status**: ⚠️ Experimental - **Option**: `timeoutMS` **Description**: Specifies the time (in milliseconds) an operation will run until it throws a timeout error. @@ -119,8 +116,6 @@ const session = client.startSession({ timeoutMS: 30000 }); ### Cursor Timeout Modes -**Status**: ⚠️ Experimental - **Type**: `CursorTimeoutMode` **Source**: - Constant definition - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) @@ -161,8 +156,6 @@ const docs = await cursor2.toArray(); // Must complete in 1000ms total ### Strict TypeScript Types -**Status**: ⚠️ Experimental - **Description**: Provides stricter type checking for MongoDB operations with better TypeScript inference for nested paths and type safety. **Types**: @@ -212,8 +205,6 @@ const update: StrictUpdateFilter = { ### Runtime Adapters -**Status**: ⚠️ Experimental - **Description**: Allows providing custom implementations of Node.js runtime modules to the driver. This enables the driver to work in non-Node.js JavaScript environments or with alternative module implementations. **Types**: @@ -250,8 +241,6 @@ const client = new MongoClient(url, { ### Client-Side Encryption Features -**Status**: ⚠️ Experimental - **Description**: Advanced client-side encryption capabilities for enhanced data security. #### Custom Key Material @@ -301,7 +290,8 @@ interface ClientEncryptionRewrapManyDataKeyResult { ### Queryable Encryption Text Search -**Status**: ⚠️ Public Technical Preview (may break at any time) +> [!NOTE] +> This feature is a Public Technical Preview **Option**: `textOptions` **Type**: `TextQueryOptions` @@ -327,8 +317,6 @@ const encrypted = await encryption.encrypt(value, { ### Encrypted Fields -**Status**: ⚠️ Experimental - **Option**: `encryptedFields` **Type**: `Document` @@ -363,8 +351,6 @@ await db.dropCollection('users', { ### GridFS Timeout Support -**Status**: ⚠️ Experimental - **Description**: Timeout support for GridFS read and write streams. #### GridFS Read Stream Timeout From 15e2bbf0cb161423780fb2bf1e929314a15ca217 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Wed, 27 May 2026 14:07:51 -0400 Subject: [PATCH 07/12] docs: wrap all timeout sections together --- EXPERIMENTAL_FEATURES.md | 95 +++++----------------------------------- 1 file changed, 12 insertions(+), 83 deletions(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index 4f1e5b4f86b..0e2741e91a1 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -14,9 +14,7 @@ This report documents all experimental features in the MongoDB Node.js Driver. T | [Runtime Adapters](#runtime-adapters) | Custom runtime module implementations | v7.2.0 | | [Queryable Encryption Text Search](#queryable-encryption-text-search) | Text search on encrypted fields | v6.19.0 | | [AbortSignal Support](#abortsignal-support) | Cancel operations using `AbortController` | v6.13.0 | -| [Cursor Timeout Modes](#cursor-timeout-modes) | Configure how timeouts apply to cursors | v6.11.0 | | [Explicit Resource Management](#explicit-resource-management) | Automatic cleanup using `Symbol.asyncDispose` | v6.9.0 | -| [GridFS Timeout Support](#gridfs-timeout-support) | Timeout options for GridFS streams | v6.6.0 | | [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | | [Client-Side Encryption Features](#client-side-encryption-features) | Custom key material and rewrap APIs | v6.0.0 | | [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | @@ -84,37 +82,14 @@ await collection.find({}, { signal }).toArray(); **Option**: `timeoutMS` -**Description**: Specifies the time (in milliseconds) an operation will run until it throws a timeout error. +**Description**: Specifies the time (in milliseconds) an operation will run until it throws a timeout error. `timeoutMS` can be configured at the client, database, collection, session, transaction, and per-operation levels, with narrower scopes overriding broader ones. -**Available On**: -- `CommandOperationOptions` - [src/db.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/db.ts) -- `ClientSessionOptions` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/sessions.ts) -- `ClientSessionStartOptions.defaultTimeoutMS` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/sessions.ts) -- `ClientEncryptionOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) -- `MongoClientOptions` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_client.ts) -- `RunCommandOptions` - [src/operations/run_command.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/operations/run_command.ts) -- `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/run_command_cursor.ts) -- `CollectionOptions` - [src/collection.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/collection.ts) -- `OperationOptions` - [src/operations/operation.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/operations/operation.ts) -- `GridFSBucketReadStreamOptions` - [src/gridfs/index.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/index.ts) -- `GridFSBucketWriteStreamOptions` - [src/gridfs/upload.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/upload.ts) -- Various database and collection operation options +See [Limit Server Execution Time (CSOT) — MongoDB Node.js Driver Docs](https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/csot/) for the full inheritance/override rules, cursor-specific behavior, Client Encryption interactions, and code examples. -**Example**: -```typescript -// Set timeout at client level -const client = new MongoClient(url, { timeoutMS: 10000 }); +#### Cursor Timeout Modes -// Set timeout at operation level -await collection.find({}, { timeoutMS: 5000 }).toArray(); - -// Set timeout for session -const session = client.startSession({ timeoutMS: 30000 }); -``` - ---- - -### Cursor Timeout Modes +> [!NOTE] +> This configures how the CSOT `timeoutMS` above is applied to cursors. **Type**: `CursorTimeoutMode` **Source**: @@ -133,24 +108,14 @@ const session = client.startSession({ timeoutMS: 30000 }); - **Non-tailable cursors**: `'cursorLifetime'` - **Tailable cursors**: `'iteration'` (since tailable cursors can have arbitrarily long lifetimes) -**Examples**: -```typescript -// Iteration mode: Each next() call must complete within 100ms -const cursor1 = collection.find({}, { - timeoutMS: 100, - timeoutMode: 'iteration' -}); -for await (const doc of cursor1) { - // Process doc - each iteration has 100ms timeout -} +#### GridFS Streams -// Cursor lifetime mode: Entire operation must complete within 1000ms -const cursor2 = collection.find({}, { - timeoutMS: 1000, - timeoutMode: 'cursorLifetime' -}); -const docs = await cursor2.toArray(); // Must complete in 1000ms total -``` +> [!NOTE] +> Applies the CSOT `timeoutMS` above to GridFS upload and download streams as a per-stream lifetime. + +**Options**: +- `timeoutMS` in `GridFSBucketReadStreamOptions` — [src/gridfs/index.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/index.ts). Limits the lifetime of a download stream; if any async operation is in progress when the timeout expires, the stream throws a timeout error. +- `timeoutMS` in `GridFSBucketWriteStreamOptions` — [src/gridfs/upload.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/upload.ts). Limits the lifetime of an upload stream. --- @@ -347,39 +312,3 @@ await db.dropCollection('users', { }); ``` ---- - -### GridFS Timeout Support - -**Description**: Timeout support for GridFS read and write streams. - -#### GridFS Read Stream Timeout - -**Option**: `timeoutMS` in `GridFSBucketReadStreamOptions` -**Source**: [src/gridfs/index.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/index.ts) - -**Description**: Specifies the lifetime duration of a GridFS read stream. If any async operations are in progress when this timeout expires, the stream will throw a timeout error. - -**Example**: -```typescript -const bucket = new GridFSBucket(db); -const downloadStream = bucket.openDownloadStream(fileId, { - timeoutMS: 30000 // 30 second timeout for the entire download -}); -``` - -#### GridFS Write Stream Timeout - -**Option**: `timeoutMS` in `GridFSBucketWriteStreamOptions` -**Source**: [src/gridfs/upload.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/upload.ts) - -**Description**: Specifies the time an upload operation will run until it throws a timeout error. - -**Example**: -```typescript -const bucket = new GridFSBucket(db); -const uploadStream = bucket.openUploadStream('filename.txt', { - timeoutMS: 60000 // 60 second timeout for the entire upload -}); -``` - From 58ea0a7f0479c138ded965b7b9f3c2b434b80b50 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Wed, 27 May 2026 16:16:59 -0400 Subject: [PATCH 08/12] docs: apply minor changes from reviewer feedback --- EXPERIMENTAL_FEATURES.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index 0e2741e91a1..982e3f8fd14 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -27,7 +27,7 @@ This report documents all experimental features in the MongoDB Node.js Driver. T ### Explicit Resource Management > [!WARNING] -> Experimental until TC39 proposal completion +> Experimental until [TC39](https://github.com/tc39/proposal-explicit-resource-management) proposal completion **Description**: Native support for JavaScript's explicit resource management using `Symbol.asyncDispose`. This feature enables automatic cleanup of resources using the `await using` syntax. @@ -45,12 +45,6 @@ await using session = client.startSession(); // No need to call client.close() or session.endSession() ``` -**References**: -- [TC39 Explicit Resource Management Proposal](https://github.com/tc39/proposal-explicit-resource-management) -- Driver upgrade notes: `etc/notes/CHANGES_7.0.0.md` - -**Stability Note**: Will remain experimental until the TC39 proposal is finalized. - --- ### AbortSignal Support @@ -170,7 +164,7 @@ const update: StrictUpdateFilter = { ### Runtime Adapters -**Description**: Allows providing custom implementations of Node.js runtime modules to the driver. This enables the driver to work in non-Node.js JavaScript environments or with alternative module implementations. +**Description**: Allows providing custom implementations of Node.js runtime modules to the driver. This is useful both for customizing how the driver uses standard modules within a Node.js runtime (for example, supplying a custom DNS resolver) and for running the driver in non-Node.js JavaScript environments. **Types**: @@ -204,7 +198,7 @@ const client = new MongoClient(url, { --- -### Client-Side Encryption Features +### Client-Side Encryption Key Management **Description**: Advanced client-side encryption capabilities for enhanced data security. From bf0ba14a4b9d0e0da0ebdd0463ef46daefecd435 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Wed, 27 May 2026 16:32:42 -0400 Subject: [PATCH 09/12] docs: clarify usage and risks of experimental features in README --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 785cb4c22a1..21f440d7041 100644 --- a/README.md +++ b/README.md @@ -353,7 +353,9 @@ The nightly build is not suitable for production use. ## Experimental Features -The MongoDB Node.js driver offers cutting-edge experimental features that give you early access to new capabilities and APIs. These features are marked with `@experimental` tags and are great for exploring new functionality and providing feedback. They may evolve in future releases. +The MongoDB Node.js driver offers cutting-edge experimental features that give you early access to new capabilities and APIs. These features are marked with `@experimental` tags and are great for exploring new functionality and providing [feedback](#support--feedback). + +Experimental features are not subject to [semantic versioning](https://semver.org/) rules, so breaking changes or removal may occur in any future release. The use of these features is not recommended for production environments. Explore the full list of experimental features, complete with descriptions and usage examples, in [EXPERIMENTAL_FEATURES.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/EXPERIMENTAL_FEATURES.md). From e433e10cd826ad73c6e00e416cc791ee8332dd01 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Wed, 27 May 2026 16:34:40 -0400 Subject: [PATCH 10/12] docs: fix anchor links --- EXPERIMENTAL_FEATURES.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index 982e3f8fd14..0d0eb6a5bb1 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -1,6 +1,6 @@ # MongoDB Node.js Driver - Experimental Features -This report documents all experimental features in the MongoDB Node.js Driver. The driver contains **34 experimental annotations** across 10 major feature categories. +This report documents all experimental features in the MongoDB Node.js Driver. The driver contains **34 experimental annotations** across 8 major feature categories. > [!WARNING] > Experimental features may change in any release, including patches and minors, and are not covered by the driver's semver guarantees. Updates can change runtime behavior or break TypeScript compilation, and may require source changes before you can upgrade. @@ -16,7 +16,7 @@ This report documents all experimental features in the MongoDB Node.js Driver. T | [AbortSignal Support](#abortsignal-support) | Cancel operations using `AbortController` | v6.13.0 | | [Explicit Resource Management](#explicit-resource-management) | Automatic cleanup using `Symbol.asyncDispose` | v6.9.0 | | [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | -| [Client-Side Encryption Features](#client-side-encryption-features) | Custom key material and rewrap APIs | v6.0.0 | +| [Client-Side Encryption Key Management](#client-side-encryption-key-management) | Custom key material and rewrap APIs | v6.0.0 | | [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | | [Encrypted Fields](#encrypted-fields) | Schema for encrypted collections | v4.6.0 | @@ -200,7 +200,7 @@ const client = new MongoClient(url, { ### Client-Side Encryption Key Management -**Description**: Advanced client-side encryption capabilities for enhanced data security. +**Description**: Experimental APIs for creating and rewrapping CSFLE data keys. #### Custom Key Material From 24f952fd0fd8afa073a04fefab28d0ce8b7f3c83 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Thu, 28 May 2026 18:25:35 -0400 Subject: [PATCH 11/12] docs: update links to point to main --- EXPERIMENTAL_FEATURES.md | 48 ++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index 0d0eb6a5bb1..49dcb8f2ba7 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -32,10 +32,10 @@ This report documents all experimental features in the MongoDB Node.js Driver. T **Description**: Native support for JavaScript's explicit resource management using `Symbol.asyncDispose`. This feature enables automatic cleanup of resources using the `await using` syntax. **Available On**: -- `MongoClient` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_client.ts) -- `ClientSession` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/sessions.ts) -- `ChangeStream` - [src/change_stream.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/change_stream.ts) -- All cursor types (`AbstractCursor`, `FindCursor`, `AggregationCursor`, etc.) - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) +- `MongoClient` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_client.ts) +- `ClientSession` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/sessions.ts) +- `ChangeStream` - [src/change_stream.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/change_stream.ts) +- All cursor types (`AbstractCursor`, `FindCursor`, `AggregationCursor`, etc.) - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/cursor/abstract_cursor.ts) **Example**: ```typescript @@ -50,7 +50,7 @@ await using session = client.startSession(); ### AbortSignal Support **Type**: `Abortable` -**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) **Description**: Allows using `AbortController` to abort asynchronous operations. The `signal.reason` value is used as the error thrown. @@ -87,10 +87,10 @@ See [Limit Server Execution Time (CSOT) — MongoDB Node.js Driver Docs](https:/ **Type**: `CursorTimeoutMode` **Source**: -- Constant definition - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) -- Type definition - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) -- Option in `AbstractCursorOptions` - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/abstract_cursor.ts) -- Option in `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/cursor/run_command_cursor.ts) +- Constant definition - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/cursor/abstract_cursor.ts) +- Type definition - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/cursor/abstract_cursor.ts) +- Option in `AbstractCursorOptions` - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/cursor/abstract_cursor.ts) +- Option in `RunCursorCommandOptions` - [src/cursor/run_command_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/cursor/run_command_cursor.ts) **Values**: - `'cursorLifetime'` - Timeout applies to the entire cursor lifetime @@ -108,8 +108,8 @@ See [Limit Server Execution Time (CSOT) — MongoDB Node.js Driver Docs](https:/ > Applies the CSOT `timeoutMS` above to GridFS upload and download streams as a per-stream lifetime. **Options**: -- `timeoutMS` in `GridFSBucketReadStreamOptions` — [src/gridfs/index.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/index.ts). Limits the lifetime of a download stream; if any async operation is in progress when the timeout expires, the stream throws a timeout error. -- `timeoutMS` in `GridFSBucketWriteStreamOptions` — [src/gridfs/upload.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/gridfs/upload.ts). Limits the lifetime of an upload stream. +- `timeoutMS` in `GridFSBucketReadStreamOptions` — [src/gridfs/download.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/gridfs/download.ts). Limits the lifetime of a download stream; if any async operation is in progress when the timeout expires, the stream throws a timeout error. +- `timeoutMS` in `GridFSBucketWriteStreamOptions` — [src/gridfs/upload.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/gridfs/upload.ts). Limits the lifetime of an upload stream. --- @@ -120,17 +120,17 @@ See [Limit Server Execution Time (CSOT) — MongoDB Node.js Driver Docs](https:/ **Types**: #### `StrictFilter` -**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) Provides strict type checking for filter predicates with proper nested path support. #### `StrictMatchKeysAndValues` -**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) Ensures type-safe matching of keys and values in update operations. #### `StrictUpdateFilter` -**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) Provides strict typing for update operators (`$set`, `$inc`, `$push`, etc.). @@ -169,17 +169,17 @@ const update: StrictUpdateFilter = { **Types**: #### `RuntimeAdapters` -**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/runtime_adapters.ts) +**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/runtime_adapters.ts) Interface for providing custom runtime module implementations. #### `OsAdapter` -**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/runtime_adapters.ts) +**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/runtime_adapters.ts) Represents the required functionality from the Node.js `os` module. **Available On**: -- `MongoClientOptions.runtimeAdapters` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_client.ts) +- `MongoClientOptions.runtimeAdapters` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_client.ts) **Example**: ```typescript @@ -207,7 +207,7 @@ const client = new MongoClient(url, { **Option**: `keyMaterial` **Type**: `Buffer | Binary` **Location**: `ClientEncryptionCreateDataKeyProviderOptions` -**Source**: [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) +**Source**: [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) **Description**: Allows providing custom key material when creating data keys, giving more control over the encryption key generation process. @@ -226,8 +226,8 @@ const dataKeyId = await encryption.createDataKey('local', { #### RewrapManyDataKey API **Interfaces**: -- `ClientEncryptionRewrapManyDataKeyProviderOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) -- `ClientEncryptionRewrapManyDataKeyResult` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) +- `ClientEncryptionRewrapManyDataKeyProviderOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) +- `ClientEncryptionRewrapManyDataKeyResult` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) **Description**: Experimental API for rewrapping multiple data keys in a single operation, useful for key rotation scenarios. @@ -256,8 +256,8 @@ interface ClientEncryptionRewrapManyDataKeyResult { **Type**: `TextQueryOptions` **Location**: `ClientEncryptionEncryptOptions` **Source**: -- Option in `ClientEncryptionEncryptOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) -- Interface `TextQueryOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/client-side-encryption/client_encryption.ts) +- Option in `ClientEncryptionEncryptOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) +- Interface `TextQueryOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) **Description**: Options for Queryable Encryption fields supporting text queries. Only valid when the encryption algorithm is set to `TextPreview`. @@ -280,8 +280,8 @@ const encrypted = await encryption.encrypt(value, { **Type**: `Document` **Available On**: -- `CreateCollectionOptions` - [src/operations/create_collection.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/operations/create_collection.ts) -- `DropCollectionOptions` - [src/operations/drop.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/operations/drop.ts) +- `CreateCollectionOptions` - [src/operations/create_collection.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/operations/create_collection.ts) +- `DropCollectionOptions` - [src/operations/drop.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/operations/drop.ts) **Description**: Specifies the schema for encrypted fields in a collection, used with Queryable Encryption. From 09bdb33ef8e76800d416ad2d881edaa8ccaa1541 Mon Sep 17 00:00:00 2001 From: Raschid Jimenez Date: Thu, 28 May 2026 18:33:25 -0400 Subject: [PATCH 12/12] docs: reorder sections to match summary table --- EXPERIMENTAL_FEATURES.md | 231 +++++++++++++++++++-------------------- 1 file changed, 114 insertions(+), 117 deletions(-) diff --git a/EXPERIMENTAL_FEATURES.md b/EXPERIMENTAL_FEATURES.md index 49dcb8f2ba7..f3503b3249a 100644 --- a/EXPERIMENTAL_FEATURES.md +++ b/EXPERIMENTAL_FEATURES.md @@ -24,25 +24,65 @@ This report documents all experimental features in the MongoDB Node.js Driver. T ## Feature Descriptions -### Explicit Resource Management +### Runtime Adapters -> [!WARNING] -> Experimental until [TC39](https://github.com/tc39/proposal-explicit-resource-management) proposal completion +**Description**: Allows providing custom implementations of Node.js runtime modules to the driver. This is useful both for customizing how the driver uses standard modules within a Node.js runtime (for example, supplying a custom DNS resolver) and for running the driver in non-Node.js JavaScript environments. -**Description**: Native support for JavaScript's explicit resource management using `Symbol.asyncDispose`. This feature enables automatic cleanup of resources using the `await using` syntax. +**Types**: + +#### `RuntimeAdapters` +**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/runtime_adapters.ts) + +Interface for providing custom runtime module implementations. + +#### `OsAdapter` +**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/runtime_adapters.ts) + +Represents the required functionality from the Node.js `os` module. **Available On**: -- `MongoClient` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_client.ts) -- `ClientSession` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/sessions.ts) -- `ChangeStream` - [src/change_stream.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/change_stream.ts) -- All cursor types (`AbstractCursor`, `FindCursor`, `AggregationCursor`, etc.) - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/cursor/abstract_cursor.ts) +- `MongoClientOptions.runtimeAdapters` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_client.ts) **Example**: ```typescript -// Automatic cleanup when scope exits -await using client = new MongoClient(url); -await using session = client.startSession(); -// No need to call client.close() or session.endSession() +// Provide custom OS module implementation +const client = new MongoClient(url, { + runtimeAdapters: { + os: { + release: () => 'custom-release', + platform: () => 'linux', + arch: () => 'x64', + type: () => 'Linux' + } + } +}); +``` + +--- + +### Queryable Encryption Text Search + +> [!NOTE] +> This feature is a Public Technical Preview + +**Option**: `textOptions` +**Type**: `TextQueryOptions` +**Location**: `ClientEncryptionEncryptOptions` +**Source**: +- Option in `ClientEncryptionEncryptOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) +- Interface `TextQueryOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) + +**Description**: Options for Queryable Encryption fields supporting text queries. Only valid when the encryption algorithm is set to `TextPreview`. + +**Example**: +```typescript +const encrypted = await encryption.encrypt(value, { + algorithm: 'TextPreview', + keyId: dataKeyId, + textOptions: { + // Text search configuration options + } +}); ``` --- @@ -72,6 +112,29 @@ await collection.find({}, { signal }).toArray(); --- +### Explicit Resource Management + +> [!WARNING] +> Experimental until [TC39](https://github.com/tc39/proposal-explicit-resource-management) proposal completion + +**Description**: Native support for JavaScript's explicit resource management using `Symbol.asyncDispose`. This feature enables automatic cleanup of resources using the `await using` syntax. + +**Available On**: +- `MongoClient` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_client.ts) +- `ClientSession` - [src/sessions.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/sessions.ts) +- `ChangeStream` - [src/change_stream.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/change_stream.ts) +- All cursor types (`AbstractCursor`, `FindCursor`, `AggregationCursor`, etc.) - [src/cursor/abstract_cursor.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/cursor/abstract_cursor.ts) + +**Example**: +```typescript +// Automatic cleanup when scope exits +await using client = new MongoClient(url); +await using session = client.startSession(); +// No need to call client.close() or session.endSession() +``` + +--- + ### Timeout Management **Option**: `timeoutMS` @@ -96,8 +159,6 @@ See [Limit Server Execution Time (CSOT) — MongoDB Node.js Driver Docs](https:/ - `'cursorLifetime'` - Timeout applies to the entire cursor lifetime - `'iteration'` - Timeout applies to each `cursor.next()` call -**Description**: Specifies how `timeoutMS` is applied to cursors. - **Default Behavior**: - **Non-tailable cursors**: `'cursorLifetime'` - **Tailable cursors**: `'iteration'` (since tailable cursors can have arbitrarily long lifetimes) @@ -113,91 +174,6 @@ See [Limit Server Execution Time (CSOT) — MongoDB Node.js Driver Docs](https:/ --- -### Strict TypeScript Types - -**Description**: Provides stricter type checking for MongoDB operations with better TypeScript inference for nested paths and type safety. - -**Types**: - -#### `StrictFilter` -**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) - -Provides strict type checking for filter predicates with proper nested path support. - -#### `StrictMatchKeysAndValues` -**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) - -Ensures type-safe matching of keys and values in update operations. - -#### `StrictUpdateFilter` -**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) - -Provides strict typing for update operators (`$set`, `$inc`, `$push`, etc.). - -**Example**: -```typescript -interface User { - name: string; - age: number; - address: { - city: string; - zip: number; - }; -} - -const collection: Collection = db.collection('users'); - -// Type-safe filter with nested paths -const filter: StrictFilter = { - 'address.city': 'New York' // ✓ Valid - // 'address.city': 123 // ✗ Compile error: number not assignable to string -}; - -// Type-safe update -const update: StrictUpdateFilter = { - $set: { age: 30 }, // ✓ Valid - // $set: { age: 'thirty' } // ✗ Compile error -}; -``` - ---- - -### Runtime Adapters - -**Description**: Allows providing custom implementations of Node.js runtime modules to the driver. This is useful both for customizing how the driver uses standard modules within a Node.js runtime (for example, supplying a custom DNS resolver) and for running the driver in non-Node.js JavaScript environments. - -**Types**: - -#### `RuntimeAdapters` -**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/runtime_adapters.ts) - -Interface for providing custom runtime module implementations. - -#### `OsAdapter` -**Source**: [src/runtime_adapters.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/runtime_adapters.ts) - -Represents the required functionality from the Node.js `os` module. - -**Available On**: -- `MongoClientOptions.runtimeAdapters` - [src/mongo_client.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_client.ts) - -**Example**: -```typescript -// Provide custom OS module implementation -const client = new MongoClient(url, { - runtimeAdapters: { - os: { - release: () => 'custom-release', - platform: () => 'linux', - arch: () => 'x64', - type: () => 'Linux' - } - } -}); -``` - ---- - ### Client-Side Encryption Key Management **Description**: Experimental APIs for creating and rewrapping CSFLE data keys. @@ -247,29 +223,51 @@ interface ClientEncryptionRewrapManyDataKeyResult { --- -### Queryable Encryption Text Search +### Strict TypeScript Types -> [!NOTE] -> This feature is a Public Technical Preview +**Description**: Provides stricter type checking for MongoDB operations with better TypeScript inference for nested paths and type safety. -**Option**: `textOptions` -**Type**: `TextQueryOptions` -**Location**: `ClientEncryptionEncryptOptions` -**Source**: -- Option in `ClientEncryptionEncryptOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) -- Interface `TextQueryOptions` - [src/client-side-encryption/client_encryption.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/client-side-encryption/client_encryption.ts) +**Types**: -**Description**: Options for Queryable Encryption fields supporting text queries. Only valid when the encryption algorithm is set to `TextPreview`. +#### `StrictFilter` +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) + +Provides strict type checking for filter predicates with proper nested path support. + +#### `StrictMatchKeysAndValues` +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) + +Ensures type-safe matching of keys and values in update operations. + +#### `StrictUpdateFilter` +**Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/main/src/mongo_types.ts) + +Provides strict typing for update operators (`$set`, `$inc`, `$push`, etc.). **Example**: ```typescript -const encrypted = await encryption.encrypt(value, { - algorithm: 'TextPreview', - keyId: dataKeyId, - textOptions: { - // Text search configuration options - } -}); +interface User { + name: string; + age: number; + address: { + city: string; + zip: number; + }; +} + +const collection: Collection = db.collection('users'); + +// Type-safe filter with nested paths +const filter: StrictFilter = { + 'address.city': 'New York' // ✓ Valid + // 'address.city': 123 // ✗ Compile error: number not assignable to string +}; + +// Type-safe update +const update: StrictUpdateFilter = { + $set: { age: 30 }, // ✓ Valid + // $set: { age: 'thirty' } // ✗ Compile error +}; ``` --- @@ -305,4 +303,3 @@ await db.dropCollection('users', { encryptedFields: encryptedFieldsConfig }); ``` -