feat(NODE-5019): add runCursorCommand API

[nbbeeken]

Description

What is changing?

• Adds a new Db API: await db.runCursorCommand(command, options)
• A new RunCommandCursor subclass of AbstractCursor
  • The subclass overrides methods that do not apply to this kind of cursor throwing errors
  • Adds getMore configurations as required by the spec
  • overrides getMore execution in order to pass through the configurations correctly

Is there new documentation needed for these changes?

At least API docs for the new command, possibly new docs site page.

What is the motivation for this change?

DRIVERS-2533: mongodb/specifications#1412

Release Highlight

runCursorCommand API

We have added the Db#runCursorCommand method which can be used to execute generic cursor commands. This API complements the generic Db#command method.

const cursor = db.runCursorCommand({ checkMetadataConsistency: 1 });
for await (const metadata of cursor) {
  console.log(metadata);
}

Double check the following

• Ran npm run check:lint script
• 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

[dariakp]

Partial feedback, need to circle back to finish review

[dariakp]

Reviewed & resolved the addressed comments

[baileympearson]

Should this test be on AbstractCursor instead of runCommandCursor, since the behavior comes from the abstract class? This test is not specific to our RunCommandCursor.

Why was it added now?

[nbbeeken]

The functionality is in the AbstractCursor but as an integration test I'm using the public API to reproduce the expected behavior. I was curious what the behavior of multiple iterators (or nested for-await loops) from one cursor is. Returning a document only once regardless of how many iterators there are is supported by nature of our dequeuing from a List. Since it is a data structure we have changed in the past it is possible that we could modify this behavior if, say, we used an offset into a List that is specific to each iterator.

[baileympearson]

Could this potentially be a method on the entities object?

[nbbeeken]

sounds good, moved to entities

[baileympearson]

Suggested change

	const changeStream = getChangeStream({ entities, operation });
	if (changeStream == null) {
	// iterateOnce is used for changes streams and regular cursors.
	// we have no other way to distinguish which scenario we are testing when we run an
	// iterateOnce operation, so we first try to get the changeStream and
	// if that fails, we know we need to get a cursor
	const cursor = entities.getEntity('cursor', operation.object);
	return cursor.tryNext();
	}
	const cursorlike = getChangeStream(..) ?? entities.getEntity('cursor');
	return cursorLike.tryNext();

[baileympearson]

same suggestion above

[nbbeeken]

Moved this to a helper on entities