mongo-query-builder-chain

JS library for easily generating mongodb queries by method chaining.

Usage

Load the library in a file

var mongoQBChain = require("mongo-query-builder-chain");

Initialize an empty mongodb query

var mongoQuery = new mongoQBChain.MongoQuery();

Initialize a mongodb query with predefined body

var mongoQuery = new mongoQBChain.MongoQuery({
  query: {
    field1: "value_or_operator1",
    field2: "value_or_operator2",
    field3: "value_or_operator3"
  },
  sort: {
    "field1.field11.field111": sort_direction1,
    "field2.field21": sort_direction2,
    field3: sort_direction3
  }
});

Query methods

Add a key field11 under field1 with a value to an existing query and ability to merge if a value with the same key already exists (in case value is of object type)

mongoQuery.addToQuery(['field1', 'field11'], value, merge);

If the key already exists, only its value will be changed. The value can be primitive, object with containing the reserved supported operators. The location of the key inside the query is determined by the provided array with the value at the beginning denoting the root location and the value at the end denoting the exact name of the key. If any portion of the path does not exist in the current body of the query, it is automatically created. It returns the current state of the mongoQuery object.

Checks whether the key field11 under field1 exists in the query. It returns true or false.

mongoQuery.hasKey(['field1', 'field11']);

Create a clause with a key clause_field with a value clause_value

mongoQuery.clause('clause_field', 'clause_value')

It returns an object with one key and its value.

Remove the key field1 with its associated value if any

mongoQuery.removeFromQuery(['field1']);

The location of the key inside the query is determined by the provided array with the value at the beginning denoting the root location and the value at the end denoting the exact name of the key. By removing the specified key, any kind of value (primitive or object) associated with it, will be removed. It returns the current state of the mongoQuery object.

Query operators

Partial support for current mongodb query operators.

Comparison operators

Full support for the current mongodb query comparison operators.

Equal to a specified value

mongoQuery.$eq(value)

It returns the object containing only the $eq operator as key and its value provided by the argument.

Inclusion in the specified array

mongoQuery.$in(array)

It returns the object containing only the $in operator as key and its value as array provided by the argument.

Similar usage is applied for the rest of the comparison operators.

Element operators

Partial support for the current mongodb query element operators.

Existing of a specified field by value

mongoQuery.$exists(value)

It returns the object containing only the $exists operator as key and its value provided by the argument. The default value is true.

Date operators

Partial support fo the current mongodb query date operators.

Adds a date match by a specified value

mongoQuery.$date(value)

It returns the object containing only the $date operator as key and its value provided by the argument. the provided argument must be of string type.

Evaluation operators

Partial support for the current mongodb query evaluation operators.

Add a text search by a specified value

mongoQuery.$search(value)

It returns the object containing the $text operator and its value - the $search operator as key and its value provided by the argument.

Remove the current text search on the keyPath location

mongoQuery.$searchRemove(keyPath)

If the $search key is the last remaining in the $text operator, the $text key will be removed automatically. It returns the current state of the mongoQuery object.

Add a text language by a specified value (the default value is "none")

mongoQuery.$language(value)

It returns the object containing only the $text operator and its value with the $language operator as key and its value provided by the argument. If the $text key does not exist in the query, it is added automatically.

Remove the current text language on the keyPath location

mongoQuery.$languageRemove(keyPath)

If the $language key is the last remaining in the $text operator, the $text key will be removed automatically. It returns the current state of the mongoQuery object.

Logical operators

Partial support for the current mongodb query logical operators.

Add an $or operator on a location keyPath as an array of fields, on clause1 and clause2

mongoQuery.$or(keyPath, [clause1, clause2])

It returns the current state of the mongoQuery object containing the $or operator under the keyPath.

Remove a clause from the $or operator under the location keyPath

mongoQuery.$orRemoveFrom(keyPath, 'clause_field1')

If the clause with the key 'clause_field1' is the last remaining in the $or operator, the $or operator will be removed automatically from the query. It returns the current state of the mongoQuery object.

Remove the $or operator under the location keyPath

mongoQuery.$orClear(keyPath)

If not specified, the default value of the keyPath is an empty array. It returns the current state of the mongoQuery object.

Sorting

Add a sort criteria with key field1.field11 that will alter the current sorting by descending (the default value for the sorting direction is ascending i.e. 1, and does not have to be provided)

mongoQuery.sort("field1.field11", -1);

Any previous sorting is maintained and the sort key is added at the end of the sort part of the body. It returns the current state of the mongoQuery object. It returns the current state of the mongoQuery object.

Clear existing sort criteria

mongoQuery.sortClear();

It returns the current state of the mongoQuery object.

Projecting

Partial support for the current mongodb query projection.

Add a projection criteria with keys field1, field2, field3 intended to be excluded

mongoQuery.projectionAdd(['field1', 'field2', 'field3'], 0);

The second argument, denoting the inclusion of the fields, accepts only 0 and 1 as values. It returns the current state of the mongoQuery object.

Add a projection criteria with keys field4, field5 intended to be included

mongoQuery.projectionAdd(['field4', 'field5']);

The default inclusion value is 1 and therefore the second argument is not necessary.

Remove a projection criteria with key field4

mongoQuery.projectionRemove('field4');

It returns the current state of the mongoQuery object.

Getting the query

Get the complete body of the query, ready for making a request to mongodb

mongoQuery.getValue();