resolve

Documentation

Overview

Package resolve provides variable resolvers for use with gopherly.dev/synthra.WithEnvSubst.

A Resolver looks up a variable name and returns its value. You can build resolvers from static maps, OS environment variables, or your own lookup logic. Use Chain to combine multiple resolvers with priority ordering (last resolver wins).

Available Resolvers

• Vars: look up variables from a map[string]string
• OS: look up variables from os.LookupEnv
• OSPrefix: look up OS env vars that match a prefix (prefix is stripped)
• Chain: combine multiple resolvers (last wins)

How Priority Works

When you pass multiple resolvers to Chain or to gopherly.dev/synthra.WithEnvSubst, they are checked in order. If more than one resolver knows the same variable, the last one in the list wins. This means you can put lower-priority defaults first and higher-priority overrides last.

Example

Combine a static map with OS environment overrides:

r := resolve.Chain(
    resolve.Vars(map[string]string{"PORT": "3000"}),
    resolve.OS(),
)
val, ok := r("PORT")
// If PORT is set in the environment, ok is true and val is the
// OS value. Otherwise val is "3000" from the static map.

Use with WithEnvSubst:

cfg := synthra.MustNew(
    synthra.WithFile("config.yaml"),
    synthra.WithEnvSubst(
        resolve.Vars(defaults),     // lowest priority
        resolve.Vars(fileVars),     // medium priority
        resolve.OSPrefix("APP_"),   // highest priority
    ),
)

Index

• type Resolver
  • func Chain(resolvers ...Resolver) Resolver
  • func OS() Resolver
  • func OSPrefix(prefix string) Resolver
  • func Vars(m map[string]string) Resolver

Types

type Resolver

type Resolver func(name string) (value string, found bool)

Resolver looks up a variable by name. It returns the value and whether the variable was found. A nil Resolver always returns ("", false). A Resolver must be safe for concurrent use.

func Chain

func Chain(resolvers ...Resolver) Resolver

Chain merges multiple resolvers into one. Resolvers are checked in order; when more than one resolves the same variable name, the last one wins (highest priority last).

If no resolvers are given, the returned Resolver always returns ("", false).

Example:

r := resolve.Chain(
    resolve.Vars(map[string]string{"PORT": "3000"}),
    resolve.OS(),
)
// If PORT is set in the environment, OS() wins.
// Otherwise Vars() provides "3000" as a fallback.

func OS

func OS() Resolver

OS returns a Resolver that looks up variables using os.LookupEnv. Each call reads the live process environment, so changes made between gopherly.dev/synthra.Synthra.Load calls are visible.

Example:

r := resolve.OS()
val, ok := r("HOME") // looks up os.LookupEnv("HOME")

func OSPrefix

func OSPrefix(prefix string) Resolver

OSPrefix returns a Resolver that looks up OS environment variables with the given prefix. The prefix is stripped before matching, so the caller asks for the short name and the resolver maps it to the prefixed environment variable.

For example, OSPrefix("APP_") resolves "PORT" by looking up "APP_PORT" in the environment. If APP_PORT is set, the resolver returns its value. If it is not set, found is false.

Example:

r := resolve.OSPrefix("APP_")
val, ok := r("PORT") // looks up os.LookupEnv("APP_PORT")

func Vars

func Vars(m map[string]string) Resolver

Vars returns a Resolver that looks up variables from a static map. The map is read as-is; keys are case-sensitive. Passing a nil map returns a Resolver that never finds any variable.

Example:

r := resolve.Vars(map[string]string{
    "ENV":  "production",
    "PORT": "8080",
})
val, ok := r("PORT") // val = "8080", ok = true