env-typed-guard

A TypeScript-first library for type-safe environment variable parsing and validation with full IntelliSense and optional logging.

---

Features

• 🔒 Type-safe: Full TypeScript support with automatic type inference
• 📋 Schema-based: Define environment variables with a clear schema
• ✅ Validation: Built-in and custom validators
• 🎯 IntelliSense: Autocomplete for environment variable names
• 🔧 Flexible: Supports string, number, boolean, and enum
• 📝 Error handling: Throw or log warnings based on configuration
• 🚀 Zero dependencies: Lightweight, focused, and portable with zero dependencies (only dotenv for peer)

⚠️ Note: This package is Node-first. Full type safety works in Node, Nest.js, and Express. For Next.js or browser environments, variables must be exposed via NEXT_PUBLIC_* and are limited to strings. (Not recommended for next js till now)

---

Installation

npm install env-typed-guard

---

Quick Start

import defineEnv from 'env-typed-guard';

const env = defineEnv({
  PORT: { type: 'number', defaultValue: 3000 },
  NODE_ENV: {
    type: 'enum',
    validValues: ['development', 'production', 'test'],
    defaultValue: 'development'
  },
  DATABASE_URL: { type: 'string' }, // Required
  DEBUG: { type: 'boolean', defaultValue: false }
});

console.log(`Server running on port ${env.PORT}`);
console.log(`Environment: ${env.NODE_ENV}`);
console.log(`Debug mode: ${env.DEBUG}`);

---

API

defineEnv(schema, config?)

Parses and validates environment variables based on a schema.

Parameters

• schema – Object defining environment variables and their types.
• config – Optional configuration:

Schema

Property	Type	Required	Description
type	'string', 'number', 'boolean', 'enum'	✅ Yes	The type of the environment variable
defaultValue	same as type	❌ No	Default value if the variable is not set
validate	(value) => boolean | string	❌ No	Custom validation function; return true or error message
validValues	string[]	❌ No*	Required if type is 'enum'; allowed values

*Only required for enum type variables.

---

Configuration (config)

Option	Type	Default	Description
debugMode	boolean	false	Enable debug logging of parsed environment variables
throw	boolean	true	Throw errors on validation failure (if false, logs only)

---

Types Supported

String

const env = defineEnv({
  API_KEY: { type: 'string', defaultValue: 'dev-key' }
});

Number

const env = defineEnv({
  PORT: { type: 'number', defaultValue: 3000 }
});
// PORT=8080 → parsed as number 8080

Boolean

const env = defineEnv({
  DEBUG: { type: 'boolean', defaultValue: false }
});
// Accepts: 'true', 'false', '1', '0' (case insensitive)

Enum

const env = defineEnv({
  LOG_LEVEL: { 
    type: 'enum', 
    validValues: ['debug', 'info', 'warn', 'error'], 
    defaultValue: 'info' 
  }
});
// Type: 'debug' | 'info' | 'warn' | 'error'

---

Advanced Usage

Custom Validation

const env = defineEnv({
  PASSWORD: {
    type: 'string',
    validate: (val) => val.length >= 8 || 'Password must be at least 8 chars'
  },
  PORT: {
    type: 'number',
    defaultValue: 3000,
    validate: (val) => (val >= 1000 && val <= 65535) || 'Port must be 1000–65535'
  }
});

Optional vs Required Variables

const env = defineEnv({
  DATABASE_URL: { type: 'string' },        // Required
  CACHE_TTL: { type: 'number', defaultValue: 300 } // Optional
});

Node vs Client (Next.js)

• Node/Nest.js/Express: Full types supported.
• Next.js client: Only strings allowed; use NEXT_PUBLIC_* prefix: (Not recommended till now)

const nextConfig = {
  env: {
    NEXT_PUBLIC_API_URL: env.API_URL, // string only
  }
};

---

Error Handling

try {
  const env = defineEnv({ REQUIRED_VAR: { type: 'string' } });
} catch (err) {
  console.error('Env validation failed:', err.message);
  process.exit(1);
}

// Or disable throwing
const env = defineEnv({ REQUIRED_VAR: { type: 'string' } }, { throw: false });

---

Debug Mode

const env = defineEnv({
  PORT: { type: 'number', defaultValue: 3000 }
}, { debugMode: true });

// Output:
// Environment variables:
//   PORT=3000 (using default)

---

Best Practices

1. Use as const for type literals:

type: 'string' as const

2. Validate early in your app startup:

const env = defineEnv(schema); // Top of main file

3. Use meaningful validation messages:

validate: (value) => value > 0 || 'Must be positive'

4. Provide defaults for optional vars:

TIMEOUT: { type: 'number', defaultValue: 5000 }

---

Environment Variable Examples

DATABASE_URL=postgres://user:pass@localhost:5432/db
PORT=8080
DEBUG=true
NODE_ENV=production

---

TypeScript Integration

• Type inference from schema
• IntelliSense autocomplete
• Compile-time type checking
• Clear error messages

---

Tested Environments

• ✅ Node.js
• ✅ Nest.js
• ✅ Express.js
• 🟨 Next.js (server-side only, client limited to strings)

---

Contributing

Currently, there are no active contribution opportunities. However, if you come across any issues, feel free to raise them in the GitHub Issues section.