LearnBoost/mongoose — pull request #947 by aheckmann (2012-06-03 00:37:03+00:00)
Title: [ready] document versioning

When updating an embedded doc property the update object
specifies the path using positional notation:

```js
doc.comments[0].title = 'changed';
doc.save() ->
Model.update(
{ _id: doc._id }
, { $set: { 'comments.0.title': 'changed' }} <== positional
)
```

This is an unsafe operation in that another update may have
occurred between the time we queried the document and
saved. If the other update changed the underlying position of the
elements we refer to in our where clause we will be
modifing the incorrect element. To mitigate the issue this commit
introduces document versioning.

Each document now receives a schema-configurable version key.
This value of this key is incremented whenever a modification to an array
potentially changes any array's elements location.

When saving a document that requires use of positional notation
we now also send along the private document version key in
the where clause set to the value received when first queried. This way,
if a change occurred sometime after we retrieved the document, our
update will fail and an error "No matching document found" is returned.

// future
_decide if we want the version key hidden from JSON.stringify by default (it is an internal prop)_