Patch v3.0.2

What's Changed

• Build(deps): Bump rollup from 4.53.3 to 4.59.0 in the npm_and_yarn group across 1 directory by @dependabot[bot] in #42
• Build(deps-dev): Bump @types/node from 25.0.3 to 25.0.10 by @dependabot[bot] in #41
• Build(deps-dev): Bump @typescript-eslint/parser from 8.53.0 to 8.54.0 by @dependabot[bot] in #38
• Build(deps-dev): Bump globals from 16.5.0 to 17.1.0 by @dependabot[bot] in #40
• Build(deps-dev): Bump @typescript-eslint/eslint-plugin from 8.53.0 to 8.54.0 by @dependabot[bot] in #39
• Build(deps-dev): Bump minimatch from 3.1.2 to 3.1.5 in the npm_and_yarn group across 1 directory by @dependabot[bot] in #43
• Build(deps-dev): Bump @vitest/coverage-v8 from 4.0.17 to 4.0.18 by @dependabot[bot] in #37

Full Changelog: v3.0.0...v3.0.2

v3.0.0 - Major Release

🚨 BREAKING CHANGES

Remove deprecated v2.0 backward compatibility API (#32)

The old v2.0 signature that accepted prefix as a string and overrides as separate parameters has been removed. Only the options-based API introduced in v2.1 is now supported.

// ❌ v2.x - REMOVED
AutoEnvParse.parse(config, 'DB');
AutoEnvParse.parse(config, 'DB', overrides);

// ✅ v3.0 - Use this
AutoEnvParse.parse(config, { prefix: 'DB' });
AutoEnvParse.parse(config, { prefix: 'DB', overrides });

📖 Migration Guide

Simple prefix usage:

// Before (v2.x)
const config = AutoEnvParse.parse(myConfig, 'DB');

// After (v3.0)
const config = AutoEnvParse.parse(myConfig, { prefix: 'DB' });

With overrides:

// Before (v2.x)
const config = AutoEnvParse.parse(myConfig, 'DB', overrides);

// After (v3.0)
const config = AutoEnvParse.parse(myConfig, { prefix: 'DB', overrides });

No prefix (default):

// Before (v2.x)
const config = AutoEnvParse.parse(myConfig);

// After (v3.0) - no change needed!
const config = AutoEnvParse.parse(myConfig);

🔧 Automated Migration

Use find/replace with regex:

• Find: \.parse\(([^,]+),\s*'([^']+)'\)
• Replace: .parse($1, { prefix: '$2' })

❌ Removed

• v2.0 API signature - parse(target, prefix, overrides) removed in favor of parse(target, options)
• Conditional logic - Simplified implementation by removing string vs options detection

📝 Changed

• API Documentation - Updated all examples to use options-based API
• README - Streamlined from 587 to 428 lines, use AEP alias throughout, add TOC
• All tests - Updated 165 tests across 9 test files to use new API

✨ Benefits

• ✅ Cleaner API - Single consistent interface
• ✅ Better extensibility - Easy to add new options without changing signature
• ✅ Less confusion - One clear way to call the function
• ✅ Reduced bundle size - Simpler implementation (~40 lines removed)
• ✅ Future-proof - New features can be added via options object

---

Full Changelog: v2.1.1...v3.0.0

v2.1.1

What's Changed

Workflow Improvements

• Switched to tag-based npm publishing workflow with provenance support
• Enhanced prepublishOnly hook with lint and typecheck

Dependency Updates

• @typescript-eslint/parser: 8.49.0 → 8.50.0 (#25)
• @typescript-eslint/eslint-plugin: 8.49.0 → 8.50.0 (#22)
• @types/node: 20.19.26 → 25.0.2 (#21)
• eslint: 9.39.1 → 9.39.2 (#23)
• globals: 15.15.0 → 16.5.0 (#24)

Full Changelog: v2.1.0...v2.1.1

v2.1.0

🎉 v2.1.0 Release

Major Features

Transform Functions (#18)

• Custom transformation functions for environment variable values
• Support for external libraries (lodash, moment, etc.) for transformations
• Graceful error handling with console warnings for failed transformations

Nested Array Support (#19)

• Dot-notation for arrays of objects (e.g., APP_SERVERS_0_HOST=value)
• Multilevel nesting support in array elements (e.g., APP_SERVICES_0_CONFIG_DATABASE_HOST=db.com)
• Sparse array handling - Non-contiguous indices automatically compacted
• Priority system - Dot-notation takes precedence over JSON when both formats exist
• Backward compatibility - JSON format continues to work perfectly
• RegExp array support - Automatically detected and handled via JSON only

.env File Loading Support (#17)

• ParseOptions interface - Modern options-based API with { prefix, overrides, sources, envFileParser }
• Multi-source loading - Load from multiple sources with configurable priority (e.g., sources: ['env', '.env', '.env.local'])
• Priority system - First source in array takes precedence (flexible override strategy)
• Default behavior - Auto-loads from ['env', '.env'] by default
• Custom parsers - "Bring your own parser" via envFileParser option (e.g., dotenv.parse)
• Built-in parser - Lightweight fallback parser for basic .env files (supports KEY=value, comments, quotes)
• Missing file handling - Warns via console.warn() when files not found (continues execution)
• Backward compatibility - v2.0 API signature (parse(target, prefix, overrides)) still works perfectly
• Zero dependencies by default - Use built-in parser or provide your own (dotenv, etc.)

Improvements

• Test organization - Split into 9 logical test files (165 tests total)
• Code refactoring - Extracted helper methods for better maintainability:
  • detectArrayIndices() - Scans environment for array index patterns
  • parseArrayElement() - Parses individual array elements with type coercion
  • parseObjectPropertiesRecursive() - Handles deep nesting in array elements
  • loadSources() - Loads and merges environment variables from multiple sources
  • parseEnvFile() - Built-in lightweight .env file parser
• Test coverage - Maintained 100% coverage across all metrics
• Documentation - Comprehensive examples for transform functions, nested arrays, and .env file loading

Benefits

✅ More powerful transformations - Leverage any external library for value processing
✅ Complex array configurations - Configure arrays of objects naturally via environment variables
✅ .env file support - Load configuration from .env files with zero dependencies
✅ Multi-source loading - Flexible priority system for environment variable sources
✅ Better maintainability - Well-organized test suite and cleaner codebase
✅ Zero breaking changes - All existing v2.0 code continues to work

---

Full Changelog: https://github.com/vlavrynovych/auto-envparse/blob/main/CHANGELOG.md#210---2025-12-13

v2.0.0 - Major API Redesign

🎉 Major API Redesign

v2.0.0 simplifies the API to have one clear, unified entry point. The goal is to make the library easier to learn and use.

⚠️ BREAKING CHANGES

1. Class Renamed: AutoEnv → AutoEnvParse

// Before (v1.x)
import { AutoEnv } from 'auto-envparse';
AutoEnv.parse(config, 'DB');

// After (v2.0)
import { AutoEnvParse } from 'auto-envparse';
AutoEnvParse.parse(config, 'DB');

2. Simplified Exports - Only One Class

// Before (v1.x) - Multiple ways
import parseEnv from 'auto-envparse';           // ❌ Removed
import { parse } from 'auto-envparse';          // ❌ Removed
import { createFrom } from 'auto-envparse';     // ❌ Removed

// After (v2.0) - One clear way
import { AutoEnvParse } from 'auto-envparse';   // ✅ Named export
// or
import AEP from 'auto-envparse';                // ✅ Default export

3. Unified parse() Method

// Before (v1.x) - Two separate methods
AutoEnv.parse(config, 'DB');
const instance = createFrom(DbClass, 'DB');

// After (v2.0) - One unified method
AutoEnvParse.parse(config, 'DB');
const instance = AutoEnvParse.parse(DbClass, 'DB');

4. parse() Now Returns the Object

// Before (v1.x) - Returns void
const config = { host: 'localhost' };
AutoEnv.parse(config, 'DB');

// After (v2.0) - Returns the object
const config = AutoEnvParse.parse({ host: 'localhost' }, 'DB');

✨ Added

• Unified parse() method with TypeScript overloads for both objects and class constructors
• Return value for parse() - Now returns the populated object/instance
• Default export - Class can be imported as default for convenience
• Emoji in description - Added ⚡ to package description

🔄 Changed

• Class name: AutoEnv → AutoEnvParse
• API surface: Reduced from 5 exports to 1 class (both named and default export)
• Method behavior: parse() now returns the parsed object instead of void

🗑️ Removed

• parseEnv() function - Use AutoEnvParse.parse() instead
• parse() function alias - Use AutoEnvParse.parse() instead
• createFrom() function - Use AutoEnvParse.parse() with class constructor instead

🎯 Benefits

• ✅ Simpler API - One class, two main methods (parse, enumValidator)
• ✅ Better discoverability - Type AutoEnvParse. to see all available methods
• ✅ One way to do it - No confusion about which import/function to use
• ✅ Better TypeScript support - Overloads provide excellent type inference
• ✅ Clearer naming - Class name matches package name
• ✅ More ergonomic - Return values enable cleaner code patterns

📚 Migration Guide

See the CHANGELOG for detailed migration instructions.

📦 Installation

npm install auto-envparse@2.0.0

🔗 Links

• npm package
• API Documentation
• Full Changelog

v1.1.1

🐛 Bug Fix

Fixed CommonJS/ESM Dual-Package Exports (#14)

Fixed package.json exports configuration to properly support both CommonJS and ESM module systems.

Changes:

• main now points to ./dist/index.cjs (CommonJS entry)
• module now points to ./dist/index.js (ESM entry)
• exports.require now points to ./dist/index.cjs
• exports.import now points to ./dist/index.js

Impact:

• ✅ Fixes compatibility with CommonJS projects (like MSR) that use require()
• ✅ Maintains full ESM support for modern projects using import
• ✅ Both module systems now work seamlessly

Testing:

• Verified CommonJS: require('auto-envparse') loads dist/index.cjs
• Verified ESM: import parseEnv from 'auto-envparse' loads dist/index.js

---

Full Changelog: v1.1.0...v1.1.1

v1.1.0

🎉 What's New in v1.1.0

⚠️ Breaking Changes

API Refactoring:

• Default export renamed: autoEnv() → parseEnv()
• Utility functions: Now accessed via AutoEnv class instead of named exports

Migration guide:

1. Replace import autoEnv with import parseEnv
2. Replace autoEnv(...) calls with parseEnv(...)
3. Replace named utility imports with AutoEnv.* access pattern
4. The parse alias continues to work

✨ Added

• Optional prefix parameter - Parse without prefixes (e.g., HOST instead of APP_HOST)
• createFrom() function - Create and populate class instances in one step
• enumValidator() helper - Enum validation with case-sensitive/insensitive options
• Prefix validation - Validates prefix format (uppercase letters and numbers only)
• Defensive error checking - Descriptive errors for invalid inputs

🚀 Improved

• Deep cloning in loadNestedFromEnv - Prevents mutation of default values
• Cross-realm object detection - New isPlainObject() helper for iframe/VM boundaries
• Enhanced toSnakeCase - Handles consecutive capitals (XMLParser → xml_parser)
• Recursive applyComplexObject - Supports deeply nested class instances
• JSON validation - Validates parsed JSON before mutation

🐛 Fixed

• Edge case handling for complex objects with empty prefix
• Shallow copy bug causing reference sharing in loadNestedFromEnv

📊 Stats

• 79 tests with 100% coverage
• Redesigned README with emoji headers
• Comprehensive API docs

---

Full Changelog: v1.0.0...v1.1.0

v1.0.0 - Initial Release

auto-envparse v1.0.0 🎉

First stable release of auto-envparse - a zero-configuration environment variable parsing library using reflection and type inference.

🌟 Features

• Zero Configuration: No schemas, validators, or manual mapping required
• Type Inference: Automatically detects types from default values
• Type Coercion: Converts strings to numbers, booleans, arrays
• Nested Objects: Supports dot-notation for nested configuration
• Custom Overrides: Optional custom parsing logic for complex cases
• Zero Dependencies: Lightweight and production-ready
• TypeScript: Full type safety with generics
• Dual Package: CJS + ESM support

📦 Installation

npm install auto-envparse

🚀 Quick Start

import autoEnv from 'auto-envparse';

const config = {
  host: 'localhost',
  port: 5432,
  ssl: false
};

// DB_HOST, DB_PORT, DB_SSL environment variables will be parsed
autoEnv(config, 'DB');

console.log(config); // { host: 'example.com', port: 3306, ssl: true }

📚 Documentation

• README.md - Complete user guide
• API.md - Detailed API reference

📊 Package Stats

• Size: 8.5 kB (tarball), 46.2 kB (unpacked)
• Tests: 36 tests with 100% coverage
• Dependencies: Zero
• Node.js: >=18.0.0
• License: MIT

🔗 Links

• npm: https://www.npmjs.com/package/auto-envparse
• Repository: https://github.com/vlavrynovych/auto-envparse
• Issues: https://github.com/vlavrynovych/auto-envparse/issues

🙏 Credits

Created by Volodymyr Lavrynovych

Extracted from msr-core where it proved valuable enough to become a standalone package.