Built-in Schemas

Reference for all built-in schemas — strings, numbers, URLs, booleans, and parsed types.

better-env ships with a set of ready-to-use schemas for common environment variable patterns. All schemas are exported from the main package.

import { requiredString, port, boolean, url } from "@ayronforge/better-env"

String schemas

Name	Type	Default	Description
requiredString	string	—	Non-empty string. Fails if the value is undefined or empty.
optionalString	string \| undefined	—	Optional string. Allows undefined values.

import { requiredString, optionalString } from "@ayronforge/better-env"

createEnv({
  server: {
    API_KEY: requiredString,       // must be present and non-empty
    OPTIONAL_FLAG: optionalString,  // can be undefined
  },
})

Number schemas

Name	Type	Default	Description
positiveNumber	number	—	Positive number parsed from string. Must be > 0.
integer	number	—	Integer parsed from string. No decimals allowed.
nonNegativeNumber	number	—	Non-negative number parsed from string. Must be >= 0.
port	number	—	Port number (1–65535), parsed from string.

import { port, positiveNumber, integer } from "@ayronforge/better-env"

createEnv({
  server: {
    PORT: port,                    // 1-65535
    MAX_RETRIES: integer,          // whole number
    RATE_LIMIT: positiveNumber,    // > 0
  },
})

Boolean schema

Name	Type	Default	Description
boolean	boolean	—	Parses 'true', 'false', '1', '0' (case-insensitive) into a boolean.

import { boolean } from "@ayronforge/better-env"

createEnv({
  server: {
    DEBUG: boolean,       // "true" → true, "0" → false
    VERBOSE: boolean,
  },
})

URL schemas

Name	Type	Default	Description
url	string	—	Valid HTTP or HTTPS URL.
postgresUrl	string	—	PostgreSQL connection URL (postgres:// or postgresql://).
redisUrl	string	—	Redis connection URL (redis:// or rediss://).
mongoUrl	string	—	MongoDB connection URL (mongodb:// or mongodb+srv://).
mysqlUrl	string	—	MySQL connection URL (mysql:// or mysqls://).
commaSeparatedUrls	string[]	—	Comma-separated list of valid HTTP/HTTPS URLs.

import { url, postgresUrl, redisUrl } from "@ayronforge/better-env"

createEnv({
  server: {
    DATABASE_URL: postgresUrl,     // postgresql://user:pass@host:5432/db
    REDIS_URL: redisUrl,           // redis://localhost:6379/0
    WEBHOOK_URL: url,              // https://example.com/webhook
  },
})

Comma-separated schemas

Name	Type	Default	Description
commaSeparated	string[]	—	Splits a comma-separated string into a trimmed string array.
commaSeparatedNumbers	number[]	—	Splits a comma-separated string into a number array. Throws if any item isn't a valid number.

import { commaSeparated, commaSeparatedNumbers } from "@ayronforge/better-env"

createEnv({
  server: {
    ALLOWED_ORIGINS: commaSeparated,        // "a.com, b.com" → ["a.com", "b.com"]
    RETRY_DELAYS: commaSeparatedNumbers,    // "100,200,500" → [100, 200, 500]
  },
})

Parameterized schemas

`stringEnum`

Creates a schema that accepts only the specified literal values:

import { stringEnum } from "@ayronforge/better-env"

createEnv({
  shared: {
    LOG_LEVEL: stringEnum(["debug", "info", "warn", "error"]),
    // Type: "debug" | "info" | "warn" | "error"
  },
})

`json`

Parses a JSON string and validates the result against an inner schema:

import { json } from "@ayronforge/better-env"
import { Schema } from "effect"

createEnv({
  server: {
    // JSON_CONFIG='{"retries":3,"timeout":5000}'
    JSON_CONFIG: json(Schema.Struct({
      retries: Schema.Number,
      timeout: Schema.Number,
    })),
  },
})

Using Effect Schema directly

Any Effect Schema works as a validator. The built-in schemas are just convenience wrappers:

import { Schema } from "effect"

createEnv({
  server: {
    PORT: Schema.NumberFromString,
    NODE_ENV: Schema.Literal("development", "production", "test"),
    API_KEY: Schema.String.pipe(Schema.minLength(32)),
    CUSTOM: Schema.transform(
      Schema.String,
      Schema.Number,
      { decode: (s) => parseInt(s, 16), encode: (n) => n.toString(16) },
    ),
  },
})

Tip

If you need a schema that doesn’t exist as a built-in, just use Effect Schema directly. better-env accepts any Schema.Schema<any, any, never>.