# dee-validator

> Object fields validator

Latest version **2.2.0** (published 2025-12-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install dee-validator
pnpm add dee-validator
yarn add dee-validator
bun add dee-validator
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2025-12-20 |
| First published | 2017-03-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=22.0.0 |
| Dependencies | 4 |
| Unpacked size | 30 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Ilya Markevich |
| Maintainers | ilya.markevich |
| Keywords | validator, validation, check, valid |

## Links

- npm: https://www.npmjs.com/package/dee-validator
- Repository: https://github.com/ilya-markevich/node-validator
- Homepage: https://github.com/ilya-markevich/node-validator#readme
- Issues: https://github.com/ilya-markevich/node-validator/issues
- npm.io page: https://npm.io/package/dee-validator

## Dependencies (4)

- [is-ip](https://npm.io/package/is-ip.md) 5.0.1
- [is-url](https://npm.io/package/is-url.md) 1.2.4
- [isemail](https://npm.io/package/isemail.md) 3.2.0
- [lodash.get](https://npm.io/package/lodash.get.md) 4.4.2

## Alternatives

- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads
- [@oridune/validator](https://npm.io/package/@oridune/validator.md) — 16 weekly downloads

## Recent versions

- 2.2.0 (latest) — 2025-12-20
- 2.1.1 — 2025-12-17
- 2.1.0 — 2025-12-17
- 2.0.2 — 2021-08-08
- 2.0.0 — 2021-08-08
- 1.1.1 — 2017-04-25
- 1.1.0 — 2017-04-24
- 1.0.0 — 2017-04-10
- 0.3.0 — 2017-03-31
- 0.2.0 — 2017-03-31
- 0.0.1 — 2017-03-30

## README

# Dee Validator

[![npm](https://img.shields.io/npm/v/dee-validator.svg?maxAge=1000)](https://www.npmjs.com/package/dee-validator)
[![npm](https://img.shields.io/npm/dt/dee-validator.svg?maxAge=1000)](https://www.npmjs.com/package/dee-validator)

Validator for NodeJS.

# Table of contents
* [Migration to v2](#migration-to-v2)
* [Usage](#usage)
* [API](#api)
  - [Validator](#validator)
    + [`Validator.extend()`](#validatorextendcustomvalidators)
  - [Validator instance](#validator-instance)
    + [`validatorInstance.getValidationObject()`](#validatorinstancegetvalidationobject)
    + [`validatorInstance.property()`](#validatorinstancepropertypropertypath)
    + [`validatorInstance.hasErrors()`](#validatorinstancehaserrors)
    + [`validatorInstance.getErrors()`](#validatorinstancegeterrors)
  - [Validator state instance](#validator-state-instance)
    + [`validatorStateInstance.optional()`](#validatorstateinstanceoptional)
    + [`validatorStateInstance.withMessage()`](#validatorstateinstancewithmessageerrormessage)
+ [Error message format](#error-message-format)
* [Fields validators](#fields-validators)
* [Author](#author)

# Migration to v2

The [v1](https://github.com/ilya-markevich/node-validator/tree/v1.1.1) doesn't support async validators meaning the API is synchronous.
For migration to v2, await `getErrors` and `hasErrors` methods.

# Usage

To use the validator just create new validator instance with an object for validation as a parameter.
Use [property](#validatorinstancepropertypropertypath) method to choose a value and [state methods](#validator-state-instance) to validate the value.
   
Example of code:
``` Javascript
const Validator = require('dee-validator');
const validator = new Validator({
    field1: 'test',
    field2: 10,
    field3: true,
    field4: [1, 'test', 3],
    field5: [{ a: 1 }, { a: null }]
});

validator.property('field1').isNotEmpty().isEqual('1');

validator.property('field2').isNotEmpty().isInteger({
    min: 1,
    max: 20
});

validator.property('field3').isNotEmpty().isString().withMessage('field3 should be a special string.');

validator.property('field4[]').isNotEmpty().isInteger().withMessage('field4 items should be integers.');

validator.property('field5[].a').isNotEmpty().isInteger().withMessage('field5.a should be integers.');

await validator.hasErrors(); // true
await validator.getErrors();
// [
//    { path: 'field1', value: 'test', errorMessage: 'field1 should be equal 1' },
//    { path: 'field3', value: true, errorMessage: 'field3 should be a special string.' }
//    { path: 'field4[1]', value: 'test', errorMessage: 'field4 items should be integers.' }
//    { path: 'field5[1].a', value: null, errorMessage: 'field5.a should be integers.' }
// ]
```

# API

## Validator

### `Validator.extend(customValidators)`
Register new custom validators.

Args:

* `customValidators [Object]`: object with custom field validators.

Example:
``` javascript
// here we create two custom validators.
// First validator: isTest. It checks if value equal to 'test' string. In case it's not, error message will be = 'should pass isTest validation'
// Second validator: isDivisibleBy. It accepts value and divisible number and check if value is divided by the number. In case it's not - custom error message will be created.
// If user doesn't pass any divisible number, 2 will be used as default.
{
  isTest: {
    execute: value => value === 'test'
  }
  isDivisibleBy: {
    execute: (value, divizor) => typeof value === 'number' && value % divizor === 0,
    getErrorMessage: (divizor) => return `should be divided by ${divizor}`,
    defaultOpts: 2
  }
}
```

## Validator instance

### `validatorInstance.getValidationObject()`
Get object for validation.

### `validatorInstance.property(propertyPath)`
Create new [validator state](#validator-state-instance) instance and return it for chaining.

Args:

* `propertyPath [String]`: path to property in validation object ([lodash.get](https://lodash.com/docs/4.17.4#get) is used to resolve a value)

### `validatorInstance.hasErrors()`
Return `Promise<true>` if validator has errors. In the other case return `Promise<false>`.

### `validatorInstance.getErrors()`
Return promise with all validation errors.

Example of an error:
``` javascript
{
    path: 'a',
    value: 'test',
    errorMessage: 'value should be a number'
}
```

## Validator state instance

### `validatorStateInstance.optional()`
Apply all checks only if a value is not `undefined` or `null`.

### `validatorStateInstance.withMessage(errorMessage)`
Set custom error message instead of default one.

See [other methods](#fields-validators) available on state instance.

# Error message format
The validator creates default error message for each property. It's quite readable (you can see how the message is created in each field validator implementation).
If you are not satisfied with default error message, you can use [withMessage](#validatorstateinstancewithmessageerrormessage) method to create a new one.

# Fields validators

- **isArray()** - check if a value is array.
- **isArrayLength(opts)** - check if an array value has correct length. `opts` is an object which defaults to `{ min: 0, max: undefined }`.
`min` and `max` options set acceptable range for the array length.
- **isBase64String()** - check if a string is in base64 format.
- **isBoolean(opts)** - check if a value is boolean. `opts` is an object which defaults to `{ convert: true }`.
If `convert = true` string values like 'true'/'false' are accepted as booleans.
- **isDate(opts)** - check if a value is date. `opts` is an object which defaults to `{ before: undefined, after: undefined }`.
`after` and `before` options set acceptable range for the date.
- **isEachIn(inArray)** - check if each item from value is in `inArray`.
- **isEmail()** - check if a string value is an email.
- **isEqual(equalTo)** - check if a value is equal to `equalTo`.
- **isFloat(opts)** - check if a value is a float. `opts` is an object which defaults to `{ min: 0, max: undefined, convert: true }`.
`min` and `max` options set acceptable range for the float value. If `convert = true` and value is a string the value will be converted to a float.
- **isIn(inArray)** - check if a value is in `inArray`.
- **isInteger(opts)** - check if a value is an integer. `opts` is an object which defaults to `{ min: 0, max: undefined, convert: true }`.
`min` and `max` options set acceptable range for the integer value. If `convert = true` and value is a string the value will be converted to an integer.
- **isIpString(opts)** - check if a string value is correct ip address. `opts` is an object which defaults to `{ v4: undefined, v6: undefined}`.
`v4` and `v6` are formats for checking. If both are undefined, the string value should be in ipv4 or ipv6 formats.
- **isJsonString()** - check if a value is json string(`JSON.parse` is used).
- **isLength(opts)** - check if a string value has correct length. `opts` is an object which defaults to `{ min: 0, max: undefined }`.
`min` and `max` options set acceptable range for the string length.
- **isLowerCaseString()** - check if all letters in a string are lowercase.
- **isMatch(regexp)** - check if a string value is matched to `regexp`.
- **isNotEmpty(opts)** - check if a string is not empty. `opts` is an object which defaults to `{ trim: false }`
- **isNumericString()** - check if a string contains only numbers.
- **isString()** - check if a value is a string.
- **isUpperCaseString()** - check if all letters in a string are uppercase.
- **isUrlString()** - check if a string value is a correct url.

# Author
Ilya Markevich

---
_Source: https://npm.io/package/dee-validator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._