env-type-safe

A type-safe environment variable manager for Node.js applications with built-in validation and TypeScript support.

Features

• 🔒 Type Safety: Full TypeScript support with type inference
• ✅ Validation: Automatic type validation for strings, numbers, and booleans
• 📁 Environment Files: Load variables from .env files (using dotenv)
• 🛡️ Runtime Safety: Throws helpful errors for missing or invalid variables
• 🔍 Debugging: Clear error messages for troubleshooting
• 🎯 Simple API: Easy to use with minimal setup

Installation

npm install env-type-safe dotenv

Note: dotenv is a peer dependency and must be installed separately.

Quick Start

import { createEnvSafe } from 'env-type-safe';

// Define your environment schema
const env = createEnvSafe({
  PORT: "number",
  API_KEY: "string",
  DEBUG: "boolean",
}, { 
  envFile: ".env" // Optional: path to .env file
});

// Type-safe access to variables
const port: number = env.get<number>("PORT");       // Returns number
const apiKey: string = env.get<string>("API_KEY");  // Returns string
const debug: boolean = env.get<boolean>("DEBUG");    // Returns boolean

// Get all variables at once
const allVars = env.getAll();

Schema Types

The package supports three types of environment variables:

| Type | Description | Example | |-----------|------------------------------------------------|------------------------| | string | Any string value | API_KEY="xyz123" | | number | Numeric values (auto-converted from string) | PORT="3000" | | boolean | Boolean values (must be "true" or "false") | DEBUG="true" |

Error Handling

The package includes comprehensive error handling:

1. Missing Variables

   // If DATABASE_URL is not defined:
   createEnvSafe({ DATABASE_URL: "string" })
   // Error: Environment variable DATABASE_URL is missing

2. Invalid Types

   // If PORT="not-a-number" in .env:
   createEnvSafe({ PORT: "number" })
   // Error: Environment variable PORT must be a number

3. Invalid Boolean Values

   // If DEBUG="yes" in .env:
   createEnvSafe({ DEBUG: "boolean" })
   // Error: Environment variable DEBUG must be 'true' or 'false'

Best Practices

1. Define Schema Once

   // config/env.ts
   export const envSchema = {
     NODE_ENV: "string",
     PORT: "number",
     DEBUG: "boolean",
     API_KEY: "string"
   };
   
   export const env = createEnvSafe(envSchema);

2. Use Type Inference

   // TypeScript will infer the correct types
   const { PORT, API_KEY, DEBUG } = env.getAll();

3. Environment File

   PORT=3000
   DEBUG=true
   API_KEY=your-secret-key

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

Author

MD Azadur Rahman