mongodb

property CLOSE

static readonly CLOSE: string;

property closed

readonly closed: boolean;

• The cursor is closed and all remaining locally buffered documents have been iterated.

property id

readonly id: any;

• The cursor has no id until it receives a response from the initial cursor creating command.

  It is non-zero for as long as the database has an open cursor.

  The initiating command may receive a zero id if the entire result is in the firstBatch.

property killed

readonly killed: boolean;

• A killCursors command was attempted on this cursor. This is performed if the cursor id is non zero.

property loadBalanced

readonly loadBalanced: boolean;

property namespace

readonly namespace: MongoDBNamespace;

property readConcern

readonly readConcern: ReadConcern;

property readPreference

readonly readPreference: ReadPreference;

method [Symbol.asyncIterator]

[Symbol.asyncIterator]: () => AsyncGenerator<TSchema, void, void>;

method addCursorFlag

addCursorFlag: (flag: CursorFlag, value: boolean) => this;

• Add a cursor flag to the cursor

  Parameter flag

  The flag to set, must be one of following ['tailable', 'oplogReplay', 'noCursorTimeout', 'awaitData', 'partial' -.

  Parameter value

  The flag boolean value.

method batchSize

batchSize: (value: number) => this;

• Set the batch size for the cursor.

  Parameter value

  The number of documents to return per batch. See find command documentation.

method bufferedCount

bufferedCount: () => number;

• Returns current buffered documents length

method clone

abstract clone: () => AbstractCursor<TSchema>;

• Returns a new uninitialized copy of this cursor, with options matching those that have been set on the current instance

method close

close: () => Promise<void>;

• Frees any client-side resources used by the cursor.

method forEach

forEach: (iterator: (doc: TSchema) => boolean | void) => Promise<void>;

• Iterates over all the documents for this cursor using the iterator, callback pattern.

  If the iterator returns false, iteration will stop.

  Parameter iterator

  The iteration callback.

  Deprecated

  - Will be removed in a future release. Use for await...of instead.

method hasNext

hasNext: () => Promise<boolean>;

method map

map: <T = any>(transform: (doc: TSchema) => T) => AbstractCursor<T>;

• Map all documents using the provided function If there is a transform set on the cursor, that will be called first and the result passed to this function's transform.

  Parameter transform

  The mapping transformation method.

  Remarks

  **Note** Cursors use null internally to indicate that there are no more documents in the cursor. Providing a mapping function that maps values to null will result in the cursor closing itself before it has finished iterating all documents. This will **not** result in a memory leak, just surprising behavior. For example:

  const cursor = collection.find({});
  cursor.map(() => null);
  
  const documents = await cursor.toArray();
  // documents is always [], regardless of how many documents are in the collection.

  Other falsey values are allowed:

  const cursor = collection.find({});
  cursor.map(() => '');
  
  const documents = await cursor.toArray();
  // documents is now an array of empty strings

  **Note for Typescript Users:** adding a transform changes the return type of the iteration of this cursor, it **does not** return a new instance of a cursor. This means when calling map, you should always assign the result to a new variable in order to get a correctly typed cursor variable. Take note of the following example:

  Example 1

  const cursor: FindCursor<Document> = coll.find();
  const mappedCursor: FindCursor<number> = cursor.map(doc => Object.keys(doc).length);
  const keyCounts: number[] = await mappedCursor.toArray(); // cursor.toArray() still returns Document[]

method maxTimeMS

maxTimeMS: (value: number) => this;

• Set a maxTimeMS on the cursor query, allowing for hard timeout limits on queries (Only supported on MongoDB 2.6 or higher)

  Parameter value

  Number of milliseconds to wait before aborting the query.

method next

next: () => Promise<TSchema | null>;

• Get the next available document from the cursor, returns null if no more documents are available.

method readBufferedDocuments

readBufferedDocuments: (number?: number) => NonNullable<TSchema>[];

• Returns current buffered documents

method rewind

rewind: () => void;

• Rewind this cursor to its uninitialized state. Any options that are present on the cursor will remain in effect. Iterating this cursor will cause new queries to be sent to the server, even if the resultant data has already been retrieved by this cursor.

method stream

stream: (options?: CursorStreamOptions) => Readable & AsyncIterable<TSchema>;

method toArray

toArray: () => Promise<TSchema[]>;

• Returns an array of documents. The caller is responsible for making sure that there is enough memory to store the results. Note that the array only contains partial results when this cursor had been previously accessed. In that case, cursor.rewind() can be used to reset the cursor.

method tryNext

tryNext: () => Promise<TSchema | null>;

• Try to get the next available document from the cursor or null if an empty batch is returned

method withReadConcern

withReadConcern: (readConcern: ReadConcernLike) => this;

• Set the ReadPreference for the cursor.

  Parameter readPreference

  The new read preference for the cursor.

method withReadPreference

withReadPreference: (readPreference: ReadPreferenceLike) => this;

• Set the ReadPreference for the cursor.

  Parameter readPreference

  The new read preference for the cursor.

method buildInfo

buildInfo: (options?: CommandOperationOptions) => Promise<Document>;

• Retrieve the server build information

  Parameter options

  Optional settings for the command

method command

command: (command: Document, options?: RunCommandOptions) => Promise<Document>;

• Execute a command

  The driver will ensure the following fields are attached to the command sent to the server: - lsid - sourced from an implicit session or options.session - $readPreference - defaults to primary or can be configured by options.readPreference - $db - sourced from the name of this database

  If the client has a serverApi setting: - apiVersion - apiStrict - apiDeprecationErrors

  When in a transaction: - readConcern - sourced from readConcern set on the TransactionOptions - writeConcern - sourced from writeConcern set on the TransactionOptions

  Attaching any of the above fields to the command will have no effect as the driver will overwrite the value.

  Parameter command

  The command to execute

  Parameter options

  Optional settings for the command

method listDatabases

listDatabases: (options?: ListDatabasesOptions) => Promise<ListDatabasesResult>;

• List the available databases

  Parameter options

  Optional settings for the command

method ping

ping: (options?: CommandOperationOptions) => Promise<Document>;

• Ping the MongoDB server and retrieve results

  Parameter options

  Optional settings for the command

method removeUser

removeUser: (username: string, options?: RemoveUserOptions) => Promise<boolean>;

• Remove a user from a database

  Parameter username

  The username to remove

  Parameter options

  Optional settings for the command

method replSetGetStatus

replSetGetStatus: (options?: CommandOperationOptions) => Promise<Document>;

• Get ReplicaSet status

  Parameter options

  Optional settings for the command

method serverInfo

serverInfo: (options?: CommandOperationOptions) => Promise<Document>;

• Retrieve the server build information

  Parameter options

  Optional settings for the command

method serverStatus

serverStatus: (options?: CommandOperationOptions) => Promise<Document>;

• Retrieve this db's server status.

  Parameter options

  Optional settings for the command

method validateCollection

validateCollection: (
    collectionName: string,
    options?: ValidateCollectionOptions
) => Promise<Document>;

• Validate an existing collection

  Parameter collectionName

  The name of the collection to validate.

  Parameter options

  Optional settings for the command

property pipeline

readonly pipeline: Document[];

method addStage

addStage: {
    (stage: Document): this;
    <T = Document>(stage: Document): AggregationCursor<T>;
};

• Add a stage to the aggregation pipeline

  Example 1

  const documents = await users.aggregate().addStage({ $match: { name: /Mike/ } }).toArray();

  Example 2

  const documents = await users.aggregate()
    .addStage<{ name: string }>({ $project: { name: true } })
    .toArray(); // type of documents is { name: string }[]

method clone

clone: () => AggregationCursor<TSchema>;

method explain

explain: (verbosity?: ExplainVerbosityLike) => Promise<Document>;

• Execute the explain for the cursor

method geoNear

geoNear: ($geoNear: Document) => this;

• Add a geoNear stage to the aggregation pipeline

method group

group: <T = TSchema>($group: Document) => AggregationCursor<T>;

• Add a group stage to the aggregation pipeline

method limit

limit: ($limit: number) => this;

• Add a limit stage to the aggregation pipeline

method lookup

lookup: ($lookup: Document) => this;

• Add a lookup stage to the aggregation pipeline

method map

map: <T>(transform: (doc: TSchema) => T) => AggregationCursor<T>;

method match

match: ($match: Document) => this;

• Add a match stage to the aggregation pipeline

method out

out: ($out: { db: string; coll: string } | string) => this;

• Add an out stage to the aggregation pipeline

method project

project: <T extends Document = Document>(
    $project: Document
) => AggregationCursor<T>;

• Add a project stage to the aggregation pipeline

  Remarks

  In order to strictly type this function you must provide an interface that represents the effect of your projection on the result documents.

  **Note for Typescript Users:** adding a transform changes the return type of the iteration of this cursor, it **does not** return a new instance of a cursor. This means when calling project, you should always assign the result to a new variable in order to get a correctly typed cursor variable. Take note of the following example:

  Example 1

  // Best way
  const docs: AggregationCursor<{ a: number }> = cursor.project<{ a: number }>({ _id: 0, a: true });
  // Flexible way
  const docs: AggregationCursor<Document> = cursor.project({ _id: 0, a: true });

  Example 2

  const cursor: AggregationCursor<{ a: number; b: string }> = coll.aggregate([]);
  const projectCursor = cursor.project<{ a: number }>({ _id: 0, a: true });
  const aPropOnlyArray: {a: number}[] = await projectCursor.toArray();
  
  // or always use chaining and save the final cursor
  
  const cursor = coll.aggregate().project<{ a: string }>({
    _id: 0,
    a: { $convert: { input: '$a', to: 'string' }
  }});