config

func MustNew ¶

func MustNew(options ...Option) *Config

MustNew creates a new Config instance with the provided options. It panics if any option returns an error. Use this in main() or initialization code where panic is acceptable. For cases where error handling is needed, use New() instead.

package main

import (
	"context"
	"fmt"
	"log"

	"rivaas.dev/config"
)

func main() {
	cfg := config.MustNew()
	if err := cfg.Load(context.Background()); err != nil {
		log.Fatal(err)
	}

	//nolint:errcheck // Error checking is omitted in the example test code
	fmt.Println("Config created successfully")
}

Output:

Config created successfully

func New ¶

func New(options ...Option) (*Config, error)

New creates a new Config instance with the provided options. It iterates through the options and applies each one to the Config instance. If any of the options return an error, the errors are collected and returned. Returns a partially initialized Config along with any errors encountered.

package main

import (
	"context"
	"fmt"
	"log"

	"rivaas.dev/config"
)

func main() {
	cfg, err := config.New()
	if err != nil {
		log.Fatal(err)
	}

	if err = cfg.Load(context.Background()); err != nil {
		log.Fatal(err)
	}

	//nolint:errcheck // Error checking is omitted in the example test code
	fmt.Println("Config created successfully")
}

Output:

Config created successfully

func TestConfig ¶

func TestConfig(t *testing.T, opts ...Option) *Config

TestConfig creates a new Config instance with the given options for testing. It fails the test if creation fails.

func TestConfigFromJSONFile ¶

func TestConfigFromJSONFile(t *testing.T, content []byte) *Config

TestConfigFromJSONFile creates a Config instance loaded from a temporary JSON file.

func TestConfigFromTOMLFile ¶

func TestConfigFromTOMLFile(t *testing.T, content []byte) *Config

TestConfigFromTOMLFile creates a Config instance loaded from a temporary TOML file.

func TestConfigFromYAMLFile ¶

func TestConfigFromYAMLFile(t *testing.T, content []byte) *Config

TestConfigFromYAMLFile creates a Config instance loaded from a temporary YAML file.

func TestConfigLoaded ¶

func TestConfigLoaded(t *testing.T, conf map[string]any) *Config

TestConfigLoaded creates and loads a Config instance with the given configuration. Note: Uses context.Background() for simplicity. For tests needing context control, create the config manually and call Load with t.Context().

func TestConfigWithBinding ¶

func TestConfigWithBinding(t *testing.T, conf map[string]any, target any) *Config

TestConfigWithBinding creates a Config instance with the given configuration and binding target.

func TestConfigWithSource ¶

func TestConfigWithSource(t *testing.T, conf map[string]any) *Config

TestConfigWithSource creates a new Config instance with a mock source for testing.

func TestConfigWithValidator ¶

func TestConfigWithValidator(t *testing.T, conf map[string]any, validator func(map[string]any) error) *Config

TestConfigWithValidator creates a Config instance with the given configuration and validator.

func NewError ¶ added in v0.2.0

func NewError(source, operation string, err error) *Error

NewError creates a new ConfigError with the provided context. This is a convenience function for creating ConfigError instances.

func NewFieldError ¶ added in v0.2.0

func NewFieldError(source, field, operation string, err error) *Error

NewFieldError creates a new ConfigError with field information. This is useful when the error is specific to a particular configuration field.

func NewMockCodec ¶

func NewMockCodec(decodeFunc func([]byte, any) error, encodeFunc func(any) ([]byte, error)) *MockCodec

NewMockCodec creates a new mock codec for testing.

func TestDumper ¶

func TestDumper() *MockDumper

TestDumper creates a mock dumper for testing.

func TestDumperWithError ¶

func TestDumperWithError(err error) *MockDumper

TestDumperWithError creates a mock dumper that returns an error on Dump.

func WithBinding ¶

func WithBinding(v any) Option

WithBinding returns an Option that configures the Config instance to bind configuration data to a struct.

package main

import (
	"context"
	"fmt"
	"log"

	"rivaas.dev/config"
	"rivaas.dev/config/codec"
)

func main() {
	type ServerConfig struct {
		Host string `config:"host"`
		Port int    `config:"port"`
	}

	type Config struct {
		Server ServerConfig `config:"server"`
	}

	yamlContent := []byte(`
server:
  host: localhost
  port: 8080
`)

	var appConfig Config
	cfg, err := config.New(
		config.WithContent(yamlContent, codec.TypeYAML),
		config.WithBinding(&appConfig),
	)
	if err != nil {
		log.Fatal(err)
	}

	if err = cfg.Load(context.Background()); err != nil {
		log.Fatal(err)
	}

	//nolint:errcheck // Error checking is omitted in the example test code
	fmt.Printf("%s:%d\n", appConfig.Server.Host, appConfig.Server.Port)
}

Output:

localhost:8080

func WithConsul ¶

func WithConsul(path string) Option

WithConsul returns an Option that configures the Config instance to load configuration data from a Consul server. The format is automatically detected from the path extension. For custom formats, use WithConsulAs instead.

If CONSUL_HTTP_ADDR is not set, this option is silently skipped, allowing development without Consul while requiring it in production environments.

Paths support environment variable expansion using ${VAR} or $VAR syntax. Example: "${APP_ENV}/service.yaml" expands to "production/service.yaml" when APP_ENV=production

Required environment variables (production only):

• CONSUL_HTTP_ADDR: The address of the Consul server (e.g., "http://localhost:8500")
• CONSUL_HTTP_TOKEN: The access token for authentication with Consul (optional)

Example:

cfg := config.MustNew(
    config.WithConsul("production/service.yaml"),  // Auto-detects YAML, skipped without CONSUL_HTTP_ADDR
)

func WithConsulAs ¶

func WithConsulAs(path string, codecType codec.Type) Option

WithConsulAs returns an Option that configures the Config instance to load configuration data from a Consul server with explicit format. Use this when you need to override the format detection.

If CONSUL_HTTP_ADDR is not set, this option is silently skipped, allowing development without Consul while requiring it in production environments.

Paths support environment variable expansion using ${VAR} or $VAR syntax. Example: "${APP_ENV}/service" expands to "production/service" when APP_ENV=production

Required environment variables (production only):

• CONSUL_HTTP_ADDR: The address of the Consul server (e.g., "http://localhost:8500")
• CONSUL_HTTP_TOKEN: The access token for authentication with Consul (optional)

Example:

cfg := config.MustNew(
    config.WithConsulAs("production/service", codec.TypeJSON),
)

func WithContent ¶

func WithContent(data []byte, codecType codec.Type) Option

WithContent returns an Option that configures the Config instance to load configuration data from a byte slice. The codecType parameter specifies the format of the data (e.g., codec.TypeJSON, codec.TypeYAML).

Example:

yamlContent := []byte("server:\n  port: 8080")
cfg := config.MustNew(
    config.WithContent(yamlContent, codec.TypeYAML),
)

package main

import (
	"context"
	"fmt"
	"log"

	"rivaas.dev/config"
	"rivaas.dev/config/codec"
)

func main() {
	jsonContent := []byte(`{
		"app": {
			"name": "MyApp",
			"version": "1.0.0"
		}
	}`)

	cfg, err := config.New(
		config.WithContent(jsonContent, codec.TypeJSON),
	)
	if err != nil {
		log.Fatal(err)
	}

	if err = cfg.Load(context.Background()); err != nil {
		log.Fatal(err)
	}

	//nolint:errcheck // Error checking is omitted in the example test code
	fmt.Println(cfg.String("app.name"))
	//nolint:errcheck // Error checking is omitted in the example test code
	fmt.Println(cfg.String("app.version"))
}

Output:

MyApp
1.0.0

func WithDumper ¶

func WithDumper(dumper Dumper) Option

WithDumper adds a dumper to the configuration loader.

func WithEnv ¶

func WithEnv(prefix string) Option

WithEnv returns an Option that configures the Config instance to load configuration data from environment variables. The prefix parameter specifies the prefix for the environment variables to be loaded. Environment variables are converted to lowercase and underscores create nested structures.

Example:

cfg := config.MustNew(
    config.WithFile("config.yaml"),
    config.WithEnv("APP_"),  // Loads APP_SERVER_PORT as server.port
)

func WithFile ¶

func WithFile(path string) Option

WithFile returns an Option that configures the Config instance to load configuration data from a file. The format is automatically detected from the file extension (.yaml, .yml, .json, .toml). For files without extensions or custom formats, use WithFileAs instead.

Paths support environment variable expansion using ${VAR} or $VAR syntax. Example: "${CONFIG_DIR}/app.yaml" expands to "/etc/myapp/app.yaml" when CONFIG_DIR=/etc/myapp

Example:

cfg := config.MustNew(
    config.WithFile("config.yaml"),     // Automatically detects YAML
    config.WithFile("override.json"),   // Automatically detects JSON
)

package main

import (
	"context"
	"fmt"
	"log"

	"rivaas.dev/config"
	"rivaas.dev/config/codec"
)

func main() {
	// Create a temporary config file (in real code, use an actual file path)
	cfg, err := config.New(
		config.WithContent([]byte(`{"name": "example"}`), codec.TypeJSON),
	)
	if err != nil {
		log.Fatal(err)
	}

	if err = cfg.Load(context.Background()); err != nil {
		log.Fatal(err)
	}

	//nolint:errcheck // Error checking is omitted in the example test code
	fmt.Println(cfg.String("name"))
}

Output:

example

func WithFileAs ¶

func WithFileAs(path string, codecType codec.Type) Option

WithFileAs returns an Option that configures the Config instance to load configuration data from a file with explicit format. Use this when the file doesn't have an extension or when you need to override the format detection.

Paths support environment variable expansion using ${VAR} or $VAR syntax. Example: "${CONFIG_DIR}/app" expands to "/etc/myapp/app" when CONFIG_DIR=/etc/myapp

Example:

cfg := config.MustNew(
    config.WithFileAs("config", codec.TypeYAML),      // No extension, specify YAML
    config.WithFileAs("config.dat", codec.TypeJSON),  // Wrong extension, specify JSON
)

func WithFileDumper ¶

func WithFileDumper(path string) Option

WithFileDumper returns an Option that configures the Config instance to dump configuration data to a file. The format is automatically detected from the file extension (.yaml, .yml, .json, .toml). For files without extensions or custom formats, use WithFileDumperAs instead.

Paths support environment variable expansion using ${VAR} or $VAR syntax. Example: "${LOG_DIR}/config.yaml" expands to "/var/log/config.yaml" when LOG_DIR=/var/log

Example:

cfg := config.MustNew(
    config.WithFile("config.yaml"),
    config.WithFileDumper("output.yaml"),  // Auto-detects YAML
)

func WithFileDumperAs ¶

func WithFileDumperAs(path string, codecType codec.Type) Option

WithFileDumperAs returns an Option that configures the Config instance to dump configuration data to a file with explicit format. Use this when the file doesn't have an extension or when you need to override the format detection.

Paths support environment variable expansion using ${VAR} or $VAR syntax. Example: "${OUTPUT_DIR}/config" expands to "/tmp/config" when OUTPUT_DIR=/tmp

Example:

cfg := config.MustNew(
    config.WithFile("config.yaml"),
    config.WithFileDumperAs("output", codec.TypeYAML),  // No extension, specify YAML
)

func WithJSONSchema ¶

func WithJSONSchema(schema []byte) Option

WithJSONSchema adds a JSON Schema for validation.

func WithSource ¶

func WithSource(loader Source) Option

WithSource adds a source to the configuration loader.

func WithTag ¶

func WithTag(tagName string) Option

WithTag sets a custom struct tag name for binding (default: "config"). This allows you to use a different tag name if "config" conflicts with other libraries.

Example:

type Config struct {
    Port int `cfg:"port"`  // Using custom tag
}

cfg := config.MustNew(
    config.WithFile("config.yaml"),
    config.WithBinding(&appConfig),
    config.WithTag("cfg"),  // Use "cfg" instead of "config"
)

func WithValidator ¶

func WithValidator(fn func(map[string]any) error) Option

WithValidator adds a custom validation function.

package main

import (
	"context"
	"fmt"
	"log"

	"rivaas.dev/config"
	"rivaas.dev/config/codec"
)

func main() {
	yamlContent := []byte(`name: myapp`)

	cfg, err := config.New(
		config.WithContent(yamlContent, codec.TypeYAML),
		config.WithValidator(func(cfgMap map[string]any) error {
			// Custom validation logic
			if _, ok := cfgMap["name"]; !ok {
				return fmt.Errorf("name is required")
			}
			return nil
		}),
	)
	if err != nil {
		log.Fatal(err)
	}

	if err = cfg.Load(context.Background()); err != nil {
		log.Fatal(err)
	}

	//nolint:errcheck // Error checking is omitted in the example test code
	fmt.Println("Validation passed")
}

Output:

Validation passed

func TestSource ¶

func TestSource(conf map[string]any) Source

TestSource creates a mock source for testing with the given configuration map.

func TestSourceWithError ¶

func TestSourceWithError(err error) Source

TestSourceWithError creates a mock source that returns an error on Load.