# pmongo

> Promised wrapper for mongodb native driver

Latest version **1.0.0** (published 2015-07-28) · Apache 2.0 license · 0 weekly downloads

## Install

```sh
npm install pmongo
pnpm add pmongo
yarn add pmongo
bun add pmongo
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2015-07-28 |
| First published | 2015-07-28 |
| Weekly downloads | 0 |
| License | Apache 2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Liandri Ltd |
| Maintainers | liandri-corp |

## Links

- npm: https://www.npmjs.com/package/pmongo
- Repository: https://github.com/liandri-corp/pmongo
- Issues: https://github.com/liandri-corp/pmongo/issues
- npm.io page: https://npm.io/package/pmongo

## Dependencies (1)

- [readable-stream](https://npm.io/package/readable-stream.md) ^2.0.2

## Recent versions

- 1.0.0 (latest) — 2015-07-28

## README

# pmongo
Promised wrapper for mongodb native driver

## Install
Pmongo is available through [npm](http://npmjs.org):

	npm install pmongo

Pmongo is based on native Promises.  
That's why you must have [nodejs](https://nodejs.org/) 0.11 version or greater or [iojs](https://iojs.org/en/index.html)  
Also pmongo depends on [node-mongodb-native](http://mongodb.github.io/node-mongodb-native/2.0/) but it is not included
in `package.json` you must specify it as a dependency in your root project

## Usage
Use pmongo just like mongojs, except you can also use the returned promise instead of the
callback.  Note that a promise isn't returned if a callback is specified.

```js
var pmongo = require('pmongo');
var db = pmongo(connectionString, [collections]);
```

The connection string should follow the format desribed in [the mongo connection string docs](http://docs.mongodb.org/manual/reference/connection-string/).
Some examples of this could be:

``` js
// simple usage for a local db
var db = pmongo('mydb', ['mycollection']);

// the db is on a remote server (the port default to mongo)
var db = pmongo('example.com/mydb', ['mycollection']);

// we can also provide some credentials
var db = pmongo('username:password@example.com/mydb', ['mycollection']);

// connect now, and worry about collections later
var db = pmongo('mydb');
var mycollection = db.collection('mycollection');
```

After we connected we can query or update the database just how we would using the mongo API with the exception that the functions return
a promise for the result rather than the result itself.  Cursor operations such as `find()` and `sort()` return a **cursor**; to get a
promise for the result, you have to force evaluation using `toArray()`.  Alternatively, you can just call `then()` on the cursor and it will call `toArray()` for you, returning a promise.  The function `findOne()` returns a promise immediately, not a cursor.

``` js
// find everything
db.mycollection.find().toArray().then(function(docs){
	// docs is an array of all the documents in mycollection
});

// find everything, but sort by name
db.mycollection.find().sort({name:1}).toArray().then(function(docs) {
	// docs is now a sorted array
});

// find a document using a native ObjectId
db.mycollection.findOne({
	_id: pmongo.ObjectId('523209c4561c640000000001')
}).then(function(doc) {
	// doc._id.toString() === '523209c4561c640000000001'
});

// find all named 'mathias' and increment their level
db.mycollection.update({name:'mathias'}, {$inc:{level:1}}, {multi:true})
	.then(function(lastErrorObject) {
		// the update is complete
	});

// find one named 'mathias', tag him as a contributor and return the modified doc
db.mycollection.findAndModify({
	query: { name: 'mathias' },
	update: { $set: { tag:'maintainer' } },
	new: true
})
.then(function(doc) {
	// doc.tag === 'maintainer'
});

// use the save function to just save a document
db.mycollection.save({created:'just now'});

```

The `forEach` function is a special case.  The library supports the mongojs style:

``` js
// iterate over all whose level is greater than 90.
db.mycollection.find({level:{$gt:90}}).forEach(function(err, doc) {
	if (doc) {
      //do things with doc
    } else {
      //the callback gets called at the end with a null doc
      console.log('Finished!');
    }
});
```

It also supports a promise version.  If you pass a callback to the `forEach` function with only one argument, you get the promise version.  The promise will resolve (with `undefined`) when the callback has been called for all documents.

``` js
// iterate over all whose level is greater than 90 (promise version)
db.mycollection.find({level:{$gt:90}}).forEach(function(doc) {
	//do things with doc
})
.then(function () {
  console.log('Finished!');
});
```

If you provide a callback to `find` or any cursor config operation mongojs will call `toArray` for you

``` js
db.mycollection.find({}, function(err, docs) { ... });

db.mycollection.find({}).limit(2).skip(1, function(err, docs) { ... });
```
is the same as

``` js
db.mycollection.find({}).toArray(function(err, docs) { ... });

db.mycollection.find({}).limit(2).skip(1).toArray(function(err, docs) { ... });
```

If you are using the promises API, **you must call toArray() on cursors** before a promise can be obtained.  E.g.:

``` js
db.mycollection.find().limit(2).skip(1).toArray()
	.then(function (docs) {
		// ...
	});
```

For more detailed information about the different usages of update and querying see [the mongo docs](http://www.mongodb.org/display/DOCS/Manual)

## Streaming cursors

All cursors are a [readable stream](http://nodejs.org/api/stream.html#stream_readable_stream) of objects.

``` js
var JSONStream = require('JSONStream');

// pipe all documents in mycollection to stdout
db.mycollection.find({}).pipe(JSONStream.stringify()).pipe(process.stdout);
```

Notice that you should pipe the cursor through a stringifier (like [JSONStream](https://github.com/dominictarr/JSONStream))
if you want to pipe it to a serial stream like a http response.

## Tailable cursors

If you are using a capped collection you can create a [tailable cursor](http://docs.mongodb.org/manual/tutorial/create-tailable-cursor/) to that collection by adding `tailable:true` to the find options

``` js
var cursor = db.mycollection.find({}, {}, {tailable:true, timeout:false});

// since all cursors are streams we can just listen for data
cursor.on('data', function(doc) {
	console.log('new document', doc);
});
```

Note that you need to explicitly set the selection parameter in the `find` call.

## Database commands

With pmongo you can run database commands just like with the mongo shell using `db.runCommand()`

```js
db.runCommand({ping:1}).then(function(res) {
	if(!err && res.ok) console.log("we're up");
});
```

or `db.collection.runCommand()`

```js
db.things.runCommand('count').then(function(res) {
	console.log(res);
});
```

## Replication Sets

Pmongo can also connect to a mongo replication set by providing a connection string with multiple hosts

``` js
var db = pmongo('rs-1.com,rs-2.com,rs-3.com/mydb?slaveOk=true', ['mycollection']);
```

For more detailed information about replica sets see [the mongo replication docs](http://www.mongodb.org/display/DOCS/Replica+Sets)

---
_Source: https://npm.io/package/pmongo · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._