Resolver functions

You may use resolver functions instead of static values within both config items and decorator values.

Functions can be composed together to create more complex value resolution logic.

ITEM=fn(arg1, arg2)
COMPOSITION=fn1(fn1Arg1, fn2(fn2Arg1, fn2Arg2))

Note that many built-in utility functions have expansion equivalents and often it will be more clear to use them that way. For example:

EXPANSION_EQUIVALENT="pre-${OTHER}-post"
USING_FN_CALLS=concat("pre-", ref(OTHER), "-post")

# mixed example
CONFIG=exec(`aws ssm get-parameter --name "/config/${APP_ENV}" --with-decryption`)

Currently, there are built-in utility functions, and soon there will be functions to handle values encrypted using varlock provided tools.

Plugins may also register additional resolvers - which can be used to generate and transform values, or fetch data from external providers.

`ref()`

References another config item (env var) - which is useful when composing multiple functions together.

Expansion equivalent: ref(OTHER_VARL) === ${OTHER_VAR} (and also $OTHER_VAR)

We recommend using the bracketed version within string templates, and the simpler version when referencing an item directly.

API_URL=https://api.example.com
USERS_API_URL=${API_URL}/users
USERS_API_URL2=concat(ref("API_URL"), "/users") # without using expansion

`concat()`

Concatenates multiple values into a single string.

Expansion uses concat() to combine multiple parts of strings when they include multiple parts.

PATH=concat("base/", ref("APP_ENV"), "/config.json")
PATH2=`base/${APP_ENV}/config.json` # equivalent using expansion

`exec()`

Executes a CLI command and uses its output as the value. This is particularly useful for integrating with external tools and services.

NOTE - many CLI tools output an additional newline. exec() will trim this automatically.

Expansion equivalent: exec(command) === $(command)

# Using 1Password CLI
API_KEY=exec(`op read "op://dev test/service x/api key"`)
# Using AWS CLI
AWS_CREDENTIALS=exec(`aws sts get-session-token --profile prod`)

`fallback()`

Returns the first non-empty value in a list of possible values.

POSSIBLY_EMPTY=
ANOTHER=
EXAMPLE=fallback(ref(POSSIBLY_EMPTY), ref(ANOTHER), "default-val")

`remap()`

Maps a value to a new value based on a set of remapping rules. This is useful for translating one value, often provided by an external platform, into another.

The first argument is the value to remap (often a ref() to another variable).
All following arguments are key=value pairs, where the key is the new value and the value is what to match against, which can be a string, undefined, or a regex() call.
If no match is found, the original value is returned.

# env var that is set by CI/platform
CI_BRANCH=

# @type=enum(development, preview, production)
APP_ENV=remap($CI_BRANCH, production="main", preview=regex(.*), development=undefined)

`regex()`

Creates a regular expression for use in other functions, such as remap().

Takes a single string argument, which is the regex pattern (using JavaScript regex syntax)
This cannot be used as a standalone value. It must be used only as a function argument.

# Example usage within remap
ENV_TYPE=remap($APP_ENV, dev=regex("^dev.*"), prod="production")

`forEnv()`

Resolves to a boolean, if the current environment matches any in the list passed in as args.

Requirements:

Requires an @currentEnv to be set in your .env.schema file
Takes one or more environment names as arguments

# @currentEnv=$APP_ENV @defaultRequired=false
# @disable=forEnv(test)  # entire file will be disabled if env is test
# ---
APP_ENV=staging

# Required only in development
# @required=forEnv(development)
DEV_API_KEY=

# Required in staging and production
# @required=forEnv(staging, production)
PROD_API_KEY=

`eq()`

Checks if 2 values are equal and resolves to a boolean.

IS_STAGING_DEPLOYMENT=eq($GIT_BRANCH, "staging")

`if()`

Checks a boolean to return a true/false option

API_URL=if(eq($GIT_BRANCH, "main"), api.example.com, staging-api.example.com)

`not()`

Negates a value and returns a boolean. Falsy values are - false, "", 0, undefined, and will be negated to true. Otherwise will return false.

# Negate the result of another function
SHOULD_DISABLE_FEATURE=not(forEnv(production))

`isEmpty()`

Returns true if the value is undefined or an empty string, false otherwise.

# Check if a value is empty
HAS_API_KEY=not(isEmpty($API_KEY))

# Use with conditional logic
API_URL=if(isEmpty($CUSTOM_API_URL), "https://api.default.com", $CUSTOM_API_URL)