Middleware for mongoose that makes filtering, sorting, pagination and projection chainable and simple to apply
npm install mongoose-middleware
Then, simply require the library and pass in the instance of the
require('mongoose') statement to the initialize method as follows:
var mongoose = ;;
Optionally configure max documents for pagination:
var mongoose = ;;
This project aims to make basic searching, sorting, filtering and projection tasks against documents stored in MongoDB trivial via Mongoose middleware. The middle exposes a set of Mongoose Query object chainable methods for ease and simplicity of use.
The following example shows usage of field projections, mandatory and optional search filters, sorting and pagination.
varmongoose =Schema = mongooseSchemaKittehModel = mongoose;;/*Retrieve the name, home and features.color of kittehs that live in Seattle,that are named "Hamish" and that are brindle, black or white in color and bornprior to January 1st, 2014. The results should be sorted by birthday indescending order and name in ascending order.*/var options =filters :field : 'name' 'home' 'features.color'mandatory :contains :home : 'seattle'exact :name : 'Hamish'lessThan :birthday : 2014 1 1optional :contains :'features.color' : 'brindle' 'black' 'white'sort : '-birthday' 'name'start : 0count : 500;KittehModel;
var options =start : 0count : 500;KittehModel;
The options submitted to the
page(options, callback) middleware method are echoed back in the response along with the results of the query and the total count of results matching the specified filters.
options :count : 500filters :field : 'name' 'home' 'features.color'mandatory :contains :'features.color' : 'brindle' 'black' 'white'exact :name : 'Hamish'optional :contains :home : 'seattle'sort : '-birthday' 'name'start : 0results : ... // the first 500 brindled, black or white kittehs named Hamish in Seattletotal : 734
The maxDocs property may optionally be specified on initialize to ensure no more than the specified number of documents are ever returned from a query. Please note that this does not affect the ability for the component to return the correct total count of results when using the pagination middleware function.
var mongoose = ;;
In order specify specific fields from a document in Mongo to be returned, the fields filter may be used.
var options =filters :field : 'name' 'home' 'qualities.demeanor';KittehModel;
Alternatively, a single field can be specified (not in an array):
Filters can be used in three ways: mandatory, optional and keyword searches. Additionally, for mandatory and optional searches, exact, contains and startsWith string pattern matches may be used.
The following filters can be used for mandatory, optional, and keyword searches.
exact- Matches the string letter for letter, but is not case sensitive
contains- Matches documents where the string exists as a substring of the field (similar to a where field like '%term%' query in a relational datastore)
startsWith- Matches documents where field begins with the string supplied (similar to a where field like 'term%' query in a relational datastore)
endsWith- Matches documents where field ends with the string supplied (similar to a where field like '%term' query in a relational datastore)
The following filters can ONLY be used for mandatory and keyword searches.
gt) - Matches documents where field value is greater than supplied number or Date value in query
gte) - Matches documents where field value is greater than or equal to supplied number or Date value in query
lt) - Matches documents where field value is less than supplied number or Date value in query
lte) - Matches documents where field value is less than or equal to supplied number or Date value in query
ne) - Matches documents where field value is not equal to the supplied value
Mandatory filters require that the document matches the specified search options or they will not be returned.
Optional searches allow you to specify more than one filter that you would like to match results for. This type of search is great for cases where you need to find documents that either match "this" OR "that". As an example, image you are searching for cats that are either manx, siamese or tabby, you would configure the filter as follows:
var options =filters :optional :exact :breed : 'manx' 'siamese' 'tabby';KittehModel;
Keyword searches provide a convenient way to search more than one field with a single string. Additionally, keyword filters work differently from mandatory and optional filters in that they do not support
startsWith. Instead the matches look for occurrences in a similar way to
contains but with the ability to specify multiple terms in the query.
The following query will search for documents where the name, description or knownAliases contain Heathcliff the Cat. If the name (or description and knownAliases) contains "Cat, the Heathcliff", "the Cat, Heathcliff", "Heathcliff Cat, the" and "the Heathcliff Cat", those results will also be returned.
var options =filters :keyword :fields : 'name' 'description' 'knownAliases'term : 'Heathcliff the Cat';KittehModel;
If you would like to ensure that matches of "Heathcliff the Cat" in that exact format are returned, simply enclose the term in quotes:
var options =filters :keyword :fields : 'name' 'description' 'knownAliases'term : '"Heathcliff the Cat"';
Sorting, at this point, is fairly basic. All descending sorts will be applied prior to ascending sorts when specifying multiple sorts of each direction. Supports JSON API specs.
var options =sort : '-name' '-description' '-knownAliases';KittehModel;
You may also specify a single field (not an array) as well as an object for both descending and ascending sorts:
var options =sort : '-name';
var options =sort :'name': -1'description': 1;
var options =sort : 'name' 'description' 'knownAliases';KittehModel;
You may also specify ascending and descending sorts together:
var options =sort : 'name' '-birthday' '-home';
Pagination is performed by swapping the
exec() function of Mongoose with
page(). Pagination may be specified as follows:
var options =start : 0count : 100;KittehModel;
When using pagination, maxDocs may specified via the
initialize() function of the library which will result in no more than that maximum number of documents being returned.
varmongoose =KittehModel = ;;var options =start : 0count : 100;KittehModel;
Please note: While the maxDocs will limit the number of returned documents, it will not affect the total count value of matching documents.
Pagination returns the specified start, count and overall total numer of matching documents as a wrapper to the results from Mongo.
options :count : 50start : 0results : ...total : 734
mongoose-middleware provides a helper function if you need to programmatically add filters to the query. It will intelligently merge structures, and ensure that elements are turned into Arrays when they need to be.
var base =filters :mandatory :exact :breed : 'manx' 'siamese' 'tabby'name : 'Ballard'model =filters :mandatory :exact :breed : 'calico'name : 'Fremont'merged = ;
filters :mandatory :exact :breed : 'manx' 'siamese' 'tabby' 'calico'name : 'Ballard' 'Fremont'
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associateddocumentation files (the "Software"), to deal in the Software without restriction, including without limitationthe rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,and to permit persons to whom the Software is furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all copies or substantial portionsof the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITEDTO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALLTHE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OFCONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGSIN THE SOFTWARE.