Skip to content

docs(NODE-7953): document that cursors do not support overlapping *next() calls - #5118

Merged
johnmtll merged 3 commits into
mainfrom
NODE-7953
Nov 16, 2026
Merged

johnmtll merged 3 commits into
mainfrom
NODE-7953

Conversation

@tadjik1

@tadjik1 tadjik1 commented Nov 12, 2026

Copy link
Copy Markdown
Member

Description

Summary of Changes

Adds TSDoc to AbstractCursor and to hasNext(), next() and tryNext() stating that overlapping calls on the same cursor are not supported.

Double check the following

  • Lint is passing (npm run check:lint)
  • Self-review completed using the steps outlined here
  • PR title follows the correct format: type(NODE-xxxx)[!]: description
    • Example: feat(NODE-1234)!: rewriting everything in coffeescript
  • Changes are covered by tests
  • New TODOs have a related JIRA ticket

@tadjik1
tadjik1 marked this pull request as ready for review November 12, 2026 14:02
@tadjik1
tadjik1 requested a review from a team as a code owner November 12, 2026 14:02
Copilot AI balanced review requested due to automatic review settings November 12, 2026 14:02

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for this documentation-only clarification of unsupported overlapping cursor calls.

No open issues 🎉

What changed in this PR

This documentation-only PR clarifies that MongoDB driver cursors do not support overlapping hasNext(), next(), or tryNext() calls on the same cursor.

Changes:

  • Adds class-level guidance to wait for each call to settle, explaining potential consequences of overlapping calls.
  • Repeats the restriction in each method’s TSDoc without changing runtime behavior.
File Description
src/​cursor/​abstract_cursor.ts Documents unsupported overlapping cursor calls at the class and method levels.

Review effort: Balanced

@PavelSafronov PavelSafronov left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ChangeStream also has the same issue, should we update those docs as well?

Comment thread src/cursor/abstract_cursor.ts Resolved
Comment thread src/cursor/abstract_cursor.ts Resolved
@johnmtll johnmtll self-assigned this Nov 12, 2026
@johnmtll johnmtll added the Primary Review In Review with primary reviewer, not yet ready for team's eyes label Nov 12, 2026
@johnmtll

Copy link
Copy Markdown
Contributor

ChangeStream also has the same issue, should we update those docs as well?

Have we confirmed this? I don't see a ticket for it, but if confirming it is additive work, I think we should create a ticket for it and descope it from this.

johnmtll
johnmtll previously approved these changes Nov 12, 2026

@johnmtll johnmtll left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! All of my review comments live in threads stemming from Pavel's suggestions (of which I'm completely aligned, albeit with small tweak suggestions)

@johnmtll johnmtll added Team Review Needs review from team and removed Primary Review In Review with primary reviewer, not yet ready for team's eyes labels Nov 12, 2026
@tadjik1

tadjik1 commented Nov 13, 2026

Copy link
Copy Markdown
Member Author

I don't know about ChangeStream methods, most likely it shares the problem, but it also has it's own resume loop (with cached resume tokens), and nobody has confirmed the behaviour there. The initial report comes from collection.hasNext() (NODE-7908), that's why I scoped ticket into these 3 *next() methods. @PavelSafronov do you want me to fill additional ticket to investigate ChangeStream mechanics?

@PavelSafronov PavelSafronov left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, no blockers, approving.

@johnmtll
johnmtll merged commit 37e6a04 into main Nov 16, 2026
40 checks passed
@johnmtll
johnmtll deleted the NODE-7953 branch November 16, 2026 23:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Team Review Needs review from team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants