@asymmetrik/mongoose-query-service

NPM module to provide common services and plugins for Mongoose models

Table of Contents

• Use
• Install
• Usage
• API
• Contribute
• License

Use

@asymmetrik/mongoose-query-service provides utility services for creating and executing Mongoose queries based on a simple input search object. Additionally, it provides several plugins (pageable and gettable) that can be applied to Mongoose Schemas to allow them to add functionality to those Mongoose Schemas.

Install

Include this module as a dependency of your application in the package.json file. For example:

{
  ...
  dependencies: {
    "@asymmetrik/mongoose-query-service": "latest"
  }
  ...
}

Usage

Include the module via require wherever applicable:

var mongooseQueryService = require('@asymmetrik/mongoose-query-service');

Plugins

Apply any of the plugins to a Mongoose model using the .plugin(...) method provided by Mongoose. For example:

var Person = new Schema({});
Person.plugin(mongooseQueryService.plugins.pageable);

Services

Service methods are available from the base @asymmetrik/mongoose-query-service module, and can be called directly with the parameters defined in the API below.

API

Plugins

The following plugins are available at the top level plugins attribute:

pageable

Applying the pageable plugin at mongooseQueryService.plugins.pageable adds a static method to Mongoose model called pagingSearch that takes an input object parameter with the following attributes:

Attribute	Optional?	Default	Description
query	Yes	{}	Filters to pass to the Mongo query
projection	Yes	{}	Attributes to return in the elements
options	Yes	{}	Query options specified by Mongoose
searchTerms	Yes	null	String of search terms that will be translated into a search on the text index for the model
populate	Yes	null	Populate options specified by Mongoose
sorting	Yes	{}	Attributes for sorting and directions of each sort. Defaults to descending sort. Accepts either an object with a standard Mongo sorting config or an array of objects with property and direction attributes that will be translated into the standard Mongo sorting config.
page	Yes	0	To support paged searches, combines with limit to set the skip attribute of the Mongo query. If limit is not provided, page is not used.
limit	Yes	null	If provided, returns up to this number of results. Combines with the page parameter when setting the skip attribute of the Mongo query

The pagingSearch method returns a Promise resolved with an object with the following attributes:

Attribute	Type	Description
hasMore	Boolean	Indicates if more documents are available if the next page of results is queried
totalSize	Number	The total count of documents that passed the query filter
pageNumber	Number	The current page of results returned. 0 if not paging
pageSize	Number	The current size of each page returned. Set to the input limit value (if provided) or the actual size
totalPages	Number	The number of pages from the the total size and page size configuration
elements	Array	The results that were found matching the current page.

Example:

var Person = new Schema({});
Person.plugin(mongooseQuerySchema.plugins.pageable);

gettable

Applying the gettable plugin at mongooseQueryService.plugins.gettable sets the toObject and toJSON attributes of the Mongoose Schema to { getters: true } so that any get method defined in a Schema Type is used when the toObject or toJSON methods are invoked on the Mongoose model.

Example:

var Person = new Schema({});
Person.plugin(mongooseQuerySchema.plugins.gettable);

Services

buildQuery(query, pagingParameters)

Converts input query and paging parameters into a pageable query object to be used with the pageable plugin's pagingSearch function.

Returns a promise resolved with the resulting search config object with the attributes:

Attribute	Type	Description
query	Boolean	Indicates if more documents are available if the next page of results is queried
sorting	Object	If a sort attribute of pagingParameters is set, builds a sorting object with a direction set by the dir attribute (defaulting to -1 for descending, or set by 'DESC' or 'ASC').
page	Number	Set by the input page attribute of pagingParameters passed into the getPage method
limit	Number	Set by the input size attribute of pagingParameters passed into the getLimit method

validateNonEmpty

Returns true of the input value is not empty (using the lodash isEmpty function)

parseDate

Parse an input as a date. Handles various types of inputs, such as Strings, Date objects, and Numbers.

@param {date} The input representing a date / timestamp

@returns The timestamp in milliseconds since the Unix epoch

getLimit

Get the limit provided by the input query parameters, if there is one. Limit is taken from the size attribute of the input queryParams object. Limit has to be at least 1 with a default value of 20 and no more than the max value.

@param queryParams

@param maxSize (optional) default: 100

@returns {number}

getPage

Page needs to be positive and has no upper bound. Taken from the page attribute of the input queryParams object. Defaults to 0.

@param queryParams

@returns {number}

contains

Determine if an array contains a given element by doing a deep comparison.

@param arr

@param element

@returns {boolean} True if the array contains the given element, false otherwise.

toMongoose

Converts an input Mongo query, possibly with $date and $obj attributes, to a query that Mongoose supports with Date and ObjectId objects mapped from those inputs as appropriate.

@param obj

@returns {object}

Contribute

PRs accepted.

License

See LICENSE for details