npm package: @sanjay144/env-warden
Description: Validate, type-check, and secure your environment variables before your Node.js app starts.
Author: Sanjai
Latest version: 1.1.0

# env-warden

> Validate, type-check, and secure your environment variables before your Node.js app starts.

Zero production dependencies · Node.js 14+ · Fails fast with clear, colorful output

---

## Install

```bash
npm install @sanjay144/env-warden
```

## Quick Start

```bash
npx env-warden init        # create env.schema.js
npx env-warden check       # validate current environment
npx env-warden generate    # create .env.example
npx env-warden types       # create env.d.ts
```

## Programmatic Usage

```js
const envWarden = require('@sanjay144/env-warden');

const env = envWarden({
  schema: require('./env.schema'),
  dotenv: true, // auto-load .env file
});

console.log(env.PORT);       // 3000  (number, not string)
console.log(env.DEBUG);      // false (boolean)
console.log(JSON.stringify(env));
// { "PORT": 3000, "API_KEY": "[REDACTED]", ... }
```

## Schema Definition

```js
// env.schema.js
module.exports = {
  NODE_ENV: {
    type: 'string',
    enum: ['development', 'staging', 'production'],
    default: 'development',
    description: 'Application environment',
  },
  PORT: {
    type: 'port',
    default: 3000,
  },
  DATABASE_URL: {
    type: 'url',
    required: true,
    sensitive: true,
  },
  API_KEY: {
    type: 'string',
    required: true,
    sensitive: true,
    minLength: 10,
    regex: /^sk_/,
  },
  DEBUG: {
    type: 'boolean',
    default: false,
  },
  ALLOWED_ORIGINS: {
    type: 'array',
    separator: ',',
    default: ['http://localhost:3000'],
  },
  ADMIN_EMAIL: {
    type: 'email',
    required: true,
  },
  RATE_LIMIT: {
    type: 'number',
    min: 1,
    max: 10000,
    default: 100,
  },
  CONFIG: {
    type: 'json',
    default: {},
  },
};
```

## Supported Types

| Type      | Coerced to      | Example value          |
|-----------|-----------------|------------------------|
| `string`  | `string`        | `hello`                |
| `number`  | `number`        | `42`, `3.14`           |
| `boolean` | `boolean`       | `true`, `1`, `yes`     |
| `array`   | `string[]`      | `a,b,c`                |
| `json`    | parsed object   | `{"key":"val"}`        |
| `url`     | `string`        | `https://example.com`  |
| `email`   | `string`        | `user@example.com`     |
| `port`    | `number`        | `8080` (1-65535)       |

## Schema Rule Options

| Property      | Type                         | Description                            |
|---------------|------------------------------|----------------------------------------|
| `type`        | `string`                     | One of the supported types             |
| `required`    | `boolean`                    | Default: `true` when no `default`      |
| `default`     | `any`                        | Fallback value                         |
| `sensitive`   | `boolean`                    | Redact in JSON/logs                    |
| `enum`        | `any[]`                      | Whitelist of allowed values            |
| `regex`       | `RegExp \| string`           | Pattern the value must match           |
| `min`         | `number`                     | Minimum (for numbers)                  |
| `max`         | `number`                     | Maximum (for numbers)                  |
| `minLength`   | `number`                     | Minimum length (string/array)          |
| `maxLength`   | `number`                     | Maximum length (string/array)          |
| `separator`   | `string`                     | Delimiter for array type               |
| `description` | `string`                     | Used in `.env.example` and `env.d.ts`  |
| `deprecated`  | `boolean \| string`          | Emit deprecation warning               |
| `validate`    | `(value, key) => bool\|str`  | Custom validator function              |

## Sensitive Value Redaction

Variables marked `sensitive: true` are accessible in code but hidden in serialization:

```js
env.API_KEY                    // "sk_live_abc123" (real value)
JSON.stringify(env)            // { "API_KEY": "[REDACTED]" }
console.log(env)               // { API_KEY: '[REDACTED]' }
```

## API

### `envWarden(options)`

| Option         | Type      | Default        | Description                     |
|----------------|-----------|----------------|---------------------------------|
| `schema`       | `object`  | **required**   | Schema definition               |
| `source`       | `object`  | `process.env`  | Override env source             |
| `dotenv`       | `boolean` | `false`        | Load `.env` before validating   |
| `dotenvPath`   | `string`  | `./.env`       | Path to `.env` file             |
| `exitOnError`  | `boolean` | `true`         | `process.exit(1)` on failure    |
| `silent`       | `boolean` | `false`        | Suppress console output         |

### CLI

```bash
env-warden init     [--output <path>]
env-warden check    [--schema <path>] [--env <path>]
env-warden generate [--schema <path>] [--output <path>]
env-warden types    [--schema <path>] [--output <path>]
```

## License

MIT