@malachi0412/envguard

Validate nested environment variables with clear, developer-friendly error messages.

This utility recursively checks a configuration object and throws a structured error when required environment variables are missing or undefined.

✨ Features

• ✅ Supports deeply nested configuration objects
• 🧭 Reports full paths (e.g. DB.CONNECTION.URL)
• 🔢 Lists all missing variables with numbering
• ⚡ Zero dependencies
• 🧪 Fully testable with Node.js built-in test runner

📦 Installation

npm install @malachi0412/envguard

🚀 Usage

import {validateEnvironmentVariables} from "@malachi0412/envguard";

validateEnvironmentVariables({
  DB: {
    HOST: process.env.DB_HOST,
    PORT: process.env.DB_PORT,
  },
  API_KEY: process.env.API_KEY,
});

❌ Example Error Output

If variables are missing, an error will be thrown:

Missing environment variables:
1. DB.HOST
2. DB.PORT
3. API_KEY

🧠 How It Works

• Traverses your configuration object recursively

• Builds a path to each key using dot notation

• Flags values that are:

  • undefined
  • null

• Aggregates all missing values before throwing a single error

🧪 Tests

This package uses the built-in Node.js test runner (node:test).

Run tests with:

npm run test

Example Test Cases

• ✔️ Does not throw when all variables are defined
• ❌ Throws for missing top-level variables
• ❌ Throws for nested missing variables
• ❌ Lists multiple missing variables correctly
• ❌ Treats null as missing
• ✔️ Handles deeply nested structures

🧩 API

validateEnvironmentVariables(configurationObject)

Parameters

• configurationObject (object) A nested object representing required environment variables.

Returns

• void (throws on failure)

Throws

• MissingEnvError When one or more variables are missing.

📁 Example Structure

{
  SERVICE: {
    DB: {
      CONNECTION: {
        URL: process.env.DB_URL
      }
    }
  }
}

⚠️ Behavior Notes

• undefined → ❌ treated as missing
• null → ❌ treated as missing
• Non-object values → ✅ considered valid if defined
• Objects → 🔁 traversed recursively

📌 Example

validateEnvironmentVariables({
  SERVICE: {
    DB: {
      CONNECTION: {
        URL: undefined,
      },
    },
  },
});

Throws:

Missing environment variable:
1. SERVICE.DB.CONNECTION.URL

🤝 Contributing

Contributions, issues, and feature requests are welcome.

📄 License

MIT