Skip to content

Typed schema based validation with low calories (KBs)

License

Notifications You must be signed in to change notification settings

poppinss/validator-lite

Repository files navigation

Validator Lite

Typed schema based validation with low calories

github-actions-image npm-image license-image typescript-image

Really simple and lightweight validation library for JavaScript. Used by @adonisjs/env for validating environment variables.

Installation

Install the module from npm registry as follows:

npm install @poppinss/validator-lite

# yarn
yarn add @poppinss/validator-lite

# pnpm 
pnpm add @poppinss/validator-lite

Basic usage

The following example shows how to use the validator :

import { schema } from '@poppinss/validator-lite'

/**
 * Define a schema
 */
const userSchema = {
  name: schema.string(),
  age: schema.number(),
  email: schema.string.optional(),
  website: schema.string({ format: 'url' }),
}

/**
 * Define the data
 */
const data = {
  name: 'John doe',
  age: 25,
  website: 'https://adonisjs.com',
}

/**
 * Validate the data
 */
for (let [key, fn] of Object.entries(userSchema)) {
  fn(key, user[key])
}

API

Following is the list of available methods :

schema.string

Validates the value to check if it exists and if it is a valid string. Empty strings fail the validations, and you must use the optional variant to allow empty strings.

{
  APP_KEY: schema.string()
}
// Mark it as optional
{
  APP_KEY: schema.string.optional()
}

You can also force the value to have one of the pre-defined formats.

// Must be a valid host (url or ip)
schema.string({ format: 'host' })
// Must be a valid URL
schema.string({ format: 'url' })
// Must be a valid email address
schema.string({ format: 'email' })

When validating the url format, you can also define additional options to force/ignore the tld and protocol.

schema.string({ format: 'url', tld: false, protocol: false })

schema.boolean

Enforces the value to be a valid string representation of a boolean. Following values are considered as valid booleans and will be converted to true or false.

  • '1', 'true' are casted to Boolean(true)
  • '0', 'false' are casted to Boolean(false)
{
  CACHE_VIEWS: schema.boolean()
}
// Mark it as optional
{
  CACHE_VIEWS: schema.boolean.optional()
}

schema.number

Enforces the value to be a valid string representation of a number.

{
  PORT: schema.number()
}
// Mark it as optional
{
  PORT: schema.number.optional()
}

schema.enum

Forces the value to be one of the pre-defined values.

{
  MY_ENUM: schema.enum(['development', 'production'] as const)
}
// Mark it as optional
{
  MY_ENUM: schema.enum.optional(['development', 'production'] as const)
}

Custom functions

For every other validation use case, you can define your custom functions.

{
  PORT: (key, value) => {
    if (!value) {
      throw new Error('Value for PORT is required')
    }
    
    if (isNaN(Number(value))) {
      throw new Error('Value for PORT must be a valid number')    
    }
    return Number(value)
  }
}
  • Make sure to always return the value after validating it.
  • The return value can be different from the initial input value.