Query and Cursor Management

/**
 * Create cursor from collection find operation
 * @param {object} [query] - Query selector
 * @param {object} [options] - Query options
 * @returns {SkinCursor} Cursor instance
 */
collection.find(query, options); // Returns cursor when no callback provided

/**
 * Convert cursor to array of documents
 * @param {function} callback - Callback function (err, docs)
 * @returns {void}
 */
toArray(callback);

/**
 * Iterate through cursor documents one by one
 * @param {function} callback - Callback function (err, doc)
 * @returns {void}
 */
each(callback);

/**
 * Get next document from cursor
 * @param {function} callback - Callback function (err, doc)
 * @returns {void}
 */
next(callback);

/**
 * Get count of documents matching cursor query
 * @param {boolean} [applySkipLimit] - Whether to apply skip/limit
 * @param {function} callback - Callback function (err, count)
 * @returns {void}
 */
count(applySkipLimit, callback);

const mongoskin = require('mongoskin');
const db = mongoskin.db('mongodb://localhost:27017/myapp');
const users = db.collection('users');

// Get all results as array
const cursor = users.find({ active: true });
cursor.toArray((err, docs) => {
  if (err) throw err;
  console.log('Found', docs.length, 'active users');
  docs.forEach(user => console.log(user.name));
});

// Iterate through results one by one
users.find({ role: 'admin' }).each((err, admin) => {
  if (err) throw err;
  if (admin) {
    console.log('Admin user:', admin.name);
  } else {
    console.log('No more admin users');
  }
});

// Get next document
const adminCursor = users.find({ role: 'admin' });
adminCursor.next((err, admin) => {
  if (err) throw err;
  if (admin) {
    console.log('First admin:', admin.name);
  }
});

// Count matching documents
users.find({ active: true }).count((err, count) => {
  if (err) throw err;
  console.log('Total active users:', count);
});

/**
 * Limit number of documents returned
 * @param {number} limit - Maximum number of documents
 * @returns {SkinCursor} this
 */
limit(limit);

/**
 * Skip number of documents
 * @param {number} skip - Number of documents to skip
 * @returns {SkinCursor} this
 */
skip(skip);

/**
 * Sort documents by specified fields
 * @param {object} sort - Sort specification object
 * @returns {SkinCursor} this
 */
sort(sort);

/**
 * Set read preference for cursor
 * @param {string} preference - Read preference
 * @returns {SkinCursor} this
 */
setReadPreference(preference);

const users = db.collection('users');

// Pagination with limit and skip
users.find({ active: true })
  .skip(20)
  .limit(10)
  .sort({ name: 1 })
  .toArray((err, page) => {
    if (err) throw err;
    console.log('Page 3 users:', page);
  });

// Complex sorting
users.find({ role: 'user' })
  .sort({ lastLogin: -1, name: 1 })
  .limit(5)
  .toArray((err, recentUsers) => {
    if (err) throw err;
    console.log('Most recently active users:', recentUsers);
  });

// Read preference for replica sets
users.find({ department: 'engineering' })
  .setReadPreference('secondary')
  .toArray((err, engineers) => {
    if (err) throw err;
    console.log('Engineers from secondary:', engineers);
  });

/**
 * Convert cursor to readable stream
 * @param {object} [options] - Stream options
 * @returns {Stream} Readable stream of documents
 */
stream(options);

/**
 * Transform cursor results through transform stream
 * @param {function} transform - Transform function
 * @param {object} [options] - Transform options
 * @returns {Stream} Transform stream
 */
pipe(transform, options);

const users = db.collection('users');

// Stream large result set
const userStream = users.find({ active: true }).stream();

userStream.on('data', (user) => {
  console.log('Processing user:', user.name);
  // Process user without loading all into memory
});

userStream.on('end', () => {
  console.log('Finished processing all users');
});

userStream.on('error', (err) => {
  console.error('Stream error:', err);
});

// Transform stream example (if supported)
const fs = require('fs');
const transform = require('stream').Transform;

const csvTransform = new transform({
  objectMode: true,
  transform(user, encoding, callback) {
    const csv = `${user.name},${user.email},${user.role}\n`;
    callback(null, csv);
  }
});

users.find({})
  .stream()
  .pipe(csvTransform)
  .pipe(fs.createWriteStream('users.csv'));

/**
 * Explain query execution plan
 * @param {function} callback - Callback function (err, explanation)
 * @returns {void}
 */
explain(callback);

/**
 * Get query hint for index usage
 * @param {object} hint - Index hint object
 * @returns {SkinCursor} this
 */
hint(hint);

const users = db.collection('users');

// Explain query execution
users.find({ email: 'user@example.com' })
  .explain((err, explanation) => {
    if (err) throw err;
    console.log('Query explanation:', explanation);
  });

// Force index usage with hint
users.find({ name: 'John' })
  .hint({ name: 1 })
  .toArray((err, johns) => {
    if (err) throw err;
    console.log('Johns found using name index:', johns);
  });

/**
 * Check if cursor is closed
 * @returns {boolean} true if cursor is closed
 */
isClosed();

/**
 * Close cursor manually
 * @param {function} [callback] - Optional callback function
 * @returns {void}
 */
close(callback);

/**
 * Rewind cursor to beginning
 * @returns {SkinCursor} this
 */
rewind();

const users = db.collection('users');
const cursor = users.find({ active: true });

// Check cursor state
console.log('Cursor closed?', cursor.isClosed());

// Process some documents
cursor.next((err, user) => {
  if (err) throw err;
  console.log('First user:', user);
  
  // Rewind to start over
  cursor.rewind();
  
  // Close cursor when done
  cursor.close((err) => {
    if (err) throw err;
    console.log('Cursor closed');
  });
});

/**
 * Set batch size for cursor operations
 * @param {number} size - Batch size
 * @returns {SkinCursor} this
 */
batchSize(size);

/**
 * Set maximum time cursor can run
 * @param {number} ms - Maximum time in milliseconds
 * @returns {SkinCursor} this
 */
maxTimeMS(ms);

/**
 * Enable tailable cursor for capped collections
 * @param {boolean} [tail] - Enable tailable cursor
 * @returns {SkinCursor} this
 */
tailable(tail);

/**
 * Return partial results if some shards are down
 * @param {boolean} [partial] - Allow partial results
 * @returns {SkinCursor} this
 */
partial(partial);

const logs = db.collection('logs'); // capped collection

// Tailable cursor for real-time log monitoring
logs.find({})
  .tailable(true)
  .each((err, log) => {
    if (err) throw err;
    if (log) {
      console.log('New log entry:', log.message);
    }
  });

// Optimized cursor with batch size
users.find({ active: true })
  .batchSize(100)
  .maxTimeMS(5000)
  .toArray((err, users) => {
    if (err) throw err;
    console.log('Retrieved users with optimized cursor');
  });

// Partial results from sharded collection
const shardedCollection = db.collection('sharded_data');
shardedCollection.find({})
  .partial(true)
  .toArray((err, results) => {
    if (err) throw err;
    console.log('Partial results:', results.length);
  });