Node.js MongoDB Driver API

Source: lib/command_cursor.js

  1. "use strict";
  3. var inherits = require('util').inherits
  4.   , ReadPreference = require('./read_preference')
  5.   , MongoError = require('mongodb-core').MongoError
  6.   , Readable = require('stream').Readable || require('readable-stream').Readable
  7.   , Define = require('./metadata')
  8.   , CoreCursor = require('./cursor')
  9.   , CoreReadPreference = require('mongodb-core').ReadPreference;
  11. /**
  12.  * @fileOverview The **CommandCursor** class is an internal class that embodies a
  13.  * generalized cursor based on a MongoDB command allowing for iteration over the
  14.  * results returned. It supports one by one document iteration, conversion to an
  15.  * array or can be iterated as a Node 0.10.X or higher stream
  16.  *
  17.  * **CommandCursor Cannot directly be instantiated**
  18.  * @example
  19.  * var MongoClient = require('mongodb').MongoClient,
  20.  *   test = require('assert');
  21.  * // Connection url
  22.  * var url = 'mongodb://localhost:27017/test';
  23.  * // Connect using MongoClient
  24.  * MongoClient.connect(url, function(err, db) {
  25.  *   // Create a collection we want to drop later
  26.  *   var col = db.collection('listCollectionsExample1');
  27.  *   // Insert a bunch of documents
  28.  *   col.insert([{a:1, b:1}
  29.  *     , {a:2, b:2}, {a:3, b:3}
  30.  *     , {a:4, b:4}], {w:1}, function(err, result) {
  31.  *     test.equal(null, err);
  32.  *
  33.  *     // List the database collections available
  34.  *     db.listCollections().toArray(function(err, items) {
  35.  *       test.equal(null, err);
  36.  *       db.close();
  37.  *     });
  38.  *   });
  39.  * });
  40.  */
  42. /**
  43.  * Namespace provided by the browser.
  44.  * @external Readable
  45.  */
  47. /**
  48.  * Creates a new Command Cursor instance (INTERNAL TYPE, do not instantiate directly)
  49.  * @class CommandCursor
  50.  * @extends external:Readable
  51.  * @fires CommandCursor#data
  52.  * @fires CommandCursor#end
  53.  * @fires CommandCursor#close
  54.  * @fires CommandCursor#readable
  55.  * @return {CommandCursor} an CommandCursor instance.
  56.  */
  57. var CommandCursor = function(bson, ns, cmd, options, topology, topologyOptions) {
  58.   CoreCursor.apply(this, Array.prototype.slice.call(arguments, 0));
  59.   var state = CommandCursor.INIT;
  60.   var streamOptions = {};
  62.   // MaxTimeMS
  63.   var maxTimeMS = null;
  65.   // Get the promiseLibrary
  66.   var promiseLibrary = options.promiseLibrary;
  68.   // No promise library selected fall back
  69.   if(!promiseLibrary) {
  70.     promiseLibrary = typeof global.Promise == 'function' ?
  71.       global.Promise : require('es6-promise').Promise;
  72.   }
  74.   // Set up
  75.   Readable.call(this, {objectMode: true});
  77.   // Internal state
  78.   this.s = {
  79.     // MaxTimeMS
  80.       maxTimeMS: maxTimeMS
  81.     // State
  82.     , state: state
  83.     // Stream options
  84.     , streamOptions: streamOptions
  85.     // BSON
  86.     , bson: bson
  87.     // Namespace
  88.     , ns: ns
  89.     // Command
  90.     , cmd: cmd
  91.     // Options
  92.     , options: options
  93.     // Topology
  94.     , topology: topology
  95.     // Topology Options
  96.     , topologyOptions: topologyOptions
  97.     // Promise library
  98.     , promiseLibrary: promiseLibrary
  99.   }
  100. }
  102. /**
  103.  * CommandCursor stream data event, fired for each document in the cursor.
  104.  *
  105.  * @event CommandCursor#data
  106.  * @type {object}
  107.  */
  109. /**
  110.  * CommandCursor stream end event
  111.  *
  112.  * @event CommandCursor#end
  113.  * @type {null}
  114.  */
  116. /**
  117.  * CommandCursor stream close event
  118.  *
  119.  * @event CommandCursor#close
  120.  * @type {null}
  121.  */
  123. /**
  124.  * CommandCursor stream readable event
  125.  *
  126.  * @event CommandCursor#readable
  127.  * @type {null}
  128.  */
  130. // Inherit from Readable
  131. inherits(CommandCursor, Readable);
  133. // Set the methods to inherit from prototype
  134. var methodsToInherit = ['_next', 'next', 'hasNext', 'each', 'forEach', 'toArray'
  135.   , 'rewind', 'bufferedCount', 'readBufferedDocuments', 'close', 'isClosed', 'kill', 'setCursorBatchSize'
  136.   , '_find', '_getmore', '_killcursor', 'isDead', 'explain', 'isNotified', 'isKilled'];
  138. // Only inherit the types we need
  139. for(var i = 0; i < methodsToInherit.length; i++) {
  140.   CommandCursor.prototype[methodsToInherit[i]] = CoreCursor.prototype[methodsToInherit[i]];
  141. }
  143. var define = CommandCursor.define = new Define('CommandCursor', CommandCursor, true);
  145. /**
  146.  * Set the ReadPreference for the cursor.
  147.  * @method
  148.  * @param {(string|ReadPreference)} readPreference The new read preference for the cursor.
  149.  * @throws {MongoError}
  150.  * @return {Cursor}
  151.  */
  152. CommandCursor.prototype.setReadPreference = function(r) {
  153.   if(this.s.state == CommandCursor.CLOSED || this.isDead()) throw MongoError.create({message: "Cursor is closed", driver:true});
  154.   if(this.s.state != CommandCursor.INIT) throw MongoError.create({message: 'cannot change cursor readPreference after cursor has been accessed', driver:true});
  156.   if(r instanceof ReadPreference) {
  157.     this.s.options.readPreference = new CoreReadPreference(r.mode, r.tags, {maxStalenessSeconds: r.maxStalenessSeconds});
  158.   } else if(typeof r == 'string') {
  159.     this.s.options.readPreference = new CoreReadPreference(r);
  160.   } else if(r instanceof CoreReadPreference) {
  161.     this.s.options.readPreference = r;
  162.   }
  164.   return this;
  165. }
  167. define.classMethod('setReadPreference', {callback: false, promise:false, returns: [CommandCursor]});
  169. /**
  170.  * Set the batch size for the cursor.
  171.  * @method
  172.  * @param {number} value The batchSize for the cursor.
  173.  * @throws {MongoError}
  174.  * @return {CommandCursor}
  175.  */
  176. CommandCursor.prototype.batchSize = function(value) {
  177.   if(this.s.state == CommandCursor.CLOSED || this.isDead()) throw MongoError.create({message: "Cursor is closed", driver:true});
  178.   if(typeof value != 'number') throw MongoError.create({message: "batchSize requires an integer", driver:true});
  179.   if(this.s.cmd.cursor) this.s.cmd.cursor.batchSize = value;
  180.   this.setCursorBatchSize(value);
  181.   return this;
  182. }
  184. define.classMethod('batchSize', {callback: false, promise:false, returns: [CommandCursor]});
  186. /**
  187.  * Add a maxTimeMS stage to the aggregation pipeline
  188.  * @method
  189.  * @param {number} value The state maxTimeMS value.
  190.  * @return {CommandCursor}
  191.  */
  192. CommandCursor.prototype.maxTimeMS = function(value) {
  193.   if(this.s.topology.lastIsMaster().minWireVersion > 2) {
  194.     this.s.cmd.maxTimeMS = value;
  195.   }
  196.   return this;
  197. }
  199. define.classMethod('maxTimeMS', {callback: false, promise:false, returns: [CommandCursor]});
  201. CommandCursor.prototype.get = CommandCursor.prototype.toArray;
  203. define.classMethod('get', {callback: true, promise:false});
  205. // Inherited methods
  206. define.classMethod('toArray', {callback: true, promise:true});
  207. define.classMethod('each', {callback: true, promise:false});
  208. define.classMethod('forEach', {callback: true, promise:false});
  209. define.classMethod('next', {callback: true, promise:true});
  210. define.classMethod('hasNext', {callback: true, promise:true});
  211. define.classMethod('close', {callback: true, promise:true});
  212. define.classMethod('isClosed', {callback: false, promise:false, returns: [Boolean]});
  213. define.classMethod('rewind', {callback: false, promise:false});
  214. define.classMethod('bufferedCount', {callback: false, promise:false, returns: [Number]});
  215. define.classMethod('readBufferedDocuments', {callback: false, promise:false, returns: [Array]});
  217. /**
  218.  * Get the next available document from the cursor, returns null if no more documents are available.
  219.  * @function CommandCursor.prototype.next
  220.  * @param {CommandCursor~resultCallback} [callback] The result callback.
  221.  * @throws {MongoError}
  222.  * @return {Promise} returns Promise if no callback passed
  223.  */
  225. /**
  226.  * Check if there is any document still available in the cursor
  227.  * @function CommandCursor.prototype.hasNext
  228.  * @param {CommandCursor~resultCallback} [callback] The result callback.
  229.  * @throws {MongoError}
  230.  * @return {Promise} returns Promise if no callback passed
  231.  */
  233. /**
  234.  * The callback format for results
  235.  * @callback CommandCursor~toArrayResultCallback
  236.  * @param {MongoError} error An error instance representing the error during the execution.
  237.  * @param {object[]} documents All the documents the satisfy the cursor.
  238.  */
  240. /**
  241.  * Returns an array of documents. The caller is responsible for making sure that there
  242.  * is enough memory to store the results. Note that the array only contain partial
  243.  * results when this cursor had been previously accessed.
  244.  * @method CommandCursor.prototype.toArray
  245.  * @param {CommandCursor~toArrayResultCallback} [callback] The result callback.
  246.  * @throws {MongoError}
  247.  * @return {Promise} returns Promise if no callback passed
  248.  */
  250. /**
  251.  * The callback format for results
  252.  * @callback CommandCursor~resultCallback
  253.  * @param {MongoError} error An error instance representing the error during the execution.
  254.  * @param {(object|null)} result The result object if the command was executed successfully.
  255.  */
  257. /**
  258.  * Iterates over all the documents for this cursor. As with **{cursor.toArray}**,
  259.  * not all of the elements will be iterated if this cursor had been previously accessed.
  260.  * In that case, **{cursor.rewind}** can be used to reset the cursor. However, unlike
  261.  * **{cursor.toArray}**, the cursor will only hold a maximum of batch size elements
  262.  * at any given time if batch size is specified. Otherwise, the caller is responsible
  263.  * for making sure that the entire result can fit the memory.
  264.  * @method CommandCursor.prototype.each
  265.  * @param {CommandCursor~resultCallback} callback The result callback.
  266.  * @throws {MongoError}
  267.  * @return {null}
  268.  */
  270. /**
  271.  * Close the cursor, sending a KillCursor command and emitting close.
  272.  * @method CommandCursor.prototype.close
  273.  * @param {CommandCursor~resultCallback} [callback] The result callback.
  274.  * @return {Promise} returns Promise if no callback passed
  275.  */
  277. /**
  278.  * Is the cursor closed
  279.  * @method CommandCursor.prototype.isClosed
  280.  * @return {boolean}
  281.  */
  283. /**
  284.  * Clone the cursor
  285.  * @function CommandCursor.prototype.clone
  286.  * @return {CommandCursor}
  287.  */
  289. /**
  290.  * Resets the cursor
  291.  * @function CommandCursor.prototype.rewind
  292.  * @return {CommandCursor}
  293.  */
  295. /**
  296.  * The callback format for the forEach iterator method
  297.  * @callback CommandCursor~iteratorCallback
  298.  * @param {Object} doc An emitted document for the iterator
  299.  */
  301. /**
  302.  * The callback error format for the forEach iterator method
  303.  * @callback CommandCursor~endCallback
  304.  * @param {MongoError} error An error instance representing the error during the execution.
  305.  */
  307. /*
  308.  * Iterates over all the documents for this cursor using the iterator, callback pattern.
  309.  * @method CommandCursor.prototype.forEach
  310.  * @param {CommandCursor~iteratorCallback} iterator The iteration callback.
  311.  * @param {CommandCursor~endCallback} callback The end callback.
  312.  * @throws {MongoError}
  313.  * @return {null}
  314.  */
  316. CommandCursor.INIT = 0;
  317. CommandCursor.OPEN = 1;
  318. CommandCursor.CLOSED = 2;
  320. module.exports = CommandCursor;