Integrate auto-envparse library to replace EnvVarParser

[vlavrynovych]

Summary

Replace the internal EnvVarParser utility class with the published auto-envparse npm package (v1.1.0). The EnvVarParser was extracted into a standalone library and is now available on npm.

Package: https://www.npmjs.com/package/auto-envparse
Repository: https://github.com/vlavrynovych/auto-envparse

Motivation

The EnvVarParser functionality is valuable beyond MSR and has been published as a standalone, reusable library. Using the npm package:

• Eliminates code duplication
• Provides versioned, tested dependency
• Allows other projects to benefit from the same functionality
• Simplifies MSR maintenance (one less internal utility to maintain)

Scope

Changes Required

1. Add Dependency

   • Add auto-envparse@^1.1.0 to package.json dependencies

2. Remove Internal Implementation

   • Delete src/util/EnvVarParser.ts (implementation now in npm package)
   • Update src/util/index.ts to remove EnvVarParser export

3. Update ConfigLoader

   • Replace local import with package import in src/util/ConfigLoader.ts
   • Update API calls to match auto-envparse API (see API Mapping below)

4. Update Documentation

   • Update /docs/guides/environment-variables.md to mention MSR uses auto-envparse library
   • Add note that EnvVarParser is now available as standalone package
   • Update API documentation if needed

5. Verify Tests

   • Keep test/unit/util/EnvVarParser.test.ts as integration test
   • Ensure all existing tests pass (verifies auto-envparse works correctly in MSR)
   • Update test imports to use auto-envparse
   • Update test/unit/util/UtilIndex.test.ts to reflect removed export

API Mapping

The auto-envparse API has been simplified and renamed:

Main Parsing Method

Before (MSR EnvVarParser):

import { EnvVarParser } from '../util/EnvVarParser';

// Parse environment variables into config object
EnvVarParser.parse(config, 'MSR', overrides);

After (auto-envparse):

import parseEnv, { parse } from 'auto-envparse';

// Option 1: Use default export
parseEnv(config, 'MSR', overrides);

// Option 2: Use named export (shorter)
parse(config, 'MSR', overrides);

Nested Object Loading

Before:

const logging = EnvVarParser.loadNestedFromEnv('MSR_LOGGING', {
    enabled: false,
    path: './logs'
});

After:

// Use the same parse function with a separate config object
const logging = {
    enabled: false,
    path: './logs'
};
parse(logging, 'MSR_LOGGING');

Utility Functions

Before:

EnvVarParser.coerceValue(value, 'boolean');
EnvVarParser.parseBoolean(value);
EnvVarParser.parseNumber(value);
EnvVarParser.toSnakeCase(str);

After:

// These were internal utilities and are not exposed in auto-envparse
// Use the main parse() function instead, which handles coercion automatically
parse(config, prefix);

Enum Validation (New Feature)

New in auto-envparse:

import { enumValidator } from 'auto-envparse';

const overrides = new Map();
overrides.set('environment', enumValidator('environment', 
    ['development', 'staging', 'production'],
    { caseSensitive: false }
));

parse(config, 'APP', overrides);

Class Instance Creation (New Feature)

New in auto-envparse:

import { createFrom } from 'auto-envparse';

class DatabaseConfig {
    host = 'localhost';
    port = 5432;
    ssl = false;
}

const dbConfig = createFrom(DatabaseConfig, 'DB');

Testing Strategy

1. Keep Existing Tests

   • test/unit/util/EnvVarParser.test.ts remains as integration test
   • Update imports to use auto-envparse package
   • Verify all 17+ tests continue passing

2. API Changes in Tests

   • Replace EnvVarParser.parse() with parse() from auto-envparse
   • Replace EnvVarParser.loadNestedFromEnv() with separate config + parse()
   • Remove tests for internal utility methods (coerceValue, parseBoolean, etc.) - these are internal to auto-envparse

3. Coverage Requirements

   • Maintain 100% coverage for ConfigLoader.ts
   • Integration test coverage maintained
   • All 1257+ MSR tests should pass

Files to Modify

Source Files

• package.json - Add auto-envparse@^1.1.0 dependency
• src/util/EnvVarParser.ts - DELETE (replaced by npm package)
• src/util/ConfigLoader.ts - Update imports and API calls
• src/util/index.ts - Remove EnvVarParser export

Test Files

• test/unit/util/EnvVarParser.test.ts - Update imports and API calls
• test/unit/util/UtilIndex.test.ts - Remove EnvVarParser export test

Documentation

• /docs/guides/environment-variables.md - Add note about auto-envparse library
• /docs/api/ConfigLoader.md - Update if EnvVarParser was mentioned

ConfigLoader Changes Example

Before:

import { EnvVarParser } from './EnvVarParser';

protected autoApplyEnvironmentVariables(
    config: C,
    prefix: string,
    overrides?: Map<string, (config: C, envVarName: string) => void>
): void {
    EnvVarParser.parse(config, prefix, overrides);
}

After:

import { parse } from 'auto-envparse';

protected autoApplyEnvironmentVariables(
    config: C,
    prefix: string,
    overrides?: Map<string, (config: C, envVarName: string) => void>
): void {
    parse(config, prefix, overrides);
}

Success Criteria

• auto-envparse@^1.1.0 added to dependencies
• src/util/EnvVarParser.ts deleted
• ConfigLoader uses auto-envparse successfully
• All existing tests pass (1257+ tests)
• 100% code coverage maintained
• Documentation updated
• npm install works without errors
• npm test works without errors
• Build succeeds

Breaking Changes

None. This is an internal implementation change. The public API of MSR (ConfigLoader, adapters, etc.) remains unchanged.

Dependencies

New Dependency:

• auto-envparse@^1.1.0 (production dependency)

Zero additional transitive dependencies - auto-envparse has zero dependencies.

Related

• Original implementation: Automate environment variable parsing using config object structure #126 (Automatic environment variable parsing)
• Extraction decision made during v0.7.0 planning
• Package published: https://www.npmjs.com/package/auto-envparse
• Repository: https://github.com/vlavrynovych/auto-envparse

Notes

• The auto-envparse package was extracted from MSR's EnvVarParser with API improvements
• Main API simplified: parse(config, prefix, overrides) replaces all methods
• Package adds new features: createFrom() for class instances, enumValidator() helper
• Package is battle-tested with 100% test coverage and full TypeScript support
• Package follows 12-Factor App principles for configuration
• API is simpler and more intuitive than the original EnvVarParser

[vlavrynovych]

Successfully integrated auto-envparse@1.1.1 to replace internal EnvVarParser utility.

Summary

Replaced the internal EnvVarParser utility with the standalone auto-envparse npm package. The internal implementation was previously extracted and published for broader reuse.

Key Changes

• ✅ Added auto-envparse@^1.1.1 as production dependency
• ✅ Updated ConfigLoader to import parse() directly from auto-envparse
• ✅ Deleted src/util/EnvVarParser.ts (now provided by npm package)
• ✅ Removed EnvVarParser from public exports
• ✅ Fixed test prefixes (TEST_DB → TESTDB) to comply with auto-envparse validation
• ✅ Updated documentation to reference standalone package
• ✅ Added Node.js engine requirement (>=20.0.0) to match auto-envparse

Additional Improvements

• Added GitHub Actions workflow for testing on Node 20.x and 22.x
• Added GitHub Actions test badge to README.md
• Improved CircleCI configuration (npm ci + package-lock.json caching)
• Fixed test:mocha:report script to only run test files

Test Results

• All 1246 tests passing ✅
• 100% code coverage maintained across all metrics ✅
• No regressions in functionality

Breaking Changes

EnvVarParser is no longer exported from src/util/index.ts. This was an internal utility and not part of the main public API.

Note: Initial integration with auto-envparse@1.1.0 (ESM) caused module loading issues in CircleCI. This was resolved by updating auto-envparse to v1.1.1 which provides proper CommonJS support.