docs; transform

slouffka · Nov 8, 2012 · 1af6a99 · 1af6a99
1 parent 1161f79
commit 1af6a99
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 2 deletions.
diff --git a/docs/guide.jade b/docs/guide.jade
@@ -408,6  408,9 @@ block content
     // since we know toJSON is called whenever a js object is stringified:
     console.log(JSON.stringify(m)); // { "_id": "504e0cd7dd992d9be2f20b6f", "name": "Max Headroom is my name" }
 
   :markdown
     To see all available `toJSON/toObject` options, read [this](/docs/api.html#document_Document-toObject).
 
   h4#toObject option: toObject
   :markdown
     Documents have a [toObject](/docs/api.html#document_Document-toObject) method which converts the mongoose document into a plain javascript object. This method accepts a few options. Instead of applying these options on a per-document basis we may declare the options here and have it applied to all of this schemas documents by default.
@@ -424,6  427,9 @@ block content
     var m = new M({ name: 'Max Headroom' });
     console.log(m); // { _id: 504e0cd7dd992d9be2f20b6f, name: 'Max Headroom is my name' }
 
   :markdown
     To see all available `toObject` options, read [this](/docs/api.html#document_Document-toObject).
 
   h4#versionKey option: versionKey
   :markdown
     The `versionKey` is a property set on each document when first created by Mongoose. This keys value contains the internal [revision](http://aaronheckmann.posterous.com/mongoose-v3-part-1-versioning) of the document. The name of this document property is configurable. The default is `__v`. If this conflicts with your application you can configure as such:

diff --git a/lib/document.js b/lib/document.js
@@ -1263,6  1263,9 @@ Document.prototype._doQueue = function () {
  * - `getters` apply all getters (path and virtual getters)
  * - `virtuals` apply virtual getters (can override `getters` option)
  * - `minimize` remove empty objects (defaults to true)
  * - `transform` a transform function to apply to the resulting document before returning
  *
  * ####Getters/Virtuals
  *
  * Example of only applying path getters
  *
@@ -1280,7  1283,80 @@ Document.prototype._doQueue = function () {
  *
  *     schema.set('toObject', { virtuals: true })
  *
- * See [schema options](/docs/guide.html#toObject) for details.
  * ####Transform
  *
  * We may need to perform a transformation of the resulting object based on some criteria, say to remove some sensitive information or return a custom object. In this case we set the optional `transform` function.
  *
  * Transform functions receive three arguments
  *
  *     function (doc, ret, options) {}
  *
  * - `doc` The mongoose document which is being converted
  * - `ret` The plain object representation which has been converted
  * - `options` The options in use (either schema options or the options passed inline)
  *
  * ####Example
  *
  *     // specify the transform schema option
  *     schema.options.toObject.transform = function (doc, ret, options) {
  *       // remove the _id of every document before returning the result
  *       delete ret._id;
  *     }
  *
  *     // without the transformation in the schema
  *     doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }
  *
  *     // with the transformation
  *     doc.toObject(); // { name: 'Wreck-it Ralph' }
  *
  * With transformations we can do a lot more than remove properties. We can even return completely new customized objects:
  *
  *     schema.options.toObject.transform = function (doc, ret, options) {
  *       return { movie: ret.name }
  *     }
  *
  *     // without the transformation in the schema
  *     doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }
  *
  *     // with the transformation
  *     doc.toObject(); // { movie: 'Wreck-it Ralph' }
  *
  * _Note: if a transform function returns `undefined`, the return value will be ignored._
  *
  * Transformations may also be applied inline, overridding any transform set in the options:
  *
  *     function xform (doc, ret, options) {
  *       return { inline: ret.name, custom: true }
  *     }
  *
  *     // pass the transform as an inline option
  *     doc.toObject({ transform: xform }); // { inline: 'Wreck-it Ralph', custom: true }
  *
  * _Note: if you call `toObject` and pass any options, the transform declared in your schema options will __not__ be applied. To force its application pass `transform: true`_
  *
  *     schema.options.toObject.hide = '_id';
  *     schema.options.toObject.transform = function (doc, ret, options) {
  *       if (options.hide) {
  *         options.hide.split(' ').forEach(function (prop) {
  *           delete ret[prop];
  *         });
  *       }
  *     }
  *
  *     var doc = new Doc({ _id: 'anId', secret: 47, name: 'Wreck-it Ralph' });
  *     doc.toObject();                                        // { secret: 47, name: 'Wreck-it Ralph' }
  *     doc.toObject({ hide: 'secret _id' });                  // { _id: 'anId', secret: 47, name: 'Wreck-it Ralph' }
  *     doc.toObject({ hide: 'secret _id', transform: true }); // { name: 'Wreck-it Ralph' }
  *
  * Transforms are applied to the document _and each of its sub-documents_. To determine whether or not you are currently operating on a sub-document you might use the following guard:
  *
  *     if ('function' == typeof doc.ownerDocument) {
  *       // working with a sub doc
  *     }
  *
  * Transforms, like all of these options, are also available for `toJSON`.
  *
  * See [schema options](/docs/guide.html#toObject) for some more details.
  *
  * @param {Object} [options]
  * @return {Object} js object
@@ -1371,7  1447,7 @@ function applyGetters (self, json, type, options) {
  *
  * See [schema options](/docs/guide.html#toJSON) for details.
  *
- * @param {Object} options same options as `Document#toObject`
  * @param {Object} options same options as [Document#toObject](#document_Document-toObject)
  * @return {Object}
  * @see Document#toObject #document_Document-toObject