Core Concepts

CtroEnv is built around three core concepts: validators, schemas, and defineEnv().

Validators

A validator is a function that takes an input value and either returns a parsed value or collects errors. Each validator has a specific type and can be refined with chainable methods.

CtroEnv provides four built-in validators:

Type Coercion

• string(): Only accepts actual strings. Non-strings produce a type error.
• number(): Accepts number values and numeric strings like "42". Rejects NaN, Infinity, empty strings, and non-numeric strings.
• boolean(): Accepts true, false, numbers 1/0, and strings "true"/"false"/ "yes"/"no"/"on"/"off"/"1"/"0" (case-insensitive, trimmed).
• pick(): Only accepts exact string matches from the provided list.

Refinements

Refinements add constraints on top of a validator. They are chainable:

string().url().min(1).max(255).optional()
number().int().positive().min(0).max(100)

Each refinement returns a new validator with the additional constraint — the original validator is not mutated. This means you can reuse base validators:

const baseUrl = string().url()
 
const serverUrl = baseUrl.describe("Server URL")
const clientUrl = baseUrl.describe("Client URL").optional()

Chainable Methods

These methods are available on every validator:

Schemas

A schema is a plain object where keys are environment variable names and values are validators:

const schema = {
  DATABASE_URL: string().url(),
  PORT: number().port().default(3000),
}

The schema definition is a Record<string, Validator<unknown>>. TypeScript infers the output type automatically.

defineEnv()

defineEnv() is the main entry point. It takes a schema and optional source, then:

1. Walks each key in the schema
2. Reads the value from the environment source
3. Runs the validator
4. Collects all errors (doesn't throw on first error)
5. Returns a deeply frozen, typed object — or throws CtroEnvError with all errors

const env = defineEnv(schema, {
  source: { DATABASE_URL: "postgresql://...", PORT: "4000" },
  prefix: "MY_APP_",  // prefix for key lookup
})

Environment Sources

An environment source is any object with a get(key: string) => string | undefined method.

Error Handling

When validation fails, defineEnv() throws a CtroEnvError:

class CtroEnvError extends Error {
  readonly errors: readonly ValidationError[]
}

Each ValidationError has:

Error Codes