Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cermati/satpam
Javascript validation library, batteries included
https://github.com/cermati/satpam
Last synced: about 2 months ago
JSON representation
Javascript validation library, batteries included
- Host: GitHub
- URL: https://github.com/cermati/satpam
- Owner: cermati
- License: mit
- Created: 2015-04-30T05:00:42.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-05-29T04:39:14.000Z (4 months ago)
- Last Synced: 2024-05-29T17:41:33.031Z (4 months ago)
- Language: JavaScript
- Homepage:
- Size: 853 KB
- Stars: 18
- Watchers: 32
- Forks: 10
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-made-by-indonesian - Satpam - `Javascript validation library, batteries included` *by [Cermati.com](https://github.com/cermati)* (S)
- made-in-indonesia - Satpam - `Javascript validation library, batteries included` *by [Cermati.com](https://github.com/cermati)* (S)
README
# Satpam
-----
Satpam is a javascript simple and effective object validation library.
[](https://travis-ci.org/cermati/satpam)
[](https://badge.fury.io/js/satpam)
## Installation
```
npm install satpam --save
```
## Quick Usage
```js
const satpam = require('satpam');
const rules = {
name: ['required'],
phone: ['required', 'numeric'],
email: ['required', 'email']
office: {
secondaryEmail: ['email'],
}
};
const input = {
name: 'Sendy',
title: 'Lord',
phone: 'hi there123',
email: '[email protected]',
office: {
secondaryEmail: 'invalid email',
}
};
const result = satpam.validate(rules, input);
if (result.success === true) {
// valid
} else {
// invalid
result.messages.office.secondaryEmail.email === 'Secondary Email must be email.';
result.messages.phone.number === 'Phone must be numeric.';
}
```
## Isolated Satpam Instance
Satpam `create` method will return an isolated `Satpam` instance based on current state of satpam validation rules and messages. The instance won't be affected when you setting up a custom validation rules or messages.
- Each instance will have cloned validation rules and messages, so it's safe to add or override validation rule without affecting other validator instances or the global satpam validator.
- The cloned validation rules and messages will be based on the current state of the global satpam validator. See [Custom Rules](#custom-rules)
```js
const satpam = require('satpam');
const validatorOne = satpam.create();
const validatorTwo = satpam.create();
```
## Front End Usage
For front end usage, you can use the dedicated front end lib.
```js
import satpam from 'satpam/lib/frontend';
```
Additionally, it's better to create your own validator instance with only the needed rules.
This will help reduce build size especially if your front end application is intended for end users.
```js
import Validator from 'satpam/lib/frontend/validator';
import minLength from 'satpam/lib/validators/min-length';
import maxLength from 'satpam/lib/validators/max-length';
const customValidator = new Validator({
validators: [minLength, maxLength]
});
const result = customValidator.validate(
{ token: ['minLength:11', 'maxLength:16'] },
{ token: '12345' }
);
```
## Available Rules
- `required`
- `numeric`
- `integer`
- `email`
- `notDisposableEmail` (well suited with email validation)
- `image`
- `alpha`
- `alphanumeric`
- `boolean`
- `creditCard`
- `containsAlphabet`
- `containsDigit`
- `containsLowerCase`
- `containsUpperCase`
- `date`
- `dateFormat:`
- `dateAfter::::`
- `dateBefore::::`
- `dateTimeAfter::::`
- `dateTimeAfterOrEqual::::`
- `dateTimeBefore::::`
- `dateTimeBeforeOrEqual::::`
- `timeAfter:
Use object notation for defining this rule
[examples](https://github.com/cermati/satpam/blob/master/test/validators/equal-to-field.spec.js#L5)
- `notEqual:$1`
- `not-equal-email-domain:$1`
`$1` is the prohibited domains separated by comma (',')
[examples](https://github.com/cermati/satpam/blob/master/test/validators/not-equal-email-domain.spec.js)
- `not-equal-to-field:$1`
Use object notation for defining this rule
[examples](https://github.com/cermati/satpam/blob/master/test/validators/not-equal-to-field.spec.js#L5)
- `requiredIf::`
```js
var input = {message: 'hi!'};
// `subject` is required if message equals `hi!`
satpam.validate({subject: 'requiredIf:message:hi!'});
```
For more complex example please see
- [`requiredIf` examples](https://github.com/cermati/satpam/blob/master/test/validators/required-if.spec.js#L147)
- [`noes` examples](https://github.com/sendyhalim/noes)
- `requiredIfNot::`
```js
var input = {message: 'hi!'};
// `subject` is required if message does not equal `hi!`
satpam.validate({subject: 'requiredIfNot:message:hi!'});
```
For more complex example please see
- [`requiredIfNot` examples](https://github.com/cermati/satpam/blob/master/test/validators/required-if-not.spec.js#L103)
- [`noes` examples](https://github.com/sendyhalim/noes)
- `minimumAge::`
- `taxId:$1` Currently only support indonesian tax id e.g. `taxId:id`
Use object notation for defining this rule
[examples](https://github.com/cermati/satpam/blob/master/test/validators/member-of.spec.js#L5)
- `beginWith:$1`
Use object notation for defining this rule
[examples](https://github.com/cermati/satpam/blob/master/test/validators/begin-with.spec.js#L5)
- `pattern:$1:$2`
`$1` is the pattern, `$2` is the regex flags
[examples](https://github.com/cermati/satpam/blob/master/test/validators/pattern.spec.js#L6)
- `uuid:$1`
`$1` is the version, available options v1, v3, v4, v5, all
[examples](https://github.com/cermati/satpam/blob/master/test/validators/uuid.spec.js#L6)
- `indonesiaIdCardNumberBirthDate:$1:$2`
`$1` is the Birth Date's key, $2 is the date format used
[examples](https://github.com/cermati/satpam/blob/master/test/validators/indonesia-id-card-number-birth-date.spec.js#L6)
- `indonesiaIdCardNumberGender:$1:$2:$3`
`$1` is the Gender's key, $2 is the value for male, $3 is the value for female
[examples](https://github.com/cermati/satpam/blob/master/test/validators/indonesia-id-card-number-gender.spec.js#L6)
- `indonesiaIdCardNumberProvince:$1`
`$1` is the Province's Key
[examples](https://github.com/cermati/satpam/blob/master/test/validators/indonesia-id-card-number-province.spec.js#L6)
- `indonesiaIdCardNumberValidProvince`
[examples](https://github.com/cermati/satpam/blob/master/test/validators/indonesia-id-card-number-valid-province.spec.js#L6)
- `indonesianName`
[examples](https://github.com/cermati/satpam/blob/master/test/validators/indonesian-name.spec.js#L6)
## Complete Examples
To see complete example usage, please see the [unit tests](https://github.com/cermati/satpam/blob/master/test/validators)
## Custom Validation Rules
Add custom validation rule(s) globally. Note that
everytime you add a custom validation rule it will affect every `Satpam` instance(s) that
is created after the custom rules addition, but not the old instance(s).
```js
const satpam = require('satpam');
// oldValidator will not have `must-be-ironman` rule, because it's created
// before we add the custom validation.
const oldValidator = satpam.create();
// The global satpam validator will has updated validation rules.
// After this statement, we can do satpam.validate({name: ['must-be-ironman']}, ...);
satpam.addCustomValidation('must-be-ironman', val => val === 'ironman');
satpam.setValidationMessage('must-be-ironman', 'Not ironman D:');
// With parameters
satpam.addCustomValidation('range:$1:$2', (val, ruleObj) => {
return val >= ruleObj.params[0] && val <= ruleObj.params[1];
});
// If validation fails it will set message to:
// "PropertyName must between 0 and 30"
satpam.setValidationMessage('range:$1:$2', '<%= propertyName %> must between <%= ruleParams[0] %> and <%= ruleParams[1] %>');
// newValidator will have `must-be-ironman` rule because it's created
// after we add the custom validation.
const newValidator = satpam.create();
```
## Optional Validation
Sometimes you want the validation to pass if any of the validation rule is satisfied,
we can do this by supplying the validation rules in an array.
```js
const rules = {
// It will pass if document is passed and either a pdf or an image
document: ['required', ['fileType:pdf', 'image']]
};
```
## Running Validation Based On Some Conditions
There's also a case when you only want to run a validation rule only if a specific condition is fulfilled.
```js
const shouldValidateZipCode = (ruleObj, inputObj) => {
return inputObj.livesInJakarta;
};
const rules = {
// Only require zip code if `livesInJakarta` is truthy
zipCode: [
{name: 'required', shouldValidate: shouldValidateZipCode}
]
};
satpam.validate(rules, {}); // {success: true}
satpam.validate(rules, {
livesInJakarta: true
}); // Will fail
```
## Custom Validation Messages
You can override each validation rule's message
```js
satpam.setValidationMessage(
'minLength:$1',
'<%= propertyName %> must have length more than <%= ruleParams[0] %>'
);
```
You can also pass a `Function` instead of a `String`
```js
/**
* @example
* const satpam = require('satpam');
*
* const rules = {name: ['minLength:10']};
* const input = {name: 'wubwub'};
* satpam.validate(rules, input);
*
* expect(ruleObj.name).to.equal('minLength');
* expect(ruleObj.fullName).to.equal('minLength:$1');
* expect(ruleObj.params).to.deep.equal([10]);
* expect(propertyName).to.equal('name');
* expect(value).to.equal('wubwub');
*
* @param {Object} ruleObj
* @param {String} ruleObj.name - The validation rule name
* e.g. `minLength:10` will have name minLength
* @param {String} ruleObj.fullName - Validation rule fullname
* e.g. `minLength:10` will have fullName `minLength:$1`
* @param {Array} ruleObj.params - The rule parameters
* e.g. `minlength:10` will have params `[10]`
* @param {String} propertyName
* @param {*} value
*/
const message = (ruleObj, propertyName, value) => {
...
};
satpam.setValidationMessage('minLength:$1', message);
```
## License
MIT
