API Reference

Complete API reference for @ayronforge/envil — all functions, schemas, errors, and types.

createEnv

The main function for creating a type-safe environment object.

Without resolvers

function createEnv<TServer, TClient, TShared, TExtends>(
  opts: EnvOptions<TServer, TClient, TShared, TExtends>
): EnvResult<TExtends, TServer, TClient, TShared>

Returns a fully typed, readonly environment object immediately.

With resolvers

function createEnv<TServer, TClient, TShared, TExtends>(
  opts: EnvOptions<TServer, TClient, TShared, TExtends> & {
    resolvers: readonly Effect.Effect<ResolverResult, ResolverError>[]
  }
): Effect.Effect<EnvResult<TExtends, TServer, TClient, TShared>, ResolverError | EnvValidationError>

Returns an Effect that resolves secrets, validates all variables, and produces the env object.

Options

Name	Type	Default	Description
server	Record<string, Schema>	—	Server-only environment variable schemas. Not validated on client.
client	Record<string, Schema>	—	Client-safe environment variable schemas. Validated everywhere.
shared	Record<string, Schema>	—	Shared environment variable schemas. Validated and accessible everywhere.
extends	readonly AnyEnv[]	—	Array of existing env objects to merge into this one.
prefix	string \| PrefixMap	—	Prefix applied to env var names when reading from the environment.
runtimeEnv	Record<string, string \| undefined>	—	Override process.env with a custom environment source.
isServer	boolean	—	Override server detection. Defaults to typeof window === 'undefined'.
emptyStringAsUndefined	boolean	—	Treat empty string values as undefined.
onValidationError	(errors: string[]) => void	—	Callback fired before EnvValidationError is thrown.
resolvers	readonly Effect.Effect<ResolverResult, ResolverError>[]	—	Array of resolver Effects. When present, createEnv returns an Effect.
autoRedactResolver	boolean	—	Default true. Auto-wraps resolver-provided values in Redacted. Types reflect this automatically.

PrefixMap

interface PrefixMap {
  server?: string
  client?: string
  shared?: string
}

safeCreateEnv

A safe alternative to createEnv that returns discriminated result objects instead of raising exceptions.

Without resolvers

function safeCreateEnv<TServer, TClient, TShared, TExtends>(
  opts: EnvOptions<TServer, TClient, TShared, TExtends>
): SafeCreateEnvResult<EnvResult<TExtends, TServer, TClient, TShared>, EnvValidationError>

Returns { success: true, data } or { success: false, error } synchronously.

With resolvers

function safeCreateEnv<TServer, TClient, TShared, TExtends>(
  opts: EnvOptions<TServer, TClient, TShared, TExtends> & {
    resolvers: readonly Effect.Effect<ResolverResult, ResolverError>[]
  }
): Effect.Effect<
  SafeCreateEnvResult<EnvResult<...>, ResolverError | EnvValidationError>,
  never
>

Returns an Effect that never fails — both resolver and validation errors are captured in the result.

Result types

Name	Type	Description
SafeCreateEnvSuccess<T>	{ success: true; data: T }	Success branch of the result.
SafeCreateEnvFailure<E>	{ success: false; error: E }	Failure branch of the result.
SafeCreateEnvResult<T, E>	SafeCreateEnvSuccess<T> \| SafeCreateEnvFailure<E>	Discriminated union of success and failure.

Accepts the same options as createEnv — see Safe Parsing for full usage details.

Schemas

All schemas are exported from @ayronforge/envil.

String schemas

Name	Type	Default	Description
requiredString	Schema<string, string>	—	Non-empty string (minLength: 1).

Number schemas

Name	Type	Default	Description
number	Schema<number, string>	—	Any number parsed from string via NumberFromString.
positiveNumber	Schema<number, string>	—	Positive number parsed from string (> 0).
integer	Schema<number, string>	—	Integer parsed from string.
nonNegativeNumber	Schema<number, string>	—	Non-negative number parsed from string (>= 0).
port	Schema<number, string>	—	Port number 1–65535, parsed from string.

Boolean schema

Name	Type	Default	Description
boolean	Schema<boolean, string>	—	Parses 'true', 'false', '1', '0' into boolean.

URL schemas

Name	Type	Default	Description
url	Schema<string, string>	—	Valid HTTP or HTTPS URL.
postgresUrl	Schema<string, string>	—	PostgreSQL connection URL.
redisUrl	Schema<string, string>	—	Redis connection URL.
mongoUrl	Schema<string, string>	—	MongoDB connection URL.
mysqlUrl	Schema<string, string>	—	MySQL connection URL.
commaSeparatedUrls	Schema<string[], string>	—	Comma-separated HTTP/HTTPS URLs.

Collection schemas

Name	Type	Default	Description
commaSeparated	Schema<string[], string>	—	Comma-separated string to trimmed string array.
commaSeparatedNumbers	Schema<number[], string>	—	Comma-separated string to number array.

Parameterized schemas

Name	Type	Default	Description
stringEnum(values)	(values: string[]) => Schema<string, string>	—	Creates a literal union schema from the provided values.
json(schema)	(schema: Schema) => Schema<T, string>	—	Parses JSON string and validates against the inner schema.

Helpers

Name	Type	Default	Description
withDefault(schema, value)	(schema: S, default: T) => Schema	—	Makes a schema optional with a default value. Supports data-first and pipe style.
optional(schema)	(schema: S) => Schema<T \| undefined>	—	Makes a schema accept undefined. Shorthand for Schema.UndefinedOr(schema).
redacted(schema)	(schema: S) => Schema<Redacted<T>>	—	Wraps schema output in Effect Redacted. Use Redacted.value() to unwrap.

Error classes

EnvValidationError

class EnvValidationError extends Error {
  readonly _tag: "EnvValidationError"
  readonly errors: ReadonlyArray<string>
}

Thrown when environment variable validation fails. Contains all validation error messages.

ClientAccessError

class ClientAccessError extends Error {
  readonly _tag: "ClientAccessError"
  readonly variableName: string
}

Thrown when client code accesses a server-only variable.

ResolverError

class ResolverError extends Data.TaggedError("ResolverError")<{
  readonly resolver: string
  readonly message: string
  readonly cause?: unknown
}>

Effect tagged error for resolver failures.

Presets

Exported from @ayronforge/envil/presets.

Name	Type	Default	Description
nextjs	{ prefix: { client: "NEXT_PUBLIC_" } }	—	Next.js client prefix preset.
vite	{ prefix: { client: "VITE_" } }	—	Vite client prefix preset.
expo	{ prefix: { client: "EXPO_PUBLIC_" } }	—	Expo client prefix preset.
nuxt	{ prefix: { client: "NUXT_PUBLIC_" } }	—	Nuxt client prefix preset.
sveltekit	{ prefix: { client: "PUBLIC_" } }	—	SvelteKit client prefix preset.
astro	{ prefix: { client: "PUBLIC_" } }	—	Astro client prefix preset.

Resolvers

fromAwsSecrets

import { fromAwsSecrets } from "@ayronforge/envil/aws"

Name	Type	Default	Description
secrets Required	Record<string, string>	—	Env var names → secret IDs. Supports #jsonKey syntax.
region	string	—	AWS region.
strict	boolean	false	When true, secret fetch/parsing errors fail with ResolverError instead of returning undefined.

fromGcpSecrets

import { fromGcpSecrets } from "@ayronforge/envil/gcp"

Name	Type	Default	Description
secrets Required	Record<string, string>	—	Env var names → secret names or full resource paths.
projectId	string	—	GCP project ID.
version	string	"latest"	Secret version.
strict	boolean	false	When true, secret fetch errors fail with ResolverError instead of returning undefined.

fromAzureKeyVault

import { fromAzureKeyVault } from "@ayronforge/envil/azure"

Name	Type	Default	Description
secrets Required	Record<string, string>	—	Env var names → Key Vault secret names.
vaultUrl Required	string	—	Azure Key Vault URL.
credential	unknown	—	Azure credential. Defaults to DefaultAzureCredential.
strict	boolean	false	When true, secret fetch errors fail with ResolverError instead of returning undefined.

fromOnePassword

import { fromOnePassword } from "@ayronforge/envil/1password"

Name	Type	Default	Description
secrets Required	Record<string, string>	—	Env var names → 1Password secret references (op:// URIs).
serviceAccountToken	string	—	1Password service account token.
strict	boolean	false	When true, batch resolution errors fail with ResolverError instead of returning undefined.

fromRemoteSecrets

import { fromRemoteSecrets } from "@ayronforge/envil"

Name	Type	Default	Description
secrets Required	Record<string, string>	—	Env var names → secret identifiers passed to the client.
client Required	SecretClient	—	Custom client implementing the SecretClient interface.
strict	boolean	false	When true, client fetch errors fail with ResolverError instead of returning undefined.

SecretClient

The client interface for fromRemoteSecrets and custom integrations.

import type { SecretClient } from "@ayronforge/envil"

interface SecretClient {
  getSecret: (secretId: string) => Promise<string | undefined>
  getSecrets?: (secretIds: string[]) => Promise<Map<string, string | undefined>>
}

getSecret — required. Fetches a single secret by ID.
getSecrets — optional. When provided and there are multiple secrets, enables batch fetching.