mongoose toObject project

toObject projection plugin for mongoose.

Adds advanced field selection capabilities to toObject with optional predefined levels and level selector capabilities.

Installation

$ npm install mongoose-to-object-project

Basic Usage

Register this plugin last as it will bootstrap any previous transform function option.

schema.plugin(require('mongoose-to-object-project'), {
  // your predefined levels:
  levels: {
    // public level
    public: 'some.deep.field.to.include -some.deep.field.to.exclude',
    // private level
    private: '-password',
    // system level
    system: ''
  },
  // (optional) default level as a String
  level: 'public',
  //  or a synchronous level selector function (preferred method).
  // All transform options are passed on to level selector functions,
  // e.g. we can get the user that requested the transform from `options.user`
  // if user is passed into `toObject` options, like `toObject({ user: req.user })`.
  level: (doc, ret, options) => doc._id.equals(options.user._id) ? 'private' : 'public'
});

Schema Tree Level Definitions

It is possible to define level inclusions and exclusions in the schema declaration.
Mixing inclusions and exclusions are prohibited and throws an error.
Inclusion levels must be predefined in plugin level options.

const schema = new Schema({
    myInvisibleField: {
      type: String,
      level: '-public -private' // visible on levels other than 'public' and 'private'
    },
    myInternalField: {
      type: String,
      level: 'internal' // only visible on 'internal' level, 'internal' must be predefined.
    }
});

schema.plugin(require('mongoose-to-object-project'), {
  levels: {
      'internal': '' // predefintion
  }
});

Plugin Options

schema.plugin(require('mongoose-to-object-project'), options);

levels: Object

Predefined levels to use with a level selector. Key is level name. Value is a Mongoose style dot-notation, space delimited projection. Mixing inclusions and exclusions is possible. Defining at least one inclusion causes all other fields to be excluded automatically like MongoDB. Child inclusions precedes Parent exclusions, e.g. '-parent parent.child1' results in all properties but parent.child1 to be excluded.

levels: {
    public: 'username rank status',
    private: '-password -secretField -secret.deep.field'
}

level: String

Basic static level selector.

level: 'public'

level: Function(doc, ret, options)

Synchronous function that must return level name to use as a string. Preferred level selector method!

• doc - Mongoose Document
• ret - Document as plain Object
• options - Transform options (Same as obj - if specified)

level: (doc, ret, options) => doc._id.equals(options.user._id) ? 'private' : 'public'

Mongoose API Extensions and Modifications

Document#toObject(obj)

Added options:

obj.projection: String - Mongoose style dot-notation, space delimited projection argument. Both inclusions and exclusions are possible but inclusions takes precedence thus excluding all other fields.

obj.level: String - Set level to use. (!)

obj.level: Function(doc, ret, options) - Synchronous function that must return level name to use as a string. (!)

• doc - Mongoose Document
• ret - Document as plain Object
• options - Transform options (Same as obj - if specified)

(!) CAUTION:
The level option is passed to the toObject method call of populated subdocuments and it may not be compatible. Therefore use with caution and if possible, avoid level option completely and depend on schema defaults instead. A Function is the preferred level selector method in plugin options.

Document#set(path, val, [type], [options])

Added options: same as toObject
See: mongoose docs Document#set

Model#toObjectOptionsExtend(obj)

This method extends obj with the default schema toObject options (Adds defaults to prototype chain).
In mongoose the options passed to toObject do not inherit the defaults, this method solves this.

Example:

let options = Model.toObjectOptionsExtend({
    user: req.user,
    projection: '-some.field.to.exclude some.field.to.include'
});
let plainObject = document.toObject(options);

Model#getLevelSchemaTree(levelName)

Returns a clone of the schema tree (plain object) with level projection applied.

Compatibility

Only intended for Mongoose v4 with NodeJS later than v4. Tested with Mongoose 4.2.8.

Q&A

Q. What about toJSON?
A.Use option json: true with toObject, same result.

License

LGPL-3

Copyright (c) 2015 Faleij faleij@gmail.com