Version: v0.7.0 - Beta.  We welcome contributors & feedback.

Input Validation

Overview

When you get the value of an input field (via the Input or Form modules), it must first be validated to make sure it is safe to work with.

Rulesets

To declare what kinds of values are allowed for a field, you assign it a ruleset.

A ruleset is just a Map of one or more validation rules.

Every ruleset must have a type rule, plus any additional constraints.

// Positive (i)nteger
Input.get('age', { type: 'i' })

// (s)tring, 3 to 12 characters long.
Input.get('color', { type: 's', min: 3, max: 10 })

Shorter Syntax

Instead of a Map, you can use a pipe-delimited string.

The first value must be the type, followed by any additional rules.

Rules that only take a true boolean can be set as a standalone flag.

Input.get('age', 'i')

Input.get('color', 's|min:3|max:12|optional')

Defaults

All fields are required unless given the optional rule.

By default, the validator applies these filters to the incoming data, unless overrided by a rule:

Types

Basic Types

type Description Length/Range Examples
b boolean -- 'true', 'false', '1', '0'
i integer 0 - any 1, 7, 1000
f float 0 - any 1.0, 3.14
s string 1 - 50 'abc 123'
ms multiline string 1 - 2000 'Hello,\nI have a bug.'
id id token
(a-z A-Z 0-9 -_.)
1 - 100 's63asg352', 'my-post'

Registration Types

type Length Characters Examples
username 3 - 20 a-z A-Z 0-9 _ cat123
password 8 - 100 any any
newPassword 8 - 100 any see below
email 4 - 60 ___@____ me@mail.com
accepted -- -- Must be 'true' or '1'

Contact Types

type Length Characters Examples
name 1 - 50 any Juan D. García-Díaz
firstName 1 - 20 any Juan
lastName 1 - 30 any García-Díaz
phone 6 - 30 0-9 ().-+ext (123) 456-7890

Content Types

type Length Characters Examples
title 1 - 80 any e.g. forum titles
comment 1 - 2000 any e.g. forum posts

Date Types

Date types return a Date object.

type Format Examples
date yyyy-mm-dd 2021-07-14
dateTime yyyy-mm-ddTMM:SS 2021-07-14T15:43
dateMonth yyyy-mm 2021-07
dateWeek yyyy-W## 2021-W13
time MM:SS 13:45

Other Types

type Length Characters Examples
url 8 - 200 http(s)://____ http://asite.com
search 1 - 100 any any
color 7 #RRGGBB #113399
json 1 - any {...} '{a:1,b:2,c:"three"}'
xDangerRaw 1 - any any --

Constraints

Constraint Rules

rule Description
optional: true Field is not required.
(All fields are required by default)
min: # String length or number must be equal or greater.
max: # String length or number must be equal or less than.
step: # Number must be divisible by step interval.
regex: pattern Entire string must match pattern.
Ex: regex: r'\w\d+'
in: list Must be in list.
Ex: in: ['red', 'blue', 'green']
notIn: list Must NOT be in list.
same: otherField Must have same value as otherField.
Ex: same: 'passwordConfirm'
notSame: otherField Must NOT have same value as otherField.

Modifier Rules

rule Description
list: true Field has multiple values (e.g. via checkboxes)
civilize: true Apply String.civilize().
xDangerAllowHtml: true Do not strip HTML tags.

Uploads

Upload input fields should have an HTML type of file.

The validation type can either be image or file.

Image Uploads

rule Description
type:image
dir:path Upload directory, relative to `data/files`.
dim:width,height Resize the image to these dimensions.
Crop to center if necessary.
keepAspectRatio:true Do not crop when resizing to `dim`.
// Example:
{
    type: 'image',
    dir: 'uploads/profiles',
    dim: '200,200',
}

File Uploads

rule Description
type:file
dir:path Upload directory, relative to `data/files`.
exts:list Allowed extensions. MIME type will be validated.
maxSizeKb:# Must not be greater than this size.
// Example:
{
    type: 'file',
    dir: 'uploads/docs',
    exts: 'doc,pdf',
    maxSizeKb: 200,
}

Passwords

Any password or newPassword field will be returned as a Password object instead of a string.

This protects it from being leaked as plain text elsewhere in your app.

New Password Validation

When created via the Form module, fields with the newPassword rule are validated on the client to prevent weak passwords.

A password is allowed if it follows these rules:

These rules effectively eliminate the top 1,000 most common passwords, and 99% of the 10,000 most common passwords.

This does not lead to perfectly secure passwords, but is a reasonable default for non-critical websites.

To support passwords created by password managers, there is a high length limit (100 characters) and no limit to the type of characters allowed.

See Also