dotenv-types/README.md

# Dotenv Types

A CLI tool that validates .env files against a schema and auto-generates TypeScript interfaces for type-safe environment variables in TypeScript projects.

## Features

- **Schema Validation**: Validate .env files against a JSON schema definition
- **TypeScript Type Generation**: Generate TypeScript interfaces from .env variables
- **Strict Type Checking**: Required vs optional values with proper type annotations
- **Nested Object Support**: Parse DB_* prefixed variables into nested objects
- **Migration Helper**: Analyze existing .env files and generate initial schema

## Installation

```bash
# Using npm
npm install -g dotenv-types

# Using yarn
yarn global add dotenv-types

# Using pnpm
pnpm add -g dotenv-types
```

Or run directly with npx:

```bash
npx dotenv-types validate
```

## Usage

### Validate Command

Validate your .env file against a schema:

```bash
dotenv-types validate -e .env -s schema.json
```

Options:
- `-e, --env <path>`: Path to .env file (default: `.env`)
- `-s, --schema <path>`: Path to schema.json file

### Generate Command

Generate TypeScript interfaces from your .env file:

```bash
dotenv-types generate -e .env -o env.d.ts
```

Options:
- `-e, --env <path>`: Path to .env file (default: `.env`)
- `-s, --schema <path>`: Path to schema.json file
- `-o, --output <path>`: Output file path (stdout if not specified)
- `-n, --name <name>`: Interface name (default: `EnvVariables`)

### Migrate Command

Generate a schema.json from an existing .env file:

```bash
dotenv-types migrate -e .env -o schema.json
```

Options:
- `-e, --env <path>`: Path to .env file (default: `.env`)
- `-o, --output <path>`: Output file path (default: `schema.json`)

## Configuration

### Schema Definition

Create a `schema.json` file to define your environment variable requirements:

```json
{
  "variables": {
    "PORT": {
      "type": "port",
      "required": true,
      "desc": "Port number for the server"
    },
    "NODE_ENV": {
      "type": "enum",
      "required": true,
      "choices": ["development", "production", "test"],
      "desc": "Environment mode"
    },
    "DATABASE_URL": {
      "type": "url",
      "required": true,
      "desc": "Database connection URL"
    },
    "DEBUG": {
      "type": "boolean",
      "required": false,
      "default": false,
      "desc": "Enable debug mode"
    }
  }
}
```

### Supported Types

| Type | Description | Example |
|------|-------------|---------|
| `string` | Any string value | `"hello"` |
| `number` | Decimal number | `3.14` |
| `int` | Integer | `42` |
| `boolean` | true/false | `true` |
| `port` | Valid port number (1-65535) | `3000` |
| `url` | Valid URL | `https://api.example.com` |
| `email` | Valid email | `user@example.com` |
| `enum` | One of specified values | `"development"` |
| `json` | Valid JSON string | `{"key": "value"}` |
| `host` | Valid hostname | `localhost` |

## Examples

### Basic Usage

1. Create a `.env` file:

```env
PORT=3000
NODE_ENV=development
DATABASE_URL=postgres://localhost:5432/mydb
DEBUG=true
```

2. Generate a schema:

```bash
dotenv-types migrate -e .env -o schema.json
```

3. Validate your .env:

```bash
dotenv-types validate -e .env -s schema.json
```

4. Generate TypeScript types:

```bash
dotenv-types generate -e .env -o env.d.ts
```

### Generated TypeScript Interface

```typescript
export interface EnvVariables {
  /** Port number for the server */
  PORT: number;

  /** Environment mode */
  NODE_ENV: 'development' | 'production' | 'test';

  /** Database connection URL */
  DATABASE_URL: string;

  /** Enable debug mode */
  DEBUG?: boolean;  // Default: false
}
```

### Nested Objects

Dotenv Types supports nested objects via underscore notation:

```env
APP_NAME=myapp
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=secret
REDIS_HOST=localhost
REDIS_PORT=6379
```

Generates:

```typescript
export interface EnvVariables {
  APP_NAME: string;
  Db?: {
    HOST?: string;
    PORT?: number;
    USER?: string;
    PASSWORD?: string;
  };
  Redis?: {
    HOST?: string;
    PORT?: number;
  };
}
```

## API Reference

### JavaScript API

```typescript
import { parseEnvFile } from 'dotenv-types/core/parser';
import { validateEnv, parseSchemaFromEnv } from 'dotenv-types/core/validator';
import { generateTypeScriptInterface } from 'dotenv-types/utils/typeGenerator';

// Parse .env file
const parsed = parseEnvFile('.env');

// Validate against schema
const schema = parseSchemaFromEnv(parsed.flat);
const result = validateEnv(parsed.flat, schema);

// Generate TypeScript interface
const code = generateTypeScriptInterface(schema, parsed);
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Run CLI locally
npm run dev -- validate -e .env
```

## License

MIT