envy

ENVY 👑 💅

Envy is a Go package that provides a flexible way to unmarshal environment variables into struct types using struct tags for validation, type conversion, and more. It offers powerful, customizable tag-based validations like checking for required fields, ensuring values match certain patterns, and verifying they fall within predefined options.

Features

Installation:

go get -u github.com/dubbikins/envy

Basic Usage

1. Define Your Struct:

   Use the env,default,options,matches,and required tags when defining your struct types.

   type Config struct {
      Port     int    `env:"PORT" default:"8080" required:"true"`
      Hostname int    `env:"HOSTNAME" default:"localhost" options:"localhost,my-domain-1.subdomain.com,my-domain-1.subdomain.com"`
      Mode     string `env:"MODE" options:"debug,release,test"`
   }
   

2. Unmarshal Environment Variables:

   Use the Unmarshal function to unmarshal a struct you've already declared and initialized, just be sure to pass a pointer to the struct, not the struct value. (Note: if you pass an uninitialized value or non-pointer value to Unmarshal, it will return an error)

   //HOSTNAME: my-domain-1.subdomain.com
   //Mode: debug
   
   cfg := &Config{}
   err := envy.Unmarshal(&cfg)
   if err != nil {
      log.Fatal(err)
   }
   ...
   

   Or use the generic New function in conjuction with the FromEnvironmentAs function which will return an instance of a type, and unmarshal it with the appropriate environment variables.

   if config, err := envy.New(envy.FromEnvironmentAs[Config]);err != nil {
      ...
   }
   ...
   

3. Access the Struct Fields:

   Then you can utilize the freshly set fields of your struct in the rest of your code! (just be sure to check for errors beforehand 😅)

   fmt.Printf("%s:%d [mode=%s]", cfg.Hostname, cfg.Port, cfg.Mode)
   // prints "my-domain-1.subdomain.com:8080 [mode=debug]"
   

Available Type Convertions 💥

Envy can unmarshall most primitive go types out of the box. Check out the following table of types to which ones are supported out of the box.

Custom Type unmarshaller

Didn't find the type you were looking for? 😦 Not to worry, it's simple to create a custom unmarshaller for any struct type! To provide custom unmarshalling for specific types in your struct, implement the TextUnmarshaler inteface by defining the UnmarshalText([]byte) error method for your type. It's that easy! This interface is a standard go interface from the encoding package, so you'll find that a lot of custom types already implement this interface.

type CustomType struct {
   // your type definition here
}

func (ct *CustomType) UnmarshalText(data []byte) error {
   // custom parsing logic here
   return nil // or an error
}

Example: Custom Parsing for Durations ⏲

The below example shows how you can wrap existing types like Duration (which is actually just a wrapper for int64), from the time package in the go standard library and implement the custom unmarshalling logic to convert the []byte value into a duration value.

import "time"

// Custom implementation for Parsing Durations from a string 
type Duration struct {
   time.Duration
}

func (d *Duration) UnmarshalText(data []byte) (err error) {
   if len(data) == 0 {
      return nil
   }
   d.Duration, err = time.ParseDuration(string(data))
   return
}

Use the custom type in your struct. The below example will convert the environment variable TIMEOUT to a time.Duration object as long as the value is in 1,2,5,10, or 25 minutes. If no value is provided, 5 minutes will be used as the defaul duration.

type Config struct {
   Timeout Duration `env:"TIMEOUT" default:"5m" options:"[1m,2m,5m,10m,15m]"`
}
if cfg, err := envy.New(envy.FromEnvironmentAs[Config]);err != nil {
   panic("oh no! something went wrong... 😢")
}
select { 
    case <-time.After(cfg.Timeout.Duration): 
        fmt.Println("Time Out!") 
} 

Reordering the Middleware Stack 🔁

Envy lets you customize the order of middleware to ensure tag parsers are processed in a sequence of your choice. By utilizing the Pop and Push methods, you can extract existing middleware and re-insert them or even replace them with custom middleware.

Here's an example:

package main

import (
   "context"
   "fmt"
   "reflect"

   "github.com/your-username/envy"
)

type Config struct {
   // your struct fields with tags here
}

func main() {
   config := &Config{}
   err := envy.Unmarshal(config, func(mw envy.TagMiddleware) {
      // Pop existing middleware
      existingMiddleware1 := mw.Pop()
      existingMiddleware2 := mw.Pop()

      // Push a custom middleware at the start
      mw.Push(
         func(next envy.TagHandler) envy.TagHandler {
            return envy.TagHandlerFunc(func(ctx context.Context, field reflect.StructField) error {
               fmt.Println("I'm the first custom tag parser")
               return next.UnmarshalField(ctx, field)
            })
         })

      // Re-insert the existing middleware
      mw.Push(existingMiddleware1, existingMiddleware2)

      // Add another custom middleware at the end
      mw.Push(
         func(next envy.TagHandler) envy.TagHandler {
            return envy.TagHandlerFunc(func(ctx context.Context, field reflect.StructField) error {
               fmt.Println("I'm the last custom tag parser")
               return next.UnmarshalField(ctx, field)
            })
         })
   })

   if err != nil {
      // handle the error
   }
}

Contributions 📣

If you find a bug or think of a new feature, please open an issue or submit a pull request! Go ahead, make the world envious! 😈