mongo-parse

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:

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

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!)
• 2.0.2
  • Exposing compressQuery
  • Fixing bug where map was treating $or like $and
• 2.0.1 - Fixing bug with fieldless operators (like $text)
• 2.0.0
  • 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
• 1.0.7
  • 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
• 1.0.0
  • Adding query matching
  • Adding DotNotationPointers document traversal utility
  • Adding implicitField property for $elemMatch parts
  • Fixing a couple bugs in mapValues
• 0.0.1 - first version

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