Class FindCursor<T, TRaw>`Abstract`

Lazily iterates over the results of some generic find operation using a Data API.

Shouldn't be directly instantiated, but rather created via Collection.find.

Typed as FindCursor<T, TRaw> where T is the type of the mapped records and TRaw is the type of the raw records before any mapping. If no mapping function is provided, T and TRaw will be the same type. Mapping is done using the FindCursor.map method.

Options may be set either through the find({}, options) method, or through the various fluent option-setting methods, which, unlike Mongo, do not mutate the existing cursor, but rather return a new, uninitialized cursor with the new option(s) set. This means that option methods may be called even after the cursor is started.

Example

interface Person {
  firstName: string,
  lastName: string,
  age: number,
}

const collection = db.collection<Person>('people');
const cursor1: Cursor<Person> = collection.find().filter({ firstName: 'John' });

// Lazily iterate all documents matching the filter
for await (const doc of cursor1) {
  console.log(doc);
}

// Rewind the cursor to be able to iterate again
cursor1.rewind();

// Get all documents matching the filter as an array
const docs = await cursor1.toArray();

// Immutably set options & map as needed (changing options returns a new, uninitialized cursor)
const cursor2: Cursor<string> = cursor
  .project<Omit<Person, 'age'>>({ age: 0 })
  .map(doc => doc.firstName + ' ' + doc.lastName);

// Get next document from cursor
const doc = await cursor2.next();

Type Parameters

T
TRaw extends SomeDoc = SomeDoc

Hierarchy (view full)

FindCursor
- CollectionFindCursor
- TableFindCursor

Index

Constructors

constructor

new FindCursor<T, TRaw>(parent, serdes, filter, options?, mapping?): FindCursor<T, TRaw>
Internal
Should not be instantiated directly.
Type Parameters
- T
- TRaw extends SomeDoc = SomeDoc
Parameters
- parent: Table<SomeRow, Partial<FoundRow<SomeRow>>, FoundRow<SomeRow>> | Collection<SomeDoc, FoundDoc<SomeDoc>>
- serdes: SerDes<any, any, any>
- filter: [Filter, boolean]
- Optional options: GenericFindOptions
- Optional mapping: ((doc) => T)
  - - (doc): T
    - Parameters
      doc: TRaw
      Returns T
Returns FindCursor<T, TRaw>
- Defined in src/documents/cursor.ts:153

Properties

`Private` #buffer

#buffer: TRaw[] = []

`Private` #consumed

#consumed: number = 0

`Private` `Readonly` #filter

#filter: [Filter, boolean]

`Private` `Optional` `Readonly` #mapping

#mapping?: ((doc) => T)

Type declaration

- (doc): T
- Parameters
  - doc: any
  Returns T

`Private` `Optional` #nextPageState

#nextPageState?: null | string

`Private` `Readonly` #options

#options: GenericFindOptions

`Private` `Readonly` #parent

#parent: Table<SomeRow, Partial<FoundRow<SomeRow>>, FoundRow<SomeRow>> | Collection<SomeDoc, FoundDoc<SomeDoc>>

`Private` `Readonly` #serdes

#serdes: SerDes<any, any, any>

`Private` `Optional` #sortVector

#sortVector?: null | DataAPIVector

`Private` #state

#state: FindCursorStatus = ...

Accessors

dataSource

get dataSource(): Table<SomeRow, Partial<FoundRow<SomeRow>>, FoundRow<SomeRow>> | Collection<SomeDoc, FoundDoc<SomeDoc>>
The table/collection which spawned this cursor.

Returns Table<SomeRow, Partial<FoundRow<SomeRow>>, FoundRow<SomeRow>> | Collection<SomeDoc, FoundDoc<SomeDoc>>
The table/collection which spawned this cursor.
- Defined in src/documents/cursor.ts:170

state

get state(): FindCursorStatus
Whether the cursor is closed, whether it be manually, or because the cursor is exhausted.

Returns FindCursorStatus
Whether or not the cursor is closed.
- Defined in src/documents/cursor.ts:179

Methods

`Private` #clone

#clone<R, RRaw>(filter, options, mapping?): FindCursor<R, RRaw>
Type Parameters
- R
- RRaw extends SomeDoc
Parameters
- filter: [Filter, boolean]
- options: GenericFindOptions
- Optional mapping: ((doc) => R)
  - - (doc): R
    - Parameters
      doc: RRaw
      Returns R
Returns FindCursor<R, RRaw>
- Defined in src/documents/cursor.ts:601

`Private` #getMore

#getMore(tm?): Promise<void>
Parameters
- Optional tm: TimeoutManager
Returns Promise<void>
- Defined in src/documents/cursor.ts:638

`Private` #next

#next(peek, tm?): Promise<nullish | TRaw>
Parameters
- peek: true
- Optional tm: TimeoutManager
Returns Promise<nullish | TRaw>
- Defined in src/documents/cursor.ts:605
#next(peek, tm?): Promise<T>
Parameters
- peek: false
- Optional tm: TimeoutManager
Returns Promise<T>
- Defined in src/documents/cursor.ts:606

[asyncIterator]

[asyncIterator](): AsyncGenerator<T, void, void>
An async iterator that lazily iterates over all records in the cursor.

Note that there'll only be partial results if the cursor has been previously iterated over. You may use FindCursor.rewind to reset the cursor.

If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return immediately.

It will close the cursor when iteration is complete, even if it was broken early.

Returns AsyncGenerator<T, void, void>
Example
```
for await (const doc of cursor) {
  console.log(doc);
}
```
- Defined in src/documents/cursor.ts:519

buffered

buffered(): number
Returns 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 (FindCursor.consumed + FindCursor.buffered).

Returns number
The number of raw records in the buffer.
- Defined in src/documents/cursor.ts:191

clone

clone(): FindCursor<TRaw, TRaw>
Returns a new, uninitialized cursor with the same filter and options set on this cursor. No state is shared between the two cursors; only the configuration.

Like mongo, mapping functions are not cloned.

Returns FindCursor<TRaw, TRaw>
A behavioral clone of this cursor.
- Defined in src/documents/cursor.ts:417

close

close(): void
Closes the cursor. The cursor will be unusable after this method is called, or until FindCursor.rewind is called.

Returns void
- Defined in src/documents/cursor.ts:596

consumeBuffer

consumeBuffer(max?): TRaw[]
Consumes up to max records from the buffer, or all records if max is not provided.

Note that this actually consumes the buffer; it doesn't just peek at it.
Parameters
- Optional max: number
  The maximum number of records to read from the buffer. If not provided, all records will be read.
Returns TRaw[]
The records read from the buffer.
- Defined in src/documents/cursor.ts:216

consumed

consumed(): number
Returns the number of records that have been read be 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 (FindCursor.consumed + FindCursor.buffered).

Returns number
The number of records that have been read be the user from the cursor.
- Defined in src/documents/cursor.ts:203

filter

filter(filter): FindCursor<T, TRaw>
Sets the filter for the cursor, overwriting any previous filter.

NB. This method does NOT mutate the cursor, and may be called even after the cursor is started; it simply returns a new, uninitialized cursor with the given new filter set.
Parameters
- filter: Filter
  A filter to select which records to return.
Returns FindCursor<T, TRaw>
A new cursor with the new filter set.
- Defined in src/documents/cursor.ts:230

forEach

forEach(consumer): Promise<void>
Iterates over all records in the cursor, calling the provided consumer for each record.

If the consumer returns false, iteration will stop.

Note that there'll only be partial results if the cursor has been previously iterated over. You may use FindCursor.rewind to reset the cursor.

If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return immediately.

It will close the cursor when iteration is complete, even if it was stopped early.
Parameters
- consumer: ((doc) => boolean) | ((doc) => void)
  The consumer to call for each record.
Returns Promise<void>
A promise that resolves when iteration is complete.
- Defined in src/documents/cursor.ts:550

getSortVector

getSortVector(): Promise<null | DataAPIVector>
Retrieves the vector used to perform the vector search, if applicable.
- If includeSortVector is not true, this will unconditionally return null. No find request will be made.
- If sort: { $vector } was used, getSortVector() will simply regurgitate that same $vector.
- If sort: { $vectorize } was used, getSortVector() will return the $vector that was created from the text.
- If vector search is not used, getSortVector() will simply return null. A find request will still be made.
If includeSortVector is true, and this function is called before any other cursor operation (such as .next() or .toArray()), it'll make an API request to fetch the sort vector, filling the cursor's buffer in the process.

If the cursor has already been executed before this function has been called, no additional API request will be made to fetch the sort vector, as it has already been cached.

But to reiterate, if includeSortVector is false, and this function is called, no API request is made, and the cursor's buffer is not populated; it simply returns null.
Returns Promise<null | DataAPIVector>
The sort vector, or null if none was used (or if includeSortVector !== true).
- Defined in src/documents/cursor.ts:484

hasNext

hasNext(): Promise<boolean>
Tests if there is a next record in the cursor.

If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return false.

Returns Promise<boolean>
Whether or not there is a next record.
- Defined in src/documents/cursor.ts:450

includeSimilarity

includeSimilarity(includeSimilarity?): FindCursor<WithSim<TRaw>, WithSim<TRaw>>
Sets whether similarity scores should be included in the cursor's results.

NB. This method does NOT mutate the cursor, and may be called even after the cursor is started; it simply returns a new, uninitialized cursor with the given new similarity setting.
Parameters
- Optional includeSimilarity: boolean
  Whether similarity scores should be included.
Returns FindCursor<WithSim<TRaw>, WithSim<TRaw>>
A new cursor with the new similarity setting.
- Defined in src/documents/cursor.ts:353

includeSortVector

includeSortVector(includeSortVector?): FindCursor<T, TRaw>
Sets whether the sort vector should be fetched on the very first API call. Note that this is a requirement to use FindCursor.getSortVector—it'll unconditionally return null if this is not set to true.

NB. This method does NOT mutate the cursor, and may be called even after the cursor is started; it simply returns a new, uninitialized cursor with the given new setting.
Parameters
- includeSortVector: boolean = true
  Whether the sort vector should be fetched on the first API call
Returns FindCursor<T, TRaw>
A new cursor with the new sort vector inclusion setting.
- Defined in src/documents/cursor.ts:375

limit

limit(limit): FindCursor<T, TRaw>
Sets the maximum number of records to return.

If limit == 0, there will be no limit on the number of records returned.

NB. This method does NOT mutate the cursor, and may be called even after the cursor is started; it simply returns a new, uninitialized cursor with the given new limit set.
Parameters
- limit: number
  The limit for this cursor.
Returns FindCursor<T, TRaw>
A new cursor with the new limit set.
- Defined in src/documents/cursor.ts:267

map

map<R>(mapping): FindCursor<R, TRaw>
Map all records using the provided mapping function. Previous mapping functions will be composed with the new mapping function (new ∘ old).

NB. This method does NOT mutate the cursor, and may be called even after the cursor is started; it simply returns a new, uninitialized cursor with the given new mapping set.

You may NOT set a projection after a mapping is already provided, to prevent potential de-sync errors. If you really want to do so, you may use FindCursor.clone to create a new cursor with the same configuration, but without the mapping, and then set the projection.
Type Parameters
- R
Parameters
- mapping: ((doc) => R)
  The mapping function to apply to all records.
  - - (doc): R
    - Parameters
      doc: T
      Returns R
Returns FindCursor<R, TRaw>
A new cursor with the new mapping set.
- Defined in src/documents/cursor.ts:398

next(): Promise<null | T>
Fetches the next record from the cursor. Returns null if there are no more records to fetch.

If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return null.

Returns Promise<null | T>
The next record, or null if there are no more records.
- Defined in src/documents/cursor.ts:439

project

project<RRaw>(projection): FindCursor<RRaw, RRaw>
Sets the projection for the cursor, overwriting any previous projection.

NB. This method does NOT mutate the cursor, and may be called even after the cursor is started; it simply returns a new, uninitialized cursor with the given new projection set.

To properly type this method, you should provide a type argument to specify the shape of the projected records.

Note that you may NOT provide a projection after a mapping is already provided, to prevent potential de-sync errors. If you really want to do so, you may use FindCursor.clone to create a new cursor with the same configuration, but without the mapping, and then set the projection.
Type Parameters
- RRaw extends SomeDoc = Partial<TRaw>
Parameters
- projection: Projection
  Specifies which fields should be included/excluded in the returned records.
Returns FindCursor<RRaw, RRaw>
A new cursor with the new projection set.
Example
```
const cursor = table.find({ name: 'John' });

// T is `any` because the type is not specified
const rawProjected = cursor.project({ id: 0, name: 1 });

// T is { name: string }
const projected = cursor.project<{ name: string }>({ id: 0, name: 1 });

// You can also chain instead of using intermediate variables
const fluentlyProjected = table
  .find({ name: 'John' })
  .project<{ name: string }>({ id: 0, name: 1 });

// It's important to keep mapping in mind
const mapProjected = table
  .find({ name: 'John' })
  .map(doc => doc.name);
  .project<string>({ id: 0, name: 1 });
```
- Defined in src/documents/cursor.ts:332

rewind

rewind(): void
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 this cursor.

Returns void
- Defined in src/documents/cursor.ts:426

skip

skip(skip): FindCursor<T, TRaw>
Sets the number of records to skip before returning.

NB. This method does NOT mutate the cursor, and may be called even after the cursor is started; it simply returns a new, uninitialized cursor with the given new skip set.
Parameters
- skip: number
  The skip for the cursor query.
Returns FindCursor<T, TRaw>
A new cursor with the new skip set.
- Defined in src/documents/cursor.ts:285

sort

sort(sort): FindCursor<T, TRaw>
Sets the sort criteria for prioritizing records.

NB. This method does NOT mutate the cursor, and may be called even after the cursor is started; it simply returns a new, uninitialized cursor with the given new sort set.
Parameters
- sort: Sort
  The sort order to prioritize which records are returned.
Returns FindCursor<T, TRaw>
A new cursor with the new sort set.
- Defined in src/documents/cursor.ts:247

toArray

toArray(): Promise<T[]>
Returns an array of all matching records in the cursor. The user should ensure that there is enough memory to store all records in the cursor.

Note that there'll only be partial results if the cursor has been previously iterated over. You may use FindCursor.rewind to reset the cursor.

If the cursor is uninitialized, it will be initialized. If the cursor is closed, this method will return an empty array.

Returns Promise<T[]>
An array of all records in the cursor.
- Defined in src/documents/cursor.ts:573

Class FindCursor<T, TRaw>Abstract

Example

Type Parameters

Hierarchy (view full)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Parameters

Returns T

Returns FindCursor<T, TRaw>

Properties

Private #buffer

Private #consumed

Private Readonly #filter

Private Optional Readonly #mapping

Type declaration

Parameters

Returns T

Private Optional #nextPageState

Private Readonly #options

Private Readonly #parent

Private Readonly #serdes

Private Optional #sortVector

Private #state

Accessors

dataSource

Returns Table<SomeRow, Partial<FoundRow<SomeRow>>, FoundRow<SomeRow>> | Collection<SomeDoc, FoundDoc<SomeDoc>>

state

Returns FindCursorStatus

Methods

Private #clone

Type Parameters

Parameters

Parameters

Returns R

Returns FindCursor<R, RRaw>

Private #getMore

Parameters

Returns Promise<void>

Private #next

Parameters

Returns Promise<nullish | TRaw>

Parameters

Returns Promise<T>

[asyncIterator]

Returns AsyncGenerator<T, void, void>

Example

buffered

Returns number

clone

Returns FindCursor<TRaw, TRaw>

close

Returns void

consumeBuffer

Parameters

Returns TRaw[]

consumed

Returns number

filter

Parameters

Returns FindCursor<T, TRaw>

forEach

Parameters

Returns Promise<void>

getSortVector

Returns Promise<null | DataAPIVector>

hasNext

Returns Promise<boolean>

includeSimilarity

Parameters

Returns FindCursor<WithSim<TRaw>, WithSim<TRaw>>

includeSortVector

Parameters

Returns FindCursor<T, TRaw>

Class FindCursor<T, TRaw>`Abstract`

`Private` #buffer

`Private` #consumed

`Private` `Readonly` #filter

`Private` `Optional` `Readonly` #mapping

`Private` `Optional` #nextPageState

`Private` `Readonly` #options

`Private` `Readonly` #parent

`Private` `Readonly` #serdes

`Private` `Optional` #sortVector

`Private` #state

`Private` #clone

`Private` #getMore

`Private` #next