minq
fluent queries for mongodb using promises
installation
$ npm install minq
usage example
var minq = require('minq')
minq.connect(connectionString)
minq
.from('foo')
.where({name: minq.like('John')})
.select(['name', 'email', 'homeAddress.zipCode'])
.limit(1000)
.toArray()
minq
.from('foo')
.skip(20)
.limit(50)
.sort('name')
.toArray()
minq
.from('foo')
.stream()
minq
.from('foo')
.where({email: /lol\.com$/)
.count()
minq
.from('foo')
.insert({name: 'Melissa', email: '[email protected]'})
minq
.drop('foo')
tools
good to know
minq queries are contstructed starting with a db and collection, then by adding various options and constraints, and ending with a finalizer. Finalizers return a Q promise.
For .one
and .toArray
, an .expect(number)
option can be used. If the query does not match the expected number, the promise will be rejected.
Read Finalizers are: .toArray
.one
.stream
.count
.assertExists
.checkExists
Note, .stream
returns a node Stream, not a promise
Mutator Finalizers are: .insert
.update
.upsert
.remove
.removeAll
.pull
.findAndModify
api reference
Uses jsig notation.
minq(db: Object) => Query
where db is a mongodb db connection object
minq.like(pattern: String) => RegExp
builds a RegExp for use with a where clause, minq.like
helps by escaping characters for you. It creates a case-insensitive regex. See like
minq.connect(connectionString: String) => Promise<MinqDb>
Set the default connection for minq to use. connectionString
should be a MongoDb uri
type MinqDb : {
$collectionName: Query
}
MinqDb is an object with property getters for each collection, similar to the db
object in mongoshell
.
Example:
minq.connect(cs).then(function (db) {
return db.users.where({email: /@gmail.com$/}).toArray()
})
minq.getCollections() => Promise<Array<String>>
Returns a promise for an array of strings containing the collection names for the default connection.
Query#clone() => Query
Deep clones a query object (most useful before the query has been executed!)
Query#from(collectionName: String) => Query
returns a new Query object configured with the collection name.
alias: Query#collection
Query#where(query: Object) => Query
(optional) query
is a mongodb query object, with standard $
operators
where
can be called multiple times to add multiple query terms. Mongodb joins them with logical AND
, see $and.
Query#select(fields: Object) => Query
(optional) fields
is a mongodb projection object, with keys corresponding to the fields of the document you want to return
Query#options(opts: Object) => Query
(optional) configure any additional options, for example {multi: true}
Query#sort(by: Object|Array) => Query
(optional) by
is a mongodb sort order option.
alias: Query#orderBy
Query#limit(number: Number) => Query
(optional) number
is a Number for the maximum number of documents you want to return.
alias: Query#take
Query#skip(number: Number) => Query
(optional) number
is a Number for the number of documents which otherwise match the query that you want to skip in the result
Query#toArray() => Promise<Array>
Read Finalizer. The promise is resolved with the array of documents matching your query or an empty array.
Query#one() => Promise<Object>
Read Finalizer. The promise is resolved with the document matching your query or null
.
alias: Query#first
, Query#firstOrDefault
. Note, first
does not throw on null, unlike in linq. Think of it as firstOrDefault
.
Query#deferToArray => () => Promise<Array>
Thunked Query.toArray
.
Query#deferOne => () => Promise<Object>
Thunked Query.one
. Other Finalizers begin executing a query immediately. This method returns a function which can be called to invoke a query and return a promise of the response. This can be useful for memoized caching and other situations.
Query#stream() => ReadStream<Object>
Read Finalizer. The stream is a mongo read stream of documents matching your query.
Query#forEach(iterator: (Object) => Promise?) => Promise
Read Finalizer. Streams the results of a query. If iterator
returns a promise, will await each of the promises,
for example if performing batch updates.
Returns a void Promise to rejoin program execution
once all results have been iterated.
Query#insert(doc: Object) => Promise<Object>
Mutator Finalizer. Insert a document collection. The promise is the inserted object, including _id if assigned by db.
Query#update(changes: Object) => Promise<Number>
Mutator Finalizer. Update documents in a collection with changes
, a mongodb setter or unsetter. Use with Query.where
or include _id
on the changes
object. The promise is the count of updated documents.
Query#upsert(setter: Object) => Promise<Number>
Mutator Finalizer. Create or update a document in a collection with setter
, a mongodb setter. The promise is the count of updated documents.
Query#remove() => Promise<Number>
Mutator Finalizer. Remove documents matching a where
query. The promise is the number of documents removed. Rejected if no where
query is specified.
Query#removeAll() => Promise<Number>
Mutator Finalizer. Remove all documents in a collection. The promise is the number of documents removed.
Query#drop(collection: String) => Promise
Finalizer. Drop an entire collection.
running the tests
$ npm install
$ npm test
contributors
jden [email protected]
license
MIT. (c) jden [email protected]. See LICENSE.md.