# @x12i/env

> Configuration normalizer for Node.js - Zero dependencies, TypeScript-first, production-ready

Latest version **4.0.3** (published 2026-06-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @x12i/env
pnpm add @x12i/env
yarn add @x12i/env
bun add @x12i/env
```

Provides the command `x12i-env`.

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.3 |
| Published | 2026-06-22 |
| First published | 2026-04-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16.0.0 |
| Dependencies | 5 |
| Unpacked size | 883.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | x12i |
| Maintainers | x12i |
| Keywords | config, configuration, env, environment, parser, validation, typescript, zero-dependencies, dotenv, convict, nconf, node-config, multi-config, merge, schema, validation, hot-reload, hierarchical, secret-masking, documentation |

## Links

- npm: https://www.npmjs.com/package/@x12i/env
- Repository: https://github.com/x12i/env
- Homepage: https://github.com/x12i/env#readme
- Issues: https://github.com/x12i/env/issues
- npm.io page: https://npm.io/package/@x12i/env

## Dependencies (5)

- [dotenv](https://npm.io/package/dotenv.md) ^17.2.3
- [commander](https://npm.io/package/commander.md) ^14.0.2
- [micro-logs](https://npm.io/package/micro-logs.md) ^1.0.0
- [cross-spawn](https://npm.io/package/cross-spawn.md) ^7.0.6
- [nx-remote-json](https://npm.io/package/nx-remote-json.md) ^1.0.2

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 4.0.3 (latest) — 2026-06-22
- 4.0.1 — 2026-04-15
- 4.0.0 — 2026-04-15

## README

# @x12i/env

> **Configuration Normalizer for Node.js**  
> Normalize diverse configuration sources into a consistent, type-safe structure.  
> Zero dependencies. TypeScript-first. Production-ready.

[![npm version](https://img.shields.io/npm/v/%40x12i%2Fenv.svg)](https://www.npmjs.com/package/@x12i/env)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Downloads](https://img.shields.io/npm/dm/%40x12i%2Fenv.svg)](https://www.npmjs.com/package/@x12i/env)

**nxconfig** combines the best features from **9+ MIT-licensed configuration libraries** into one powerful, zero-dependency package. Perfect for cloud-native applications, microservices, and enterprise systems.

---

## 🧰 Toolbox of Pre-Configuration

**@x12i/env** provides **Out-of-the-Box (OOTB) Presets** - a **toolbox of pre-configured patterns** designed to create a **common ground** for configuration across different projects and use cases.

### What This Means

- **Toolbox Approach**: Pre-configured patterns for common infrastructure needs (MongoDB, Redis, S3/Spaces)
- **Specific Support Out of the Box**: Ready-made configuration normalization for role-based databases, caches, and storage
- **Doesn't Prevent Other Stuff**: Fully flexible - custom config maps work alongside presets
- **Common Ground from One Place**: All OOTB parts are already preconfigured with standardized structure, naming, and fallback logic
- **Optional Until Used**: Nothing is required - use what you need, ignore what you don't

### OOTB Presets Include

- **MongoDB**: Role-based database configuration with shared connection defaults and per-role overrides
- **Redis**: Role-based cache configuration with connection and DB index management
- **S3/Spaces Storage**: Role-based bucket configuration with purpose buckets (backup, records, versions, content)

All presets include **deterministic fallback chains** and are **fully optional**. See [OOTB_PRESETS_DESIGN.md](./OOTB_PRESETS_DESIGN.md) for complete documentation.

---

## ✨ Why nxconfig?

**nxconfig** is a **configuration normalizer** that transforms diverse configuration inputs (different naming conventions, formats, sources) into a consistent, predictable structure. It combines the best features from 9+ popular MIT-licensed packages into one powerful, zero-dependency solution.

**Core Normalization Features:**
- **Variable Name Normalization**: Accepts multiple naming conventions (e.g., `MONGO_URI`, `MONGODB_URI`, `MONGO_URL`) → normalizes to `config.database.mongodb.uri`
- **Type Normalization**: Automatically coerces strings to proper types (number, boolean, array, json, etc.) with validation
- **Priority Normalization**: 3-tier fallback system (AI-specific → feature-specific → base/default)
- **Case Normalization**: Converts `SCREAMING_SNAKE_CASE` env vars to `camelCase` config paths
- **Source Normalization**: Unifies configuration from env vars, files, secrets, CLI args into one structure
- **Structure Normalization**: Provides consistent, predictable configuration structure with TypeScript IntelliSense

**Additional Capabilities:**
- **ENV Token Resolution** with multi-environment file support
- **Schema Validation** with detailed error reporting
- **Multi-Config Merging** with intelligent conflict resolution
- **Environment Variable Inspection** with sensitive data masking
- **Hot Reload** and **Auto-Documentation** generation

---

## 🎯 Configuration Normalization Strategy

### What is Configuration Normalization?

Configuration normalization is the process of transforming diverse configuration inputs (different naming conventions, formats, types, sources) into a **consistent, predictable structure** that your application can reliably consume.

**The Problem:**
- Different projects use different variable names (`MONGO_URI` vs `MONGODB_URI` vs `MONGO_URL`)
- Environment variables are always strings, but you need proper types (numbers, booleans, arrays)
- Configuration comes from multiple sources (env vars, files, secrets, CLI args)
- Different environments need different specificity levels (development vs production vs feature-specific)

**The Solution:**
@x12i/env normalizes all these variations into a single, consistent configuration structure with proper types, predictable paths, and TypeScript IntelliSense support.

### Normalization Dimensions

#### 1. **Variable Name Normalization**

Multiple naming conventions for the same configuration are normalized to a single path:

```typescript
// Accepts ANY of these variable names:
// - MONGO_URI
// - MONGO_URL  
// - MONGODB_URI
// - XRONOX_MONGO_URI

// All normalize to:
config.database.mongodb.uri
```

**Example:**
```typescript
// In your config map:
uri: 'ENV.MONGO_URI||ENV.MONGO_URL||ENV.MONGODB_URI||default-value'

// Result: Single config path regardless of which variable is set
```

#### 2. **Type Normalization**

String values from environment variables are automatically coerced to proper types with validation:

```typescript
// Input (string): "8080"
port: 'ENV.PORT:port||3000'

// Normalized Output (number): 8080
// Validated: Must be 0-65535
```

**Supported Types:**
- **Numbers**: `number`, `int`, `nat`, `port`, `bigint`
- **Booleans**: `boolean` (accepts "true"/"false", "1"/"0", "yes"/"no")
- **Collections**: `array`, `json`
- **Formats**: `duration`, `bytes`, `url`, `email`, `ipaddress`, `regex`

#### 3. **Priority Normalization (3-Tier Fallback)**

Different specificity levels are normalized through a hierarchical fallback system:

```typescript
// Tier 1: Application/Feature-Specific (Highest Priority)
// Tier 2: Role/Feature-Specific (Medium Priority)  
// Tier 3: Base/Default (Lowest Priority)

logsUri: 'ENV.MONGO_AI_LOGS_URI||ENV.MONGO_LOGS_URI||ENV.MONGO_URI||...'
```

**How It Works:**
1. First checks for Tier 1 (most specific)
2. Falls back to Tier 2 if Tier 1 not found
3. Falls back to Tier 3 (base/default) if Tier 2 not found
4. Uses hardcoded default if none found

**Example:**
```bash
# Scenario 1: Tier 1 set
MONGO_AI_LOGS_URI=mongodb://ai-logs:27017
# Result: Uses ai-logs (Tier 1)

# Scenario 2: Only Tier 2 set
MONGO_LOGS_URI=mongodb://logs:27017
# Result: Uses logs (Tier 2)

# Scenario 3: Only Tier 3 set
MONGO_URI=mongodb://base:27017
# Result: Uses base (Tier 3)
```

#### 4. **Case Normalization**

Environment variables use `SCREAMING_SNAKE_CASE`, but configuration uses `camelCase`:

```typescript
// Input: MONGO_URI, REDIS_HOST, API_TIMEOUT
// Normalized: { mongoUri, redisHost, apiTimeout }
```

#### 5. **Source Normalization**

Configuration from multiple sources is unified into a single structure:

**Sources Supported:**
- Environment variables (`process.env`)
- `.env` files (with shared .env support)
- Secret management systems (ATM)
- Command-line arguments
- Configuration files (JSON, JS)
- Remote configuration

**Result:** Single `config` object regardless of source.

#### 6. **Structure Normalization**

All configuration follows a consistent, predictable hierarchy:

```typescript
// All database configurations normalize to:
config.database.mongodb.uri
config.database.mongodb.database
config.database.mongodb.roles.runtime.connectionString

// All API configurations normalize to:
config.api.port
config.api.host
config.api.timeout
```

**Benefits:**
- Predictable paths across projects
- TypeScript IntelliSense support
- Easy to navigate and understand

#### 7. **Format Normalization**

Same value represented in different formats is normalized to a standard format:

```typescript
// Duration: "30s", "1m", "500ms" → 30000 (milliseconds)
timeout: 'ENV.TIMEOUT:duration||30s'

// Array: "tag1,tag2,tag3" → ["tag1", "tag2", "tag3"]
tags: 'ENV.TAGS:array'

// Boolean: "true", "1", "yes" → true
enabled: 'ENV.ENABLED:boolean'
```

### Normalization Patterns

#### Pattern 1: Multi-Variable Fallback
Support legacy and new variable names:

```typescript
apiKey: 'ENV.OPENAI_API_KEY||ENV.OPENAI_KEY||ATM.SECRET.openai-key'
```

#### Pattern 2: 3-Tier Priority Fallback
Support different specificity levels:

```typescript
// Application-specific → Feature-specific → Base/default
logsUri: 'ENV.MONGO_AI_LOGS_URI||ENV.MONGO_LOGS_URI||ENV.MONGO_URI'
```

#### Pattern 3: Type + Default Normalization
Ensure type safety with sensible defaults:

```typescript
// Always results in a valid port number (0-65535)
port: 'ENV.PORT:port||8080'
```

### Normalization Rules

1. **First Match Wins**: When multiple fallback options are available, the first non-empty value is used
2. **Type Coercion Always Applied**: String values are automatically coerced to the specified type with validation
3. **Defaults Always Provided**: If no value is found, a sensible default is used (if specified)
4. **Validation on Normalization**: Type validation occurs during normalization, ensuring invalid values are caught early
5. **Case Preservation in Paths**: Config paths preserve the structure defined in the map, regardless of input case

### Benefits of Normalization

✅ **Developer Experience**: Consistent API regardless of input, TypeScript IntelliSense support, predictable structure  
✅ **Flexibility**: Support multiple naming conventions, backward compatible with legacy configs, easy migration paths  
✅ **Reliability**: Type safety, validation at normalization time, clear error messages  
✅ **Maintainability**: Single source of truth for structure, centralized normalization rules, easy to extend

### Real-World Example

**Input Variations:**
```bash
# Different naming conventions
MONGO_URI=mongodb://localhost:27017
MONGO_DB=myapp

# Or feature-specific
MONGO_LOGS_URI=mongodb://logs:27017
MONGO_LOGS_DB=logs-db

# Or application-specific
MONGO_AI_LOGS_URI=mongodb://ai-logs:27017
MONGO_AI_LOGS_DB=ai-activities
```

**Normalized Output:**
```typescript
{
  database: {
    mongodb: {
      logsUri: 'mongodb://ai-logs:27017',  // Tier 1 wins
      logsDatabase: 'ai-activities'         // Tier 1 wins
    }
  }
}
```

**Type Normalization Example:**
```bash
# Input (all strings)
PORT=8080
ENABLED=true
TIMEOUT=30s
TAGS=tag1,tag2
```

```typescript
// Normalized Output (proper types)
{
  port: 8080,                    // number
  enabled: true,                 // boolean
  timeout: 30000,                // number (milliseconds)
  tags: ['tag1', 'tag2']         // array
}
```

---

## 📦 Installation
 
 ```bash
 npm install @x12i/env
 ```
 
 ```bash
 yarn add @x12i/env
 ```
 
 ```bash
 pnpm add @x12i/env
 ```
 
 ---
 
## 🖥️ CLI Usage (Cross-Platform Execution)

`@x12i/env` ships the `x12i-env` CLI for cross-platform script execution with environment variables (Windows/Linux/macOS), eliminating the need for packages like `cross-env`. This is the successor to the legacy `nx-config2` CLI — same behavior, new name.

> **Migration:** If you previously used `nx-config2 run …`, replace it with `x12i-env run …`. No other changes are required.
 
 ### Running Commands
 
 ```bash
 # Works on Windows, macOS, and Linux
 npx x12i-env run --env ENABLE_LOGGING=true -- node script.js
 ```
 
 ### Options
 
 | Option | Description |
 |--------|-------------|
 | `--env KEY=VALUE` | Set an environment variable (can be used multiple times) |
 | `--env-file .env` | Load environment variables from a file |
 | `--verbose` | Enable verbose logging |
 
 ### Use in package.json
 
 ```json
 {
   "scripts": {
     "test": "x12i-env run --env NODE_ENV=test --env DEBUG=true -- jest",
     "start": "x12i-env run --env-file .env.prod -- node dist/index.js"
   }
 }
 ```
 
 ---
 
 ## 📋 Variable Metadata
 
 nxconfig now includes a standard metadata definitions file for common environment variables, promoting consistency across projects.
 
 - **Common Variables**: `metadata/common-variables.json`
 - **Schema**: `metadata/schema.json`
 
 You can use these definitions as a reference for naming conventions and type configurations.
 
 ---


## 🚀 Quick Start

### nxConfig API (NEW! - Intelligent Configuration Management)

The `nxConfig` API provides intelligent configuration management with nested properties, type coercion, and advanced features:

```typescript
import { nxConfig } from '@x12i/env';

// Simple variable access
const apiUrl = nxConfig.API_URL;
const port = nxConfig.PORT;
const debugMode = nxConfig.DEBUG_MODE;

// Nested property access
const database = nxConfig.database;
// Returns: {
//   host: 'localhost',
//   port: 5432,
//   user: 'admin',
//   password: '***',
//   pool: { min: 2, max: 10 }
// }

// Deep nested access
const googleClientId = nxConfig.features.authentication.oauth.google.clientId;

// Type-safe access with automatic coercion
const port = nxConfig.server.port;  // Automatically converted to number
const enabled = nxConfig.features.analytics;  // Automatically converted to boolean
const hosts = nxConfig.allowedHosts;  // Automatically converted to array
```

**Key Features:**
- ✅ **Nested Properties**: Access deeply nested configuration with dot notation
- ✅ **Type Coercion**: Automatic conversion (string → number, boolean, array, JSON)
- ✅ **Secret Management**: Automatic masking of sensitive data
- ✅ **Configuration Files**: Load from JavaScript, JSON, YAML, TOML files
- ✅ **Environment Variables**: Automatic mapping with `__` for nesting
- ✅ **Hot Reload**: Watch files and reload automatically
- ✅ **Version History**: Track configuration changes
- ✅ **Multi-Tenancy**: Support for tenant-specific configuration
- ✅ **Export/Import**: Export to JSON, YAML, .env formats

### Basic Usage (Traditional API)

```typescript
import { initConfig } from '@x12i/env';

// Set environment variables
process.env.DB_HOST = 'localhost';
process.env.DB_PORT = '5432';
process.env.API_KEY = 'secret123';

const config = {
  database: {
    host: 'ENV.DB_HOST',
    port: 'ENV.DB_PORT:port',     // Auto-validates port range
    password: 'ENV.DB_PASSWORD||changeme'  // Default value
  },
  api: {
    key: 'ENV.API_KEY',
    timeout: 'ENV.TIMEOUT:duration||30s'   // Parses "30s" to 30000ms
  }
};

const result = initConfig(config, {
  dotenvPath: '.env',
  verbose: true
});

console.log(result.config);
// {
//   database: { host: 'localhost', port: 5432, password: 'changeme' },
//   api: { key: 'secret123', timeout: 30000 }
// }
```

---

## 🎯 Core Features

### 1. ENV Token Resolution

Use `ENV.VARIABLE` tokens in your configuration:

```typescript
const config = {
  service: 'ENV.SERVICE_NAME',
  port: 'ENV.PORT:number||3000'
};
```

### 1.1. Multi-Environment File Support (NEW!)

Load variables from different environment files based on the token pattern:

```typescript
const config = {
  // Simple pattern: loads from .env or process.env
  app: {
    name: 'ENV.APP_NAME||my-app',
    version: 'ENV.APP_VERSION||1.0.0'
  },
  
  // Multi-segment pattern: loads from .env.test file
  test: {
    apiKey: 'ENV.TEST.API_KEY',
    dbHost: 'ENV.TEST.DB_HOST',
    dbPort: 'ENV.TEST.DB_PORT:port'
  },
  
  // Multi-segment pattern: loads from .env.prod.database file
  production: {
    database: {
      host: 'ENV.PROD.DATABASE.HOST',
      port: 'ENV.PROD.DATABASE.PORT:port',
      ssl: 'ENV.PROD.DATABASE.SSL:boolean'
    }
  }
};
```

**Pattern Rules:**
- `ENV.VARIABLE` → loads from `.env` file or `process.env`
- `ENV.TEST.VARIABLE` → loads from `.env.test` file
- `ENV.PROD.DATABASE.HOST` → loads from `.env.prod.database` file
- `ENV.STAGING.API.KEY` → loads from `.env.staging.api` file

The last segment is always the variable name, everything before it becomes the environment file path.

### 2. Type Coercion (15+ Built-in Types)

nxconfig provides comprehensive type coercion with built-in validation for 15+ data types. Each type includes validation, error handling, and automatic conversion:

```typescript
'ENV.PORT:port'           // Validates 0-65535, throws error if invalid
'ENV.ENABLED:boolean'     // Converts 'true'/'false', '1'/'0' to boolean
'ENV.COUNT:number'        // Converts to number, validates not NaN
'ENV.COUNT:int'           // Integer only, validates whole numbers
'ENV.COUNT:nat'           // Natural number (>=0), validates non-negative
'ENV.MAX:bigint'          // BigInt support for large numbers
'ENV.TAGS:array'          // Comma-separated string to array
'ENV.DATA:json'           // JSON parsing with error handling
'ENV.URL:url'             // URL validation using native URL constructor
'ENV.EMAIL:email'         // Email validation with regex pattern
'ENV.IP:ipaddress'        // IPv4/IPv6 address validation
'ENV.TIMEOUT:duration'    // Duration parsing: "5s", "10m", "2h", "1d", "1w"
'ENV.DATE:timestamp'      // Date parsing, returns milliseconds
'ENV.PATTERN:regex'       // RegExp compilation with error handling
```

**Type Validation Features:**
- **Automatic Error Handling**: Invalid values throw descriptive errors
- **Range Validation**: Port numbers (0-65535), natural numbers (≥0)
- **Format Validation**: Email, URL, IP address patterns
- **Custom Validators**: Extend with your own validation functions
- **Null Safety**: Handles undefined/null values gracefully

### 3. Default Values

nxconfig supports comprehensive default value handling with multiple fallback strategies:

```typescript
'ENV.HOST||localhost'           // Simple default value
'ENV.PORT:number||3000'         // Default with type coercion
'ENV.DEBUG:boolean||false'      // Boolean default
'ENV.TIMEOUT:duration||30s'     // Duration default
'ENV.TAGS:array||item1,item2'   // Array default
```

**Default Value Features:**
- **Multiple Fallback Levels**: ENV variable → default value → options defaults
- **Type-Aware Defaults**: Defaults are processed through type coercion

### 2.1. Automatic JSON-like Parsing (NEW!)

nxconfig automatically detects and parses JSON-like strings in environment variables, even without explicit type annotations. Values that start with `{` and end with `}` are parsed as objects, and values that start with `[` and end with `]` are parsed as arrays.

**Object Parsing:**
```typescript
// .env file
DATABASE_CONFIG={"host":"localhost","port":5432,"ssl":true}

// Config
const config = {
  database: 'ENV.DATABASE_CONFIG'  // Automatically parsed as object
};

// Result
// { database: { host: 'localhost', port: 5432, ssl: true } }
```

**Array Parsing:**
```typescript
// .env file
ALLOWED_HOSTS=["localhost","example.com","127.0.0.1"]
PORT_NUMBERS=[3000,8080,9000]
COMPLEX_ARRAY=[{"name":"server1","port":3000},{"name":"server2","port":8080}]

// Config
const config = {
  hosts: 'ENV.ALLOWED_HOSTS',           // String array
  ports: 'ENV.PORT_NUMBERS',            // Number array
  servers: 'ENV.COMPLEX_ARRAY'           // Array of objects
};

// Result
// {
//   hosts: ['localhost', 'example.com', '127.0.0.1'],
//   ports: [3000, 8080, 9000],
//   servers: [{ name: 'server1', port: 3000 }, { name: 'server2', port: 8080 }]
// }
```

**Fallback Behavior:**
- If parsing fails (invalid JSON), the original string value is returned
- This ensures no errors occur when a string happens to start with `{` or `[` but isn't JSON

```typescript
// .env file
NOT_JSON={not valid json

// Config
const config = {
  value: 'ENV.NOT_JSON'  // Returns "{not valid json" (string)
};
```

**Array Type Enhancement:**
The `array` type now supports both JSON arrays and comma-separated strings:

```typescript
// JSON array (parsed as typed array)
ENV.ITEMS:array with value "[1,2,3]" → [1, 2, 3] (numbers)

// Comma-separated string (split and trimmed)
ENV.ITEMS:array with value "a,b,c" → ['a', 'b', 'c'] (strings)
```

### 2.2. JSON File References (NEW!)

nxconfig supports referencing external JSON files directly from environment variables using the `{{path.json}}` syntax. This is useful for complex configurations that are better stored in separate files.

**File Reference Pattern:**
```typescript
// .env file
DATABASE_CONFIG={{./configuration-examples/database.json}}
SERVER_LIST={{./configs/servers.json}}

// Config
const config = {
  database: 'ENV.DATABASE_CONFIG',  // Loads from ./configuration-examples/database.json
  servers: 'ENV.SERVER_LIST'          // Loads from ./configs/servers.json
};

// Result - automatically loads and parses the JSON files
// {
//   database: { host: 'localhost', port: 5432, ... },
//   servers: [{ name: 'server1', port: 3000 }, ...]
// }
```

**Path Resolution:**
- Paths are resolved relative to the config file location (if parsing from a file)
- Otherwise, paths are resolved relative to `process.cwd()`
- Supports both relative paths (`./config.json`) and absolute paths (`/absolute/path.json`)

**Fallback Behavior:**
- If the file doesn't exist, the original string value `{{path.json}}` is returned
- If the file exists but contains invalid JSON, the original string is returned
- This ensures no errors occur when files are missing or malformed

```typescript
// .env file
MISSING_FILE={{./nonexistent.json}}

// Config
const config = {
  value: 'ENV.MISSING_FILE'  // Returns "{{./nonexistent.json}}" (string)
};
```

**Configuration Options:**
- `heuristicJsonParsing`: Enable/disable automatic JSON detection (including file references) (default: `true`)
- `lenientJson`: When using `:json` type, return original string on parse failure instead of throwing (default: `false`)

```typescript
// Disable automatic JSON parsing (including file references)
parseConfig(config, { heuristicJsonParsing: false });

// Use lenient JSON parsing (no errors on invalid JSON)
parseConfig(config, { lenientJson: true });
```

### 2.3. Config Object File References (NEW!)

nxconfig supports loading JSON files directly from config objects using the reserved `_loadFile` property. This allows you to reference external JSON files in your configuration structure.

**Config File Reference Pattern:**
```typescript
const config = {
  // Load entire object from file
  database: { _loadFile: './configs/database.json' },
  
  // Load entire array from file
  servers: { _loadFile: './configs/servers.json' },
  
  // Mix file references with direct values
  app: {
    name: 'my-app',
    config: { _loadFile: './configs/app-config.json' }
  }
};

// Result - automatically loads and parses JSON files
// {
//   database: { host: 'localhost', port: 5432, ... },
//   servers: [{ name: 'server1', port: 3000 }, ...],
//   app: {
//     name: 'my-app',
//     config: { timeout: 5000, ... }
//   }
// }
```

**Important Notes:**
- `_loadFile` is a **reserved property name** - when present, the entire object is replaced with the file's contents
- File contents can be either JSON objects or JSON arrays
- Paths are resolved relative to the config file location (if parsing from a file) or `process.cwd()` (if parsing from an object)
- If the file doesn't exist or contains invalid JSON, the original object (with `_loadFile`) is returned and a warning is generated
- The loaded content is recursively parsed, so it can contain ENV tokens, nested `_loadFile` references, etc.

**Example from Config File:**
```json
{
  "database": { "_loadFile": "./database.json" },
  "servers": { "_loadFile": "./servers.json" }
}
```

- **Warning System**: Logs when defaults are used for transparency
- **Nested Defaults**: Support for complex default structures

### 3. Automatic Config Loading (NEW!)

nxconfig provides an automatic config loader that uses a default config map covering common use cases, then automatically adds any additional environment variables as camelCase properties at the root level.

**Basic Usage:**
```typescript
import { autoLoadConfig } from '@x12i/env';

// Automatically load all config from environment variables
const config = autoLoadConfig();

// Access structured config
console.log(config.api.port);        // From ENV.API_PORT
console.log(config.database.uri);   // From ENV.MONGO_URI
console.log(config.logging.level);  // From ENV.LOG_LEVEL

// Additional env vars automatically added as camelCase
// ENV.CUSTOM_VAR → config.customVar
// ENV.MY_APP_VAR → config.myAppVar
```

**Default Config Map:**
The auto-loader includes a pre-configured map covering:
- `api`: port, allowedCollections, mode, dataFolder, timeout, host, corsOrigins, rateLimitWindow, rateLimitMax
- `atm`: enabled, endpoint, token, accountId, cache settings, retry settings
- `ai`: Comprehensive coverage for 20+ AI/LLM providers (OpenAI, Anthropic, Google, Azure, etc.)
- `vectordb`: Pinecone, Weaviate, Qdrant, Milvus, Chroma, Supabase, ElasticSearch
- `database`: MySQL, MongoDB, Redis, SQLite, CockroachDB, DynamoDB, Cassandra, Neo4j
- `dataTier`: mode (xronox/nx-mongo), engine, xronox settings, nxMongo settings
- `storage`: S3-compatible storage with full aliasing (S3_/SPACE_/STORAGE_)
- `messaging`: RabbitMQ, Kafka, SQS, Pub/Sub, NATS
- `observability`: Prometheus, Grafana, DataDog, New Relic, Sentry, OpenTelemetry
- `logging`: level, format, toFile, filePath, toUnified, debugNamespace, maxFiles, maxSize, compress
- `email`: SendGrid, Mailgun, AWS SES, SMTP
- `payment`: Stripe, PayPal, Square
- `auth`: Auth0, Okta, Clerk, Supabase Auth
- `search`: Algolia, MeiliSearch, Typesense
- `cdn`: Cloudflare, Cloudinary, ImageKit
- `analytics`: Google Analytics, Mixpanel, Segment, PostHog
- `featureFlags`: LaunchDarkly, Flagsmith
- `deployment`: Vercel, Netlify, Docker Hub

**Features:**
- **Default Config Map**: Common patterns pre-configured with ENV tokens
- **Automatic Addition**: All `ALL_UPPERCASE` env vars not in default config are added as camelCase at root
- **JSON Parsing**: JSON-like env vars are automatically parsed
- **Beautified Output**: Config is sorted with default sections first, then alphabetically
- **Non-strict by Default**: Missing optional vars don't throw errors

**Options:**
```typescript
autoLoadConfig({
  dotenvPath: '.env',           // .env file path (default: '.env')
  includeAllEnvVars: true,      // Include additional env vars (default: true)
  beautify: true,               // Sort keys nicely (default: true)
  verbose: false,               // Log resolved vars (default: false)
  heuristicJsonParsing: true,   // Auto-parse JSON (default: true)
  sections: ['DATABASE', 'AI'], // Optional: only load these .env sections
  groups: ['database.mongodb', 'ai.openai'] // Optional: only load these groups from DEFAULT_CONFIG_MAP
});
```

**Example:**
```typescript
// .env file
API_PORT=8080
MONGO_URI=mongodb://localhost:27017/mydb
LOG_LEVEL=debug
DATATIER_MODE=nx-mongo
XRONOX_ENABLED=false
NX_MONGO_ENABLED=true
CUSTOM_VAR=custom-value
JSON_CONFIG={"key":"value"}

// Auto-load config
const config = autoLoadConfig();

// Result structure:
// {
//   api: { port: 8080, ... },
//   database: { mongodb: { uri: 'mongodb://...', ... }, ... },
//   dataTier: { mode: 'nx-mongo', nxMongo: { enabled: true, ... }, ... },
//   logging: { level: 'debug', ... },
//   customVar: 'custom-value',
//   jsonConfig: { key: 'value' }
// }
```

### 4. Prefix/Suffix Support

nxconfig provides flexible environment variable resolution with prefix and suffix support for multi-tenant and environment-specific configurations:

```typescript
// All AWS_* variables
parseConfig(config, { prefix: 'AWS_' });

// Environment-specific variables
parseConfig(config, { 
  suffix: '_PROD'  // Prefers API_KEY_PROD over API_KEY
});

// Combined prefix and suffix
parseConfig(config, { 
  prefix: 'APP_',
  suffix: '_PROD'  // Looks for APP_API_KEY_PROD
});
```

**Prefix/Suffix Features:**
- **Priority Resolution**: Suffix takes precedence over prefix
- **Fallback Chain**: ENV_VAR_SUFFIX → ENV_VAR_PREFIX → ENV_VAR
- **Multi-Environment Support**: Perfect for dev/staging/prod setups
- **Tenant Isolation**: Use prefixes for multi-tenant applications

### 5. Environment Variable Inspection

Inspect and analyze environment variables in your .env files with detailed information:

```typescript
import { getEnvVariables } from '@x12i/env';

// Get variables from default .env file
const defaultVars = getEnvVariables();

// Get variables from specific environment file
const testVars = getEnvVariables('test');        // .env.test
const prodVars = getEnvVariables('prod');        // .env.prod
const dbVars = getEnvVariables('prod.database'); // .env.prod.database

console.log(testVars);
// [
//   { varName: 'API_KEY', length: 20, synthesizedValue: 'te***89' },
//   { varName: 'DB_HOST', length: 18, synthesizedValue: 'test-db.example.com' },
//   { varName: 'PASSWORD', length: 25, synthesizedValue: 'su***23' }
// ]
```

**Environment Variable Inspection Features:**
- **Variable Discovery**: List all variables in any .env file
- **Sensitive Data Masking**: Automatically mask passwords, keys, and tokens
- **Length Information**: Get original value length for validation
- **Multi-Environment Support**: Works with any environment file path
- **Safe Inspection**: Sensitive fields are automatically masked
- **TypeScript Support**: Full type definitions for variable information

---

## 🔥 Multi-Config Features

nxconfig provides powerful multi-configuration management with intelligent merging, inheritance, and flexible source handling:

### Smart Configuration Merging

Merge multiple configuration sources with intelligent conflict resolution:

```typescript
import { parseMultiConfig } from '@x12i/env';

// Merge multiple configs into one
const result = parseMultiConfig({
  sources: ['./base.json', './production.json', './overrides.json'],
  mergeStrategy: 'deep',  // 'deep' | 'shallow' | 'override' | 'append'
  priority: 'last',       // 'first' | 'last'
  verbose: true
});

console.log(result.config); // Deeply merged configuration
```

**Smart Merging Features:**
- **Conflict Resolution**: Intelligent handling of overlapping keys
- **Type Preservation**: Maintains data types during merging
- **Array Handling**: Smart array concatenation and deduplication
- **Nested Merging**: Deep recursive object merging
- **Error Recovery**: Graceful handling of merge conflicts

### Named Configuration Access

Keep configurations separate but accessible by name for multi-environment setups:

```typescript
// Keep configs separate but accessible by name
const result = parseMultiConfig({
  sources: ['./prod.json', './staging.json', './dev.json'],
  keepSeparate: true,
  names: ['production', 'staging', 'development']
});

console.log(result.configs.production);  // Production config
console.log(result.configs.staging);     // Staging config
console.log(result.configs.development); // Development config
```

**Named Access Features:**
- **Environment Isolation**: Keep configs completely separate
- **Dynamic Selection**: Choose config at runtime based on environment
- **Memory Efficient**: Only load needed configurations
- **Type Safety**: Full TypeScript support for named configs

### Configuration Inheritance

Build complex configuration hierarchies with base configs and overrides:

```typescript
// Load base config first, then layer sources
const result = parseMultiConfig({
  extends: './base-config.json',  // Loaded first
  sources: ['./env-specific.json'],
  mergeStrategy: 'deep'
});
```

**Inheritance Features:**
- **Base Configuration**: Define common settings once
- **Layered Overrides**: Environment-specific customizations
- **Inheritance Chains**: Support for multiple levels of inheritance
- **Override Protection**: Prevent accidental base config modification

### Merge Strategies

Choose the right merging strategy for your use case:

```typescript
// Deep merge (recursive object merging, array concatenation)
mergeStrategy: 'deep'      // Best for complex nested configs

// Shallow merge (Object.assign style)
mergeStrategy: 'shallow'   // Fast, simple merging

// Override (last source wins completely)
mergeStrategy: 'override'  // Complete replacement

// Append (array-focused merging)
mergeStrategy: 'append'    // Array concatenation with deduplication
```

**Merge Strategy Details:**
- **Deep**: Recursively merges objects, concatenates arrays, preserves structure
- **Shallow**: Fast Object.assign-style merging, arrays are replaced
- **Override**: Last source completely replaces previous sources
- **Append**: Array-focused merging with intelligent deduplication

---

## 🛠️ Advanced Features

### Schema Validation (Convict-inspired)

nxconfig provides comprehensive schema validation with detailed error reporting and custom validators:

```typescript
const result = initConfig(config, {
  schema: {
    port: {
      type: 'port',
      required: true,
      doc: 'Server port number',
      env: 'PORT',
      arg: 'port',  // --port from command line
      default: 3000,
      min: 1000,
      max: 9999
    },
    apiKey: {
      type: 'string',
      required: true,
      sensitive: true,  // Masks in logs
      nullable: false,
      format: (val) => val.length >= 32  // Custom validator
    },
    environment: {
      type: 'string',
      enum: ['development', 'staging', 'production'],
      default: 'development'
    },
    timeout: {
      type: 'duration',
      doc: 'Request timeout',
      default: '30s'
    }
  }
});
```

**Schema Validation Features:**
- **Type Validation**: Automatic type checking with detailed error messages
- **Range Validation**: Min/max values for numeric types
- **Enum Constraints**: Restrict values to predefined options
- **Custom Validators**: Define your own validation functions
- **Required Fields**: Enforce mandatory configuration values
- **Sensitive Data**: Automatic masking of sensitive fields in logs
- **Documentation**: Built-in field documentation support
- **Command-line Integration**: Map schema fields to CLI arguments

### Hierarchical Configuration (nconf-inspired)

Build complex configuration hierarchies with priority-based value resolution:

```typescript
import { ConfigurationHierarchy } from '@x12i/env';

const config = new ConfigurationHierarchy();

// Priority: overrides > env > file > defaults
config.set('database:host', '127.0.0.1');
config.set('database:port', 5432);

console.log(config.get('database:host')); // '127.0.0.1'
console.log(config.toObject());
```

**Hierarchical Features:**
- **Priority Resolution**: Clear precedence order for value sources
- **Nested Key Access**: Use colon-separated keys for deep access
- **Dynamic Updates**: Modify configuration at runtime
- **Memory Management**: Efficient storage and retrieval
- **Type Safety**: Full TypeScript support for hierarchical access

### Command-line Arguments

Parse command-line arguments directly into your configuration:

```typescript
// node app.js --port=8080 --debug=true

const result = parseConfig(config, {
  commandLineArgs: true
});
```

**CLI Integration Features:**
- **Automatic Parsing**: Parse `--flag=value` and `--flag` patterns
- **Type Coercion**: Apply type conversion to CLI values
- **Priority Override**: CLI args override environment variables
- **Validation**: Validate CLI arguments against schema
- **Help Generation**: Auto-generate help text from schema

### Auto-Documentation Generation

Generate comprehensive documentation for your configuration automatically:

```typescript
const result = initConfig(config, {
  generateDocs: true,
  docsPath: './ENV_VARS.md',
  descriptions: {
    API_KEY: 'Authentication key for external services',
    DB_HOST: 'Database server hostname',
    PORT: 'HTTP server port (1000-65535)'
  },
  schema: {
    PORT: {
      type: 'port',
      required: true,
      doc: 'Server listening port'
    }
  }
});

// Generates beautiful markdown documentation!
```

**Documentation Features:**
- **Markdown Generation**: Professional documentation format
- **Variable Tables**: Organized tables with types, defaults, descriptions
- **Usage Examples**: Auto-generated usage examples
- **Sensitive Data**: Automatic masking of sensitive fields
- **Schema Integration**: Include validation rules in documentation

**Output:**

```markdown
# Configuration Documentation

## Environment Variables

| Variable | Type | Required | Default | Description | Sensitive |
|----------|------|----------|---------|-------------|-----------|
| `API_KEY` | `string` | ✅ Yes | - | Authentication key... | 🔒 Yes |
| `PORT` | `port` | ✅ Yes | `3000` | Server listening port | ❌ No |

## Usage Example

```bash
export API_KEY="your-api-key"
export PORT="8080"
```
```

### Directory Auto-Creation

Automatically create missing directories for path-based configurations:

```typescript
const config = {
  uploadDir: 'ENV.UPLOAD_PATH',
  cacheDir: 'ENV.CACHE_PATH',
  logDir: 'ENV.LOG_PATH'
};

parseConfig(config, {
  createDirectories: true  // Creates missing directories
});
```

**Directory Features:**
- **Automatic Creation**: Creates missing directories recursively
- **Permission Handling**: Respects existing permissions
- **Error Recovery**: Graceful handling of creation failures
- **Path Validation**: Validates paths before creation
- **Verbose Logging**: Logs directory creation activities

### Path Validation

Validate file and directory existence with comprehensive error reporting:

```typescript
schema: {
  configFile: {
    type: 'string',
    isFile: true,        // Validates file exists
    required: true
  },
  dataDir: {
    type: 'string',
    isDirectory: true,   // Validates directory exists
    required: true
  }
}
```

**Path Validation Features:**
- **File Existence**: Validate files exist and are readable
- **Directory Validation**: Check directory existence and permissions
- **Path Resolution**: Handle relative and absolute paths
- **Error Details**: Detailed error messages for missing paths
- **Schema Integration**: Works seamlessly with validation schemas

### Secret Masking

Automatically detect and mask sensitive data in configurations:

```typescript
import { maskSecrets } from '@x12i/env';

const config = {
  api_key: 'secret123456',
  password: 'mypassword',
  username: 'john'
};

console.log(maskSecrets(config));
// {
//   api_key: 'se***56',
//   password: 'my***rd',
//   username: 'john'
// }
```

**Secret Masking Features:**
- **Automatic Detection**: Identifies sensitive fields by name patterns
- **Smart Masking**: Preserves first/last characters for readability
- **Schema Integration**: Use schema to mark sensitive fields
- **Custom Patterns**: Define your own sensitive field patterns
- **Log Safety**: Safe for logging and debugging

### Hot Reload

Watch configuration files for changes and automatically reload:

```typescript
import { watchConfig } from '@x12i/env';

const watcher = watchConfig('./config.json', {
  interval: 2000,
  onChange: (newConfig) => {
    console.log('⚡ Config reloaded:', newConfig);
  },
  onError: (error) => {
    console.error('❌ Error:', error);
  }
});

// Stop watching later
watcher.stop();
```

**Hot Reload Features:**
- **File Watching**: Monitor configuration files for changes
- **Automatic Reload**: Seamlessly reload on file changes
- **Error Handling**: Graceful error recovery and reporting
- **Performance**: Efficient file change detection
- **Memory Management**: Proper cleanup and resource management

### Convict-style API

Use a familiar convict-style API for configuration management:

```typescript
import { createConfig } from '@x12i/env';

const config = createConfig({
  env: {
    doc: 'The application environment',
    format: ['production', 'development', 'test'],
    default: 'development',
    env: 'NODE_ENV'
  },
  port: {
    doc: 'The port to bind',
    format: 'port',
    default: 8080,
    env: 'PORT',
    arg: 'port'
  }
});

config.validate();
console.log(config.get('port'));
console.log(config.getProperties());
```

**Convict-style Features:**
- **Familiar API**: Drop-in replacement for convict users
- **Schema Definition**: Define configuration schema declaratively
- **Validation**: Built-in validation with detailed error messages
- **Documentation**: Automatic documentation generation
- **Type Safety**: Full TypeScript support
- **Environment Integration**: Seamless environment variable handling

### Environment Variable Inspection

Inspect and analyze environment variables in your .env files with detailed information:

```typescript
import { getEnvVariables } from '@x12i/env';

// Get variables from default .env file
const defaultVars = getEnvVariables();

// Get variables from specific environment file
const testVars = getEnvVariables('test');        // .env.test
const prodVars = getEnvVariables('prod');        // .env.prod
const dbVars = getEnvVariables('prod.database'); // .env.prod.database

console.log(testVars);
// [
//   { varName: 'API_KEY', length: 20, synthesizedValue: 'te***89' },
//   { varName: 'DB_HOST', length: 18, synthesizedValue: 'test-db.example.com' },
//   { varName: 'PASSWORD', length: 25, synthesizedValue: 'su***23' }
// ]
```

**Environment Variable Inspection Features:**
- **Variable Discovery**: List all variables in any .env file
- **Sensitive Data Masking**: Automatically mask passwords, keys, and tokens
- **Length Information**: Get original value length for validation
- **Multi-Environment Support**: Works with any environment file path
- **Safe Inspection**: Sensitive fields are automatically masked
- **TypeScript Support**: Full type definitions for variable information

---

## 📖 Complete Examples

### Environment Variable Inspection (NEW!)

```typescript
import { getEnvVariables, parseConfig } from '@x12i/env';

// Inspect variables from different environment files
const defaultVars = getEnvVariables();           // .env
const testVars = getEnvVariables('test');        // .env.test
const prodVars = getEnvVariables('prod');        // .env.prod
const dbVars = getEnvVariables('prod.database'); // .env.prod.database

console.log('Default environment variables:', defaultVars.length);
console.log('Test environment variables:', testVars.length);
console.log('Production environment variables:', prodVars.length);
console.log('Database environment variables:', dbVars.length);

// Display variable information with sensitive data masking
testVars.forEach(variable => {
  console.log(`${variable.varName}: ${variable.synthesizedValue} (length: ${variable.length})`);
});

// Use in configuration validation
const config = parseConfig({
  api: {
    key: 'ENV.TEST.API_KEY',
    host: 'ENV.TEST.API_HOST'
  }
});

// Verify all required variables exist
const requiredVars = ['API_KEY', 'API_HOST'];
const missingVars = requiredVars.filter(varName => 
  !testVars.some(v => v.varName === varName)
);

if (missingVars.length > 0) {
  console.error('Missing required variables:', missingVars);
}
```

### Cloud-Native Application

```typescript
import { initConfig } from '@x12i/env';

const config = initConfig({
  service: {
    name: 'ENV.SERVICE_NAME',
    version: 'ENV.APP_VERSION',
    port: 'ENV.PORT:port||8080',
    host: 'ENV.HOST||0.0.0.0'
  },
  database: {
    url: 'ENV.DATABASE_URL',
    poolSize: 'ENV.DB_POOL_SIZE:nat||10',
    ssl: 'ENV.DB_SSL:boolean||true'
  },
  redis: {
    url: 'ENV.REDIS_URL',
    ttl: 'ENV.REDIS_TTL:duration||1h'
  },
  logging: {
    level: 'ENV.LOG_LEVEL||info',
    pretty: 'ENV.LOG_PRETTY:boolean||false'
  }
}, {
  prefix: 'APP_',
  requiredVars: ['SERVICE_NAME', 'DATABASE_URL'],
  dotenvPath: '.env',
  generateDocs: true,
  docsPath: './docs/ENV_VARS.md',
  schema: {
    port: {
      type: 'port',
      min: 1000,
      max: 65535,
      doc: 'HTTP server port'
    }
  },
  verbose: true
});

console.log('✅ Configuration loaded successfully!');
```

### Multi-Environment Setup

```typescript
const env = process.env.NODE_ENV || 'development';

const config = initConfig('./config.json', {
  dotenvPath: `.env.${env}`,
  suffix: `_${env.toUpperCase()}`,
  overrides: {
    environment: env
  },
  defaults: {
    LOG_LEVEL: 'info',
    PORT: '3000'
  }
});
```

### Multi-Environment File Setup (NEW!)

```typescript
// .env.test file
API_KEY=test-api-key-123
DB_HOST=test-db.example.com
DB_PORT=5432

// .env.prod.database file  
HOST=prod-db.example.com
PORT=5432
SSL=true

// .env.staging.api file
KEY=staging-api-key-456
TIMEOUT=30s

const config = {
  // Simple pattern
  app: {
    name: 'ENV.APP_NAME||my-app'
  },
  
  // Test environment
  test: {
    apiKey: 'ENV.TEST.API_KEY',
    dbHost: 'ENV.TEST.DB_HOST',
    dbPort: 'ENV.TEST.DB_PORT:port'
  },
  
  // Production database
  production: {
    database: {
      host: 'ENV.PROD.DATABASE.HOST',
      port: 'ENV.PROD.DATABASE.PORT:port',
      ssl: 'ENV.PROD.DATABASE.SSL:boolean'
    }
  },
  
  // Staging API
  staging: {
    api: {
      key: 'ENV.STAGING.API.KEY',
      timeout: 'ENV.STAGING.API.TIMEOUT:duration'
    }
  }
};

const result = initConfig(config, { verbose: true });
```

### AWS Configuration with Prefix

```typescript
process.env.AWS_ACCESS_KEY_ID = 'AKIA...';
process.env.AWS_SECRET_ACCESS_KEY = 'secret...';
process.env.AWS_REGION = 'us-east-1';
process.env.AWS_LOG_DIR = './aws-logs';

const awsConfig = initConfig({
  accessKeyId: 'ENV.ACCESS_KEY_ID',
  secretAccessKey: 'ENV.SECRET_ACCESS_KEY',
  region: 'ENV.REGION',
  logDir: 'ENV.LOG_DIR'
}, {
  prefix: 'AWS_',
  createDirectories: true,
  schema: {
    logDir: {
      type: 'string',
      isDirectory: true
    }
  }
});
```

### Multi-Config Production Setup

```typescript
import { parseMultiConfig } from '@x12i/env';

// Production environment with multiple config sources
const result = parseMultiConfig({
  sources: [
    './configs/base.json',           // Base configuration
    './configs/database.json',       // Database settings
    './configs/redis.json',          // Redis settings
    './configs/production.json',     // Production overrides
    './configs/secrets.json'         // Secret values
  ],
  mergeStrategy: 'deep',
  priority: 'last',
  dotenvPath: '.env.production',
  prefix: 'APP_',
  verbose: true,
  schema: {
    port: {
      type: 'port',
      required: true,
      doc: 'HTTP server port'
    }
  }
});

console.log('🔧 Merged configuration:', result.config);
console.log('📊 Resolved variables:', result.resolvedVars);
```

### Separate Environment Configs

```typescript
// Load all environment configs separately
const envConfigs = parseMultiConfig({
  sources: [
    './configs/development.json',
    './configs/staging.json',
    './configs/production.json'
  ],
  keepSeparate: true,
  names: ['development', 'staging', 'production'],
  dotenvPath: '.env',
  verbose: true
});

// Use the appropriate config based on NODE_ENV
const env = process.env.NODE_ENV || 'development';
const currentConfig = envConfigs.configs[env];

console.log(`🌍 Using ${env} configuration:`, currentConfig);
```

---

## 🔧 API Reference

### Core Functions

#### `parseConfig<T>(config, options?)`

Parse a configuration object and resolve ENV tokens.

**Options:**
- `strict`: Throw on missing vars (default: `true`)
- `verbose`: Log resolved variables (default: `false`)
- `dotenvPath`: Load .env file
- `prefix`: Prepend to all ENV var names
- `suffix`: Append to all ENV var names (env-specific)
- `defaults`: Default values for ENV vars
- `transform`: Custom transformers
- `createDirectories`: Auto-create directories
- `commandLineArgs`: Parse from process.argv
- `envSeparator`: For nested keys (default: `__`)
- `heuristicJsonParsing`: Auto-detect and parse JSON-like strings (default: `true`)
- `lenientJson`: Return original string on JSON parse failure instead of throwing (default: `false`)

#### `parseMultiConfig<T>(options)` (NEW!)

Smart multi-config handling with merge strategies.

**Options:**
- `sources`: Array of config sources
- `mergeStrategy`: How to merge configs ('deep' | 'shallow' | 'override' | 'append')
- `keepSeparate`: Keep configs separate (named access)
- `names`: Names for each config (if keepSeparate)
- `extends`: Base config to extend from
- `priority`: Which source has priority ('first' | 'last')
- All `parseConfig` options

#### `initConfig<T>(config, options?)`

One-call initialization with validation.

**Additional Options:**
- `requiredVars`: Required environment variables
- `validateOnInit`: Run validation (default: `true`)
- `throwOnMissing`: Throw if vars missing (default: `true`)
- `schema`: Schema validation
- `generateDocs`: Auto-generate docs
- `docsPath`: Where to save docs
- `descriptions`: Variable descriptions
- `overrides`: Highest priority values
- `stores`: Multiple configuration stores

**ERC Compliance Options (NEW!):**
- `ercMode`: Enable ERC compliance mode (default: `false`)
- `componentName`: Component name for ERC manifest (required if `ercMode` or `generateManifest` is true)
- `componentVersion`: Component version string
- `ercVersion`: ERC standard version (default: `'1.1.0'`)
- `ercDependencies`: Array of ERC-compliant dependency package names
- `generateManifest`: Generate `erc-manifest.json` (default: `false`)
- `manifestPath`: Path to save ERC manifest (default: `'./erc-manifest.json'`)
- `generateEnvExample`: Generate `.env.example` file (default: `false`)
- `envExamplePath`: Path to save `.env.example` (default: `'./.env.example'`)
- `validateERC`: Validate ERC compliance (default: `false`)
- `updateReadme`: Update README with ERC badge (default: `false`)
- `readmePath`: Path to README file (default: `'./README.md'`)

#### `remoteConfig<T>(options?)` (NEW!)

Initialize configuration from a remote JSON source using `nx-remote-json`. Fetches configuration from disk, S3-compatible storage, or MongoDB, then processes it through the standard `initConfig` pipeline.

**Options:**
- `remoteJsonConfig`: Configuration for the remote JSON client
- `mode`: Backend mode (`"disk"`, `"storage"`, or `"database"`) - supports `ENV.VARIABLE` pattern
- `jsonRouter`: Router name for the remote config - supports `ENV.VARIABLE` pattern
- `jsonKey`: Key name for the remote config - supports `ENV.VARIABLE` pattern
- All `initConfig` options (except `stores`)

**Example:**
```typescript
import { remoteConfig } from '@x12i/env';
// Import your remote JSON client implementation

const result = await remoteConfig({
  remoteJsonConfig: {
    disk: {
      rootLocation: "/data/configs",
      mapping: [{ jsonRouter: "app", folder: "app-configs" }]
    }
  },
  mode: "disk",
  jsonRouter: "app",
  jsonKey: "production"
});

console.log(result.config);
```

**Using Environment Variables:**
```typescript
// Set environment variables
process.env.CONFIG_MODE = "storage";
process.env.CONFIG_ROUTER = "settings";
process.env.CONFIG_KEY = "user-123";

const result = await remoteConfig({
  remoteJsonConfig: {
    storage: {
      region: "us-east-1",
      endpoint: "https://s3.amazonaws.com",
      bucket: "my-bucket",
      accessKey: process.env.AWS_ACCESS_KEY!,
      secretKey: process.env.AWS_SECRET_KEY!,
      mapping: [{ jsonRouter: "settings", folder: "settings" }]
    }
  },
  mode: "ENV.CONFIG_MODE",      // Resolved from process.env.CONFIG_MODE
  jsonRouter: "ENV.CONFIG_ROUTER",  // Resolved from process.env.CONFIG_ROUTER
  jsonKey: "ENV.CONFIG_KEY"         // Resolved from process.env.CONFIG_KEY
});
```

#### `verify(variableNames)`

Validate environment variables are set.

#### `watchConfig<T>(configPath, options?)`

Watch a config file for changes.

#### `createConfig<T>(schema)`

Create a convict-style config with schema.

#### `autoLoadConfig<T>(options?)` (NEW!)

Automatically load configuration from environment variables using a default config map plus any additional env vars.

**Options:**
- `dotenvPath`: Path to .env file (default: `.env`)
- `includeAllEnvVars`: Include all env vars not in default config (default: `true`)
- `beautify`: Sort and format output nicely (default: `true`)
- `enableSharedEnv`: Enable shared .env file support (default: `true`)
- `sharedEnvRequired`: Require shared files to exist (default: `true`)
- `sections`: Optional array of section names to load from `.env` (e.g. `['DATABASE', 'AI']`)
- `groups`: Optional array of group paths from `DEFAULT_AUTO_CONFIG_MAP` to load (e.g. `['database.mongodb', 'ai.openai']`)
- All `parseConfig` options

**Sections in .env:**

Sections are defined using headers like `[DATABASE]` and `[AI]`:

```bash
[DATABASE]
MONGO_URI=mongodb://...
MONGO_LOGS_DB=logs-db

[AI]
OPENAI_API_KEY=sk-...
GROK_API_KEY=...
```

Then load only specific sections:

```typescript
const config = autoLoadConfig({
  sections: ['DATABASE', 'AI']
});
```

**Groups in DEFAULT_AUTO_CONFIG_MAP:**

Groups correspond to dot-notation paths in the default config map (e.g. `database.mongodb`, `ai.openai`, `contentRegistry.github`):

```typescript
const config = autoLoadConfig({
  groups: ['database.mongodb', 'ai.openai', 'contentRegistry.github']
});
```

### Utility Functions

#### `normalizeMongoUri(uri)`

Normalize MongoDB connection URIs by adding the `mongodb://` prefix if missing.

**Parameters:**
- `uri` (string | undefined): MongoDB connection URI

**Returns:** string | undefined - Normalized URI with protocol prefix

**Example:**
```typescript
import { normalizeMongoUri } from '@x12i/env';

const uri = normalizeMongoUri('localhost:27017/mydb');
// Returns: 'mongodb://localhost:27017/mydb'

// Already has prefix - no change
const uri2 = normalizeMongoUri('mongodb://localhost:27017/mydb');
// Returns: 'mongodb://localhost:27017/mydb'

// Handles undefined gracefully
const uri3 = normalizeMongoUri(undefined);
// Returns: undefined
```

**Use Case:**
Downstream packages can use this utility to ensure MongoDB URIs are properly formatted before database connection:

```typescript
import { normalizeMongoUri } from '@x12i/env';

// In ActivityTracker or other MongoDB client initialization
const mongoUri = normalizeMongoUri(config.MONGO_URI);
await mongoose.connect(mongoUri);
```

#### `maskSecrets(config, path?, schema?)`

Mask sensitive fields in configuration.

#### `extractEnvTokens(config)`

Extract all ENV tokens from a configuration.

#### `generateDocumentation(config, resolvedVars, descriptions?, schema?)`

Generate markdown documentation.

#### `validateRequiredEnvVars(variableNames)`

Validate required environment variables.

---

## 🔐 ERC (Environment Requirements Contract) Compliance

**@x12i/env** now includes built-in support for **ERC compliance**, making it easy to create ERC-compliant components with automatic manifest generation, dependency scanning, and `.env.example` generation.

### What is ERC?

ERC (Environment Requirements Contract) is a standard for documenting and managing environment variable requirements across components and their dependencies. It ensures:

- ✅ **Transparent Requirements**: All environment variables are documented
- ✅ **Dependency Awareness**: Transitive requirements from dependencies are automatically merged
- ✅ **Zero-Config Setup**: `.env.example` files are generated automatically
- ✅ **Validation**: ERC compliance can be verified at build/runtime
- ✅ **CI/CD Integration**: `erc-verify` command for pipelines

### Quick Start with ERC

Enable ERC mode with just a few options:

```typescript
import { initConfig } from '@x12i/env';

export class AIGateway {
  constructor(config = {}) {
    this.config = initConfig({
      github: {
        token: 'ENV.GITHUB_TOKEN',
        apiUrl: 'ENV.GITHUB_API_URL||https://api.github.com'
      },
      api: {
        timeout: 'ENV.GATEWAY_TIMEOUT:duration||30s'
      }
    }, {
      ercMode: true,  // Enable ERC compliance mode
      componentName: 'ai-gateway',
      componentVersion: '1.1.0',
      generateManifest: true,  // Generates erc-manifest.json
      generateEnvExample: true,  // Generates .env.example
      validateERC: true,
      updateReadme: true  // Adds ERC badge to README
    }).config;
  }
}
```

### Generated Files

#### `erc-manifest.json`

```json
{
  "component": "ai-gateway",
  "version": "1.1.0",
  "ercCompliant": true,
  "ercVersion": "1.1.0",
  "requirements": {
    "required": [
      {
        "variable": "GITHUB_TOKEN",
        "type": "string",
        "sensitive": true,
        "description": "GitHub API authentication token"
      }
    ],
    "optional": [
      {
        "variable": "GITHUB_API_URL",
        "type": "url",
        "default": "https://api.github.com",
        "description": "Override default GitHub API endpoint"
      },
      {
        "variable": "GATEWAY_TIMEOUT",
        "type": "duration",
        "default": "30s",
        "description": "Request timeout"
      }
    ]
  },
  "dependencies": []
}
```

#### `.env.example`

```bash
# ============================================
# ai-gateway Configuration
# ============================================

# [REQUIRED]
GITHUB_TOKEN=your_secret_here
# Purpose: GitHub API authentication token

# [OPTIONAL]
# GITHUB_API_URL=https://api.github.com
# Purpose: Override default GitHub API endpoint
# Default: https://api.github.com

# GATEWAY_TIMEOUT=30s
# Purpose: Request timeout
# Default: 30s
```

### Transitive Requirement Merging

When your component depends on ERC-compliant packages, their requirements are automatically merged:

```typescript
import { initConfig } from '@x12i/env';

export class AISkills {
  constructor(config = {}) {
    this.config = initConfig({
      apiKey: 'ENV.AI_SKILLS_API_KEY',
      timeout: 'ENV.AI_SKILLS_TIMEOUT:duration||60s'
    }, {
      ercMode: true,
      componentName: 'ai-skills',
      ercDependencies: [
        '@athenices/ai-gateway',  // Reads its erc-manifest.json
        '@xeonoces/cloud-storage'
      ],
      generateManifest: true,
      generateEnvExample: true
    }).config;
  }
}
```

The generated `.env.example` will include:
- Your component's requirements
- All required variables from `@athenices/ai-gateway`
- All required variables from `@xeonoces/cloud-storage`
- All optional variables with their defaults

### ERC Functions

#### `generateERCManifest(config, options)`

Generate an ERC manifest from a configuration object.

```typescript
import { generateERCManifest } from '@x12i/env';

const manifest = generateERCManifest(config, {
  componentName: 'my-component',
  componentVersion: '1.0.0',
  ercVersion: '1.1.0',
  schema: mySchema,
  descriptions: myDescriptions
});
```

#### `mergeERCRequirements(ownRequirements, dependencies, projectRoot?)`

Merge requirements from ERC-compliant dependencies.

```typescript
import { mergeERCRequirements } from '@x12i/env';

const merged = mergeERCRequirements(
  { required: [...], optional: [...] },
  ['@athenices/ai-gateway', '@xeonoces/cloud-storage']
);
```

#### `generateEnvExample(requirements, options)`

Generate a `.env.example` file from ERC requirements.

```typescript
import { generateEnvExample } from '@x12i/env';

const envExample = generateEnvExample(requirements, {
  componentName: 'my-component',
  dependencyManifests: dependencyManifestsMap
});
```

#### `validateERC(manifestPath?, projectRoot?)`

Validate ERC compliance of a project.

```typescript
import { validateERC } from '@x12i/env';

const result = validateERC('./erc-manifest.json');
if (!result.valid) {
  console.error('ERC validation failed:', result.errors);
}
```

### CLI: `erc-verify`

Verify ERC compliance from the command line:

```bash
# Basic verification
npx x12i-env erc-verify

# With custom manifest path
npx x12i-env erc-verify --manifest ./custom-manifest.json

# Strict mode (exit with error code on failure)
npx x12i-env erc-verify --strict

# Verbose output
npx x12i-env erc-verify --verbose
```

### ERC Badge

When `updateReadme: true` is set, @x12i/env automatically adds an ERC badge to your README:

```markdown
![ERC 1.1.0](https://img.shields.io/badge/ERC-1.1.0-blue)
```

### Benefits

✅ **Zero Config Implementation**: Components become ERC-compliant with 3 lines of code  
✅ **Automatic Documentation**: `.env.example` generated automatically  
✅ **Transitive Requirements**: Dependencies auto-merged  
✅ **Validation Built-in**: ERC compliance checked at build/runtime  
✅ **CI/CD Integration**: `erc-verify` command for pipelines  
✅ **Type Safety**: Full TypeScript support  
✅ **Migration Path**: Easy upgrade for existing components  

---

## 🎨 TypeScript Support & IntelliSense

Full TypeScript support with comprehensive IntelliSense for `autoLoadConfig()`:

### Default Config Types

The `DefaultConfig` interface provides full IntelliSense for all default configuration sections:

```typescript
import { autoLoadConfig, DefaultConfig } from '@x12i/env';

// Explicit typing for best IntelliSense support
const config: DefaultConfig = autoLoadConfig();

// Full IntelliSense works for all sections:
config.ai?.openai?.apiKey              // ✅ OpenAI API key
config.ai?.xai?.apiKey                 // ✅ Grok/XAI API key
config.database?.mongodb?.uri          // ✅ MongoDB URI
config.database?.mongodb?.logsDatabase // ✅ Logs database
config.contentRegistry?.local?.path   // ✅ Content registry path
config.logging?.level                 // ✅ Log level
config.testing?.scopedTextFile        // ✅ Test config
config.agent?.id                      // ✅ Agent ID

// Nested MongoDB role configurations:
config.database?.mongodb?.roles?.runtime?.connectionString
config.database?.mongodb?.roles?.metadata?.database
config.database?.mongodb?.roles?.knowledge?.database
config.database?.mongodb?.roles?.memory?.database
```

### Generic Type Parameter

You can also use the generic type parameter:

```typescript
const config = autoLoadConfig<DefaultConfig>();
// Same IntelliSense support
```

### Extending Default Config

Extend `DefaultConfig` to add your own custom properties:

```typescript
import { DefaultConfig } from '@x12i/env';

interface MyAppConfig extends DefaultConfig {
  customField?: {
    myValue?: string;
  };
}

const config = autoLoadConfig<MyAppConfig>({
  includeAllEnvVars: true // Allows additional properties
});
```

### Legacy Type Support

For `initConfig()` and other functions, you can still use custom interfaces:

```typescript
interface AppConfig {
  database: {
    host: string;
    port: number;
  };
  api: {
    key: string;
    timeout: number;
  };
}

const result = initConfig<AppConfig>(config);
// result.config is typed as AppConfig
```

---
_Source: https://npm.io/package/@x12i/env · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._