The environment registry type
The union of all variable types in the registry
StaticcreateCreates a new empty VariableRegistry for the specified environment registry.
The environment registry type
The environment registry to create variables for
A new VariableRegistry with no variables
Adds a new variable definition to the registry.
This method ensures type safety by preventing duplicate variable names and validating that the variable is defined for valid environments.
A new VariableRegistry with the added variable
const varReg = varReg
.addVar("DATABASE_URL", (v) => v
.for("local", "from-env")
.for("workflows", "from-github-secrets"))
.addVar("IS_WORKFLOW", (v) => v
.for("local", "hardcoded", "false")
.for("workflows", "hardcoded", "true"))
.addVar("DOCUMENT_BUCKET", (v) => v
.dynamicFor("local", "documentBucket"))
Merges this variable registry with another one.
This method ensures type safety by preventing conflicts between variable names from both registries.
The variable registry to merge with
A new VariableRegistry with variables from both registries
const openAIVarReg = envReg.createVariableRegistry()
.addVar("OPENAI_API_KEY", (v) => v
.for("workflows", "from-aws-secrets")
.for("local", "from-env"))
const globalVarReg = envReg.createVariableRegistry()
.mergeWith(openAIVarReg)
.addVar("DATABASE_URL", (v) => v
.for("workflows", "from-github-secrets")
.for("local", "from-env"))
InternalCreates a resolver for a specific environment.
The resolver provides type-safe access to variable values for the specified environment. It automatically handles dynamic data requirements based on the variable definitions.
The name of the environment to create a resolver for
The environment data for the target environment
Dynamic data (optional, required only if variables use dynamic resolution)
A Resolver instance for the specified environment
const resolver = varReg.createResolver(
"local",
{ env: { DATABASE_URL: "test" } },
{ documentBucket: "my document bucket name" }
)
// Get values
const isWorkflow = resolver.get("IS_WORKFLOW") // "false"
const dbUrl = resolver.get("DATABASE_URL") // "test"
const bucket = resolver.get("DOCUMENT_BUCKET") // "my document bucket name"
Creates a resolver with dynamic environment selection at runtime.
This method solves the TypeScript limitation where conditional resolver creation breaks type inference. Instead of creating resolvers conditionally, you provide all possible environment configurations upfront and select the environment at runtime.
The resolver only allows access to variables that are defined in ALL possible environments to maintain type safety.
A Resolver instance for the dynamically selected environment
// Instead of this (which breaks type inference):
// const resolver = condition ?
// varReg.createResolver("env1", data1) :
// varReg.createResolver("env2", data2)
// Use this (maintains type safety):
const resolver = varReg.createDynamicResolver({
env1: [{ env: { DATABASE_URL: "dev" } }],
env2: [{ env: { DATABASE_URL: "prod" } }]
}, () => process.env.NODE_ENV === "production" ? "env2" : "env1")
// Only variables defined in both environments are accessible
const dbUrl = resolver.get("DATABASE_URL") // Type-safe access
// With dynamic data:
const resolver = varReg.createDynamicResolver({
local: [{ env: {} }, { bucket: "dev-bucket" }],
prod: [{ env: {} }, { bucket: "prod-bucket" }]
}, () => process.env.NODE_ENV === "production" ? "prod" : "local")
Lists all variables that use a specific resolution tag in a given environment.
This method filters variables based on their environment-specific resolution definitions and returns the names of variables that use the specified tag in their user-defined resolutions.
An array of variable names that use the specified tag in the given environment
Registry for managing variable definitions across multiple environments.
The VariableRegistry provides a fluent API for defining variables and their resolution methods for different environments. It ensures type safety by preventing duplicate variable names and validating environment references.
Example