envfy

A lightweight, type-safe environment variable validator for Node.js and TypeScript.

envfy validates, parses, and infers the types of your environment variables at application startup, helping your application fail fast when configuration is invalid.

Features

• String validation
• Number parsing and validation
• Boolean parsing and validation
• Enum validation
• Optional environment variables
• Default values
• Aggregated validation errors
• Automatic TypeScript type inference
• Zero runtime dependencies

---

Why envfy?

• Lightweight and dependency-free
• Strong TypeScript support with inferred return types
• Simple, declarative schema syntax
• Fail-fast configuration validation
• Suitable for small projects and production applications

---

Installation

npm install @yasserfedsi/envfy

---

Basic Usage

import { validateEnv } from "@yasserfedsi/envfy";

const env = validateEnv({
  PORT: "number",
  DATABASE_URL: "string",
  DEBUG: "boolean",
});

console.log(env.PORT); // number
console.log(env.DATABASE_URL); // string
console.log(env.DEBUG); // boolean

TypeScript automatically infers the correct return types.

---

Supported Schema Types

Primitive Types

const env = validateEnv({
  PORT: "number",
  DATABASE_URL: "string",
  DEBUG: "boolean",
});

---

Enum Validation

const env = validateEnv({
  NODE_ENV: ["development", "production", "test"] as const,
});

If .env contains:

NODE_ENV=staging

An error is thrown:

NODE_ENV must be one of: development, production, test

---

Optional Variables

const env = validateEnv({
  API_KEY: {
    type: "string",
    optional: true,
  },
});

Missing optional variables are ignored.

If present, they are validated normally.

---

Default Values

const env = validateEnv({
  PORT: {
    type: "number",
    default: 3000,
  },

  HOST: {
    type: "string",
    default: "localhost",
  },

  DEBUG: {
    type: "boolean",
    default: false,
  },
});

If the environment variables are missing, the default values are returned.

Environment variables always override defaults.

---

Aggregated Errors

Instead of stopping at the first validation error, envfy collects every validation error before throwing.

Example:

PORT=abc
DEBUG=yes

validateEnv({
  PORT: "number",
  DEBUG: "boolean",
  DATABASE_URL: "string",
});

Produces:

Environment validation failed

PORT must be a valid number
DEBUG must be true or false
Missing environment variable: DATABASE_URL

---

TypeScript Inference

envfy automatically infers the returned object.

const env = validateEnv({
  PORT: "number",

  DEBUG: "boolean",

  NODE_ENV: ["development", "production", "test"] as const,

  API_KEY: {
    type: "string",
    optional: true,
  },

  HOST: {
    type: "string",
    default: "localhost",
  },
});

TypeScript infers:

{
  PORT: number;
  DEBUG: boolean;
  NODE_ENV: "development" | "production" | "test";
  API_KEY?: string;
  HOST: string;
}

No manual interfaces or type assertions are required.

---

Complete Example

.env

PORT=3000
DEBUG=true
NODE_ENV=development
DATABASE_URL=postgres://localhost/db

import { validateEnv } from "@yasserfedsi/envfy";

const env = validateEnv({
  PORT: "number",

  DEBUG: "boolean",

  NODE_ENV: ["development", "production", "test"] as const,

  DATABASE_URL: "string",
});

console.log(env);

Output:

{
  PORT: 3000,
  DEBUG: true,
  NODE_ENV: "development",
  DATABASE_URL: "postgres://localhost/db",
}

---

API

validateEnv(schema)

Validates and parses environment variables.

Returns a fully typed object containing the validated values.

Throws:

• EnvValidationError when one or more environment variables fail validation.
• Error when the schema configuration itself is invalid.

---

Roadmap

Completed

• String validation
• Number validation
• Boolean validation
• Enum validation
• Optional variables
• Default values
• Aggregated validation errors
• Automatic TypeScript type inference

Planned

• Custom validators
• Value transformers
• Array support
• Custom error formatting
• Browser compatibility

---

Contributing

Contributions, bug reports, feature requests, and pull requests are welcome.

Please read the contribution guidelines before opening a pull request.

---

Changelog

See CHANGELOG.md for a complete release history.

---

License

MIT License.