⚠️ Maintainer Wanted ⚠️

Due lack of time I've decided to not actively maintain this repo any more. I will apply any security related PRs from bots and the community. The package has been stable for quite a long while. There is the odd bug or edge case, but they are far apart and other than that It Just Works:tm:.

I still care to see this package live on, so should any individual, company, or open-source organziation want to take over the project please contact me.

mongoose-hidden 🙈

A Mongoose schema plugin that hooks into toJSON() and toObject() to allow hiding of properties you do not want sent client-side, like passwords and other secrets and sensitive information.

Install

npm i mongoose-hidden

Usage

A simple example that hides passwords:

let mongoose = require('mongoose')
let Schema = mongoose.Schema
let mongooseHidden = require('mongoose-hidden')()

let UserSchema = new Schema(
  name: String,
  password: { type: String, hide: true },
  email: String
)

UserSchema.plugin(mongooseHidden)

let User = mongoose.model('User', UserSchema)
let user = new User({
  name: 'Joe',
  email: 'joe@example.com',
  password: 'secret'
})

user.save(function() {
  console.log(user.toJSON()) // { name: 'Joe', email: 'joe@example.com' }
})

Property params: hide, hideJSON, hideObject

A property will be hidden in all cases when toJSON and toObject is invoked if the property parameter hide is used. Alternatively use hideJSON or hideObject to target either of the serialization functions.

let UserSchema = new Schema(
  ...
  password: { type: String, hideJSON: true }, // hidden for toJSON but not for toObject
  ...
)

The value of hide, hideJSON, and hideObject can be a callback with the following signature:

function (doc, ret) // same as the transform function callback

Option: hidden

If you find yourself hiding the same properties over and over again you can initialize the plugin with the hidden option.

There are two ways to set this up and they can be combined for more granular control.

// Passing constructor parameters
const mongooseHidden = require('mongoose-hidden')({ hidden: { _id: true, password: true } })
UserSchema.plugin(mongooseHidden)

// Passing plugin parameters when attaching to schema
const mongooseHidden = require('mongoose-hidden')()
UserSchema.plugin(mongooseHidden, { hidden: { _id: true, password: true } })

// Here they are used together
const mongooseHidden = require('mongoose-hidden')({ hidden: { _id: true, password: true } })
UserSchema.plugin(mongooseHidden, { hidden: { resetToken: true } })
PaymentSchema.plugin(mongooseHidden, { hidden: { _id: false, authToken: true } }) // unhides _id

//.. another example:

if (app === 'web') {
  UserSchema.plugin(mongooseHidden, { hidden: { _id: true, password: true } })
} else if (app == 'private-api') {
  UserSchema.plugin(mongooseHidden, { hidden: { password: true } })
} else {
  UserSchema.plugin(mongooseHidden)
}

Option: defaultHidden

By default _id and __v properties are hidden. You can override this behaviour, when you load the plugin:

let mongooseHidden = require('mongoose-hidden')({ defaultHidden: { password: true } })
UserSchema.plugin(mongooseHidden)

This effectively overrides the plugin defaults leaving only password hidden and _id and __v are left untouched.

Alternatively if you only want to unhide the params hidden by the plugin by default you can pass the plugin option autoHideJSON and autoHideObject with a value of false.

Option: virtuals

Hiding of virtuals can be done as well. Be sure to include the plugin after you turn on virtuals.

// By default in Mongoose virtuals will not be included. Turn on before enabling plugin.
schema.set('toJSON', { virtuals: true })
schema.set('toObject', { virtuals: true })

// Enable plugin
schema.plugin(mongooseHidden, { virtuals: { fullname: 'hideJSON' } })

The value of the virtuals key can be: hide, hideJSON and hideObject.

For nested virtuals use the path for the key above, e.g. 'nested.virtual': 'hideJSON'.

Note: If you don't turn on virtuals for toObject, fullname in the above example fullname will NOT be hidden despite its hideJSON value.

Option: applyRecursively

Off by default, but when turned on the plugin will attach itself to any child schemas as well.

Transform

The mongoose-hidden is written as a transform function. If you implement your own transform functions be sure to add them prior to applying the plugin. The plugin will then invoke that function before hiding properties.

let mongooseHidden = require('mongoose-hidden')()

// First define transform function
UserSchema.set('toJSON', {
  transform: function (doc, ret, opt) {
    ret['name'] = 'Mr ' + ret['name']
    return ret
  },
})

// Then apply plugin
UserSchema.plugin(mongooseHidden)

All names will now be prefixed with "Mr".

Changelog

See CHANGELOG.md

Limitations

• Always set { getters: true, virtuals: true } before installing plugin if you want virtuals to be returned:

schema.set('toJSON', { getters: true, virtuals: true })
schema.plugin(require(mongooseHidden))

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Albert Hambardzumyan ⚠️ 🐛	Awele 📖	Dan Trocchio 🐛 ⚠️ 💻	Michael Bøcker-Larsen 🐛 💻 🚧 📖	Nathan Phillip Brink 📖	Pavel Evdokimov 🐛 💻 ⚠️	Thomas Sieverding 🐛 💻
lally elias 🐛 💻	mars 🐛 💻	proswdev 🐛 ⚠️ 💻

This project follows the all-contributors specification. Contributions of any kind welcome!