@poppinss/validator-lite

Validator Lite

Typed schema-based validation with low calories

A lightweight schema-based validation library similar to Zod and VineJS. It is used by the @adonisjs/env package for validating environment variables, as bundling a full-blown validation library to validate environment variables seems like overkill.

Installation

Install the module from the npm registry as follows:

npm install @poppinss/validator-lite

yarn add @poppinss/validator-lite

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 envSchema = {
  HOST: schema.string({ format: 'host' }),
  PORT: schema.number(),
  APP_URL: schema.string.optional({ type: 'url', tld: false }),
}

/**
 * Define the data
 */
const envVariables = {
  HOST: 'localhost',
  PORT: '3333'
}

/**
 * Validate the data
 */
for (let [key, schemaFn] of Object.entries(envSchema)) {
  schemaFn(key, envVariables[key])
}

API

Following is the list of available methods :

schema.string

Validate the value to exist and be a valid non-empty string.

{
  APP_KEY: schema.string()
}

{
  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 address)
 */
schema.string({ format: 'host' })

/**
 * Must be a valid URL with or without tld
 */
schema.string({ format: 'url' })
schema.string({ format: 'url', tld: false })

/**
 * Must be a valid email address
 */
schema.string({ format: 'email' })

/**
 * Must be a valid UUID
 */
schema.string({ format: 'uuid' })

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

schema.string({
  format: 'url',
  tld: false, // allow URL without .com, .net, and so on
  protocol: false
})

schema.boolean

Validate the value to exist and be a valid non-empty boolean value. The following values will be cast to a JavaScript boolean data type.

• '1', 'true' are casted to Boolean(true)
• '0', 'false' are casted to Boolean(false)

{
  CACHE_VIEWS: schema.boolean()
}

{
  CACHE_VIEWS: schema.boolean.optional()
}

schema.number

Validate the value to exist and be a valid non-empty numeric value. The string representation of a number value will be cast to a JavaScript number data type.

{
  PORT: schema.number()
}

{
  PORT: schema.number.optional()
}

schema.enum

Validate the value to exist and must be one of the pre-defined values.

{
  NODE_ENV: schema.enum(['development', 'production'] as const)
}

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

Custom functions

For all other validation use cases, you can use custom functions. A custom function can throw errors for invalid values and must return the final output value.

{
  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)
  }
}