api.md

Interface reference (API)

PROJECT PAGE | README | EXAMPLES

Short list of all exports

class Rules(...)

• .validate(...)
• Errors that are returned by validate():
• Rules.OBJECT_IS_MISSING
• Rules.INVALID_OBJ_REDUNDANT_PROPS
• Rules.VALIDATION_PROP_REQUIRED

class Rule - Rule wrapper

• Rule.INVALID_RULE
• Rule.INVALID_VALUE
• Rule.INVALID_REGEXP

Schema helpers
min(n)
max(n)
isBoolean(value): boolean
isNumber(value): boolean
isString(value): boolean
isDate(value): boolean
isArray(value): boolean
isFunction(value): boolean
isRegExp(value): boolean
isObject(value): boolean

---

class Rules

new Rules(schema: schema, redundantProps: boolean = true)

Instantiates validation object.

schema: { field : Rule | Array<Rule>} // field is simple object property
Rule: 
    Number | String | Boolean | Array | Date
  | RegExp 
  | 'optional' // denotes optional field of the schema
  | 'required'
  | function (fieldValue): Error | String

The schema is a normal js object which contains
constructors names like String as validating rules (rule for the rest of document)
Every such rule is matched against built-in validators, for example for Boolean
constructor there isBoolean(...) function will be used (see exports above).

You can create your own rule by providing simple function.
Such function are restricted to return string and error types only.
If string is returned then Rule.INVALID_RULE is thrown by .validate(...)
The rules by itself can be combined into arrays. See examples below.

The 'optional' rule allows validation pass free (without errors) if
respective field's value is missing
meanwhile 'required' will throw Rules.VALIDATION_PROP_REQUIRED error.

.validate(...)

validate(target: object, synchronous: boolean = false, verbose: boolean): Promise<target> // default
validate(target: object, synchronous: boolean = true , verbose: boolean): target // throws error

Validation function of the stigma object.
target - simple js object to be validated.
synchronous - configure if promise will be returned or target object itself simple error/string.

Synchronous api:

  new Rules({foo: 'optional', bar: 'required'})
    .validate({
      foo: null,// no errors
      bar: null // error
    },true)

Promise-based api is also available (asynchronous api):

new Rules(...).validate(dataStructure)
  .then(dataStructure => ...)
  .catch(error => /* do something with error * )

You can also use async/await:

const targetObject = await ....validate(targetObject,...); 

Rules static errors

Whenever the error occurs the method throws the following errors:
Rules.OBJECT_IS_MISSING - when first argument is missing
Rules.INVALID_OBJ_REDUNDANT_PROPS - when there are redundunt (regarding those in schema) fileds in the provided object
Rules.VALIDATION_PROP_REQUIRED - when value is 'required' by the schema but missing in provided object

class Rule

new Rule(rule,name)

The rule wrapper.

Rule static errors

Rule.INVALID_REGEXP - thrown if provided regexp fails against provided value

Rule helpers

Here also some useful exports that can be used during schema building:
min(n: string | number): (v) => ... - return function can be used to restrict string length or number count
max(n: string | number): (v) => ... - see usage below

EXAMPLES

Creating function rule

Let's assume we want to validate _id field. We can do this by creating a validation function
that checks ID class and returns error (just string) if something is going wrong:

import {Rules} from 'stigma';
error = new Rules({_id: value => (value instanceof IDClass) || 'IDClass instance expected!' })
  .validate(someObject, true)

You won't get the true in the promise if value is instance of the IDClass.

Combining several rules

Schema below contains two rules: String and max
The key below is expected to be of string type and no more than six chars long:

import {Rules, max} from 'stigma';
// return error if "key" is not a string or longer than 6 chars
error = new Rules({key: [ String, max(6) ] }).validate({key: 'keyvalue'}, true)

---

Go back to the top