🔒 env-safe-type

Type-safe, runtime-validated environment variable management for TypeScript and JavaScript

🚀 Quick Start

Installation

npm install env-safe-type

Basic Usage

import { envSchema } from "env-safe-type";

// Define your environment schema
const env = envSchema({
  PORT: { type: "number", default: 3000 },
  NODE_ENV: {
    type: "enum",
    values: ["development", "production", "test"],
    default: "development",
  },
  DEBUG: { type: "boolean", default: false },
  API_KEY: { type: "string", required: true },
});

// Now env is fully typed!
console.log(env.PORT); // number
console.log(env.NODE_ENV); // "development" | "production" | "test"
console.log(env.DEBUG); // boolean
console.log(env.API_KEY); // string

JavaScript Usage

const { envSchema } = require("env-safe-type");

const env = envSchema({
  PORT: { type: "number", default: 3000 },
  API_KEY: { type: "string", required: true },
});

console.log(env.PORT); // 3000 (or value from process.env.PORT)
console.log(env.API_KEY); // string from process.env.API_KEY

📖 Supported Types

String

const env = envSchema({
  DATABASE_URL: { type: "string", required: true },
  APP_NAME: { type: "string", default: "My App" },
});

Number

const env = envSchema({
  PORT: { type: "number", default: 3000 },
  TIMEOUT: { type: "number", required: true },
});

Boolean

const env = envSchema({
  DEBUG: { type: "boolean", default: false },
  ENABLE_CACHE: { type: "boolean", default: true },
});

Accepted boolean values: "true", "false", "1", "0", "yes", "no" (case-insensitive)

Enum

const env = envSchema({
  NODE_ENV: {
    type: "enum",
    values: ["development", "production", "test"],
    default: "development",
  },
});

⚙️ Configuration Options

| Option | Type | Required | Description | | ---------- | --------------------------------------------- | ------------- | ---------------------------------------------- | | type | "string" \| "number" \| "boolean" \| "enum" | ✅ Yes | The type of the environment variable | | required | boolean | ❌ No | If true, throws error if variable is missing | | default | string \| number \| boolean | ❌ No | Default value if variable is not set | | values | readonly string[] | ✅ (for enum) | Allowed values for enum type |

🎯 TypeScript Support

Full type inference is supported:

const env = envSchema({
  PORT: { type: "number", default: 3000 },
  DEBUG: { type: "boolean", default: false },
});

// TypeScript knows the exact types!
type EnvType = typeof env;
// EnvType = { PORT: number; DEBUG: boolean }

❌ Error Handling

import { envSchema, EnvValidationError } from "env-safe-type";

try {
  const env = envSchema({
    API_KEY: { type: "string", required: true },
  });
} catch (error) {
  if (error instanceof EnvValidationError) {
    console.error("Validation failed:", error.message);
    // Output: "Environment variable "API_KEY" is required but not set"
    process.exit(1);
  }
  throw error;
}

📦 Examples

Express.js Integration

import express from "express";
import { envSchema } from "env-safe-type";

const env = envSchema({
  PORT: { type: "number", default: 3000 },
  NODE_ENV: {
    type: "enum",
    values: ["development", "production"],
    default: "development",
  },
});

const app = express();

app.listen(env.PORT, () => {
  console.log(`Server running on port ${env.PORT} in ${env.NODE_ENV} mode`);
});

Next.js Integration

// lib/env.ts
import { envSchema } from "env-safe-type";

export const env = envSchema({
  DATABASE_URL: { type: "string", required: true },
  NEXT_PUBLIC_API_URL: { type: "string", required: true },
  ENABLE_ANALYTICS: { type: "boolean", default: false },
});

🔧 CommonJS and ESM Support

Works with both CommonJS and ESM:

// CommonJS
const { envSchema } = require("env-safe-type");

// ESM
import { envSchema } from "env-safe-type";

📚 More Examples

Check the examples folder for:

• Basic JavaScript usage
• TypeScript examples
• Express.js integration
• Next.js integration

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub: https://github.com/asadchaudhary79/env-type-safe
• NPM: https://www.npmjs.com/package/env-safe-type
• Issues: https://github.com/asadchaudhary79/env-type-safe/issues