Validation with v (Reference)

v is a convenience wrapper around Zod tailored for settings. It enables coercion and concise validation chains.

Coercion by default

@setting(v.number().int().min(1).max(10).default(5))
retries!: number

@setting(v.boolean())
debug!: boolean

@setting(v.date())
launchDate!: Date

Accepts strings from env (e.g., "5", "true", "2025-05-16").

Strings

@setting(v.string().min(5).max(15))
username!: string

@setting(v.string().email())
contact!: string

@setting(v.string().regex(/^[a-z]{3,10}$/))
slug!: string

Enums

@setting(v.enum(['debug','info','warn','error']))
logLevel!: string

Arrays and objects

@setting(v.array(v.number()))
thresholds!: number[]

@setting.array() // defaults to array of strings
hosts!: string[]

// Objects
@setting(v.object({ name: v.string(), age: v.number() }))
user!: { name: string; age: number }
// or, simple JSON object without a shape
@setting.object()
meta!: Record<string, unknown>

Objects are JSON‑parsed from env strings (e.g., APP_USER={"name":"Ada","age":42}).

Env examples

# arrays
export APP_HOSTS='["a.example.org","b.example.org"]'

# objects
export APP_USER='{"name":"Ada","age":42}'

Defaults

Two default styles:

@setting.string()
host: string = 'localhost'        // assignment default

@setting(v.string().default('x'))
name!: string                     // validator default

Assignment defaults are clear for simple cases; validator defaults shine with other constraints.