LearnBoost/mongoose — pull request #803 by aheckmann (2012-03-30 13:31:41+00:00)
Title: Add findAndModify support

The `findAndModify` MongoDB command is a few different operations smashed into one. They break down into two concepts:

1) an update of zero or one document
2) the removal of zero or one document

After the above operation completes, the affected document (if any) is returned to the client. This pull request introduces findAnyModify support through two new methods: `updateOne`, and `removeOne`:

Model additions:

`Model.updateOne(query, update, options, callback)`
`Model.removeOne(query, options, callback)`

Query additions:

`Query#updateOne(query, update, options, callback)`
`Query#removeOne(query, options, callback)`

All queries and update documents are casted according to their schemas.

### Model.updateOne()

Issues a mongodb findAndModify update command.

Finds a matching document, updates it according to the `update` arg, passing any `options`, and returns the found document (if any) to the callback. The query executes immediately if `callback` is passed else a Query object is returned.

Available options:

`new`: bool - true to return the modified document rather than the original. defaults to true
`upsert`: bool - creates the object if it doesn't exist. defaults to false.
`sort`: if multiple documents are found by the conditions, sets the sort order to choose which doc to update

Examples:

A.updateOne(conditions, update, options, callback) // executes
A.updateOne(conditions, update, options) // returns Query
A.updateOne(conditions, update, callback) // executes
A.updateOne(conditions, update) // returns Query
A.updateOne() // returns Query

### Query#updateOne()

Same as Model.updateOne().

Examples:

A.where().updateOne(conditions, update, options, callback) // executes
A.where().updateOne(conditions, update, options) // returns Query
A.where().updateOne(conditions, update, callback) // executes
A.where().updateOne(conditions, update) // returns Query
A.where().updateOne() // returns Query

### Model.removeOne()

Issue a mongodb findAndModify remove command.

Finds a matching document, removes it, passing the found document (if any) to the callback. Executes immediately if `callback` is passed else a Query object is returned.

Available options:

`sort`: if multiple documents are found by the conditions, sets the sort order to choose which doc to update

Examples:

A.removeOne(conditions, options, callback) // executes
A.removeOne(conditions, options) // return Query
A.removeOne(conditions, callback) // executes
A.removeOne(conditions) // returns Query
A.removeOne() // returns Query

### Query#removeOne()

Same as Model.removeOne().

Examples:

A.where().removeOne(conditions, options, callback) // executes
A.where().removeOne(conditions, options) // return Query
A.where().removeOne(conditions, callback) // executes
A.where().removeOne(conditions) // returns Query
A.where().removeOne() // returns Query