satpam

Satpam

---

Satpam is a javascript simple and effective object validation library.

Installation

npm install satpam --save

Quick Usage

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: '[e-mail]',
  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

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.

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.

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:<format, e.g. DD-MM-YYYY>

• dateAfter:<the date input format, e.g. DD-MM-YYYY>:<date after e.g. 'now' or 20-1-2015>:<offset>:<unit of time e.g. 'days'>

• dateBefore:<the date input format, e.g. DD-MM-YYYY>:<date after e.g. 'now' or 20-1-2015>:<offset>:<unit of time e.g. 'days'>

• dateTimeAfter:<the date input format, e.g. YYYY-MM-DDTHH:mm:ss.SSS[Z]>:<date time after e.g. 'now' or 20-1-2015T18:30:00.000+07>:<offset>:<unit of time e.g. 'hours'>

• dateTimeAfterOrEqual:<the date input format, e.g. YYYY-MM-DDTHH:mm:ss.SSS[Z]>:<date time after or equal e.g. 'now' or 20-1-2015T18:30:00.000+07>:<offset>:<unit of time e.g. 'hours'>

• dateTimeBefore:<the date input format, e.g. YYYY-MM-DDTHH:mm:ss.SSS[Z]>:<date time before e.g. 'now' or 20-1-2015T18:30:00.000+07>:<offset>:<unit of time e.g. 'hours'>

• dateTimeBeforeOrEqual:<the date input format, e.g. YYYY-MM-DDTHH:mm:ss.SSS[Z]>:<date time before or equal e.g. 'now' or 20-1-2015T18:30:00.000+07>:<offset>:<unit of time e.g. 'hours'>

• timeAfter:<time after i.e. 'now' or time in unix form>:<offset>:<unit of time e.g. 'minutes'>

• timeAfterOrEqual:<time after or equal i.e. 'now' or time in unix form>:<offset>:<unit of time e.g. 'minutes'>

• timeBefore:<time before i.e. 'now' or time in unix form>:<offset>:<unit of time e.g. 'minutes'>

• timeBeforeOrEqual:<time before or equal i.e. 'now' or time in unix form>:<offset>:<unit of time e.g. 'minutes'>

• url

• urlProtocol:$1

• string

• plainObject Check if the given value is a plain object (passing string, array, or anything will return to false)

• nonBlank

• mongoId Check if the given string is a valid mongodb object id

• phoneNumber (Currently only supports Indonesia phone number)

• mobilePhoneNumber (Currently only supports Indonesia mobile phone number)

• length:<length>

• fileType:<extension> Please check file-type

• maxLength:<length>

• minLength:<length>

• maxValue:<max value>

• minValue:<min value>

• memberOf:$1

• some-memberOf:$1 Check if the given value has at least one of items in the list

• equal:$1

• equal-to-field:$1

  Use object notation for defining this rule examples

• notEqual:$1

• not-equal-email-domain:$1

  $1 is the prohibited domains separated by comma (',') examples

• not-equal-to-field:$1

  Use object notation for defining this rule examples

• requiredIf:<fieldName>:<value>

  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
  • noes examples

• requiredIfNot:<fieldName>:<value>

  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
  • noes examples

• minimumAge:<age>:<dateFormat>

• taxId:$1 Currently only support indonesian tax id e.g. taxId:id

  Use object notation for defining this rule examples

• beginWith:$1

  Use object notation for defining this rule examples

• pattern:$1:$2

  $1 is the pattern, $2 is the regex flags examples

• uuid:$1

  $1 is the version, available options v1, v3, v4, v5, all examples

• indonesiaIdCardNumberBirthDate:$1:$2

  $1 is the Birth Date's key, $2 is the date format used examples

• indonesiaIdCardNumberGender:$1:$2:$3

  $1 is the Gender's key, $2 is the value for male, $3 is the value for female examples

• indonesiaIdCardNumberProvince:$1

  $1 is the Province's Key examples

• indonesiaIdCardNumberValidProvince

  examples

• indonesianName

  examples

Complete Examples

To see complete example usage, please see the unit tests

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).

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.

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.

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

satpam.setValidationMessage(
  'minLength:$1',
  '<%= propertyName %> must have length more than <%= ruleParams[0] %>'
);

You can also pass a Function instead of a String

/**
 * @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