config

Documentation

Index

• Variables
• func AccessAs[T any](cfg Map, name string) T
• type Config
• type Map
  • func New(opts *Opts) Map
• type Opts

Variables

var (
	//nolint:gochecknoglobals
	NoSchema = &gojsonschema.Schema{}

	ErrNoRegisteredName   = errors.New("could not find a config entry with that name")
	ErrEnvVarRef          = errors.New("could not find an environment variable")
	ErrPathVarRef         = errors.New("could not find path variable")
	ErrPathVarRefCircular = errors.New("circular path reference detected")
	ErrMalformedPathRef   = errors.New("malformed path reference")
	ErrMalformedEnvRef    = errors.New("malformed env reference")
	ErrUnmarshal          = errors.New("failed to decode configuration")
	ErrSubmatchEnv        = errors.New("failed to find submatch in env match")
	ErrSchema             = errors.New("schema validation failed")
)

Functions

func AccessAs

func AccessAs[T any](cfg Map, name string) T

AccessAs accesses a configuration entry by name and casts it to the provided type T. It panics if the config entry is not found or if the type assertion fails.

Types

type Config

type Config interface {
	// SchemaJSONLoader returns the JSON loader for the config struct schema.
	//
	// Example:
	//   func (c *MyConfigStruct) SchemaJSONLoader() gojsonschema.JSONLoader {
	//       return gojsonschema.NewBytesLoader([]byte(`{
	//           "type": "object",
	//           "properties": {
	//               "key": { "type": "string" }
	//           },
	//           "required": ["key"]
	//       }`))
	//   }
	//
	// This provides the JSON loader for the schema used in validation.
	//
	// Returns nil if no schema validation is needed.
	SchemaJSONLoader() gojsonschema.JSONLoader
}

type Map

type Map interface {
	// Register a configuration producer entry with a name and a config struct.
	// The config struct must implement the Config interface.
	//
	// Example:
	//   cfgMap.Register("myConfig", &MyConfigStruct{})
	//
	// This registers a configuration entry named "myConfig" with the provided config struct.
	//
	// The config struct will be populated when Load and Parse are called.
	//
	// Panics if the name is already registered.
	Register(name string, cfg Config)
	// Load configuration data for a registered config entry by name.
	//
	// Example:
	//   err := cfgMap.Load("myConfig", []byte(`{"key": "value"}`))
	//
	// This loads the provided JSON data into the config entry named "myConfig".
	// Returns an error if the name is not registered.
	//
	// MustLoad is similar to Load but panics on error.
	//
	// The actual unmarshalling into the config struct happens when Parse is called.
	//
	// Returns an error if the name is not registered.
	Load(name string, data []byte) error
	// MustLoad is similar to Load but panics on error.
	//
	// Example:
	//   cfgMap.MustLoad("myConfig", []byte(`{"key": "value"}`))
	//
	// This loads the provided JSON data into the config entry named "myConfig".
	// Panics if the name is not registered.
	//
	// The actual unmarshalling into the config struct happens when Parse is called.
	//
	// Panics if the name is not registered.
	MustLoad(name string, data []byte)
	// Parse all loaded configuration entries.
	//
	// This performs the following steps:
	// 1. Resolves all environment variable and path references in the loaded JSON data.
	// 2. Validates the JSON data against the schema provided by the config struct.
	// 3. Unmarshals the JSON data into the config struct.
	//
	// Returns an error if any step fails.
	Parse() error
	// Access a configuration entry by name.
	//
	// Example:
	//   cfg, err := cfgMap.Access("myConfig")
	//
	// This accesses the config entry named "myConfig" and returns the config struct.
	//
	// Returns an error if the name is not registered.
	Access(name string) (Config, error)
}

Map is a configuration map that holds multiple configuration entries.

Each configuration entry is registered with a name and a config struct that implements the Config interface.

Configuration data can be loaded for each entry, and all entries can be parsed to resolve references, validate against schemas, and unmarshal into the config structs.

Example usage:

cfgMap := config.New(&config.Opts{})
cfgMap.Register("myConfig", &MyConfigStruct{})
err := cfgMap.Load("myConfig", []byte(`{"key": "value"}`))
if err != nil {
    panic(err)
}
err = cfgMap.Parse()
if err != nil {
    panic(err)
}
myCfg, err := cfgMap.Access("myConfig")
if err != nil {
    panic(err)
}

This creates a configuration map, registers a config entry, loads JSON data into it, parses all entries, and accesses the populated config struct.

Returns errors if any step fails, such as loading data for an unregistered name, schema validation failures, or unmarshalling errors.

func New

func New(opts *Opts) Map

type Opts

type Opts struct {
	// GlobalSchemas are JSON schemas that are applied to all config entries.
	//
	// These schemas can define common structures or constraints that apply to all config entries.
	//
	// Example:
	//   globalSchemaLoader := gojsonschema.NewBytesLoader([]byte(`{
	//       "type": "object",
	//       "properties": {
	//           "globalKey": { "type": "string" }
	//       }
	//   }`))
	//   opts := &Opts{
	//       GlobalSchemas: []gojsonschema.JSONLoader{globalSchemaLoader},
	//   }
	//
	// This sets a global schema that requires a "globalKey" property in all config entries.
	//
	// If no global schemas are needed, this can be left nil or empty.
	GlobalSchemas []gojsonschema.JSONLoader
}