API Reference

Complete API reference for @ayronforge/better-env — 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
}

Schemas

All schemas are exported from @ayronforge/better-env.

String schemas

Name	Type	Default	Description
requiredString	Schema<string, string>	—	Non-empty string (minLength: 1).
optionalString	Schema<string \| undefined, string \| undefined>	—	Optional string. Allows undefined.

Number schemas

Name	Type	Default	Description
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.
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/better-env/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.

Resolvers

fromAwsSecrets

import { fromAwsSecrets } from "@ayronforge/better-env/aws"

Name	Type	Default	Description
secrets Required	Record<string, string>	—	Env var names → secret IDs. Supports #jsonKey syntax.
region	string	—	AWS region.

fromGcpSecrets

import { fromGcpSecrets } from "@ayronforge/better-env/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.

fromAzureKeyVault

import { fromAzureKeyVault } from "@ayronforge/better-env/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.

fromOnePassword

import { fromOnePassword } from "@ayronforge/better-env/1password"

Name	Type	Default	Description
secrets Required	Record<string, string>	—	Env var names → 1Password secret references (op:// URIs).
serviceAccountToken	string	—	1Password service account token.

fromRemoteSecrets

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

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.

SecretClient

The client interface for fromRemoteSecrets and custom integrations.

import type { SecretClient } from "@ayronforge/better-env"

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.