{"id":36956586,"url":"https://github.com/vlavrynovych/auto-envparse","last_synced_at":"2026-01-16T08:14:20.991Z","repository":{"id":328230885,"uuid":"1113342855","full_name":"vlavrynovych/auto-envparse","owner":"vlavrynovych","description":"⚡ Automatic environment variable parsing with zero configuration and type inference","archived":false,"fork":false,"pushed_at":"2025-12-29T17:30:09.000Z","size":630,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-31T08:43:18.067Z","etag":null,"topics":["12-factor","dotenv","env","environment","environment-variables","parser","schema","zero-config","zero-configuration"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/auto-envparse","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vlavrynovych.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T21:08:11.000Z","updated_at":"2025-12-28T18:24:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vlavrynovych/auto-envparse","commit_stats":null,"previous_names":["vlavrynovych/auto-envparse"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/vlavrynovych/auto-envparse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlavrynovych%2Fauto-envparse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlavrynovych%2Fauto-envparse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlavrynovych%2Fauto-envparse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlavrynovych%2Fauto-envparse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vlavrynovych","download_url":"https://codeload.github.com/vlavrynovych/auto-envparse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlavrynovych%2Fauto-envparse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28387596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T13:42:20.960Z","status":"ssl_error","status_checked_at":"2026-01-13T13:42:03.276Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["12-factor","dotenv","env","environment","environment-variables","parser","schema","zero-config","zero-configuration"],"created_at":"2026-01-13T14:01:22.072Z","updated_at":"2026-01-16T08:14:20.962Z","avatar_url":"https://github.com/vlavrynovych.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# auto-envparse\n\n\u003e ⚡ Automatic environment variable parsing with zero configuration and type inference\n\n[![NPM Version][npm-image]][npm-url]\n[![Test](https://github.com/vlavrynovych/auto-envparse/actions/workflows/test.yml/badge.svg)](https://github.com/vlavrynovych/auto-envparse/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Following [12-Factor App](https://12factor.net/config) principles** - Store configuration in the environment without schemas, validators, or manual type conversion. Your object structure **IS** your schema.\n\n---\n\n## 📋 Table of Contents\n\n- [💡 Why auto-envparse?](#-why-auto-envparse)\n- [🎯 Features](#-features)\n- [📦 Installation](#-installation)\n- [🚀 Quick Start](#-quick-start)\n- [📖 Type Coercion \u0026 Advanced Types](#-type-coercion--advanced-types)\n- [📁 .env File Loading](#-env-file-loading)\n- [🛠️ Custom Validation \u0026 Transforms](#️-custom-validation--transforms)\n- [📚 Documentation](#-documentation)\n- [🎨 TypeScript Support](#-typescript-support)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n- [🔗 Links](#-links)\n\n---\n\n## 💡 Why auto-envparse?\n\nMost environment variable libraries force you to write schemas and validators before you can parse anything:\n\n```typescript\n// ❌ Other libraries: Define schema + types + validators\nconst schema = {\n  host: str({ default: 'localhost' }),\n  port: num({ default: 5432 }),\n  ssl: bool({ default: false })\n};\nconst config = cleanEnv(process.env, schema);\n```\n\n**auto-envparse takes a different approach.** If you already have a configuration object with defaults, that's all you need:\n\n```typescript\n// ✅ auto-envparse: Your object IS the schema\nimport AEP from 'auto-envparse';\n\nconst config = {\n    host: 'localhost',\n    port: 5432,\n    ssl: false\n};\n\nAEP.parse(config, { prefix: 'DB' }); // Done!\n```\n\n**The type of each default value tells auto-envparse how to parse it.** No schemas. No validators. No manual type conversion. Just works.\n\n### Works with Classes Too\n\n```typescript\nimport AEP from 'auto-envparse';\n\nclass DatabaseConfig {\n    host = 'localhost';\n    port = 5432;\n    ssl = false;\n}\n\n// Environment: DB_HOST=example.com, DB_PORT=3306, DB_SSL=true\nconst config = AEP.parse(DatabaseConfig, { prefix: 'DB' });\n// Returns a fully populated DatabaseConfig instance\n```\n\nPerfect for existing codebases with class-based configuration.\n\n---\n\n## 🎯 Features\n\n- ✨ **Zero Configuration** - Object structure defines the schema\n- 🎯 **Type Inference** - Automatic type detection from default values\n- 🔄 **Type Coercion** - String env vars → correct types (string, number, boolean, array)\n- 🐫 **Smart Naming** - Auto camelCase → SNAKE_CASE conversion\n- 🏗️ **Nested Objects** - Full support with dot-notation (e.g., `DB_POOL_MIN`)\n- 📋 **Nested Arrays** - Arrays of objects with dot-notation (e.g., `SERVERS_0_HOST`)\n- 📁 **.env File Loading** - Load from .env files with configurable priority\n- 🔀 **Multi-Source Support** - Merge variables from multiple sources (env, .env, .env.local)\n- 🔀 **Transform Functions** - Custom value transformations with external libraries\n- 🛠️ **Custom Overrides** - Add validation or custom parsing when needed\n- 📦 **Dual Package** - ESM and CommonJS support\n- 🎨 **TypeScript** - Full type safety included\n- 🪶 **Lightweight** - Zero dependencies\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install auto-envparse\n```\n\n```bash\nyarn add auto-envparse\n```\n\n---\n\n## 🚀 Quick Start\n\n### 1. Basic Usage\n\n```typescript\nimport AEP from 'auto-envparse';\n\nconst config = {\n    apiUrl: 'http://localhost:3000',\n    timeout: 5000,\n    debug: false\n};\n\n// Environment variables: APP_API_URL, APP_TIMEOUT, APP_DEBUG\nAEP.parse(config, { prefix: 'APP' });\n\nconsole.log(config.timeout); // Automatically converted to number\n```\n\n**Shorter alias:** Import as default for shorter code:\n\n```typescript\nimport AEP from 'auto-envparse';\nAEP.parse(config, { prefix: 'APP' });\n```\n\n### 2. Without Prefix\n\nPrefix is optional - omit it for global environment variables:\n\n```typescript\nimport AEP from 'auto-envparse';\n\nconst config = {\n    host: 'localhost',\n    port: 3000,\n    nodeEnv: 'development'\n};\n\n// Environment variables: HOST, PORT, NODE_ENV\nAEP.parse(config);\n```\n\n### 3. Nested Objects\n\n```typescript\nimport AEP from 'auto-envparse';\n\nconst config = {\n    database: {\n        host: 'localhost',\n        port: 5432,\n        pool: {\n            min: 2,\n            max: 10\n        }\n    }\n};\n\n// Environment:\n// APP_DATABASE_HOST=prod.com\n// APP_DATABASE_PORT=5433\n// APP_DATABASE_POOL_MIN=5\n// APP_DATABASE_POOL_MAX=20\nAEP.parse(config, { prefix: 'APP' });\n```\n\n### 4. Class-Based Configuration\n\n```typescript\nimport AEP from 'auto-envparse';\n\nclass ServerConfig {\n    host = '0.0.0.0';\n    port = 3000;\n\n    getUrl(): string {\n        return `http://${this.host}:${this.port}`;\n    }\n}\n\n// Environment: SERVER_HOST=example.com, SERVER_PORT=8080\nconst config = AEP.parse(ServerConfig, { prefix: 'SERVER' });\nconsole.log(config.getUrl()); // 'http://example.com:8080'\n```\n\n---\n\n## 📖 Type Coercion \u0026 Advanced Types\n\nauto-envparse automatically converts environment variables based on your default value types:\n\n| Type | Example | Result |\n|------|---------|--------|\n| `string` | `DB_HOST=prod.com` | `'prod.com'` |\n| `number` | `DB_PORT=3306` | `3306` |\n| `boolean` | `DB_SSL=true` | `true` (supports: true/false, 1/0, yes/no, on/off) |\n| `object` | `DB_POOL_MIN=5` | Nested via dot-notation or JSON |\n| `array` | `SERVERS_0_HOST=x.com` | Arrays via dot-notation or JSON |\n\n**Arrays of Objects:**\n```typescript\nconst config = { servers: [{ host: 'localhost', port: 8080 }] };\n// SERVERS_0_HOST=s1.com, SERVERS_0_PORT=8080, SERVERS_1_HOST=s2.com, SERVERS_1_PORT=8081\nAEP.parse(config, { prefix: 'APP' });\n```\n\nSee [API.md](API.md) for complete type coercion details and edge cases.\n\n---------------|---------|--------|------|\n| `'localhost'` | `'prod.com'` | `'prod.com'` | `string` |\n| `5432` | `'3306'` | `3306` | `number` |\n| `false` | `'true'` | `true` | `boolean` |\n| `['a']` | `'[\"x\",\"y\"]'` | `['x', 'y']` | `array` |\n\n### Boolean Parsing\n\nFlexible boolean parsing (case-insensitive):\n\n- **Truthy**: `'true'`, `'1'`, `'yes'`, `'on'`\n- **Falsy**: Everything else\n\n### Nested Arrays\n\nArrays of objects support both JSON and dot-notation formats. Dot-notation takes priority:\n\n**Dot-Notation Format** (Recommended):\n```typescript\nconst config = {\n    servers: [{\n        host: 'localhost',\n        port: 3000\n    }]\n};\n\n// Environment variables:\n// APP_SERVERS_0_HOST=server1.com\n// APP_SERVERS_0_PORT=8080\n// APP_SERVERS_1_HOST=server2.com\n// APP_SERVERS_1_PORT=8081\n\nAEP.parse(config, { prefix: 'APP' });\n// Result: servers = [\n//   { host: 'server1.com', port: 8080 },\n//   { host: 'server2.com', port: 8081 }\n// ]\n```\n\n**JSON Format** (Also supported):\n```typescript\n// APP_SERVERS='[{\"host\":\"server1.com\",\"port\":8080}]'\nAEP.parse(config, { prefix: 'APP' });\n```\n\n**Features**:\n- ✅ Multilevel nesting: `APP_SERVICES_0_CONFIG_DATABASE_HOST=db.com`\n- ✅ Sparse arrays: Indices `0, 2, 5` → compact array with 3 elements\n- ✅ Type coercion: String env vars → proper types in array elements\n- ✅ Empty arrays skipped (require template element)\n\n---\n\n## 📁 .env File Loading\n\nLoad from `.env` files with configurable priority:\n\n```typescript\nimport AEP from 'auto-envparse';\n\nconst config = { host: 'localhost', port: 3000 };\n\n// Default: loads from ['env', '.env']\nAEP.parse(config, { prefix: 'APP' });\n\n// Multi-source with priority (first wins):\nAEP.parse(config, {\n    prefix: 'APP',\n    sources: ['env', '.env.local', '.env']  // process.env \u003e .env.local \u003e .env\n});\n\n// Custom parser (e.g., dotenv):\nimport { parse } from 'dotenv';\nAEP.parse(config, {\n    prefix: 'APP',\n    sources: ['.env'],\n    envFileParser: parse\n});\n```\n\nThe built-in parser supports `KEY=value`, comments, and quotes. For advanced features (multiline, variable expansion), use `dotenv.parse`. See [API.md](API.md) for details.\n\n---\n\n\n## 🛠️ Custom Validation \u0026 Transforms\n\nAdd custom validation using overrides:\n\n```typescript\nimport AEP from 'auto-envparse';\n\nconst config = { port: 3000, env: 'dev' as 'dev' | 'staging' | 'prod' };\n\nconst overrides = new Map([\n    // Custom validation\n    ['port', (obj, envVar) =\u003e {\n        const port = parseInt(process.env[envVar] || '');\n        if (port \u003e= 1 \u0026\u0026 port \u003c= 65535) obj.port = port;\n        else throw new Error(`Invalid port: ${port}`);\n    }],\n\n    // Enum validation (built-in helper)\n    ['env', AEP.enumValidator('env', ['dev', 'staging', 'prod'])],\n\n    // Transform values (built-in helper)\n    ['timeout', AEP.transform('timeout', (val) =\u003e Math.max(parseInt(val), 1000))]\n]);\n\nAEP.parse(config, { prefix: 'APP', overrides });\n```\n\n**Helpers available:**\n- `AEP.enumValidator(key, allowedValues)` - Validate enum values\n- `AEP.transform(key, fn)` - Transform values with custom logic\n\nSee [API.md](API.md) for complete override examples and helper documentation.\n\n---\n\n## 📚 Documentation\n\n- **[API.md](./API.md)** - Complete API reference with all methods and options\n- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and migration guides\n\n---\n\n---\n\n---\n\n## 🎨 TypeScript Support\n\nFull type safety with TypeScript:\n\n```typescript\nimport AEP from 'auto-envparse';\n\ninterface Config {\n    host: string;\n    port: number;\n    ssl: boolean;\n}\n\nconst config: Config = {\n    host: 'localhost',\n    port: 5432,\n    ssl: false\n};\n\nAEP.parse(config, { prefix: 'DB' });\n\n// All types are preserved and enforced\nconst host: string = config.host;\nconst port: number = config.port;\nconst ssl: boolean = config.ssl;\n```\n\n### Dual Package Support\n\nauto-envparse supports both CommonJS and ESM:\n\n```typescript\n// ESM (import) - Default export (recommended)\nimport AEP from 'auto-envparse';\nAEP.parse(config, { prefix: 'DB' });\n\n// ESM (import) - Named export\nimport { AutoEnvParse } from 'auto-envparse';\nAutoEnvParse.parse(config, { prefix: 'DB' });\n\n// CommonJS (require) - Default export\nconst AEP = require('auto-envparse').default;\nAEP.parse(config, { prefix: 'DB' });\n\n// CommonJS (require) - Named export\nconst { AutoEnvParse } = require('auto-envparse');\nAutoEnvParse.parse(config, { prefix: 'DB' });\n```\n\nWorks seamlessly in both module systems!\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\nSee [GitHub Issues](https://github.com/vlavrynovych/auto-envparse/issues) for open tasks and discussions.\n\n---\n\n## 📄 License\n\nMIT © [Volodymyr Lavrynovych](https://github.com/vlavrynovych)\n\n---\n\n## 🔗 Links\n\n- 📦 [npm Package](https://www.npmjs.com/package/auto-envparse)\n- 🐙 [GitHub Repository](https://github.com/vlavrynovych/auto-envparse)\n- 📖 [API Documentation](./API.md)\n- 🐛 [Issue Tracker](https://github.com/vlavrynovych/auto-envparse/issues)\n\n[npm-image]: https://img.shields.io/npm/v/auto-envparse.svg?style=flat\n[npm-url]: https://npmjs.org/package/auto-envparse\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlavrynovych%2Fauto-envparse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvlavrynovych%2Fauto-envparse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlavrynovych%2Fauto-envparse/lists"}