mongo-parse
============
A parser for mongo db queries and projections. You can use this to analyze, modify, and match against MongoDb queries, as well as test projections for inclusiveness or exclusiveness.
Example:
```javascript
var parser = require('mongo-parse')
var ObjectId = require('mongodb').ObjectId
var query = parser.parse({ "powerlevel": { $gt: 9000 }})
// query.parts contains:
{field: 'powerlevel', operator: '$gt', operand: 9000}
var query2 = {$and:
{userId: "507f191e810c19729de860ea"}, {animal: {$in: 'beefalo', 'deerclops'}}}
var newQuery = parser.parse(query2).mapValues(function(field, stringId) {
if(field === 'userId')
return ObjectId(stringId) // change a string ID into an ObjectId when you need to
else
return stringId
})
// newQuery is {$and:
{userId: ObjectId("29g8j3h27fh382dh82ae23")}, {animal: {$in: 'beefalo', 'deerclops'}}}
parser.parse(newQuery).matches({userId: ObjectId("507f191e810c19729de860ea"), animal: 'deerclops'}) // returns true
```
Install
=======
```
npm install mongo-parse
```
Usage
=====
```javascript
var parser = require('mongo-parse')
```
var queryObject = parser.parse(mongoQuery) - Returns an object that contains a list of query parts, and methods for interacting with the query.
queryObject.parts - A list of QueryPart objects.
queryObject.mapValues(function(field, value) {...}) - Returns a new mongo query object with values mapped based on the passed in
callback. The callback will be called for each leaf-node in the query.
For example, in the query `{x:1, $and:[{y:2,z:3}]}`, the callback will be called 3 times.
The value returned from the callback function will replace the original value in the new returned query.
Query parts that don't relate to a field may not trigger the callback. The callback's parameters:
field - The field the query part is for. E.g. for {x:1}, the field will be "x". Can be undefined for certain query parts that don't relate to a specific field (e.g. the $text operator).
value - The value that query part is querying with. E.g. for {x:1}, the value will be 1.
queryObject.map(function(field, value) {...}) - Returns a new mongo query object with query parts mapped based on the
return value of the passed-in callback.
The callback will be called for each leaf-node in the query.
For example, in the query `{x:1, $and:[{y:2,z:3}]}`, the callback will be called 3 times.
If the value returned from the callback is `null`, the original query part will be removed.
If the value returned from the callback is `undefined`, the original query part will be kept.
Otherwise, the query part will be replaced with the query parts contained in the returned query object.
Query parts that don't relate to a field may not trigger the callback. The callback's parameters:
field - The field the query part is for. E.g. for {x:1}, the field will be "x". Can be undefined for certain query parts that don't relate to a specific field (e.g. the $text operator).
value - The value that query part is querying with. E.g. for {x:1}, the value will be 1.
queryObject.matches(document, validate) - Returns true if the query matches the passed mongodb
document object. The following mongo operators are supported: basic equality ({field:value}), $gt, $gte, $lt, $lte, $ne, $in, $nin, $all, $mod, $exists, $regex, $size, $elemMatch, $not, $and, $or, $nor, $where (and implicit where - passing a function), $comment. The following mongo operators are not yet supported $geoIntersects, $geoWithin, $nearSphere, $near, $text, projection operators ($, $meta, $slice)
validate - (Optional - Default: true) Whether to validate that the passed document is a correctly structured mongo document or not.
parser.search(documents, query, sort, validate) - Returns the list of matching
documents sorted.
documents - The array of documents to search.
query - The mongo query to search with.
sort - (Optional) A mongo sort definition to sort by.
validate - (Optional - Default: true) Whether to validate that the passed document is a correctly structured mongo document or not.
parser.inclusive(mongoProjection) - Returns
true if the projection is inclusive,
false if it is exclusive, and
undefined if it is neither. If it is neither, you may either add more exclusive terms or more inclusive terms. Note that fields using the
$elemMatch or
$slice projection operators can be used with both inclusive and exclusive queries and so have no bearing on inclusiveness. See
here for more info on projections.
parser.compressQuery(query) - Returns the same query but shortened, but collapsing $ands, $ors, and $eqs.
QueryPart
--------------
A QueryPart contains the following properties:
field - The field a query part relates to. Can be undefined if the queryPart doesn't related to a specific field.
operator - The operator of a query part.
operand - The operand for a query part. This is the whole value or object contained for the given operation. For example, for {x: 2} the operand is 2, for {x: {$lt:3}} the operand is {$lt:3}, and for {$and:{x:1},{y:2}}, the operand is [{x:1},{y:2}].
parts - A list of QueryPart for parts contained within the given query part. For example, for {a:{$not:{$lt: 4}}} the parts contains the $lt operator, for {$and:[{x:1},{y:2}]} there are two elements in parts: one for {x:1} and one for {y:2}.
implicitField - If false, it means that the parts of this $elemMatch query part contains normal query parts. If true, it means that the parts of this $elemMatch query part contains field operators (like $gt or $in) that will have undefined field properties. implicitField will be undefined for any QueryPart object who's operator is not "$elemMatch".
DotNotationPointers
--------------------
var pointers = parser.DotNotationPointers(rootObject, field) - A function that returns a list of DotNotationPointer objects, which allow you to get and set a nested property inside a mongo document object using dot notation.
rootObject - an object that may have the given field
field - a fieldname, which can be expressed in dot notation (e.g. 'x' and 'x.y.0.z' are both valid for field)
Note that this returns a list because a single
field path can map to many actual properties because of how mongo fans out the matching paths for arrays. For example,
DotNotationPointers({a:[{b:1},{b:2}]},"a.b") will return two pointers, one pointing to "a.0.b" and one pointing to "a.1.b".
DotNotationPointer
------------------
A pointer that can get and set a nested property within a mongo document object using dot notation. The object has the following properties:
pointer.val - a getter/setter value that can be used to both get and set the value selected by the
field passed into the
DotNotationPointers function. Setting the field to
undefined will
delete it from the object.
pointer.property - an array representing the
field, split by '.'. For example, for
'a' this will hold
['a'], and for
'a.b' this will hold
['a','b'].
pointer.propertyInfo - an object with the following properties:
obj - an object reference for use in getting or setting the value pointed to.
last - the property within obj that holds the value pointed to.
Todo
====
- document projection method (and projection operators)
- Add projection to the
search method
- Support crazier mongo operators ($geoIntersects, $near, etc)
Changelog
========
- 2.1.0 - Adding support for
null
- 2.0.3 - Fixing bug where the
validate parameter wasn't being respected in certain cases (Thanks jgpacheco!)
* Exposing compressQuery
* Fixing bug where `map` was treating $or like $and
- 2.0.1 - Fixing bug with fieldless operators (like $text)
* BREAKING CHANGE: For basic equality, part.operator will no longer be undefined, but will be $eq.
* Support $eq
* map method
* query simplification
- 1.1.0 -
DotNotationPointer.val = undefined now deletes the property
- 1.0.8 - Adding a parameter to turn off document validation for
search and matches
* Adding the `search` method
* Changing from use of `eval` to using the more isolated `new Function`
- 1.0.6 - Fixing $in and $nin, which previously didn't work for array values
- 1.0.5 - Fixing bug where {id:1} was returning undefined rather than true for
inclusive
- 1.0.4 - Adding the
inclusive method.
- 1.0.3 - Merging in create propety fix by Toby Ealden
- 1.0.2 - Removing dependency on proto, since this library doesn't really need much object orientedness
- 1.0.1 - Fixing bug in $exists matching
* Adding query matching
* Adding DotNotationPointers document traversal utility
* Adding implicitField property for $elemMatch parts
* Fixing a couple bugs in mapValues
How to Contribute!
============
Anything helps:
- Creating issues (aka tickets/bugs/etc). Please feel free to use issues to report bugs, request features, and discuss changes
- Updating the documentation: ie this readme file. Be bold! Help create amazing documentation!
- Submitting pull requests.
How to submit pull requests:
- Please create an issue and get my input before spending too much time creating a feature. Work with me to ensure your feature or addition is optimal and fits with the purpose of the project.
- Fork the repository
- clone your forked repo onto your machine and run
npm install at its root
- If you're gonna work on multiple separate things, its best to create a separate branch for each of them
- edit!
- If it's a code change, please add to the unit tests (at test/grapetreeTest.js) to verify that your change
- When you're done, run the unit tests and ensure they all pass
- Commit and push your changes
- Submit a pull request: https://help.github.com/articles/creating-a-pull-request
License
=======
Released under the MIT license: http://opensource.org/licenses/MIT
