monSQLize chain calling method support documentation

Overview

Now you can build queries using chained calls just like you would with the native MongoDB driver. Chained methods fully support caching, parameter validation and error handling.

🎯 Supported chain calling method (completely implemented)

1. `find()` method

✅ Supported chain calls (12 methods in total)

Methods	Syntax	Description	Exposed capabilities
`.limit(n)`	`.limit(number)`	Limit the number of returned documents	`find()` query chain
`.skip(n)`	`.skip(number)`	Number of skipped documents	`find()` query chain
`.sort(spec)`	`.sort(object)`	Sorting rules	`find()` query chain
`.project(spec)`	`.project(object)`	Field projection	`find()` query chain
`.hint(spec)`	`.hint(object\|string)`	Index prompt	`find()` query chain
`.collation(spec)`	`.collation(object)`	Sorting rules	`find()` query chain
`.comment(str)`	`.comment(string)`	Query comments	`find()` query chain
`.maxTimeMS(ms)`	`.maxTimeMS(number)`	Query timeout	`find()` query chain
`.batchSize(n)`	`.batchSize(number)`	batch size	`find()` query chain
`.explain(v)`	`.explain(string?)`	Return query execution plan	`find()` query chain
`.stream()`	`.stream()`	Return streaming results	`find()` query chain
`.toArray()`	`.toArray()`	Explicit conversion to array	`find()` query chain

limit(0) intentionally keeps the MongoDB cursor semantics: it means "no limit" and may return all matching documents. Use a positive limit for bounded reads; explicit positive limits are capped by findMaxLimit.

📝 Usage example

//Basic usage - limit and skip
const results = await collection('products')
  .find({ category: 'electronics' })
  .limit(10)
  .skip(5);

//sort query
const results = await collection('products')
  .find({ inStock: true })
  .sort({ price: -1 })
  .limit(10);

//Field projection
const results = await collection('products')
  .find({ category: 'books' })
  .project({ name: 1, price: 1 })
  .limit(5);

//Complex combinations - multiple chained methods
const results = await collection('products')
  .find({ category: 'electronics', inStock: true })
  .sort({ rating: -1, sales: -1 })
  .skip(5)
  .limit(10)
  .project({ name: 1, price: 1 })
  .hint({ category: 1, price: -1 })
  .maxTimeMS(5000)
  .comment('Complex query');

//Query execution plan
const plan = await collection('products')
  .find({ category: 'electronics' })
  .sort({ price: -1 })
  .limit(10)
  .explain('executionStats');

//Streaming query
const stream = collection('products')
  .find({ category: 'books' })
  .sort({ createdAt: -1 })
  .limit(100)
  .stream();

2. `aggregate()` method

✅ Supported chain calls (9 methods in total)

Methods	Syntax	Description	Exposed capabilities
`.hint(spec)`	`.hint(object\|string)`	Index prompt	`aggregate()` query chain
`.collation(spec)`	`.collation(object)`	Sorting rules	`aggregate()` query chain
`.comment(str)`	`.comment(string)`	Query comments	`aggregate()` query chain
`.maxTimeMS(ms)`	`.maxTimeMS(number)`	Query timeout	`aggregate()` query chain
`.allowDiskUse(bool)`	`.allowDiskUse(boolean)`	Allow disk use	`aggregate()` query chain
`.batchSize(n)`	`.batchSize(number)`	batch size	`aggregate()` query chain
`.explain(v)`	`.explain(string?)`	Return the aggregate execution plan	`aggregate()` query chain
`.stream()`	`.stream()`	Return streaming results	`aggregate()` query chain
`.toArray()`	`.toArray()`	Explicit conversion to array	`aggregate()` query chain

📝 Usage example (2. aggregate() method)

//Basic aggregation
const results = await collection('orders')
  .aggregate([
    { $match: { status: 'paid' } },
    { $group: { _id: '$category', total: { $sum: '$amount' } } }
  ])
  .allowDiskUse(true);

//Complete chain call
const results = await collection('orders')
  .aggregate([
    { $match: { status: 'paid' } },
    { $group: { _id: '$category', total: { $sum: '$amount' } } },
    { $sort: { total: -1 } }
  ])
  .hint({ status: 1, createdAt: -1 })
  .allowDiskUse(true)
  .maxTimeMS(10000)
  .comment('Category Sales Statistics');

//aggregate execution plan
const plan = await collection('orders')
  .aggregate([
    { $match: { status: 'paid' } },
    { $group: { _id: '$customerId', total: { $sum: '$amount' } } }
  ])
  .explain('executionStats');

//streaming aggregation
const stream = collection('orders')
  .aggregate([
    { $match: { status: 'paid' } },
    { $limit: 100 }
  ])
  .stream();

🆚 MongoDB native chain method comparison

Complete comparison table

Method	MongoDB native support	monSQLize v3	Description
`.limit()`	✅	✅	Fully supported
`.skip()`	✅	✅	Fully supported
`.sort()`	✅	✅	Fully supported
`.project()`	✅	✅	Fully supported
`.hint()`	✅	✅	Fully supported
`.collation()`	✅	✅	Fully supported
`.comment()`	✅	✅	Fully supported
`.maxTimeMS()`	✅	✅	Fully supported
`.batchSize()`	✅	✅	Fully supported
`.explain()`	✅	✅	Fully supported
`.toArray()`	✅	✅	Fully supported
`.stream()`	✅	✅	Fully supported (use `.stream()` instead of `.forEach()`)
`.forEach()`	✅	Implemented via `.stream()`	Use streaming instead
`.map()`	✅	Implemented via `.stream()`	Use streaming instead
`.hasNext()`	✅	❌	Not supported (conflicts with cache architecture)
`.next()`	✅	❌	Not supported (conflicts with cache architecture)
`.close()`	✅	❌	Not required (automatic management)

Summary: monSQLize v3 supports the 12 chaining methods listed above. Use the table as the capability contract; application coverage depends on the query patterns your service uses.

✨ Highlights of new features

1. Promise compatibility

The chained call object implements the complete Promise interface:

//directly await
const results = await collection('products').find({}).limit(10);

//Use .then()
collection('products')
  .find({}).limit(10)
  .then(results => console.log(results));

//Use .catch()
const results = await collection('products')
  .find({}).limit(10)
  .catch(err => []);

2. Automatic parameter verification

//✅ Correct
.limit(10)
.skip(5)

//❌ Error - automatically throw exception
.limit(-1)        // Error: limit() requires a non-negative integer
.skip("invalid")  // Error: skip() requires a non-negative integer
.sort("invalid")  // Error: sort() requires an object or array

3. Execution protection

To prevent accidental re-execution:

const chain = collection('products').find({}).limit(5);

//First time execution ✅
await chain.toArray();

//The second execution ❌ throws an error
await chain.toArray(); // Error: Query already executed

4. Full cache support

The chained call uses the same cache key as the options parameter:

//These two methods share the cache
await collection('products').find({}).limit(10).sort({ price: -1 });
await collection('products').find({}, { limit: 10, sort: { price: -1 } });

🔄 Backwards Compatibility

100% backwards compatible

All existing code without modification:

//Old Code - Keep working ✅
const results = await collection('products').find(
  { category: 'electronics' },
  { limit: 10, sort: { price: -1 } }
);

//New Code - Chained Calls ✅
const results = await collection('products')
  .find({ category: 'electronics' })
  .limit(10)
  .sort({ price: -1 });

Automatic detection

monSQLize will automatically detect the calling method:

No options parameter → return chain builder
with options parameter → execute query directly

Chain call complete API documentation - Detailed usage guide and best practices
Chain call example - Current TypeScript example
find method document - find method detailed description
aggregate method document - detailed description of aggregate method
explain method document - Performance analysis tool

Feedback and Suggestions: If you have questions or suggestions, please submit GitHub Issue.

#monSQLize chain calling method support documentation

#Overview

#🎯 Supported chain calling method (completely implemented)

#1. find() method

#✅ Supported chain calls (12 methods in total)

#📝 Usage example

#2. aggregate() method

#✅ Supported chain calls (9 methods in total)

#📝 Usage example (2. aggregate() method)

#🆚 MongoDB native chain method comparison

#Complete comparison table

#✨ Highlights of new features

#1. Promise compatibility

#2. Automatic parameter verification

#3. Execution protection

#4. Full cache support

#🔄 Backwards Compatibility

#100% backwards compatible

#Automatic detection

#📚 Related documents