docs(NODE-7396): document experimental features#4873
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for all experimental features in the MongoDB Node.js Driver v7.1.0. The documentation catalogues 31 experimental annotations across 9 major feature categories, providing developers with a single reference point for understanding which APIs may undergo breaking changes in future releases.
Changes:
- Added EXPERIMENTAL_FEATURES.md documenting all experimental features with descriptions, code examples, source file references, and stability notes
- Organized features into logical categories including resource management, timeouts, encryption, and strict TypeScript types
- Included practical usage examples and warnings about production readiness for each experimental feature
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
RaschidJFR
force-pushed
the
NODE-7396/experimental_feature_report
branch
from
041a977 to
e9ec56a
Compare
| ### Explicit Resource Management | ||
|
|
||
| **Status**: ⚠️ Experimental (until TC39 proposal completion) |
There was a problem hiding this comment.
The proposal is complete for Explicit Resource Management 🎉
There was a problem hiding this comment.
Copleted? I see the proposal is in Stage 3:
https://github.com/tc39/proposal-explicit-resource-management
There was a problem hiding this comment.
I'm not sure where on that page I see anything saying the current stage.
But it's listed here in finished proposals!
https://github.com/tc39/proposals/blob/main/finished-proposals.md
|
|
||
| ### Timeout Management | ||
|
|
||
| **Status**: ⚠️ Experimental |
There was a problem hiding this comment.
All statuses are experimental and things that are no longer experiment will be removed from this document right? so maybe this is redundant but I think a good replacement would be a **Path To Stable**: ... section
| #### `StrictMatchKeysAndValues<TSchema>` | ||
| **Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) |
There was a problem hiding this comment.
Is this important to elevate to its own section? it's unlikely users would interact with this type directly
| ### Client-Side Encryption Features | ||
|
|
||
| **Status**: ⚠️ Experimental | ||
|
|
||
| **Description**: Advanced client-side encryption capabilities for enhanced data security. |
There was a problem hiding this comment.
This makes it seem like all of CSFLE is experimental but its just the specific features listed below, maybe just lift up each feature to be a top-level section?
|
|
||
| --- | ||
|
|
||
| ## Feature Descriptions |
There was a problem hiding this comment.
IMO, these features should be ordered the same as the table above.
| | [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.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 | |
There was a problem hiding this comment.
Some of these features have been experimental for a while. It would be nice to explain what's happening with some of these "older" features: will we remove the experimental label? If so, when? And how do we pick which features will be experimental vs "core"?
|
|
||
| --- | ||
|
|
||
| ### AbortSignal Support |
There was a problem hiding this comment.
Mention the introduced-in version somewhere in this section.
tadjik1
requested review from
PavelSafronov and
nbbeeken
and removed request for
dariakp
Description
Closes NODE-7396
Summary of Changes
Adds EXPERIMENTAL_FEATURES.md documenting all 31 experimental annotations in the driver (v7.1.0). Includes descriptions, code examples, and source links for each experimental feature.
Notes for Reviewers
Need a hand reviewing the accuracy of the content added.
Release Highlight
Release notes highlight
Added EXPERIMENTAL_FEATURES.md providing comprehensive documentation of all experimental features in the driver, including usage examples and stability notes.
Double check the following
npm run check:lint)type(NODE-xxxx)[!]: descriptionfeat(NODE-1234)!: rewriting everything in coffeescriptChanges are covered by testsNew TODOs have a related JIRA ticket