lib/schematype.js
'use strict';
var error = require('./error')
, utils = require('./utils');
var errorMessages = error.messages;
var CastError = error.CastError;
var ValidatorError = error.ValidatorError;
/**
* SchemaType constructor
*
* @param {String} path
* @param {Object} [options]
* @param {String} [instance]
* @api public
*/
function SchemaType (path, options, instance) {
this.path = path;
this.instance = instance;
this.validators = [];
this.setters = [];
this.getters = [];
this.options = options;
for (var i in options) if (this[i] && 'function' === typeof this[i]) {
var opts = Array.isArray(options[i])
? options[i]
: [options[i]];
this[i].apply(this, opts);
}
}
/**
* Sets a default value for this SchemaType.
*
* ####Example:
*
* var schema = new Schema({ n: { type: Number, default: 10 })
* var M = db.model('M', schema)
* var m = new M;
* console.log(m.n) // 10
*
* Defaults can be either `functions` which return the value to use as the default or the literal value itself. Either way, the value will be cast based on its schema type before being set during document creation.
*
* ####Example:
*
* // values are cast:
* var schema = new Schema({ aNumber: Number, default: "4.815162342" })
* var M = db.model('M', schema)
* var m = new M;
* console.log(m.aNumber) // 4.815162342
*
* // default unique objects for Mixed types:
* var schema = new Schema({ mixed: Schema.Types.Mixed });
* schema.path('mixed').default(function () {
* return {};
* });
*
* // if we don't use a function to return object literals for Mixed defaults,
* // each document will receive a reference to the same object literal creating
* // a "shared" object instance:
* var schema = new Schema({ mixed: Schema.Types.Mixed });
* schema.path('mixed').default({});
* var M = db.model('M', schema);
* var m1 = new M;
* m1.mixed.added = 1;
* console.log(m1.mixed); // { added: 1 }
* var m2 = new M;
* console.log(m2.mixed); // { added: 1 }
*
* @param {Function|any} val the default value
* @return {defaultValue}
* @api public
*/
SchemaType.prototype.default = function (val) {
if (1 === arguments.length) {
this.defaultValue = typeof val === 'function'
? val
: this.cast( val );
return this;
} else if ( arguments.length > 1 ) {
this.defaultValue = _.toArray( arguments );
}
return this.defaultValue;
};
/**
* Adds a setter to this schematype.
*
* ####Example:
*
* function capitalize (val) {
* if ('string' != typeof val) val = '';
* return val.charAt(0).toUpperCase() + val.substring(1);
* }
*
* // defining within the schema
* var s = new Schema({ name: { type: String, set: capitalize }})
*
* // or by retreiving its SchemaType
* var s = new Schema({ name: String })
* s.path('name').set(capitalize)
*
* Setters allow you to transform the data before it gets to the raw mongodb document and is set as a value on an actual key.
*
* Suppose you are implementing user registration for a website. Users provide an email and password, which gets saved to mongodb. The email is a string that you will want to normalize to lower case, in order to avoid one email having more than one account -- e.g., otherwise, avenue@q.com can be registered for 2 accounts via avenue@q.com and AvEnUe@Q.CoM.
*
* You can set up email lower case normalization easily via a Storage setter.
*
* function toLower (v) {
* return v.toLowerCase();
* }
*
* var UserSchema = new Schema({
* email: { type: String, set: toLower }
* })
*
* var User = db.model('User', UserSchema)
*
* var user = new User({email: 'AVENUE@Q.COM'})
* console.log(user.email); // 'avenue@q.com'
*
* // or
* var user = new User
* user.email = 'Avenue@Q.com'
* console.log(user.email) // 'avenue@q.com'
*
* As you can see above, setters allow you to transform the data before it gets to the raw mongodb document and is set as a value on an actual key.
*
* _NOTE: we could have also just used the built-in `lowercase: true` SchemaType option instead of defining our own function._
*
* new Schema({ email: { type: String, lowercase: true }})
*
* Setters are also passed a second argument, the schematype on which the setter was defined. This allows for tailored behavior based on options passed in the schema.
*
* function inspector (val, schematype) {
* if (schematype.options.required) {
* return schematype.path + ' is required';
* } else {
* return val;
* }
* }
*
* var VirusSchema = new Schema({
* name: { type: String, required: true, set: inspector },
* taxonomy: { type: String, set: inspector }
* })
*
* var Virus = db.model('Virus', VirusSchema);
* var v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' });
*
* console.log(v.name); // name is required
* console.log(v.taxonomy); // Parvovirinae
*
* @param {Function} fn
* @return {SchemaType} this
* @api public
*/
SchemaType.prototype.set = function (fn) {
if ('function' !== typeof fn)
throw new TypeError('A setter must be a function.');
this.setters.push(fn);
return this;
};
/**
* Adds a getter to this schematype.
*
* ####Example:
*
* function dob (val) {
* if (!val) return val;
* return (val.getMonth() + 1) + "/" + val.getDate() + "/" + val.getFullYear();
* }
*
* // defining within the schema
* var s = new Schema({ born: { type: Date, get: dob })
*
* // or by retreiving its SchemaType
* var s = new Schema({ born: Date })
* s.path('born').get(dob)
*
* Getters allow you to transform the representation of the data as it travels from the raw mongodb document to the value that you see.
*
* Suppose you are storing credit card numbers and you want to hide everything except the last 4 digits to the mongoose user. You can do so by defining a getter in the following way:
*
* function obfuscate (cc) {
* return '****-****-****-' + cc.slice(cc.length-4, cc.length);
* }
*
* var AccountSchema = new Schema({
* creditCardNumber: { type: String, get: obfuscate }
* });
*
* var Account = db.model('Account', AccountSchema);
*
* Account.findById(id, function (err, found) {
* console.log(found.creditCardNumber); // '****-****-****-1234'
* });
*
* Getters are also passed a second argument, the schematype on which the getter was defined. This allows for tailored behavior based on options passed in the schema.
*
* function inspector (val, schematype) {
* if (schematype.options.required) {
* return schematype.path + ' is required';
* } else {
* return schematype.path + ' is not';
* }
* }
*
* var VirusSchema = new Schema({
* name: { type: String, required: true, get: inspector },
* taxonomy: { type: String, get: inspector }
* })
*
* var Virus = db.model('Virus', VirusSchema);
*
* Virus.findById(id, function (err, virus) {
* console.log(virus.name); // name is required
* console.log(virus.taxonomy); // taxonomy is not
* })
*
* @param {Function} fn
* @return {SchemaType} this
* @api public
*/
SchemaType.prototype.get = function (fn) {
if ('function' !== typeof fn)
throw new TypeError('A getter must be a function.');
this.getters.push(fn);
return this;
};
/**
* Adds validator(s) for this document path.
*
* Validators always receive the value to validate as their first argument and must return `Boolean`. Returning `false` means validation failed.
*
* The error message argument is optional. If not passed, the [default generic error message template](#error_messages_StorageError-messages) will be used.
*
* ####Examples:
*
* // make sure every value is equal to "something"
* function validator (val) {
* return val == 'something';
* }
* new Schema({ name: { type: String, validate: validator }});
*
* // with a custom error message
*
* var custom = [validator, 'Uh oh, {PATH} does not equal "something".']
* new Schema({ name: { type: String, validate: custom }});
*
* // adding many validators at a time
*
* var many = [
* { validator: validator, msg: 'uh oh' }
* , { validator: anotherValidator, msg: 'failed' }
* ]
* new Schema({ name: { type: String, validate: many }});
*
* // or utilizing SchemaType methods directly:
*
* var schema = new Schema({ name: 'string' });
* schema.path('name').validate(validator, 'validation of `{PATH}` failed with value `{VALUE}`');
*
* ####Error message templates:
*
* From the examples above, you may have noticed that error messages support baseic templating. There are a few other template keywords besides `{PATH}` and `{VALUE}` too. To find out more, details are available [here](#error_messages_StorageError-messages)
*
* ####Asynchronous validation:
*
* Passing a validator function that receives two arguments tells mongoose that the validator is an asynchronous validator. The first argument passed to the validator function is the value being validated. The second argument is a callback function that must called when you finish validating the value and passed either `true` or `false` to communicate either success or failure respectively.
*
* schema.path('name').validate(function (value, respond) {
* doStuff(value, function () {
* ...
* respond(false); // validation failed
* })
* }, '{PATH} failed validation.');
*
* You might use asynchronous validators to retreive other documents from the database to validate against or to meet other I/O bound validation needs.
*
* Validation occurs `pre('save')` or whenever you manually execute [document#validate](#document_Document-validate).
*
* If validation fails during `pre('save')` and no callback was passed to receive the error, an `error` event will be emitted on your Models associated db [connection](#connection_Connection), passing the validation error object along.
*
* var conn = mongoose.createConnection(..);
* conn.on('error', handleError);
*
* var Product = conn.model('Product', yourSchema);
* var dvd = new Product(..);
* dvd.save(); // emits error on the `conn` above
*
* If you desire handling these errors at the Model level, attach an `error` listener to your Model and the event will instead be emitted there.
*
* // registering an error listener on the Model lets us handle errors more locally
* Product.on('error', handleError);
*
* @param {RegExp|Function|Object} obj validator
* @param {String} [message] optional error message
* @return {SchemaType} this
* @api public
*/
SchemaType.prototype.validate = function (obj, message, type) {
if ('function' == typeof obj || obj && 'RegExp' === utils.getFunctionName(obj.constructor)) {
var properties;
if (message instanceof Object && !type) {
properties = utils.clone(message);
if (!properties.message) {
properties.message = properties.msg;
}
properties.validator = obj;
} else {
if (!message) message = errorMessages.general.default;
if (!type) type = 'user defined';
properties = { message: message, type: type, validator: obj };
}
this.validators.push(properties);
return this;
}
var i;
var length;
var arg;
for (i=0, length=arguments.length; i<length; i++) {
arg = arguments[i];
if (!(arg && 'Object' === utils.getFunctionName(arg.constructor) )) {
var msg = 'Invalid validator. Received (' + typeof arg + ') '
+ arg
+ '. See http://mongoosejs.com/docs/api.html#schematype_SchemaType-validate';
throw new Error(msg);
}
this.validate(arg.validator, arg);
}
return this;
};
/**
* Adds a required validator to this schematype.
*
* ####Example:
*
* var s = new Schema({ born: { type: Date, required: true })
*
* // or with custom error message
*
* var s = new Schema({ born: { type: Date, required: '{PATH} is required!' })
*
* // or through the path API
*
* Schema.path('name').required(true);
*
* // with custom error messaging
*
* Schema.path('name').required(true, 'grrr :( ');
*
*
* @param {Boolean} required enable/disable the validator
* @param {String} [message] optional custom error message
* @return {SchemaType} this
* @see Customized Error Messages #error_messages_StorageError-messages
* @api public
*/
SchemaType.prototype.required = function (required, message) {
if (false === required) {
this.validators = this.validators.filter(function (v) {
return v.validator != this.requiredValidator;
}, this);
this.isRequired = false;
return this;
}
var self = this;
this.isRequired = true;
this.requiredValidator = function (v) {
// in here, `this` refers to the validating document.
// no validation when this path wasn't selected in the query.
if (this !== undefined && // специальная проверка из-за strict mode и особенности .call(undefined)
'isSelected' in this &&
!this.isSelected(self.path) &&
!this.isModified(self.path)) return true;
return (('function' === typeof required) && !required.apply(this)) ||
self.checkRequired(v, this);
};
if ('string' === typeof required) {
message = required;
required = undefined;
}
var msg = message || errorMessages.general.required;
this.validators.push({ validator: this.requiredValidator, message: msg, type: 'required' });
return this;
};
/**
* Gets the default value
*
* @param {Object} scope the scope which callback are executed
* @param {Boolean} init
* @api private
*/
SchemaType.prototype.getDefault = function (scope, init) {
var ret = 'function' === typeof this.defaultValue
? this.defaultValue.call(scope)
: this.defaultValue;
if (null !== ret && undefined !== ret) {
return this.cast(ret, scope, init);
} else {
return ret;
}
};
/**
* Applies setters
*
* @param {*} value
* @param {Object} scope
* @param {Boolean} init
* @param {*} priorVal
* @api private
*/
SchemaType.prototype.applySetters = function (value, scope, init, priorVal) {
if (SchemaType._isRef( this, value )) {
return init
? value
: this.cast(value, scope, init, priorVal);
}
var v = value
, setters = this.setters
, len = setters.length
, caster = this.caster;
if (Array.isArray(v) && caster && caster.setters) {
for (var i = 0; i < v.length; i++) {
v[i] = caster.applySetters(v[i], scope, init, priorVal);
}
}
if (!len) {
if (null === v || undefined === v) return v;
return this.cast(v, scope, init, priorVal);
}
while (len--) {
v = setters[len].call(scope, v, this);
}
if (null === v || undefined === v) return v;
// do not cast until all setters are applied #665
v = this.cast(v, scope, init, priorVal);
return v;
};
/**
* Applies getters to a value
*
* @param {Object} value
* @param {Object} scope
* @api private
*/
SchemaType.prototype.applyGetters = function( value, scope ){
if ( SchemaType._isRef( this, value ) ) return value;
var v = value
, getters = this.getters
, len = getters.length;
if ( !len ) {
return v;
}
while ( len-- ) {
v = getters[ len ].call(scope, v, this);
}
return v;
};
/**
* Performs a validation of `value` using the validators declared for this SchemaType.
*
* @param {*} value
* @param {Function} callback
* @param {Object} scope
* @api private
*/
SchemaType.prototype.doValidate = function (value, callback, scope) {
var err = false
, path = this.path
, count = this.validators.length;
if (!count) return callback(null);
var validate = function validate(ok, validatorProperties) {
if (err) return;
if (ok === undefined || ok) {
--count || callback(null);
} else {
err = new ValidatorError(validatorProperties);
callback(err);
}
};
var self = this;
this.validators.forEach(function (v) {
if (err) {
return;
}
var validator = v.validator;
var message = v.message;
var type = v.type;
var validatorProperties = utils.clone(v);
validatorProperties.path = path;
validatorProperties.value = value;
if (validator instanceof RegExp) {
validate(validator.test(value), validatorProperties);
} else if ('function' === typeof validator) {
if (value === undefined && !self.isRequired) {
validate(true, validatorProperties);
return;
}
if (2 === validator.length) {
validator.call(scope, value, function (ok) {
validate(ok, validatorProperties);
});
} else {
validate(validator.call(scope, value), validatorProperties);
}
}
});
};
/**
* Performs a validation of `value` using the validators declared for this SchemaType.
*
* ####Note:
*
* This method ignores the asynchronous validators.
*
* @param {any} value
* @param {Object} scope
* @return {StorageError|undefined}
* @api private
*/
SchemaType.prototype.doValidateSync = function (value, scope) {
var err = null
, path = this.path
, count = this.validators.length;
if (!count) return null;
var validate = function(ok, validatorProperties) {
if (err) return;
if (ok === undefined || ok) {
} else {
err = new ValidatorError(validatorProperties);
}
};
var self = this;
if (value === undefined && !self.isRequired) {
return null;
}
this.validators.forEach(function (v) {
if (err) {
return;
}
var validator = v.validator;
var validatorProperties = utils.clone(v);
validatorProperties.path = path;
validatorProperties.value = value;
if (validator instanceof RegExp) {
validate(validator.test(value), validatorProperties);
} else if ('function' === typeof validator) {
// if not async validators
if (2 !== validator.length) {
validate(validator.call(scope, value), validatorProperties);
}
}
});
return err;
};
/**
* Determines if value is a valid Reference.
*
* На клиенте в качестве ссылки можно хранить как id, так и полные документы
*
* @param {SchemaType} self
* @param {Object} value
* @return {Boolean}
* @api private
*/
SchemaType._isRef = function( self, value ){
// fast path
var ref = self.options && self.options.ref;
if ( ref ) {
if ( null == value ) return true;
if ( _.isObject( value ) ) {
return true;
}
}
return false;
};
//exports
module.exports = SchemaType;
SchemaType.CastError = CastError;
SchemaType.ValidatorError = ValidatorError;