Skip to content

Commit 041a977

Browse files
RaschidJFRRaschidJFR
committed
docs(NODE-7396): document experimental features
1 parent e5a85d0 commit 041a977

1 file changed

Lines changed: 359 additions & 0 deletions

File tree

‎EXPERIMENTAL_FEATURES.md‎

Lines changed: 359 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,359 @@
1+
# MongoDB Node.js Driver - Experimental Featuress
2+
3+
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.
4+
5+
---
6+
7+
## Summary
8+
9+
| Feature | Description | Introduced in | Status |
10+
|---------|-------------|---------------|--------|
11+
| [Explicit Resource Management](#explicit-resource-management) | Automatic cleanup using `Symbol.asyncDispose` | v6.9.0 | ⚠️ Experimental |
12+
| [AbortSignal Support](#abortsignal-support) | Cancel operations using `AbortController` | v6.13.0 | ⚠️ Experimental |
13+
| [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | ⚠️ Experimental |
14+
| [Cursor Timeout Modes](#cursor-timeout-modes) | Configure how timeouts apply to cursors | v6.11.0 | ⚠️ Experimental |
15+
| [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | ⚠️ Experimental |
16+
| [Client-Side Encryption Features](#client-side-encryption-features) | Custom key material and rewrap APIs | v6.0.0 | ⚠️ Experimental |
17+
| [Queryable Encryption Text Search](#queryable-encryption-text-search) | Text search on encrypted fields | v6.19.0 | ⚠️ Public Technical Preview |
18+
| [Encrypted Fields](#encrypted-fields) | Schema for encrypted collections | v4.6.0 | ⚠️ Experimental |
19+
| [GridFS Timeout Support](#gridfs-timeout-support) | Timeout options for GridFS streams | v6.6.0 | ⚠️ Experimental |
20+
21+
---
22+
23+
## Feature Descriptions
24+
25+
### Explicit Resource Management
26+
27+
**Status**: ⚠️ Experimental (until TC39 proposal completion)
28+
29+
**Description**: Native support for JavaScript's explicit resource management using `Symbol.asyncDispose`. This feature enables automatic cleanup of resources using the `await using` syntax.
30+
31+
**Available On**:
32+
- `MongoClient` - [src/mongo_client.ts:466](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_client.ts#L466)
33+
- `ClientSession` - [src/sessions.ts:293](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L293)
34+
- `ChangeStream` - [src/change_stream.ts:576](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/change_stream.ts#L576)
35+
- 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)
36+
37+
**Example**:
38+
```typescript
39+
// Automatic cleanup when scope exits
40+
await using client = new MongoClient(url);
41+
await using session = client.startSession();
42+
// No need to call client.close() or session.endSession()
43+
```
44+
45+
**References**:
46+
- [TC39 Explicit Resource Management Proposal](https://github.com/tc39/proposal-explicit-resource-management)
47+
- Driver upgrade notes: `etc/notes/CHANGES_7.0.0.md`
48+
49+
**Stability Note**: Will remain experimental until the TC39 proposal is finalized.
50+
51+
---
52+
53+
### AbortSignal Support
54+
55+
**Status**: ⚠️ Experimental
56+
57+
**Type**: `Abortable`
58+
**Source**: [src/mongo_types.ts:488](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L488)
59+
60+
**Description**: Allows using `AbortController` to abort asynchronous operations. The `signal.reason` value is used as the error thrown.
61+
62+
**Example**:
63+
```typescript
64+
const controller = new AbortController();
65+
const { signal } = controller;
66+
67+
// Abort operation after 5 seconds
68+
setTimeout(() => controller.abort(new Error('Operation timeout')), 5000);
69+
70+
await collection.find({}, { signal }).toArray();
71+
```
72+
73+
**⚠️ Important Warning**:
74+
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.
75+
76+
---
77+
78+
### Timeout Management
79+
80+
**Status**: ⚠️ Experimental
81+
82+
**Option**: `timeoutMS`
83+
84+
**Description**: Specifies the time (in milliseconds) an operation will run until it throws a timeout error.
85+
86+
**Available On**:
87+
- `CommandOperationOptions` - [src/db.ts:97](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/db.ts#L97)
88+
- `ClientSessionOptions` - [src/sessions.ts:141](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L141)
89+
- `ClientSessionStartOptions.defaultTimeoutMS` - [src/sessions.ts:63](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/sessions.ts#L63)
90+
- `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)
91+
- `MongoClientOptions` - [src/mongo_client.ts:145](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_client.ts#L145)
92+
- `RunCommandOptions` - [src/operations/run_command.ts:19](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/run_command.ts#L19)
93+
- `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)
94+
- `CollectionOptions` - [src/collection.ts:123](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/collection.ts#L123)
95+
- `OperationOptions` - [src/operations/operation.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/operation.ts#L42)
96+
- `GridFSBucketReadStreamOptions` - [src/gridfs/index.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/index.ts#L42)
97+
- `GridFSBucketWriteStreamOptions` - [src/gridfs/upload.ts:36](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/upload.ts#L36)
98+
- Various database and collection operation options
99+
100+
**Example**:
101+
```typescript
102+
// Set timeout at client level
103+
const client = new MongoClient(url, { timeoutMS: 10000 });
104+
105+
// Set timeout at operation level
106+
await collection.find({}, { timeoutMS: 5000 }).toArray();
107+
108+
// Set timeout for session
109+
const session = client.startSession({ timeoutMS: 30000 });
110+
```
111+
112+
---
113+
114+
### Cursor Timeout Modes
115+
116+
**Status**: ⚠️ Experimental
117+
118+
**Type**: `CursorTimeoutMode`
119+
**Source**:
120+
- 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)
121+
- 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)
122+
- 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)
123+
- 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)
124+
125+
**Values**:
126+
- `'cursorLifetime'` - Timeout applies to the entire cursor lifetime
127+
- `'iteration'` - Timeout applies to each `cursor.next()` call
128+
129+
**Description**: Specifies how `timeoutMS` is applied to cursors.
130+
131+
**Default Behavior**:
132+
- **Non-tailable cursors**: `'cursorLifetime'`
133+
- **Tailable cursors**: `'iteration'` (since tailable cursors can have arbitrarily long lifetimes)
134+
135+
**Examples**:
136+
```typescript
137+
// Iteration mode: Each next() call must complete within 100ms
138+
const cursor1 = collection.find({}, {
139+
timeoutMS: 100,
140+
timeoutMode: 'iteration'
141+
});
142+
for await (const doc of cursor1) {
143+
// Process doc - each iteration has 100ms timeout
144+
}
145+
146+
// Cursor lifetime mode: Entire operation must complete within 1000ms
147+
const cursor2 = collection.find({}, {
148+
timeoutMS: 1000,
149+
timeoutMode: 'cursorLifetime'
150+
});
151+
const docs = await cursor2.toArray(); // Must complete in 1000ms total
152+
```
153+
154+
---
155+
156+
### Strict TypeScript Types
157+
158+
**Status**: ⚠️ Experimental
159+
160+
**Description**: Provides stricter type checking for MongoDB operations with better TypeScript inference for nested paths and type safety.
161+
162+
**Types**:
163+
164+
#### `StrictFilter<TSchema>`
165+
**Source**: [src/mongo_types.ts:622](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L622)
166+
167+
Provides strict type checking for filter predicates with proper nested path support.
168+
169+
#### `StrictMatchKeysAndValues<TSchema>`
170+
**Source**: [src/mongo_types.ts:664](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L664)
171+
172+
Ensures type-safe matching of keys and values in update operations.
173+
174+
#### `StrictUpdateFilter<TSchema>`
175+
**Source**: [src/mongo_types.ts:634](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/mongo_types.ts#L634)
176+
177+
Provides strict typing for update operators (`$set`, `$inc`, `$push`, etc.).
178+
179+
**Example**:
180+
```typescript
181+
interface User {
182+
name: string;
183+
age: number;
184+
address: {
185+
city: string;
186+
zip: number;
187+
};
188+
}
189+
190+
const collection: Collection<User> = db.collection('users');
191+
192+
// Type-safe filter with nested paths
193+
const filter: StrictFilter<User> = {
194+
'address.city': 'New York' // ✓ Valid
195+
// 'address.city': 123 // ✗ Compile error: number not assignable to string
196+
};
197+
198+
// Type-safe update
199+
const update: StrictUpdateFilter<User> = {
200+
$set: { age: 30 }, // ✓ Valid
201+
// $set: { age: 'thirty' } // ✗ Compile error
202+
};
203+
```
204+
205+
**⚠️ Production Warning**: As experimental features, these types can change at any time and are not recommended for production settings.
206+
207+
---
208+
209+
### Client-Side Encryption Features
210+
211+
**Status**: ⚠️ Experimental
212+
213+
**Description**: Advanced client-side encryption capabilities for enhanced data security.
214+
215+
#### Custom Key Material
216+
217+
**Option**: `keyMaterial`
218+
**Type**: `Buffer | Binary`
219+
**Location**: `ClientEncryptionCreateDataKeyProviderOptions`
220+
**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)
221+
222+
**Description**: Allows providing custom key material when creating data keys, giving more control over the encryption key generation process.
223+
224+
**Example**:
225+
```typescript
226+
const encryption = new ClientEncryption(client, {
227+
keyVaultNamespace: 'encryption.__keyVault',
228+
kmsProviders: { local: { key: localMasterKey } }
229+
});
230+
231+
const dataKeyId = await encryption.createDataKey('local', {
232+
keyMaterial: customKeyBuffer // Experimental option
233+
});
234+
```
235+
236+
#### RewrapManyDataKey API
237+
238+
**Interfaces**:
239+
- `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)
240+
- `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)
241+
242+
**Description**: Experimental API for rewrapping multiple data keys in a single operation, useful for key rotation scenarios.
243+
244+
**Interface Definition**:
245+
```typescript
246+
interface ClientEncryptionRewrapManyDataKeyProviderOptions {
247+
provider: ClientEncryptionDataKeyProvider;
248+
masterKey?: AWSEncryptionKeyOptions | AzureEncryptionKeyOptions |
249+
GCPEncryptionKeyOptions | KMIPEncryptionKeyOptions | undefined;
250+
}
251+
252+
interface ClientEncryptionRewrapManyDataKeyResult {
253+
/** The result of rewrapping data keys. If unset, no keys matched the filter. */
254+
bulkWriteResult?: BulkWriteResult;
255+
}
256+
```
257+
258+
---
259+
260+
### Queryable Encryption Text Search
261+
262+
**Status**: ⚠️ Public Technical Preview (may break at any time)
263+
264+
**Option**: `textOptions`
265+
**Type**: `TextQueryOptions`
266+
**Location**: `ClientEncryptionEncryptOptions`
267+
**Source**:
268+
- 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)
269+
- 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)
270+
271+
**Description**: Options for Queryable Encryption fields supporting text queries. Only valid when the encryption algorithm is set to `TextPreview`.
272+
273+
**Example**:
274+
```typescript
275+
const encrypted = await encryption.encrypt(value, {
276+
algorithm: 'TextPreview',
277+
keyId: dataKeyId,
278+
textOptions: {
279+
// Text search configuration options
280+
}
281+
});
282+
```
283+
284+
**⚠️ 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.
285+
286+
---
287+
288+
### Encrypted Fields
289+
290+
**Status**: ⚠️ Experimental
291+
292+
**Option**: `encryptedFields`
293+
**Type**: `Document`
294+
295+
**Available On**:
296+
- `CreateCollectionOptions` - [src/operations/create_collection.ts:98](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/create_collection.ts#L98)
297+
- `DropCollectionOptions` - [src/operations/drop.ts:15](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/operations/drop.ts#L15)
298+
299+
**Description**: Specifies the schema for encrypted fields in a collection, used with Queryable Encryption.
300+
301+
**Example**:
302+
```typescript
303+
// Create collection with encrypted fields
304+
await db.createCollection('users', {
305+
encryptedFields: {
306+
fields: [
307+
{
308+
path: 'ssn',
309+
bsonType: 'string',
310+
keyId: dataKeyId
311+
}
312+
]
313+
}
314+
});
315+
316+
// Drop collection with encrypted fields
317+
await db.dropCollection('users', {
318+
encryptedFields: encryptedFieldsConfig
319+
});
320+
```
321+
322+
---
323+
324+
### GridFS Timeout Support
325+
326+
**Status**: ⚠️ Experimental
327+
328+
**Description**: Timeout support for GridFS read and write streams.
329+
330+
#### GridFS Read Stream Timeout
331+
332+
**Option**: `timeoutMS` in `GridFSBucketReadStreamOptions`
333+
**Source**: [src/gridfs/index.ts:42](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/index.ts#L42)
334+
335+
**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.
336+
337+
**Example**:
338+
```typescript
339+
const bucket = new GridFSBucket(db);
340+
const downloadStream = bucket.openDownloadStream(fileId, {
341+
timeoutMS: 30000 // 30 second timeout for the entire download
342+
});
343+
```
344+
345+
#### GridFS Write Stream Timeout
346+
347+
**Option**: `timeoutMS` in `GridFSBucketWriteStreamOptions`
348+
**Source**: [src/gridfs/upload.ts:36](https://github.com/mongodb/node-mongodb-native/blob/v7.1.0/src/gridfs/upload.ts#L36)
349+
350+
**Description**: Specifies the time an upload operation will run until it throws a timeout error.
351+
352+
**Example**:
353+
```typescript
354+
const bucket = new GridFSBucket(db);
355+
const uploadStream = bucket.openUploadStream('filename.txt', {
356+
timeoutMS: 60000 // 60 second timeout for the entire upload
357+
});
358+
```
359+

0 commit comments

Comments
 (0)