From 81cd5cbfcc8eb52343342b39c9a47fc8732d0e61 Mon Sep 17 00:00:00 2001 From: Sergey Zelenov Date: Thu, 12 Nov 2026 15:00:22 +0100 Subject: [PATCH 1/2] docs(NODE-7953): document that cursors do not support overlapping *next() calls --- src/cursor/abstract_cursor.ts | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/src/cursor/abstract_cursor.ts b/src/cursor/abstract_cursor.ts index c4936b79c7..c327308b62 100644 --- a/src/cursor/abstract_cursor.ts +++ b/src/cursor/abstract_cursor.ts @@ -158,7 +158,16 @@ export type AbstractCursorEvents = { [AbstractCursor.CLOSE](): void; }; -/** @public */ +/** + * Base class for all cursors. + * + * A cursor does not support overlapping calls to `hasNext()`, `next()` or `tryNext()`. + * Wait for each call to settle before making the next one on the same cursor. Calls that overlap + * can each send their own command to the server, which can result in duplicate commands, server + * cursors that are never closed, or session errors. + * + * @public + */ export abstract class AbstractCursor< TSchema = any, CursorEvents extends AbstractCursorEvents = AbstractCursorEvents @@ -437,6 +446,12 @@ export abstract class AbstractCursor< return readable; } + /** + * Check if there is any document still available in the cursor. + * + * Do not call this method while a previous `hasNext()`, `next()` or `tryNext()` call on the same + * cursor is still pending. Overlapping calls are not supported. + */ async hasNext(): Promise { this.signal?.throwIfAborted(); @@ -463,7 +478,12 @@ export abstract class AbstractCursor< return false; } - /** Get the next available document from the cursor, returns null if no more documents are available. */ + /** + * Get the next available document from the cursor, returns null if no more documents are available. + * + * Do not call this method while a previous `hasNext()`, `next()` or `tryNext()` call on the same + * cursor is still pending. Overlapping calls are not supported. + */ async next(): Promise { this.signal?.throwIfAborted(); @@ -495,6 +515,9 @@ export abstract class AbstractCursor< /** * Try to get the next available document from the cursor or `null` if an empty batch is returned + * + * Do not call this method while a previous `hasNext()`, `next()` or `tryNext()` call on the same + * cursor is still pending. Overlapping calls are not supported. */ async tryNext(): Promise { this.signal?.throwIfAborted(); From 6ea797e064880db9945ad042ee171a2e5a1ce6ae Mon Sep 17 00:00:00 2001 From: Sergey Zelenov Date: Fri, 13 Nov 2026 10:43:46 +0100 Subject: [PATCH 2/2] change base class comment --- src/cursor/abstract_cursor.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/cursor/abstract_cursor.ts b/src/cursor/abstract_cursor.ts index c327308b62..347703cf6d 100644 --- a/src/cursor/abstract_cursor.ts +++ b/src/cursor/abstract_cursor.ts @@ -161,10 +161,10 @@ export type AbstractCursorEvents = { /** * Base class for all cursors. * - * A cursor does not support overlapping calls to `hasNext()`, `next()` or `tryNext()`. - * Wait for each call to settle before making the next one on the same cursor. Calls that overlap - * can each send their own command to the server, which can result in duplicate commands, server - * cursors that are never closed, or session errors. + * A cursor does not support overlapping calls to any method that reads from the cursor, such as + * `hasNext()`, `next()` or `tryNext()`. Wait for each call to settle before making the next one on + * the same cursor. Calls that overlap can result in undefined behaviour, which could produce + * unpredictable or incorrect results. * * @public */