Essentials

Environment

The environment is the least trustworthy input an app has: strings, possibly missing, possibly malformed. @stone-js/env reads it through typed getters that parse and validate, turning a whole class of runtime mysteries into a loud failure at startup.

#Typed getters

The principle

Reading process.env.X gives you a string or undefined, and every caller re-implements parsing and validation. Centralise it: read each value once, typed and checked, and fail immediately when it is wrong.

In Stone.js

Each getter parses to a type and validates. A required value that is absent or malformed throws an EnvError at read time, so misconfiguration is caught at the edge, not deep in a handler.

app/config.tsts

import { getString, getNumber, getBoolean, getUrl, getEnum } from '@stone-js/env'

const dbUrl   = getUrl('DATABASE_URL')                 // throws if absent or not a URL
const pageSize = getNumber('PAGE_SIZE', 20)            // parsed, with a default
const debug   = getBoolean('DEBUG', false)
const region  = getString('REGION', 'eu-west-3')
const tier    = getEnum('TIER', ['free', 'pro'], 'free')

#The getters

Getter	Type	Description
getString(key, default?)	`string`	A required or defaulted string.
getNumber(key, default?)	`number`	Parsed and checked as a number.
getBoolean(key, default?)	`boolean`	Parses true/false/1/0.
getUrl(key, default?)	`URL`	Validates a URL.
getEnum(key, values, default?)	`union`	Restricts to a set of allowed values.
getJson(key, default?)	`object`	Parses a JSON value.
getArray / getEmail / getHost / getObject	`various`	Further typed getters for common shapes.