Abstract Protected constructorInternal Should not be instantiated directly.
Optional mapping: ((doc) => T)Private Internal _consumedProtected Optional Internal _currentPrivate Internal _isOptional Readonly Internal _mappingProtected Internal _stateReadonly Internal _timeoutThis temporary error-ing property exists for migration convenience, and will be removed in a future version.
.bufferedCount() has been renamed to simply be .buffered().This temporary error-ing property exists for migration convenience, and will be removed in a future version.
.readBufferedDocuments() has been renamed to be .consumeBuffer().Gets the current status of the cursor.
See CursorState for more information on the possible states, and how they may be transitioned between each other.
const cursor = collection.find({});
console.log(cursor.state); // 'idle'
await cursor.next();
console.log(cursor.state); // 'started'
cursor.close();
console.log(cursor.state); // 'closed'
CursorState
An async iterator that lazily iterates over all records in the cursor.
⚠️Warning: There'll only be partial results if the cursor has been consumed prior. You may use AbstractCursor.rewind to reset the cursor.
breaks, iteration will stop earlyconst cursor = collection.find({ age: { $gt: 30 } });
// Iterate over all matching records
for await (const doc of cursor) {
console.log(doc);
if (doc.name === 'John') {
break; // Stop iteration early
}
}
// Cursor is now closed
console.log(cursor.state); // 'closed'
Protected Abstract _fetchPrivate _iteratorProtected Abstract _tmGets the number of raw records in the buffer.
Unless the cursor was closed before the buffer was completely read, the total number of records retrieved from the
server is equal to (consumed() + buffered()).
The number of raw records currently in the buffer.
const cursor = collection.find({});
console.log(cursor.buffered()); // 0
await cursor.next(); // Fetches a page of results
console.log(cursor.buffered()); // Number of records in buffer
AbstractCursor.consumed
Abstract cloneCreates a new cursor with the exact same configuration as the current cursor.
The new cursor will be in the 'idle' state, regardless of the state of the current cursor, and will start its own iteration from the beginning, sending new queries to the server, even if the resultant data was already fetched by the original cursor.
A new cursor with the same configuration as the current cursor.
const cursor = collection.find({ age: { $gt: 30 } }).sort({ name: 1 });
// Clone the cursor before use
const clone1 = cursor.clone();
const clone2 = cursor.clone();
// Each cursor operates independently
const firstResult = await clone1.toArray();
const firstTwoRecords = await clone2.next();
// Original cursor is still usable
for await (const doc of cursor) {
console.log(doc);
}
Cloning a cursor is different from rewinding it. Cloning creates an independent new cursor with the same configuration as the original, while rewinding resets the current cursor to its initial state.
See AbstractCursor.rewind for more information on rewinding.
AbstractCursor.rewind
Closes the cursor. The cursor will be unusable after this method is called, or until AbstractCursor.rewind is called.
const cursor = collection.find({});
// Use the cursor
const doc = await cursor.next();
// Close the cursor when done
cursor.close();
// Attempting to use a closed cursor
await cursor.next(); // Throws CursorError
AbstractCursor.rewind - To reset a closed cursor to make it usable again
Consumes up to max records from the buffer, or all records if max is not provided.
⚠️Warning: This actually consumes the buffer; it doesn't just peek at it.
🚨Important: The records returned from this method are not affected by
cursor.map().
Optional max: numberThe optional max number of records to read from the buffer.
The records read from the buffer.
const cursor = collection.find({});
await cursor.next(); // Populates the buffer
// Consume up to 5 records from the buffer
const records = cursor.consumeBuffer(5);
console.log(records.length); // Number of records consumed (up to 5)
// Consume all remaining records
const remaining = cursor.consumeBuffer();
Gets the number of records that have been read by the user from the cursor.
Unless the cursor was closed before the buffer was completely read, the total number of records retrieved from the
server is equal to (consumed() + buffered()).
The number of records that have been read from the cursor.
const cursor = collection.find({});
console.log(cursor.consumed()); // 0
await cursor.next();
console.log(cursor.consumed()); // 1
AbstractCursor.buffered
Iterates over all records in the cursor, calling the provided consumer for each record.
⚠️Warning: There'll only be partial results if the cursor has been consumed prior. You may use AbstractCursor.rewind to reset the cursor.
✏️Note: If you get an IDE error "Promise returned from forEach argument is ignored", you may simply ignore it. It is a known WebStorm bug.
false or Promise<false>, iteration will stop earlyThe consumer to call for each record. Return false to stop iteration.
A promise that resolves when iteration is complete.
const cursor = collection.find({ age: { $gt: 30 } });
// Process all records
await cursor.forEach((doc) => {
console.log(doc);
});
// Process records until a condition is met
await cursor.forEach(async (doc) => {
if (await isSpecial(doc)) {
return false;
}
});
Tests if there is a next record in the cursor.
falseWhether or not there is a next record.
const cursor = collection.find({ name: 'John' });
// Check if there are any records
if (await cursor.hasNext()) {
const john = await cursor.next();
console.log(john);
}
// Use in a loop
while (await cursor.hasNext()) {
const record = await cursor.next();
console.log(record);
}
Abstract mapMap all records using the provided mapping function. Previous mapping functions will be composed with the new mapping function (new ∘ old).
🚨Important: This method does NOT mutate the cursor; it returns a new cursor with the new mapping function applied.
⚠️Warning: You may NOT provide a projection after a mapping is already provided, to prevent potential type de-sync errors.
A new cursor with the new mapping set.
const cursor = table.find({ name: 'John' })
.map(row => row.name);
.map(name => name.toLowerCase());
// T is `string` because the mapping function returns a string
const name = await cursor.next();
name === 'john'; // true
Fetches the next record from the cursor. Returns null if there are no more records to fetch.
nullnull will be returnedThe next record, or null if there are no more records.
const cursor = collection.find({ name: 'John' });
// Get the first record
const john = await cursor.next();
// Get the next record (or null if no more records)
const nextRecord = await cursor.next();
// Exhaust the cursor
let doc;
while ((doc = await cursor.next()) !== null) {
console.log(doc);
}
Rewinds the cursor to its uninitialized state, clearing the buffer and any state.
Any configuration set on the cursor will remain, but iteration will start from the beginning, sending new queries to the server, even if the resultant data was already fetched by the cursor.
const cursor = collection.find({}).sort({ name: 1 });
// Read some data
const first = await cursor.next();
// Rewind the cursor
cursor.rewind();
// Start again from the beginning
const firstAgain = await cursor.next();
// first and firstAgain are the same record
Rewinding a cursor is different from cloning it. Cloning creates an independent new cursor with the same state and configuration as the original, while rewinding resets the current cursor to its initial state.
See AbstractCursor.clone for more information on cloning.
AbstractCursor.clone
Returns an array of all matching records in the cursor.
⚠️Warning: The user should ensure that there is enough memory to store all records in the cursor.
⚠️Warning: There'll only be partial results if the cursor has been consumed prior. You may use AbstractCursor.rewind to reset the cursor.
An array of all records in the cursor.
const cursor = collection.find({ department: 'Engineering' });
// Get all matching records as an array
const engineers = await cursor.toArray();
console.log(`Found ${engineers.length} engineers`);
// For a large result set, consider using lazy iteration instead
for await (const doc of cursor.rewind()) {
// Process one document at a time
}
Overview
Represents some lazy, abstract iterable cursor over any arbitrary data, which may or may not be paginated.
Typing
In full, the cursor is typed as
AbstractCursor<T, TRaw>, whereTis the type of the mapped records, andTRawis the type of the raw records before any mapping.If no mapping function is provided,
TandTRawwill be the same type. Mapping is done using the AbstractCursor.map method.TRawis currently only publicly exposed inconsumeBuffer().See