app.go

package env

import (
	"flag"
	"fmt"
	"os"
	"strings"
)

const (
	// Testing identifies the test application environment.
	Testing = "testing"
	// Local identifies the local development application environment.
	Local = "local"
	// Staging identifies the pre-production application environment.
	Staging = "staging"
	// Production identifies the production application environment.
	Production = "production"
)

// IsAppEnvTesting reports whether APP_ENV is "testing" or the process looks like `go test`.
// @group Application environment
// @behavior readonly
//
// Checks APP_ENV, the -test.v flag, and arguments ending with ".test" or "-test.run".
//
// Example: APP_ENV explicitly testing
//
//	_ = os.Setenv("APP_ENV", env.Testing)
//	env.Dump(env.IsAppEnvTesting())
//	// #bool true
//
// Example: no test markers
//
//	_ = os.Unsetenv("APP_ENV")
//	env.Dump(env.IsAppEnvTesting())
//	// #bool false (outside of test binaries)
func IsAppEnvTesting() bool {
	return isAppEnvTestingValue(os.Getenv("APP_ENV"))
}

// isAppEnvTestingValue reports test mode while allowing the loader to evaluate a planned APP_ENV.
func isAppEnvTestingValue(appEnv string) bool {
	return appEnv == Testing ||
		flag.Lookup("test.v") != nil ||
		isTestSuffixFromArguments()
}

// isTestSuffixFromArguments reports whether command-line arguments carry a Go test marker.
func isTestSuffixFromArguments() bool {
	for _, arg := range os.Args {
		if strings.HasSuffix(arg, ".test") || strings.HasSuffix(arg, "-test.run") {
			return true
		}
	}
	return false
}

// GetAppEnv returns the current APP_ENV (empty string if unset).
// @group Application environment
// @behavior readonly
//
// Example: simple retrieval
//
//	_ = os.Setenv("APP_ENV", "staging")
//	env.Dump(env.GetAppEnv())
//	// #string "staging"
func GetAppEnv() string {
	return os.Getenv("APP_ENV")
}

// IsAppEnv checks if APP_ENV matches any of the provided environments.
// @group Application environment
// @behavior readonly
//
// Example: match any allowed environment
//
//	_ = os.Setenv("APP_ENV", "staging")
//	env.Dump(env.IsAppEnv(env.Production, env.Staging))
//	// #bool true
//
// Example: unmatched environment
//
//	_ = os.Setenv("APP_ENV", "local")
//	env.Dump(env.IsAppEnv(env.Production, env.Staging))
//	// #bool false
func IsAppEnv(envs ...string) bool {
	current := os.Getenv("APP_ENV")
	for _, env := range envs {
		if current == env {
			return true
		}
	}
	return false
}

// IsAppEnvProduction checks if APP_ENV is "production".
// @group Application environment
// @behavior readonly
//
// Example:
//
//	_ = os.Setenv("APP_ENV", env.Production)
//	env.Dump(env.IsAppEnvProduction())
//	// #bool true
func IsAppEnvProduction() bool {
	return IsAppEnv(Production)
}

// IsAppEnvStaging checks if APP_ENV is "staging".
// @group Application environment
// @behavior readonly
//
// Example:
//
//	_ = os.Setenv("APP_ENV", env.Staging)
//	env.Dump(env.IsAppEnvStaging())
//	// #bool true
func IsAppEnvStaging() bool {
	return IsAppEnv(Staging)
}

// IsAppEnvLocalOrStaging checks if APP_ENV is either "local" or "staging".
// @group Application environment
// @behavior readonly
//
// Example:
//
//	_ = os.Setenv("APP_ENV", env.Local)
//	env.Dump(env.IsAppEnvLocalOrStaging())
//	// #bool true
func IsAppEnvLocalOrStaging() bool {
	return IsAppEnv(Local, Staging)
}

// IsAppEnvLocal checks if APP_ENV is "local".
// @group Application environment
// @behavior readonly
//
// Example:
//
//	_ = os.Setenv("APP_ENV", env.Local)
//	env.Dump(env.IsAppEnvLocal())
//	// #bool true
func IsAppEnvLocal() bool {
	return IsAppEnv(Local)
}

// IsAppEnvTestingOrLocal checks if APP_ENV is "testing" or "local".
// @group Application environment
// @behavior readonly
//
// Example:
//
//	_ = os.Setenv("APP_ENV", env.Testing)
//	env.Dump(env.IsAppEnvTestingOrLocal())
//	// #bool true
func IsAppEnvTestingOrLocal() bool {
	return IsAppEnv(Testing, Local)
}

// SetAppEnv sets APP_ENV to a supported value.
// @group Application environment
// @behavior mutates-process-env
//
// Returns an error when the environment is unsupported.
//
// Example: set a supported environment
//
//	_ = env.SetAppEnv(env.Staging)
//	env.Dump(env.GetAppEnv())
//	// #string "staging"
func SetAppEnv(appEnv string) error {
	if !isValidAppEnv(appEnv) {
		return fmt.Errorf("invalid APP_ENV: %s", appEnv)
	}
	return os.Setenv("APP_ENV", appEnv)
}

// SetAppEnvLocal sets APP_ENV to "local".
// @group Application environment
// @behavior mutates-process-env
//
// Example:
//
//	_ = env.SetAppEnvLocal()
//	env.Dump(env.GetAppEnv())
//	// #string "local"
func SetAppEnvLocal() error {
	return SetAppEnv(Local)
}

// SetAppEnvStaging sets APP_ENV to "staging".
// @group Application environment
// @behavior mutates-process-env
//
// Example:
//
//	_ = env.SetAppEnvStaging()
//	env.Dump(env.GetAppEnv())
//	// #string "staging"
func SetAppEnvStaging() error {
	return SetAppEnv(Staging)
}

// SetAppEnvProduction sets APP_ENV to "production".
// @group Application environment
// @behavior mutates-process-env
//
// Example:
//
//	_ = env.SetAppEnvProduction()
//	env.Dump(env.GetAppEnv())
//	// #string "production"
func SetAppEnvProduction() error {
	return SetAppEnv(Production)
}

// SetAppEnvTesting sets APP_ENV to "testing".
// @group Application environment
// @behavior mutates-process-env
//
// Example:
//
//	_ = env.SetAppEnvTesting()
//	env.Dump(env.GetAppEnv())
//	// #string "testing"
func SetAppEnvTesting() error {
	return SetAppEnv(Testing)
}

// isValidAppEnv reports whether appEnv is one of the supported application environments.
func isValidAppEnv(appEnv string) bool {
	switch appEnv {
	case Testing, Local, Staging, Production:
		return true
	default:
		return false
	}
}