Format

This section describes the format (the sanitation schema) we give to Sandhands to define how it should sanitize the input.

Primitives Basics

Null and undefined can be passed in as is, and it will expect strict equality.

const {valid} = require('sandhands')

valid('', null) // false
valid(undefined, null) // false
valid(null, null) // true

valid('', undefined) // false
valid(null, undefined) // false
valid(undefined, undefined) // true

Numbers, Strings, and Booleans can be passed in by using their class names.

const {valid} = require('sandhands')

valid(12, String) // false
valid(String, String) // false
valid('hello world', String) // true

valid('ganondorf', Number) // false
valid(Number, Number) // false
valid(42, Number) // true

Options

All data types have a set of default options which accompany them. We can override the defaults with our own arguments two different ways
The first way is we can pass the options as the third argument after the format to the method.

const {valid} = require('sandhands')

console.log(valid('hello', String, {minLength: 8})) // false
console.log(valid('hello world', String, {minLength: 8})) // true

The second way to pass options is inside the format itself. We use a special object syntax to designate this:

const {valid} = require('sandhands')

console.log(valid("Lily", {_: String, lowercase: true})) // false
console.log(valid("lily", {_: String, lowercase: true})) // true

Strings

The following options are available for strings:

email

Flag as true to required the string be a valid email.

lowercase

Flag as true to required the string be lowercase.

uppercase

Flag as true to required the string be uppercase.

minLength

Set the minimum required length of the string. Default: 1

maxLength

Set the maximum required length of the string.

length

Set the exact required length of the string.

allowed

Set a string to whitelist the input string.

banned

Set a string to blacklist the input string.

whitespace

Flag as false to require the string to contain no whitespaces.

regex

Set a regular expression to test the input string.

trimmed

Flag as true to require the string to not begin or end with whitespace.

Numbers

integer

Flag as true to require whole numbers. Default: false

allowNaN

Flag as true to allow NaN. Default: false

finite

Flag as false to allow Infinity. Default: true

min

Set the minimum value of the input

max

Set the maximum value of the input

even

Flag as true to require even numbers.

odd

Flag as true to require odd numbers.

Objects

We can sanitize objects by creating our own object representing how we expect the input to be formatted.

strict

Flag as true to require all input values to be defined by the format in order to be valid (unless flagged as optional). This also prevents the user from providing their own additional properties. Default: true

allOptional

Flag as true to make all of the properties optional

bannedProps

Provide an array of property names (strings) to designate which properties are not allowed to be provided.

optionalProps

Provide an array of property names (strings) to designate which properties are optional.

Here's an example of the sanitation behavior using these options

const {valid} = require('sandhands')

console.log(valid({}, {})) // true
console.log(valid({}, {a: String})) // false
console.log(valid({a: 'hello world'}, {a: String})) // true
console.log(valid({}, {_: {a: String}, optionalProps: ["a"]})) // true
console.log(valid({b: 12}, {})) // false
console.log(valid({b: 12}, {}, {strict: false})) // true

Arrays

We can sanitize arrays by creating our own array representing how we expect the input to be formatted. The default array behavior might seem confusing at first, however once you understand it in practice it is simple and expressive.

standard

Manually set the standard to use for all array values

firstAsStandard

Flag as true to splice the first element of the format array and use it to validate all values of the input array that are not explicitly defined by the format array. The values of all of the format array are all shifted to the left by one index. Default: true if the array length is equal to 1

strict

Flag as true to require all array indexs to be defined by the format in order to be valid. Default: true if the format length is at least 1

minLength

Set the minimum required length of the array. Default: 1 unless the format array is empty and there is no standard.

maxLength

Set the maximum length of the array.

length

Set the exact required length of the array.

Here's an example of the sanitation behavior using these options

const {valid} = require('sandhands')

console.log(valid([], [])) // true
console.log(valid([], [Number])) // true - Because the format array is only one element long the first value is set as the firstAsStandard format, and strict is not assumed to be true.
console.log(valid([12], [Number])) // true
console.log(valid([54, 25], [Number])) // true - As you can see
console.log(valid([12, 12], [Number, Number])) // true - Because the format array is longer than one element firstAsStandard is not assumed and strict is set to true.

console.log(valid([52, 63, 14], [Number, Number])) // false - Because strict is assumed extra array elements will cause validation to fail.

console.log(valid(['a', 15, 25], {_:[Number, String], firstAsStandard: true})) // true - We can also use firstAsStandard alongside with specific formats for certain array indexes by setting it explicitly in the inline options. The first index (Number) will be the standard format for all indexes, and the second index will now become the beginning of the array of custom formats for specific indexes, meaning the first array index will be expected to be a string, and all following indexes will be expected to be numbers.

Functions

Functions automatically support all of the object options because functions are effectively also objects.

Universal Options

validate

Expects a function or array of functions to compare the input with. If any don't return true, reject the input.

equalTo

Expects the input to be strictly equal (using the === operator) to the value of the equalTo option.

deepEqualTo

Expects the input to be deeply equal to the value of the deepEqualTo option.

nullable

Flag as true in order to accept null instead of the provided format, hence making the input "nullable".

All

The All format is a special class we can import that acts as a wildcard. Please be careful with this as any kind of dangerous input could be passed. Please only use this if you know what you are doing.

Here's an example of the sanitation behavior using these options

const {valid, All} = require('sandhands')

console.log(valid("Hello :)", All)) // true
console.log(valid(Infinity, All)) // true
console.log(valid({a: 'hello world', b: 12}, {a: String, b: All})) // true