3.0.0 • Published 9 months ago

mongoose-unique-validator v3.0.0

Weekly downloads
26,745
License
MIT
Repository
github
Last release
9 months ago

mongoose-unique-validator

Build Status

mongoose-unique-validator is a plugin which adds pre-save validation for unique fields within a Mongoose schema.

This makes error handling much easier, since you will get a Mongoose validation error when you attempt to violate a unique constraint, rather than an E11000 error from MongoDB.

Usage

Yarn: yarn add mongoose-unique-validator

NPM: npm install --save mongoose-unique-validator

Then, apply the plugin to your schema:

var mongoose = require('mongoose');
var uniqueValidator = require('mongoose-unique-validator');

var mySchema = mongoose.Schema(/* put your schema definition here */);
mySchema.plugin(uniqueValidator);

Example

Let’s say you have a user schema. You can easily add validation for the unique constraints in this schema by applying the uniqueValidator plugin to your user schema:

var mongoose = require('mongoose');
var uniqueValidator = require('mongoose-unique-validator');

// Define your schema as normal.
var userSchema = mongoose.Schema({
    username: { type: String, required: true, unique: true },
    email: { type: String, index: true, unique: true, required: true },
    password: { type: String, required: true }
});

// Apply the uniqueValidator plugin to userSchema.
userSchema.plugin(uniqueValidator);

Now when you try to save a user, the unique validator will check for duplicate database entries and report them just like any other validation error:

var user = new User({ username: 'JohnSmith', email: 'john.smith@gmail.com', password: 'j0hnNYb0i' });
user.save(function (err) {
    console.log(err);
});
{
    message: 'Validation failed',
    name: 'ValidationError',
    errors: {
        username: {
            message: 'Error, expected `username` to be unique. Value: `JohnSmith`',
            name: 'ValidatorError',
            kind: 'unique',
            path: 'username',
            value: 'JohnSmith'
        }
    }
}

Find + Updates

When using findOneAndUpdate and related methods, mongoose doesn't automatically run validation. To trigger this, you need to pass a configuration object. For technical reasons, this plugin requires that you also set the context option to query.

{ runValidators: true, context: 'query' }

A full example:

User.findOneAndUpdate(
    { email: 'old-email@example.com' },
    { email: 'new-email@example.com' },
    { runValidators: true, context: 'query' },
    function(err) {
        // ...
    }
)

Custom Error Types

You can pass through a custom error type as part of the optional options argument:

userSchema.plugin(uniqueValidator, { type: 'mongoose-unique-validator' });

After running the above example the output will be:

{
    message: 'Validation failed',
    name: 'ValidationError',
    errors: {
        username: {
            message: 'Error, expected `username` to be unique. Value: `JohnSmith`',
            name: 'ValidatorError',
            kind: 'mongoose-unique-validator',
            path: 'username',
            value: 'JohnSmith'
        }
    }
}

You can also specify a default custom error type by overriding the plugin defaults.type variable:

uniqueValidator.defaults.type = 'mongoose-unique-validator'

Custom Error Messages

You can pass through a custom error message as part of the optional options argument:

userSchema.plugin(uniqueValidator, { message: 'Error, expected {PATH} to be unique.' });

You have access to all of the standard Mongoose error message templating:

  • {PATH}
  • {VALUE}
  • {TYPE}

You can also specify a default custom error message by overriding the plugin defaults.message variable:

uniqueValidator.defaults.message = 'Error, expected {PATH} to be unique.'

Case Insensitive

For case-insensitive matches, include the uniqueCaseInsensitive option in your schema. Queries will treat john.smith@gmail.com and John.Smith@gmail.com as duplicates.

var userSchema = mongoose.Schema({
    username: { type: String, required: true, unique: true },
    email: { type: String, index: true, unique: true, required: true, uniqueCaseInsensitive: true },
    password: { type: String, required: true }
});

Additional Conditions

For additional unique-constraint conditions (ex: only enforce unique constraint on non soft-deleted records), the MongoDB option partialFilterExpression can be used.

Note: the option index must be passed as an object containing unique: true, or else partialFilterExpression will be ignored.

var userSchema = mongoose.Schema({
    username: { type: String, required: true, unique: true },
    email: {
        type: String,
        required: true,
        index: {
            unique: true,
            partialFilterExpression: { deleted: false }
        } 
    },
    password: { type: String, required: true }
});

Caveats

Because we rely on async operations to verify whether a document exists in the database, it's possible for two queries to execute at the same time, both get 0 back, and then both insert into MongoDB.

Outside of automatically locking the collection or forcing a single connection, there's no real solution.

For most of our users this won't be a problem, but is an edge case to be aware of.

artesants-bot-templatestready-clidomain-schema-tpmbahuntnet-servercszoldseg-node-backendcutnut-servermeen-cmstranslectra@groc/models@genie.tech/utils@zerointermittency/mongo@xchanin-sha/pull-it-off@ycs/auth@ycs/coreAPI-Documentationsurf2gather-backendreaktorexpressgpsexpress-boilerplate-hacktiv8express-app1express-firebase-mongoose-templatefh-mbaas-middlewarefast-furniture-utilheadlight-utilintegration-backendjcarlessgrandcentralgpstest1graph-commongeofence-monitoringleafingio-node-seedlets-chatkomalog_and_reg_meanmagejsevolvus-userexamia-dbevls-user-demomongoose-kitmongoose-common-pluginmqtt_manager_commonmulti-database-mongoosemongocrudmeanstackmean-guide-backendmongoose-supportrapidstackoodebe-mongo-pluginoutline.jsoba-dev-apisoils-plugin-authnodejs-api-boilerplatenode_design_patternreader-scraperreadme-shieldreposedristky-dbsammler-strategy-githubrootpanelng2-forms-demongx-formnode-devisespirit.io-mongodb-connectoruh-dbuser-acl-module@ampraveeen/nestjs-user-management@almedso/cosmea-core@almedso/cosmea-skeleton18plus-weryfikacjazqs-coreeducationlr3dvp-liteticketdvp-mongomodelseazin-server@ci-media-module/api@ci-user-module/apite-auth-be@invisible/mongoose@invisible/mongoose-extras@korenezri/easy-peasy-backend@codice-progressio/express-authentication@3merge/express-auth-middleware@adarsht756/my-packagewrauth@samanmoss2/my-math-library@evolvus/evolvus-charges-billing@evolvus/evolvus-master-currency@evolvus/evolvus-supported-date-formats@easyaccomod/schemas@noreajs/mongoose@dracul/media-backendbakat-dbapi-services_betaapi-services_beta_1@onebro/oba-dev-workers@onebro/oba-mongoose@odecon/odecon-server-base@sparkle-dev/cohope-common-server@soundy/db-manager
2.0.4

9 months ago

3.0.0

9 months ago

2.0.3

3 years ago

2.0.2

4 years ago

2.0.1

4 years ago

2.0.0

4 years ago

1.0.6

5 years ago

1.0.5

5 years ago

1.0.4

5 years ago

1.0.3

6 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago

0.6.2

7 years ago

0.6.1

7 years ago

0.6.0

7 years ago

0.5.1

7 years ago

0.5.0

7 years ago

0.4.1

8 years ago

0.3.0

9 years ago

0.2.0

9 years ago

0.1.2

9 years ago

0.1.1

9 years ago

0.1.0

9 years ago