-
Notifications
You must be signed in to change notification settings - Fork 0
/
package.json
44 lines (44 loc) · 30.3 KB
/
package.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
"name": "mquery",
"version": "0.5.3",
"description": "Expressive query building for MongoDB",
"main": "index.js",
"scripts": {
"test": "make test"
},
"repository": {
"type": "git",
"url": "git://github.com/aheckmann/mquery.git"
},
"dependencies": {
"sliced": "0.0.5",
"debug": "0.7.4",
"regexp-clone": "0.0.1"
},
"devDependencies": {
"mongodb": "1.3.23",
"mocha": "1.9.x"
},
"bugs": {
"url": "https://github.com/aheckmann/mquery/issues/new"
},
"author": {
"name": "Aaron Heckmann",
"email": "aaron.heckmann+github@gmail.com"
},
"license": "MIT",
"keywords": [
"mongodb",
"query",
"builder"
],
"homepage": "https://github.com/aheckmann/mquery/",
"readme": "#mquery\n===========\n\n`mquery` is a fluent mongodb query builder designed to run in multiple environments. As of v0.1, `mquery` runs on `Node.js` only with support for the MongoDB shell and browser environments planned for upcoming releases.\n\n##Features\n\n - fluent query builder api\n - custom base query support\n - MongoDB 2.4 geoJSON support\n - method + option combinations validation\n - node.js driver compatibility\n - environment detection\n - [debug](https://github.com/visionmedia/debug) support\n - separated collection implementations for maximum flexibility\n\n[![Build Status](https://travis-ci.org/aheckmann/mquery.png)](https://travis-ci.org/aheckmann/mquery)\n\n##Use\n\n```js\nrequire('mongodb').connect(uri, function (err, db) {\n if (err) return handleError(err);\n\n // get a collection\n var collection = db.collection('artists');\n\n // pass it to the constructor\n mquery(collection).find({..}, callback);\n\n // or pass it to the collection method\n mquery().find({..}).collection(collection).exec(callback)\n\n // or better yet, create a custom query constructor that has it always set\n var Artist = mquery(collection).toConstructor();\n Artist().find(..).where(..).exec(callback)\n})\n```\n\n`mquery` requires a collection object to work with. In the example above we just pass the collection object created using the official [MongoDB driver](https://github.com/mongodb/node-mongodb-native).\n\n\n##Fluent API\n\n- [find](#find)\n- [findOne](#findOne)\n- [count](#count)\n- [remove](#remove)\n- [update](#update)\n- [findOneAndUpdate](#findoneandupdate)\n- [findOneAndRemove](#findoneandremove)\n- [distinct](#distinct)\n- [exec](#exec)\n- [all](#all)\n- [and](#and)\n- [box](#box)\n- [circle](#circle)\n- [elemMatch](#elemmatch)\n- [equals](#equals)\n- [exists](#exists)\n- [geometry](#geometry)\n- [gt](#gt)\n- [gte](#gte)\n- [in](#in)\n- [intersects](#intersects)\n- [lt](#lt)\n- [lte](#lte)\n- [maxDistance](#maxdistance)\n- [mod](#mod)\n- [ne](#ne)\n- [nin](#nin)\n- [nor](#nor)\n- [near](#near)\n- [or](#or)\n- [polygon](#polygon)\n- [regex](#regex)\n- [select](#select)\n- [selected](#selected)\n- [selectedInclusively](#selectedinclusively)\n- [selectedExclusively](#selectedexclusively)\n- [size](#size)\n- [slice](#slice)\n- [within](#within)\n- [where](#where)\n- [$where](#where-1)\n- [batchSize](#batchsize)\n- [comment](#comment)\n- [hint](#hint)\n- [limit](#limit)\n- [maxScan](#maxscan)\n- [skip](#skip)\n- [sort](#sort)\n- [read](#read)\n- [slaveOk](#slaveok)\n- [snapshot](#snapshot)\n- [tailable](#tailable)\n\n## Helpers\n\n- [collection](#collection)\n- [merge](#mergeobject)\n- [setOptions](#setoptionsoptions)\n- [mquery.canMerge](#mquerycanmerge)\n- [mquery.use$geoWithin](#mqueryusegeowithin)\n\n###find()\n\nDeclares this query a _find_ query. Optionally pass a match clause and / or callback. If a callback is passed the query is executed.\n\n```js\nmquery().find()\nmquery().find(match)\nmquery().find(callback)\nmquery().find(match, function (err, docs) {\n assert(Array.isArray(docs));\n})\n```\n\n###findOne()\n\nDeclares this query a _findOne_ query. Optionally pass a match clause and / or callback. If a callback is passed the query is executed.\n\n```js\nmquery().findOne()\nmquery().findOne(match)\nmquery().findOne(callback)\nmquery().findOne(match, function (err, doc) {\n if (doc) {\n // the document may not be found\n console.log(doc);\n }\n})\n```\n\n###count()\n\nDeclares this query a _count_ query. Optionally pass a match clause and / or callback. If a callback is passed the query is executed.\n\n```js\nmquery().count()\nmquery().count(match)\nmquery().count(callback)\nmquery().count(match, function (err, number){\n console.log('we found %d matching documents', number);\n})\n```\n\n###remove()\n\nDeclares this query a _remove_ query. Optionally pass a match clause and / or callback. If a callback is passed the query is executed.\n\n```js\nmquery().remove()\nmquery().remove(match)\nmquery().remove(callback)\nmquery().remove(match, function (err){})\n```\n\n###update()\n\nDeclares this query an _update_ query. Optionally pass an update document, match clause, options or callback. If a callback is passed, the query is executed. To force execution without passing a callback, run `update(true)`.\n\n```js\nmquery().update()\nmquery().update(match, updateDocument)\nmquery().update(match, updateDocument, options)\n\n// the following all execute the command\nmquery().update(callback)\nmquery().update({$set: updateDocument, callback)\nmquery().update(match, updateDocument, callback)\nmquery().update(match, updateDocument, options, function (err, result){})\nmquery().update(true) // executes (unsafe write)\n```\n\n#####the update document\n\nAll paths passed that are not `$atomic` operations will become `$set` ops. For example:\n\n```js\nmquery(collection).where({ _id: id }).update({ title: 'words' }, callback)\n```\n\nbecomes\n\n```js\ncollection.update({ _id: id }, { $set: { title: 'words' }}, callback)\n```\n\nThis behavior can be overridden using the `overwrite` option (see below).\n\n#####options\n\nOptions are passed to the `setOptions()` method.\n\n- overwrite\n\nPassing an empty object `{ }` as the update document will result in a no-op unless the `overwrite` option is passed. Without the `overwrite` option, the update operation will be ignored and the callback executed without sending the command to MongoDB to prevent accidently overwritting documents in the collection.\n\n```js\nvar q = mquery(collection).where({ _id: id }).setOptions({ overwrite: true });\nq.update({ }, callback); // overwrite with an empty doc\n```\n\nThe `overwrite` option isn't just for empty objects, it also provides a means to override the default `$set` conversion and send the update document as is.\n\n```js\n// create a base query\nvar base = mquery({ _id: 108 }).collection(collection).toConstructor();\n\nbase().findOne(function (err, doc) {\n console.log(doc); // { _id: 108, name: 'cajon' })\n\n base().setOptions({ overwrite: true }).update({ changed: true }, function (err) {\n base.findOne(function (err, doc) {\n console.log(doc); // { _id: 108, changed: true }) - the doc was overwritten\n });\n });\n})\n```\n\n- multi\n\nUpdates only modify a single document by default. To update multiple documents, set the `multi` option to `true`.\n\n```js\nmquery()\n .collection(coll)\n .update({ name: /^match/ }, { $addToSet: { arr: 4 }}, { multi: true }, callback)\n\n// another way of doing it\nmquery({ name: /^match/ })\n .collection(coll)\n .setOptions({ multi: true })\n .update({ $addToSet: { arr: 4 }}, callback)\n\n// update multiple documents with an empty doc\nvar q = mquery(collection).where({ name: /^match/ });\nq.setOptions({ multi: true, overwrite: true })\nq.update({ });\nq.update(function (err, result) {\n console.log(arguments);\n});\n```\n\n###findOneAndUpdate()\n\nDeclares this query a _findAndModify_ with update query. Optionally pass a match clause, update document, options, or callback. If a callback is passed, the query is executed.\n\nWhen executed, the first matching document (if found) is modified according to the update document and passed back to the callback.\n\n#####options\n\nOptions are passed to the `setOptions()` method.\n\n- `new`: boolean - true to return the modified document rather than the original. defaults to true\n- `upsert`: boolean - creates the object if it doesn't exist. defaults to false\n- `sort`: if multiple docs are found by the match condition, sets the sort order to choose which doc to update\n\n```js\nquery.findOneAndUpdate()\nquery.findOneAndUpdate(updateDocument)\nquery.findOneAndUpdate(match, updateDocument)\nquery.findOneAndUpdate(match, updateDocument, options)\n\n// the following all execute the command\nquery.findOneAndUpdate(callback)\nquery.findOneAndUpdate(updateDocument, callback)\nquery.findOneAndUpdate(match, updateDocument, callback)\nquery.findOneAndUpdate(match, updateDocument, options, function (err, doc) {\n if (doc) {\n // the document may not be found\n console.log(doc);\n }\n})\n ```\n\n###findOneAndRemove()\n\nDeclares this query a _findAndModify_ with remove query. Optionally pass a match clause, options, or callback. If a callback is passed, the query is executed.\n\nWhen executed, the first matching document (if found) is modified according to the update document, removed from the collection and passed to the callback.\n\n#####options\n\nOptions are passed to the `setOptions()` method.\n\n- `sort`: if multiple docs are found by the condition, sets the sort order to choose which doc to modify and remove\n\n```js\nA.where().findOneAndRemove()\nA.where().findOneAndRemove(match)\nA.where().findOneAndRemove(match, options)\n\n// the following all execute the command\nA.where().findOneAndRemove(callback)\nA.where().findOneAndRemove(match, callback)\nA.where().findOneAndRemove(match, options, function (err, doc) {\n if (doc) {\n // the document may not be found\n console.log(doc);\n }\n})\n ```\n\n###distinct()\n\nDeclares this query a _distinct_ query. Optionally pass the distinct field, a match clause or callback. If a callback is passed the query is executed.\n\n```js\nmquery().distinct()\nmquery().distinct(match)\nmquery().distinct(match, field)\nmquery().distinct(field)\n\n// the following all execute the command\nmquery().distinct(callback)\nmquery().distinct(field, callback)\nmquery().distinct(match, callback)\nmquery().distinct(match, field, function (err, result) {\n console.log(result);\n})\n```\n\n###exec()\n\nExecutes the query.\n\n```js\nmquery().findOne().where('route').intersects(polygon).exec(function (err, docs){})\n```\n\n-------------\n\n###all()\n\nSpecifies an `$all` query condition\n\n```js\nmquery().where('permission').all(['read', 'write'])\n```\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/operator/all/)\n\n###and()\n\nSpecifies arguments for an `$and` condition\n\n```js\nmquery().and([{ color: 'green' }, { status: 'ok' }])\n```\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/operator/and/)\n\n###box()\n\nSpecifies a `$box` condition\n\n```js\nvar lowerLeft = [40.73083, -73.99756]\nvar upperRight= [40.741404, -73.988135]\n\nmquery().where('location').within().box(lowerLeft, upperRight)\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/box/)\n\n###circle()\n\nSpecifies a `$center` or `$centerSphere` condition.\n\n```js\nvar area = { center: [50, 50], radius: 10, unique: true }\nquery.where('loc').within().circle(area)\nquery.circle('loc', area);\n\n// for spherical calculations\nvar area = { center: [50, 50], radius: 10, unique: true, spherical: true }\nquery.where('loc').within().circle(area)\nquery.circle('loc', area);\n```\n\n- [MongoDB Documentation - center](http://docs.mongodb.org/manual/reference/operator/center/)\n- [MongoDB Documentation - centerSphere](http://docs.mongodb.org/manual/reference/operator/centerSphere/)\n\n###elemMatch()\n\nSpecifies an `$elemMatch` condition\n\n```js\nquery.where('comment').elemMatch({ author: 'autobot', votes: {$gte: 5}})\n\nquery.elemMatch('comment', function (elem) {\n elem.where('author').equals('autobot');\n elem.where('votes').gte(5);\n})\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/elemMatch/)\n\n###equals()\n\nSpecifies the complementary comparison value for the path specified with `where()`.\n\n```js\nmquery().where('age').equals(49);\n\n// is the same as\n\nmquery().where({ 'age': 49 });\n```\n\n###exists()\n\nSpecifies an `$exists` condition\n\n```js\n// { name: { $exists: true }}\nmquery().where('name').exists()\nmquery().where('name').exists(true)\nmquery().exists('name')\n\n// { name: { $exists: false }}\nmquery().where('name').exists(false);\nmquery().exists('name', false);\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/exists/)\n\n###geometry()\n\nSpecifies a `$geometry` condition\n\n```js\nvar polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]]\nquery.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA })\n\n// or\nvar polyB = [[ 0, 0 ], [ 1, 1 ]]\nquery.where('loc').within().geometry({ type: 'LineString', coordinates: polyB })\n\n// or\nvar polyC = [ 0, 0 ]\nquery.where('loc').within().geometry({ type: 'Point', coordinates: polyC })\n\n// or\nquery.where('loc').intersects().geometry({ type: 'Point', coordinates: polyC })\n\n// or\nquery.where('loc').near().geometry({ type: 'Point', coordinates: [3,5] })\n```\n\n`geometry()` **must** come after `intersects()`, `within()`, or `near()`.\n\nThe `object` argument must contain `type` and `coordinates` properties.\n\n- type `String`\n- coordinates `Array`\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/geometry/)\n\n###gt()\n\nSpecifies a `$gt` query condition.\n\n```js\nmquery().where('clicks').gt(999)\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/gt/)\n\n###gte()\n\nSpecifies a `$gte` query condition.\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/gte/)\n\n```js\nmquery().where('clicks').gte(1000)\n```\n\n###in()\n\nSpecifies an `$in` query condition.\n\n```js\nmquery().where('author_id').in([3, 48901, 761])\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/in/)\n\n###intersects()\n\nDeclares an `$geoIntersects` query for `geometry()`.\n\n```js\nquery.where('path').intersects().geometry({\n type: 'LineString'\n , coordinates: [[180.0, 11.0], [180, 9.0]]\n})\n\n// geometry arguments are supported\nquery.where('path').intersects({\n type: 'LineString'\n , coordinates: [[180.0, 11.0], [180, 9.0]]\n})\n```\n\n**Must** be used after `where()`.\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/geoIntersects/)\n\n###lt()\n\nSpecifies a `$lt` query condition.\n\n```js\nmquery().where('clicks').lt(50)\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/lt/)\n\n###lte()\n\nSpecifies a `$lte` query condition.\n\n```js\nmquery().where('clicks').lte(49)\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/lte/)\n\n###maxDistance()\n\nSpecifies a `$maxDistance` query condition.\n\n```js\nmquery().where('location').near({ center: [139, 74.3] }).maxDistance(5)\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/maxDistance/)\n\n###mod()\n\nSpecifies a `$mod` condition\n\n```js\nmquery().where('count').mod(2, 0)\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/mod/)\n\n###ne()\n\nSpecifies a `$ne` query condition.\n\n```js\nmquery().where('status').ne('ok')\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/ne/)\n\n###nin()\n\nSpecifies an `$nin` query condition.\n\n```js\nmquery().where('author_id').nin([3, 48901, 761])\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/nin/)\n\n###nor()\n\nSpecifies arguments for an `$nor` condition.\n\n```js\nmquery().nor([{ color: 'green' }, { status: 'ok' }])\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/nor/)\n\n###near()\n\nSpecifies arguments for a `$near` or `$nearSphere` condition.\n\nThese operators return documents sorted by distance.\n\n####Example\n\n```js\nquery.where('loc').near({ center: [10, 10] });\nquery.where('loc').near({ center: [10, 10], maxDistance: 5 });\nquery.near('loc', { center: [10, 10], maxDistance: 5 });\n\n// GeoJSON\nquery.where('loc').near({ center: { type: 'Point', coordinates: [10, 10] }});\nquery.where('loc').near({ center: { type: 'Point', coordinates: [10, 10] }, maxDistance: 5, spherical: true });\nquery.where('loc').near().geometry({ type: 'Point', coordinates: [10, 10] });\n\n// For a $nearSphere condition, pass the `spherical` option.\nquery.near({ center: [10, 10], maxDistance: 5, spherical: true });\n```\n\n[MongoDB Documentation](http://www.mongodb.org/display/DOCS/Geospatial+Indexing)\n\n###or()\n\nSpecifies arguments for an `$or` condition.\n\n```js\nmquery().or([{ color: 'red' }, { status: 'emergency' }])\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/or/)\n\n###polygon()\n\nSpecifies a `$polygon` condition\n\n```js\nmquery().where('loc').within().polygon([10,20], [13, 25], [7,15])\nmquery().polygon('loc', [10,20], [13, 25], [7,15])\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/polygon/)\n\n###regex()\n\nSpecifies a `$regex` query condition.\n\n```js\nmquery().where('name').regex(/^sixstepsrecords/)\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/regex/)\n\n###select()\n\nSpecifies which document fields to include or exclude\n\n```js\n// 1 means include, 0 means exclude\nmquery().select({ name: 1, address: 1, _id: 0 })\n\n// or\n\nmquery().select('name address -_id')\n```\n\n#####String syntax\n\nWhen passing a string, prefixing a path with `-` will flag that path as excluded. When a path does not have the `-` prefix, it is included.\n\n```js\n// include a and b, exclude c\nquery.select('a b -c');\n\n// or you may use object notation, useful when\n// you have keys already prefixed with a \"-\"\nquery.select({a: 1, b: 1, c: 0});\n```\n\n_Cannot be used with `distinct()`._\n\n###selected()\n\nDetermines if the query has selected any fields.\n\n```js\nvar query = mquery();\nquery.selected() // false\nquery.select('-name');\nquery.selected() // true\n```\n\n###selectedInclusively()\n\nDetermines if the query has selected any fields inclusively.\n\n```js\nvar query = mquery().select('name');\nquery.selectedInclusively() // true\n\nvar query = mquery();\nquery.selected() // false\nquery.select('-name');\nquery.selectedInclusively() // false\nquery.selectedExclusively() // true\n```\n\n###selectedExclusively()\n\nDetermines if the query has selected any fields exclusively.\n\n```js\nvar query = mquery().select('-name');\nquery.selectedExclusively() // true\n\nvar query = mquery();\nquery.selected() // false\nquery.select('name');\nquery.selectedExclusively() // false\nquery.selectedInclusively() // true\n```\n\n###size()\n\nSpecifies a `$size` query condition.\n\n```js\nmquery().where('someArray').size(6)\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/size/)\n\n###slice()\n\nSpecifies a `$slice` projection for a `path`\n\n```js\nmquery().where('comments').slice(5)\nmquery().where('comments').slice(-5)\nmquery().where('comments').slice([-10, 5])\n```\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/projection/slice/)\n\n###within()\n\nSets a `$geoWithin` or `$within` argument for geo-spatial queries.\n\n```js\nmquery().within().box()\nmquery().within().circle()\nmquery().within().geometry()\n\nmquery().where('loc').within({ center: [50,50], radius: 10, unique: true, spherical: true });\nmquery().where('loc').within({ box: [[40.73, -73.9], [40.7, -73.988]] });\nmquery().where('loc').within({ polygon: [[],[],[],[]] });\n\nmquery().where('loc').within([], [], []) // polygon\nmquery().where('loc').within([], []) // box\nmquery().where('loc').within({ type: 'LineString', coordinates: [...] }); // geometry\n```\n\nAs of mquery 2.0, `$geoWithin` is used by default. This impacts you if running MongoDB < 2.4. To alter this behavior, see [mquery.use$geoWithin](#mqueryusegeowithin).\n\n**Must** be used after `where()`.\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/reference/operator/geoWithin/)\n\n###where()\n\nSpecifies a `path` for use with chaining\n\n```js\n// instead of writing:\nmquery().find({age: {$gte: 21, $lte: 65}});\n\n// we can instead write:\nmquery().where('age').gte(21).lte(65);\n\n// passing query conditions is permitted too\nmquery().find().where({ name: 'vonderful' })\n\n// chaining\nmquery()\n.where('age').gte(21).lte(65)\n.where({ 'name': /^vonderful/i })\n.where('friends').slice(10)\n.exec(callback)\n```\n\n###$where()\n\nSpecifies a `$where` condition.\n\nUse `$where` when you need to select documents using a JavaScript expression.\n\n```js\nquery.$where('this.comments.length > 10 || this.name.length > 5').exec(callback)\n\nquery.$where(function () {\n return this.comments.length > 10 || this.name.length > 5;\n})\n```\n\nOnly use `$where` when you have a condition that cannot be met using other MongoDB operators like `$lt`. Be sure to read about all of [its caveats](http://docs.mongodb.org/manual/reference/operator/where/) before using.\n\n-----------\n\n###batchSize()\n\nSpecifies the batchSize option.\n\n```js\nquery.batchSize(100)\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/method/cursor.batchSize/)\n\n###comment()\n\nSpecifies the comment option.\n\n```js\nquery.comment('login query');\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/operator/)\n\n###hint()\n\nSets query hints.\n\n```js\nmquery().hint({ indexA: 1, indexB: -1 })\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/operator/hint/)\n\n###limit()\n\nSpecifies the limit option.\n\n```js\nquery.limit(20)\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/method/cursor.limit/)\n\n###maxScan()\n\nSpecifies the maxScan option.\n\n```js\nquery.maxScan(100)\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/operator/maxScan/)\n\n###skip()\n\nSpecifies the skip option.\n\n```js\nquery.skip(100).limit(20)\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/method/cursor.skip/)\n\n###sort()\n\nSets the query sort order.\n\nIf an object is passed, key values allowed are `asc`, `desc`, `ascending`, `descending`, `1`, and `-1`.\n\nIf a string is passed, it must be a space delimited list of path names. The sort order of each path is ascending unless the path name is prefixed with `-` which will be treated as descending.\n\n```js\n// these are equivalent\nquery.sort({ field: 'asc', test: -1 });\nquery.sort('field -test');\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/method/cursor.sort/)\n\n###read()\n\nSets the readPreference option for the query.\n\n```js\nmquery().read('primary')\nmquery().read('p') // same as primary\n\nmquery().read('primaryPreferred')\nmquery().read('pp') // same as primaryPreferred\n\nmquery().read('secondary')\nmquery().read('s') // same as secondary\n\nmquery().read('secondaryPreferred')\nmquery().read('sp') // same as secondaryPreferred\n\nmquery().read('nearest')\nmquery().read('n') // same as nearest\n```\n\n#####Preferences:\n\n- `primary` - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.\n- `secondary` - Read from secondary if available, otherwise error.\n- `primaryPreferred` - Read from primary if available, otherwise a secondary.\n- `secondaryPreferred` - Read from a secondary if available, otherwise read from the primary.\n- `nearest` - All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.\n\nAliases\n\n- `p` primary\n- `pp` primaryPreferred\n- `s` secondary\n- `sp` secondaryPreferred\n- `n` nearest\n\n#####Preference Tags:\n\nTo keep the separation of concerns between `mquery` and your driver\nclean, `mquery#read()` no longer handles specifying a second `tags` argument as of version 0.5.\nIf you need to specify tags, pass any non-string argument as the first argument.\n`mquery` will pass this argument untouched to your collections methods later.\nFor example:\n\n```js\n// example of specifying tags using the Node.js driver\nvar ReadPref = require('mongodb').ReadPreference;\nvar preference = new ReadPref('secondary', [{ dc:'sf', s: 1 },{ dc:'ma', s: 2 }]);\nmquery(..).read(preference).exec();\n```\n\nRead more about how to use read preferences [here](http://docs.mongodb.org/manual/applications/replication/#read-preference) and [here](http://mongodb.github.com/node-mongodb-native/driver-articles/anintroductionto1_1and2_2.html#read-preferences).\n\n###slaveOk()\n\nSets the slaveOk option. `true` allows reading from secondaries.\n\n**deprecated** use [read()](#read) preferences instead if on mongodb >= 2.2\n\n```js\nquery.slaveOk() // true\nquery.slaveOk(true)\nquery.slaveOk(false)\n```\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/method/rs.slaveOk/)\n\n###snapshot()\n\nSpecifies this query as a snapshot query.\n\n```js\nmquery().snapshot() // true\nmquery().snapshot(true)\nmquery().snapshot(false)\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB documentation](http://docs.mongodb.org/manual/reference/operator/snapshot/)\n\n###tailable()\n\nSets tailable option.\n\n```js\nmquery().tailable() <== true\nmquery().tailable(true)\nmquery().tailable(false)\n```\n\n_Cannot be used with `distinct()`._\n\n[MongoDB Documentation](http://docs.mongodb.org/manual/tutorial/create-tailable-cursor/)\n\n##Helpers\n\n###collection()\n\nSets the querys collection.\n\n```js\nmquery().collection(aCollection)\n```\n\n\n###merge(object)\n\nMerges other mquery or match condition objects into this one. When an muery instance is passed, its match conditions, field selection and options are merged.\n\n```js\nvar drum = mquery({ type: 'drum' }).collection(instruments);\nvar redDrum = mqery({ color: 'red' }).merge(drum);\nredDrum.count(function (err, n) {\n console.log('there are %d red drums', n);\n})\n```\n\nInternally uses `mquery.canMerge` to determine validity.\n\n###setOptions(options)\n\nSets query options.\n\n```js\nmquery().setOptions({ collection: coll, limit: 20 })\n```\n\n#####options\n\n- [tailable](#tailable) *\n- [sort](#sort) *\n- [limit](#limit) *\n- [skip](#skip) *\n- [maxScan](#maxScan) *\n- [batchSize](#batchSize) *\n- [comment](#comment) *\n- [snapshot](#snapshot) *\n- [hint](#hint) *\n- [slaveOk](#slaveOk) *\n- [safe](http://docs.mongodb.org/manual/reference/write-concern/): Boolean - passed through to the collection. Setting to `true` is equivalent to `{ w: 1 }`\n- [collection](#collection): the collection to query against\n\n_* denotes a query helper method is also available_\n\n###mquery.canMerge(conditions)\n\nDetermines if `conditions` can be merged using `mquery().merge()`.\n\n```js\nvar query = mquery({ type: 'drum' });\nvar okToMerge = mquery.canMerge(anObject)\nif (okToMerge) {\n query.merge(anObject);\n}\n```\n\n##mquery.use$geoWithin\n\nMongoDB 2.4 introduced the `$geoWithin` operator which replaces and is 100% backward compatible with `$within`. As of mquery 0.2, we default to using `$geoWithin` for all `within()` calls.\n\nIf you are running MongoDB < 2.4 this will be problematic. To force `mquery` to be backward compatible and always use `$within`, set the `mquery.use$geoWithin` flag to `false`.\n\n```js\nmquery.use$geoWithin = false;\n```\n\n##Custom Base Queries\n\nOften times we want custom base queries that encapsulate predefined criteria. With `mquery` this is easy. First create the query you want to reuse and call its `toConstructor()` method which returns a new subclass of `mquery` that retains all options and criteria of the original.\n\n```js\nvar greatMovies = mquery(movieCollection).where('rating').gte(4.5).toConstructor();\n\n// use it!\ngreatMovies().count(function (err, n) {\n console.log('There are %d great movies', n);\n});\n\ngreatMovies().where({ name: /^Life/ }).select('name').find(function (err, docs) {\n console.log(docs);\n});\n```\n\n##Validation\n\nMethod and options combinations are checked for validity at runtime to prevent creation of invalid query constructs. For example, a `distinct` query does not support specifying options like `hint` or field selection. In this case an error will be thrown so you can catch these mistakes in development.\n\n##Debug support\n\nDebug mode is provided through the use of the [debug](https://github.com/visionmedia/debug) module. To enable:\n\n DEBUG=mquery node yourprogram.js\n\nRead the debug module documentation for more details.\n\n## General compatibility\n\n#### ObjectIds\n\n`mquery` clones query arguments before passing them to a `collection` method for execution.\nThis prevents accidental side-affects to the objects you pass.\nTo clone `ObjectIds` we need to make some assumptions.\n\nFirst, to check if an object is an `ObjectId`, we check its constructors name. If it matches either\n`ObjectId` or `ObjectID` we clone it.\n\nTo clone `ObjectIds`, we call its optional `clone` method. If a `clone` method does not exist, we fall\nback to calling `new obj.constructor(obj.id)`. We assume, for compatibility with the\nNode.js driver, that the `ObjectId` instance has a public `id` property and that\nwhen creating an `ObjectId` instance we can pass that `id` as an argument.\n\n#### Read Preferences\n\n`mquery` supports specifying [Read Preferences]() to control from which MongoDB node your query will read.\nThe Read Preferences spec also support specifying tags. To pass tags, some\ndrivers (Node.js driver) require passing a special constructor that handles both the read preference and its tags.\nIf you need to specify tags, pass an instance of your drivers ReadPreference constructor or roll your own. `mquery` will store whatever you provide and pass later to your collection during execution.\n\n##Future goals\n\n - mongo shell compatibility\n - browser compatibility\n\n## Installation\n\n $ npm install mquery\n\n## License\n\n[MIT](https://github.com/aheckmann/mquery/blob/master/LICENSE)\n\n",
"readmeFilename": "README.md",
"_id": "mquery@0.5.3",
"dist": {
"shasum": "ac669b2a7c7c6594d52106b6fbc068b6b66d6099"
},
"_from": "mquery@0.5.3",
"_resolved": "https://registry.npmjs.org/mquery/-/mquery-0.5.3.tgz"
}