npm package: @miit-daga/env-guard
Description: Schema-based validator for environment variables with TypeScript support
Author: Miit Daga
Latest version: 0.1.1

# 🛡️ env-guard

[![Test Status](https://img.shields.io/badge/tests-116%20passing-brightgreen.svg)]()
[![Coverage](https://img.shields.io/badge/coverage-94.16%25-brightgreen.svg)]()
[![License](https://img.shields.io/badge/license-MIT-green.svg)]()

**🤖 AI-Crafted in a Day**: This entire package was vibe-coded in 1 day using MiniMax M2 LLM and GROK Code Fast 1. Zero human-written code - just pure AI creativity unleashed!

**Schema-based validator for environment variables with TypeScript support**

env-guard is a zero-dependency, enterprise-grade validation library for Node.js environment variables. It provides type safety, runtime validation, automatic .env.example generation, and comprehensive error reporting.

## ✨ Features

- **🔒 Type Safety**: Full TypeScript support with type inference
- **⚡ Zero Dependencies**: Lightweight with no external dependencies
- **🎯 Schema-Based**: Define once, validate anywhere
- **🔄 Type Coercion**: Automatic string → number/boolean conversion
- **✅ Built-in Validators**: URL, port, email, IP, JSON, regex validation
- **🌍 Environment Context**: Different rules for dev/staging/production
- **📝 Auto-Generation**: Generate .env.example files automatically
- **🛠️ CLI Tool**: Command-line interface for validation and generation
- **💪 Enterprise Ready**: 94.16% test coverage, comprehensive error handling

## 🎯 Why Choose env-guard?

### ⚡ Zero Dependencies
**Lightweight, fast, and secure.** Your project stays lean. No need to install or learn heavy schema libraries like Zod.

### 🛠️ Powerful & Expressive Schema
**Define complex rules with a simple, intuitive JavaScript object.** You don't just check for a string; you validate the format and type with built-in special types.

```javascript
// A simple object is all you need:
const schema = defineSchema({
  PORT: { type: 'port', default: 3000 },
  API_URL: { type: 'url', required: true },
  _environments: {
    production: { API_URL: { required: true } }
  }
});
```

### 🔄 Complete CLI Workflow
**A fully integrated toolchain that ensures consistency from development to production.** Go from schema definition to .env.example generation to CI validation with a single, reliable tool.

### 🏢 Enterprise-Ready
**Built-in support for environment-specific rules** makes managing complex deployments for development, staging, and production trivial.

## 📊 How env-guard is Different

| Feature | env-guard (Your Library) | Zod-based Validators | .env.example Validators |
|---------|---------------------------|---------------------|------------------------|
| Dependencies | Zero | Requires Zod | Often none |
| Schema | Powerful JS Object | Zod Schema (external) | Limited (file-based) |
| Built-in Types | port, url, ip, email | string, number, etc. | No types, just keys |
| CLI Toolchain | ✅ Yes (Generate, Validate, Check) | Usually none | Usually none |
| Learning Curve | Minimal (Just JS objects) | Moderate (Learn Zod) | Minimal |

## 🚀 Quick Start

### Installation

```bash
npm install @miit-daga/env-guard
# or
yarn add @miit-daga/env-guard
```

### Basic Usage

```javascript
const { defineSchema, validateEnv } = require('@miit-daga/env-guard');

// Define your schema
const schema = defineSchema({
  PORT: {
    type: 'port',
    required: true,
    default: 3000,
    description: 'Server port number'
  },
  NODE_ENV: {
    type: 'string',
    enum: ['development', 'production', 'test'],
    default: 'development'
  },
  DEBUG: {
    type: 'boolean',
    default: false
  }
});

// Validate environment variables
const result = validateEnv(schema, process.env);

if (result.success) {
  console.log('✅ Validation successful!');
  console.log('PORT:', result.data.PORT);
  console.log('NODE_ENV:', result.data.NODE_ENV);
} else {
  console.log('❌ Validation failed:');
  result.errors.forEach(error => {
    console.log(`- ${error.field}: ${error.message}`);
  });
}
```

## 📋 API Reference

### Core Functions

#### `defineSchema(schema)`
Compiles a schema definition into a validated schema object.

```javascript
const compiledSchema = defineSchema({
  DATABASE_URL: {
    type: 'url',
    required: true,
    description: 'Database connection string'
  },
  API_KEY: {
    type: 'string',
    required: true,
    minLength: 32
  }
});
```

#### `validateEnv(schema, envVars, environment)`
Validates environment variables against a compiled schema.

```javascript
const result = validateEnv(schema, process.env, 'production');
// Returns: { success: boolean, data?: object, errors: array, hasErrors: boolean }
```

### Schema Options

Each field in your schema can have the following options:

| Option | Type | Description |
|--------|------|-------------|
| `type` | `string` | **Required**. Field type: `'string'`, `'number'`, `'boolean'`, `'url'`, `'port'`, `'email'`, `'ip'`, `'json'`, `'regex'` |
| `required` | `boolean` | Whether the field must be present (default: `false`) |
| `default` | `any` | Default value if not provided (can be a function) |
| `description` | `string` | Field description for documentation |
| `enum` | `array` | Array of allowed values |
| `validate` | `function` | Custom validation function |
| `transform` | `function` | Transform function applied after coercion |
| `minLength` | `number` | Minimum string length (string type only) |
| `maxLength` | `number` | Maximum string length (string type only) |
| `min` | `number` | Minimum numeric value (number type only) |
| `max` | `number` | Maximum numeric value (number type only) |
| `protocols` | `array` | Allowed URL protocols (url type only) |
| `version` | `string` | IP version: `'ipv4'`, `'ipv6'`, `'any'` (ip type only) |
| `pattern` | `RegExp` | Regex pattern (regex type only) |

### Type Coercion

env-guard automatically coerces string values to their target types:

```javascript
// String values are trimmed
'  hello  ' → 'hello'

// Number coercion with validation
'8080' → 8080
'abc' → ValidationError

// Boolean coercion
'true' → true
'1' → true
'false' → false
'0' → false
'maybe' → ValidationError
```

### Built-in Validators

#### URL Validator
```javascript
validators.url('https://example.com'); // ✅ true
validators.url('http://localhost:3000'); // ✅ true
validators.url('invalid-url'); // ❌ 'Invalid URL format'
```

#### Port Validator
```javascript
validators.port(3000); // ✅ true
validators.port(65536); // ❌ 'Port must be between 1 and 65535'
```

#### Email Validator
```javascript
validators.email('user@example.com'); // ✅ true
validators.email('invalid-email'); // ❌ 'Invalid email format'
```

#### IP Validator
```javascript
validators.ip('192.168.1.1'); // ✅ true
validators.ip('::1'); // ✅ true (IPv6)
validators.ip('invalid-ip'); // ❌ 'Invalid IP address format'
```

#### JSON Validator
```javascript
validators.json('{"key": "value"}'); // ✅ true
validators.json('invalid-json'); // ❌ 'Invalid JSON format'
```

## 🛠️ CLI Tool

env-guard includes a powerful CLI for validation and .env.example generation.

### Installation

```bash
npm install -g @miit-daga/env-guard
```

### Commands

#### Validate Environment
```bash
env-guard validate --schema schema.js
env-guard validate --schema schema.js --env-file .env.local
env-guard validate --schema schema.js --format json
```

#### Generate .env.example
```bash
env-guard generate --schema schema.js
env-guard generate --schema schema.js --output my-env.example --include-comments
```

#### Check Schema
```bash
env-guard check --schema schema.js
env-guard check --schema schema.js --detailed
```

## 🌟 Advanced Features

### Custom Validators
```javascript
const schema = defineSchema({
  API_KEY: {
    type: 'string',
    required: true,
    validate: (value) => {
      if (!value.startsWith('sk-')) {
        return 'API key must start with "sk-"';
      }
      return true;
    }
  }
});
```

### Transforms
```javascript
const schema = defineSchema({
  DATABASE_URL: {
    type: 'string',
    transform: (url) => {
      return url.replace('localhost', '127.0.0.1');
    }
  }
});
```

### Environment-Specific Rules
```javascript
const schema = {
  API_URL: {
    type: 'url',
    required: false,
    description: 'API base URL'
  },
  _environments: {
    production: {
      API_URL: {
        required: true
      }
    }
  }
};

const result = validateEnv(defineSchema(schema), env, 'production');
// API_URL becomes required in production environment
```

## 🏗️ Framework Integration

### Express.js
```javascript
// app.js
const express = require('express');
const { defineSchema, validateEnv } = require('@miit-daga/env-guard');

const app = express();

// Define schema
const schema = defineSchema({
  PORT: { type: 'port', required: true, default: 3000 },
  DATABASE_URL: { type: 'url', required: true },
  JWT_SECRET: { type: 'string', required: true, minLength: 32 }
});

// Validate and configure
const result = validateEnv(schema, process.env);
if (!result.success) {
  console.error('Environment validation failed:', result.errors);
  process.exit(1);
}

app.set('port', result.data.PORT);
app.set('env', result.data.NODE_ENV);
```
```

### Next.js
```javascript
// next.config.js
const { defineSchema, validateEnv } = require('@miit-daga/env-guard');

const schema = defineSchema({
  DATABASE_URL: { type: 'url', required: true },
  NEXT_PUBLIC_API_URL: { type: 'url', required: true }
});

const envValidation = validateEnv(schema, process.env);
if (!envValidation.success) {
  console.error('❌ Environment validation failed:');
  envValidation.errors.forEach(error => {
    console.error(`  ${error.field}: ${error.message}`);
  });
  process.exit(1);
}

module.exports = {
  env: {
    DATABASE_URL: envValidation.data.DATABASE_URL,
    NEXT_PUBLIC_API_URL: envValidation.data.NEXT_PUBLIC_API_URL
  }
};
```

## 📝 Example Files

See the `examples/` directory for complete integration examples:

- `basic-usage.js` - Basic usage examples
- `express-integration.js` - Express.js integration
- `nextjs-integration.js` - Next.js integration
- `nestjs-integration.js` - NestJS integration

## 🐛 Error Handling

env-guard provides detailed, actionable error messages:

```javascript
const result = validateEnv(schema, {
  PORT: 'not-a-port',
  API_KEY: 'abc'
});

console.log(result.errors);
// [
//   {
//     field: 'PORT',
//     message: 'Port must be an integer between 1 and 65535',
//     value: 'not-a-port',
//     expected: 'valid port number',
//     received: 'string',
//     type: 'FormatError'
//   },
//   {
//     field: 'API_KEY',
//     message: 'String must be at least 32 characters long',
//     value: 'abc',
//     expected: 'min 32 chars',
//     received: '3 chars',
//     type: 'FormatError'
//   }
// ]
```

## 🔧 Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Build TypeScript
npm run build

# Run CLI
node bin/env-guard.js validate --schema schema.js
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

We welcome contributions! Here's how you can help:

### Getting Started
1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/your-feature-name`
3. **Make your changes**
4. **Add tests** for any new functionality
5. **Run the test suite**: `npm test`
6. **Submit a pull request**

### Development Guidelines
- Follow the existing code style (ESLint + Prettier)
- Add tests for new features and bug fixes
- Update documentation for API changes
- Ensure all tests pass before submitting

## 🆘 Support

Need help? Here are your options:

### 📖 Documentation
- [API Reference](API.md)
- [CLI Documentation](CLI.md)
- [Quick Start Guide](QUICKSTART.md)
- [Troubleshooting](TROUBLESHOOTING.md)

### 🐛 Issues
Found a bug? [Open an issue](https://github.com/miit-daga/env-guard/issues) on GitHub.

### 💬 Discussions
Have questions or ideas? [Start a discussion](https://github.com/miit-daga/env-guard/discussions) on GitHub.

## 👤 Author

**Miit Daga**

💼 [LinkedIn](https://www.linkedin.com/in/miit-daga/)  
🌐 [Website](https://miitdaga.dev/)

## 📊 Test Coverage

- **116 tests passing** (100% success rate)
- **94.16% code coverage**
- **Zero dependencies**
- **TypeScript strict mode**

---

**Built with ❤️ for the Node.js community**