mongoose-beautiful-unique-validation
Plugin for Mongoose that turns duplicate errors into regular Mongoose validation errors.
Mongoose's unicity constraint actually relies on MongoDB's unique
indexes. It means that, if you have a schema like this one:
mongoose.Schema({
name: {
type: String,
unique: true
}
});
Duplicates will be reported with a driver-level error of this kind:
{
"name": "MongoError",
"message": "insertDocument :: caused by :: 11000 E11000 duplicate key error index: example.users.$name_1 dup key: { : \"John\" }",
"index": 0,
"code": 11000,
"errmsg": "insertDocument :: caused by :: 11000 E11000 duplicate key error index: example.users.$name_1 dup key: { : \"John\" }"
}
Because these errors are not of the same kind as normal Validation errors, you need to handle them as a special case that complicates the validation logic and leaves room for bugs. This plugin solves this problem by turning driver-level duplicate errors (E11000 and E11001) into regular Validation errors.
{
"name": "ValidationError",
"message": "Model validation failed",
"errors": {
"name": {
"name":"ValidatorError",
"kind": "unique",
"message": "Path `name` (John) is not unique.",
"path": "name",
"value": "John"
}
}
}
Install
npm install --save mongoose-beautiful-unique-validation
Supported versions of Mongoose
Starting from version 7.0.0, this module only supports Mongoose 4.11.4 and upper. Usage with older Mongoose versions might work, but is not supported. If we need to use outdated versions of Mongoose, use older versions of this package as documented in the table below.
Note that only security fixes will be backported to older versions.
This package’s version | Supported Mongoose versions |
---|
7 | ≥ 4.11.4 |
5, 6 | ≥ 4.5.0 |
1, 2, 3, 4 | ≥ 4.0.0 |
Supported versions of Node
This module currently supports Node.js 4, 5, 6, 7 and 8. If you find a bug while using one of these versions, please fill a bug report!
Example
Saving a duplicate document
const beautifyUnique = require('mongoose-beautiful-unique-validation');
const userSchema = mongoose.Schema({
name: {
type: String,
unique: 'Two users cannot share the same username ({VALUE})'
}
});
userSchema.plugin(beautifyUnique);
const User = mongoose.model('Model', userSchema);
User.on('index', err => {
if (err) {
console.error('Indexes could not be created:', err);
return;
}
const admin1 = new User({
name: 'admin'
});
const admin2 = new User({
name: 'admin'
});
admin1.save()
.then(() => console.log('Success saving admin1!'))
.catch(err => console.error('admin1 could not be saved: ', err));
admin2.save()
.then(() => console.log('Success saving admin2!'))
.catch(err => console.error('admin2 could not be saved: ', err));
});
Updating a document to be a duplicate
const beautifyUnique = require('mongoose-beautiful-unique-validation');
const userSchema = mongoose.Schema({
name: {
type: String,
unique: 'Two users cannot share the same username ({VALUE})'
}
});
userSchema.plugin(beautifyUnique);
const User = mongoose.model('Model', userSchema);
User.on('index', err => {
if (err) {
console.error('Indexes could not be created:', err);
return;
}
let admin1 = new User({
name: 'admin1'
});
let admin2 = new User({
name: 'admin2'
});
Promise.all([
admin1.save(),
admin2.save()
]).then(() => {
admin2
.update({
$set: {name: 'admin1'}
})
.exec()
.then(() => console.log('Success updating admin2!'))
.catch(err => console.error('admin2 could not be updated:', err))
}).catch(err => console.error('Could not save documents:', err));
});
Usage
Schemata in which this module is plugged in will produce beautified duplication errors. You can also use it as a global plugin.
You need to plug in this module after declaring all indexes on the schema, otherwise they will not be beautified.
The reported error has the same shape as normal validation errors. For each field that has a duplicate value, an item is added to the errors
attribute. See examples above.
Error messages
By default, the validation error message will be Path `{PATH}` ({VALUE}) is not unique.
, with {PATH}
replaced by the name of the duplicated field and {VALUE}
by the value that already existed.
To set a custom validation message on a particular path, add your message in the unique
field (instead of true
), during the schema's creation.
const userSchema = mongoose.Schema({
name: {
type: String,
+ unique: 'Two users cannot share the same username ({VALUE})'
- unique: true
}
});
When using the plugin globally or with a schema that has several paths with unique values, you might want to override the default message value. You can do that through the defaultMessage
option while adding the plugin.
userSchema.plugin(beautifyUnique, {
defaultMessage: "This custom message will be used as the default"
});
Note: Custom messages defined in the schema will always take precedence over the global default message.
Contributions
This is free and open source software. All contributions (even small ones) are welcome. Check out the contribution guide to get started!
Thanks to all contributors:
License
Released under the MIT license. See the full license text.