HMVE

Handle mongoose validation error with custom and localize messages

What ?

Mongoose has schema validation, but its error message isn't user-friendly, example :

schema : fullName : { type : String, minlength : 3 }
data   : fullName : 'Bi'

Will generate error message :

Path `fullName` (`Bi`) is shorter than the minimum allowed length (3).

With hmve, you can custom error message, like :

Full name must be at least 3 characters long

and localize :

(Vietnamese) Họ tên phải dài ít nhất 3 kí tự

Config

Let's view simple config file, for :

• Single language - English
• Single language - not English
• Multi language

Use

Add path names

• For single language, just add $name to mongoose Schema :

    username : { type : String, required : true, unique : true, $name : 'tên tài khoản' },

  If $name not specific, hmve will use path ('username')

• For multi language, use setPathNames() with language package name

  hmve.setPathNames(UserModel, { username : 'tên tài khoản', address : { country : 'quốc gia' } }, 'vi');
  hmve.setPathNames(UserModel, { username : 'ユーザー名'    , address : { country : '国'       } }, 'jpa');

Handle error

hmve only handle mongoose validation error, other error type will be return directly.

On mongoose document validate()

Cann't handle unique error.

let user = UserModel({ username : 'boo' });
user.validate(err => {
  err = hmve(UserModel, err);
  if (err) {
      return res.status(400).json({ error : err.message });
    }
  }
});

On mongoose model write method like create(), findOneAndUpdate(), ...

Can handle unique error.

UserModel
  .create({ username : 'boo' })
  .then(user => res.json(user))
  .catch(err => {
    err = hmve(UserModel, err);
    // you can change error code in config()
    if (err.code === 'ERR_MONGOOSE_VALIDATION') { 
      return res.status(400).json({ error : err.message });
    }
    return res.status(500).json({ error : `ERROR DB ${err.message}` });
  });

List error kinds and their context variables

Use this to write custom message templates

| KIND | CONTEXT VARIABLE | |----- | ---------------- | | * | PATH, PATH_NAME, VALUE | | type | TYPE, TYPE_NAME, STRING_VALUE | | min | MIN | | max | MAX | | minlength | MIN_LENGTH | | maxlength | MAX_LENGTH | | regexp | | | enum | ENUM_VALUES, STRING_ENUM_VALUES | | validate | | | unique | |

Error Object

{
   "message"    : "Birthday must be a date, Username is required, Full name must be at least 3 characters long",
   "messages"   : [
     "Birthday must be a date",
     "Username is required",
     "FullName must be at least 3 characters long"
   ],
   "name"       : "ValidationError",
   "code"       : "ERR_MONGOOSE_VALIDATION",
   "model_name" : "Users",
   "pack"       : "DEFAULT",
   "errors"     : [
     {
       "message"      : "Birthday must be a date",
       "context"      : {
         "KIND"         : "type",
         "PATH_NAME"    : "birthday",
         "PATH"         : "birthday",
         "TYPE"         : "Date",
         "TYPE_NAME"    : "date",
         "VALUE"        : "is a date?",
         "STRING_VALUE" : "\"is a date?\""
       },
       "template"     : "{PATH_NAME} must be a {TYPE_NAME}"
     },
     {
       "message"      : "Username is required",
       "context"      : {
         "KIND"         : "required",
         "PATH_NAME"    : "username",
         "PATH"         : "username"
       },
       "template"     : "{PATH_NAME} is required"
     },
     {
       "message"      : "Full name must be at least 3 characters long",
       "context"      : {
         "KIND"         : "minlength",
         "PATH_NAME"    : "full name",
         "PATH"         : "fullName",
         "VALUE"        : "Bi",
         "MIN_LENGTH"   : 3
       },
       "template"     : "{PATH_NAME} must be at least {MIN_LENGTH} characters long"
     }
   ],
}

API LIST

| API | Description | | --- | --- | |hmve(model, validationError, [options])|Handle mongoose validation error| |validate(doc, [options])|Validate mongoose document, handle error with hmve| |setMessageTemplates(messageTemplate, [packageName])|Set message template for a package| |setTypeNames(typeNames, [packageName])|Set type names for a package| |setPathNames(model, pathNames, [packageName])|Set path names for a package| |config(options)|Config|

Handler

hmve(model, validationError, [options]) ⇒ Object

Handle only mongoose validation error, other error type will be return directly.

Returns: Object - user-friendly error

| Param | Type | Description | | --- | --- | --- | | model | Object | Mongoose model object or name | | validationError | Object | Mongoose validation error | | [options] | Object | options |

Options

| field | Type | Description | Example | | --- | --- | --- | --- | | package | String | Language package name. Default is config.default_package. Must be provide in multi language mode. | 'vi', 'jp' | | exclude_errors | String|Array | One or more error kinds will be excluded. Ex: exclude 'required' error when validating update data. | 'required', ['required, 'unique'] |

Example

const hmve = require('hmve');

const UsersSchema = new Schema({
  username : { type : String, required : true                    },
  fullName : { type : String, minlength : 3, $name : 'full name' },
  birthday : { type : Date  ,                                    },
});

const UsersModel = mongoose.model('Users', UsersSchema, 'Users');

let user = UsersModel({
  fullName : 'Bi',
  birthday : 'is a date?',
});

user.validate(err => {
  err = hmve(UsersModel, err);
  if (err) {
     res.status(400).json(err.message); 
     // Birthday must be a date, Username is required, Full name must be at least 3 characters long
  }
});

validate(doc, [options]) ⇒ object

Validate mongoose document, handle error with hmve. This just a convenience syntax with async/await.

Returns: object - user-friendly error

| Param | Type | Description | | --- | --- | --- | | doc | Object | mongoose document | | [options] | Object | same as hmve() options|

Example

const hmve = require('hmve');

const UsersSchema = new Schema({
  username : { type : String, required : true                    },
  fullName : { type : String, minlength : 3, $name : 'full name' },
  birthday : { type : Date  ,                                    },
});

const UsersModel = mongoose.model('Users', UsersSchema, 'Users');

let user = UsersModel({
  fullName : 'Bi',
  birthday : 'is a date?',
});

let err = await hmve.validate(user);
if (err) {
   res.status(400).json(err.message); 
   // Birthday must be a date, Username is required, Full name must be at least 3 characters long
}

Setter

setMessageTemplates(messageTemplate, [packageName])

Set message template for a package

See: getMessageTemplates('DEFAULT') to view default message template

| Param | Type | Description | | --- | --- | --- | | messageTemplate | Object | { <error_kind> : <message_template> } | | [packageName] | String | Package name, ex: 'en', 'vi', 'jp' |

Example

hmve.setMessageTemplates({ 
  DEFAULT   : '{PATH_NAME} không hợp lệ',
  type      : '{PATH_NAME} phải là {TYPE_NAME}',
  required  : 'Thiếu thông tin {PATH_NAME}',
  min       : '{PATH_NAME} không được nhỏ hơn {MIN}',
  max       : '{PATH_NAME} không được lớn hơn {MAX}',
  minlength : '{PATH_NAME} dài ít nhất {MIN_LENGTH} kí tự',
  maxlength : '{PATH_NAME} không vượt quá {MAX_LENGTH} kí tự',
  enum      : '{PATH_NAME} phải thuộc một trong các giá trị sau : {STRING_ENUM_VALUES}',
  regex     : '{PATH_NAME} không hợp lệ',
  unique    : '{PATH_NAME} {VALUE} đã được sử dụng, vui lòng chọn {PATH_NAME} khác',
}, 'vi');

setTypeNames(typeNames, [packageName])

Set type names for a package

See: getTypeNames('DEFAULT') to view default type names

| Param | Type | Description | | --- | --- | --- | | typeNames | Object | { : <type_name> } | | [packageName] | String | Package name, ex: 'en', 'vi', 'jp' |

Example

hmve.setTypeNames({ 
  number  : 'số',
  boolean : 'luận lý',
  date    : 'ngày',
  string  : 'chuỗi',
  array   : 'mảng',
  object  : 'đối tượng',
  buffer  : 'bộ nhớ đệm',
}, 'vi');

setPathNames(model, pathNames, [packageName])

Set path names for a package

| Param | Type | Description | | --- | --- | --- | | model | Object | String | mongoose model or model name | | pathNames | Object | { : <path_name> }, which has the same structure as Mongoose Schema | | [packageName] | String | package name, ex: 'en', 'vi' |

Example

hmve.setPathNames('User', {
   username : 'tên tài khoản',
   age      : 'tuổi',
   address  : {
     country : 'quốc gia',
     province : 'tỉnh thành'
   }
}, 'vi');

config(options)

set options

| Param | Type | Description | | --- | --- | --- | | options | Object | options |

Example

hmve.config({
   default_package           : 'DEFAULT',
   msg_delimiter             : ', ',
   path_name_key             : '$name',
   link_to_errors            : 'errors',
   upper_first               : true,
   link_to_origin_error      : false,
   additional_error_fields   : {
     error_name                : 'ValidationError',
     error_code                : 'ERR_MONGOOSE_VALIDATION',
    },
   additional_context_fields : {
     // <context_key> : <schema_key>
   }
});