nestjs-env-getter 1.0.0-beta.2 → 1.0.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2026-01-17
+
+### Added
+
+- **Custom .env Parser**: Replaced `dotenv` dependency with a robust, custom-built parser.
+  - Full support for multiline strings (e.g., private keys).
+  - Variable interpolation/expansion (e.g., `APP_URL=${HOST}:${PORT}`).
+  - Detection of circular variable references.
+  - Detailed error reporting for malformed lines and unterminated quotes.
+  - Support for `export` prefix and miscellaneous quoting styles (single/double).
+
+### Changed
+
+- **Dependency Removal**: Removed `dotenv` to reduce external dependencies and control parsing logic directly.
+- **Example Project**: Updated `nestjs-server` example to demonstrate new parser features and diverse variable types.
+
+## [1.0.0-beta.3] - 2025-11-26
+
+### Added
+
+- Improved file watcher resilience: re-establishes the file watcher after each successful update to handle atomic file replacements (e.g., Vault Agent credential rotations).
+
+### Changed
+
+- Increased default `debounceMs` from `200` to `350` ms to reduce noisy re-parses on rapid file updates.
+- Documentation and unit tests updated to cover file replacement and re-establishment behavior.
+
 ## [1.0.0-beta.2] - 2025-10-17
 
 ### Added

package/README.md

@@ -8,9 +8,22 @@
 - **Built-in Validation**: Validate variables against allowed values or use custom validation functions.
 - **Required vs. Optional**: Clearly distinguish between required variables that terminate the process if missing and optional ones with default values.
 - **Error Handling**: Automatically terminates the process with a descriptive error message if a required variable is missing or invalid.
-- **`.env` Support**: Automatically loads environment variables from a `.env` file using `dotenv`.
+- **`.env` Support**: Built-in parser with variable interpolation, multiline strings, and system env priority.
 - **Configuration Scaffolding**: Includes a CLI helper to quickly set up a centralized configuration file.
 
+## Environment File Parsing
+
+The module includes a zero-dependency `.env` file parser. Key behaviors:
+
+- **System environment priority**: Variables already set in `process.env` are NOT overwritten by `.env` file values. This ensures CI/CD and Docker environment injections take precedence over local files.
+- **Variable interpolation**: Use `${VAR_NAME}` syntax to reference other variables.
+- **Quoting rules**:
+  - **Unquoted**: Value ends at `#` (comment) or end of line.
+  - **Single quotes** (`'`): Raw literal, no escape processing.
+  - **Double quotes** (`"`): Supports `\n`, `\t`, `\\`, `\"` escapes and multiline values.
+- **`export` prefix**: Automatically stripped for shell compatibility.
+- **Empty values**: `KEY=` results in an empty string (not undefined).
+
 ## Installation
 
 ```bash
@@ -272,7 +285,7 @@ Load and validate configuration from JSON files with automatic file watching and
     { enabled: false },
   );
 
-  // Custom debounce timing (default is 200ms)
+  // Custom debounce timing (default is 350ms)
   const config = this.envGetter.getRequiredConfigFromFile(
     "config.json",
     undefined,
@@ -381,14 +394,14 @@ When the file watcher detects changes, it updates the **same object instance** i
 **File Watcher Options:**
 
 - `enabled` (boolean, default: `true`): Enable or disable automatic file watching
-- `debounceMs` (number, default: `200`): Delay in milliseconds before re-reading the file after a change
+- `debounceMs` (number, default: `350`): Delay in milliseconds before re-reading the file after a change
 
 **Features:**
 
 - ✅ Supports both absolute and relative paths (relative to `process.cwd()`)
 - ✅ Automatic JSON parsing and validation
 - ✅ **Hot-reload with reference preservation** - updates existing object instances in-place
-- ✅ File watching with automatic change detection
+- ✅ File watching with automatic change detection and file replacement support (e.g., Vault agent flow)
 - ✅ Debouncing to prevent excessive re-reads
 - ✅ Class-based validation with constructor pattern
 - ✅ **Graceful error handling for optional configs** - missing files or JSON parsing errors return default values

package/dist/app-config/app-config.module.d.ts

@@ -1,9 +1,9 @@
-import { DynamicModule, Provider, Type, InjectionToken, OptionalFactoryDependency } from "@nestjs/common";
+import { DynamicModule, Provider, Type, InjectionToken, OptionalFactoryDependency, ModuleMetadata } from "@nestjs/common";
 export interface AppConfigModuleOptions {
     useClass?: Type<unknown>;
     useFactory?: (...args: unknown[]) => unknown;
     inject?: (InjectionToken | OptionalFactoryDependency)[];
-    imports?: any[];
+    imports?: ModuleMetadata["imports"];
     providers?: Provider[];
 }
 export declare class AppConfigModule {

package/dist/env-getter/env-getter.service.d.ts

@@ -345,6 +345,7 @@ export declare class EnvGetterService implements OnModuleDestroy {
      * Sets up a file watcher for a configuration file.
      * - Watches for file changes and automatically re-reads and updates the cached config.
      * - Applies debouncing to avoid excessive re-reads.
+     * - Re-establishes the watcher after each successful update to handle file replacements (e.g., Vault agent flow).
      * - Emits 'updated' or 'error' events on re-parse.
      * @param filePath - The absolute path to the config file.
      * @param cls - (Optional) A class constructor to validate and instantiate the parsed config.

package/dist/env-getter/env-getter.service.js

@@ -10,7 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnvGetterService = void 0;
-const dotenv_1 = require("dotenv");
+const utils_1 = require("../shared/utils");
 const events_1 = require("events");
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -34,11 +34,11 @@ let EnvGetterService = class EnvGetterService {
      */
     safeObjectCopy(source) {
         const copy = Object.create(null);
-        Object.keys(source)
-            .filter((key) => !this.isUnsafeKey(key))
-            .forEach((key) => {
-            copy[key] = source[key];
-        });
+        for (const key of Object.keys(source)) {
+            if (!this.isUnsafeKey(key)) {
+                copy[key] = source[key];
+            }
+        }
         return copy;
     }
     constructor() {
@@ -49,7 +49,7 @@ let EnvGetterService = class EnvGetterService {
          * Emits 'updated' and 'error' events globally for all config files.
          */
         this.events = new events_1.EventEmitter();
-        (0, dotenv_1.config)({ quiet: true });
+        (0, utils_1.loadEnvFile)(".env", { quiet: true });
     }
     /**
      * Lifecycle hook called when the module is being destroyed.
@@ -434,8 +434,8 @@ let EnvGetterService = class EnvGetterService {
      */
     stopProcess(message) {
         // eslint-disable-next-line no-console
-        console.log("\x1b[31m%s\x1b[0m", message);
-        process.exit(1);
+        console.error(`\x1b[31m${message}\x1b[0m`);
+        throw new Error(message);
     }
     /**
      * Checks if an environment variable exists.
@@ -599,6 +599,7 @@ let EnvGetterService = class EnvGetterService {
      * Sets up a file watcher for a configuration file.
      * - Watches for file changes and automatically re-reads and updates the cached config.
      * - Applies debouncing to avoid excessive re-reads.
+     * - Re-establishes the watcher after each successful update to handle file replacements (e.g., Vault agent flow).
      * - Emits 'updated' or 'error' events on re-parse.
      * @param filePath - The absolute path to the config file.
      * @param cls - (Optional) A class constructor to validate and instantiate the parsed config.
@@ -610,20 +611,43 @@ let EnvGetterService = class EnvGetterService {
         var _a, _b, _c;
         const watcherOptions = {
             enabled: (_a = options === null || options === void 0 ? void 0 : options.enabled) !== null && _a !== void 0 ? _a : true,
-            debounceMs: (_b = options === null || options === void 0 ? void 0 : options.debounceMs) !== null && _b !== void 0 ? _b : 200,
+            debounceMs: (_b = options === null || options === void 0 ? void 0 : options.debounceMs) !== null && _b !== void 0 ? _b : 350,
             breakOnError: (_c = options === null || options === void 0 ? void 0 : options.breakOnError) !== null && _c !== void 0 ? _c : true,
         };
-        if (!watcherOptions.enabled || this.fileWatchers.has(filePath))
+        if (!watcherOptions.enabled)
             return;
+        // Close existing watcher if present (for re-establishment)
+        const existingWatcher = this.fileWatchers.get(filePath);
+        if (existingWatcher) {
+            existingWatcher.close();
+            this.fileWatchers.delete(filePath);
+        }
         let debounceTimer = null;
         const watcher = (0, fs_1.watch)(filePath, (eventType) => {
-            if (eventType === "change") {
+            // Handle both "change" and "rename" events to catch file replacements
+            if (eventType === "change" || eventType === "rename") {
                 if (debounceTimer)
                     clearTimeout(debounceTimer);
                 debounceTimer = setTimeout(() => {
+                    // Verify file still exists before attempting to read
+                    if (!(0, fs_1.existsSync)(filePath)) {
+                        // File was deleted, emit error event
+                        const errorEvent = {
+                            filePath,
+                            error: new Error(`Config file '${filePath}' was deleted`),
+                            timestamp: Date.now(),
+                        };
+                        this.events.emit(`error:${filePath}`, errorEvent);
+                        return;
+                    }
                     try {
                         // Re-parse the config (isInitialLoad = false, with breakOnError setting)
                         this.readAndParseConfigFile(filePath, cls, false, watcherOptions.breakOnError, isOptional);
+                        // Close the old watcher
+                        watcher.close();
+                        this.fileWatchers.delete(filePath);
+                        // Re-establish the watcher to handle file replacement scenarios (e.g., Vault agent)
+                        this.setupFileWatcher(filePath, cls, options, isOptional);
                         // Emit file-specific success event
                         const event = {
                             filePath,

package/dist/env-getter/types/file-watcher-options.type.d.ts

@@ -9,7 +9,7 @@ export type FileWatcherOptions = {
     enabled?: boolean;
     /**
      * Debounce delay in milliseconds before re-reading the file after a change is detected.
-     * @default 200
+     * @default 350
      */
     debounceMs?: number;
     /**

package/dist/shared/utils/env-parser/env-parser.utils.d.ts

@@ -0,0 +1,41 @@
+import { type EnvParseOptions, type EnvParseResult } from "./types";
+/**
+ * Parses environment variables from a string.
+ * @param content - The .env file content as a string.
+ * @param options - Parsing options.
+ * @returns An {@link EnvParseResult} containing parsed variables, errors, and success flag.
+ * @throws {Error} If parsing fails and options.accumulate is false.
+ */
+export declare function parseEnvString(content: string, options?: EnvParseOptions): EnvParseResult;
+/**
+ * Parses a single .env file.
+ * @param filePath - Path to the .env file.
+ * @param options - Parsing options.
+ * @returns An {@link EnvParseResult} with variables, errors, and success status.
+ * @throws {Error} If file is missing or reading fails and options.accumulate is false.
+ */
+export declare function parseEnvFile(filePath: string, options?: EnvParseOptions): EnvParseResult;
+/**
+ * Parses multiple .env files with cascading priority (later files override earlier ones).
+ * @param filePaths - Array of .env file paths in order of priority, last wins.
+ * @param options - Parsing options.
+ * @returns Combined {@link EnvParseResult} from all files.
+ * @throws {Error} If any file parsing fails and options.accumulate is false.
+ */
+export declare function parseEnvFiles(filePaths: string[], options?: EnvParseOptions): EnvParseResult;
+/**
+ * Loads environment variables from a .env file into `process.env`.
+ * By default, existing system environment variables take precedence (they are NOT overwritten).
+ * Use `{ override: true }` to force overwrite.
+ * @param filePath - Path to the .env file (defaults to `.env`).
+ * @param options - Parsing and loading options.
+ * @throws {Error} If parsing fails and options.accumulate is false.
+ */
+export declare function loadEnvFile(filePath?: string, options?: EnvParseOptions): void;
+/**
+ * Loads multiple .env files into `process.env` with cascading priority.
+ * @param filePaths - Array of .env file paths.
+ * @param options - Parsing and loading options.
+ * @throws {Error} If any file parsing fails and options.accumulate is false.
+ */
+export declare function loadEnvFiles(filePaths: string[], options?: EnvParseOptions): void;

package/dist/shared/utils/env-parser/env-parser.utils.js

@@ -0,0 +1,442 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvString = parseEnvString;
+exports.parseEnvFile = parseEnvFile;
+exports.parseEnvFiles = parseEnvFiles;
+exports.loadEnvFile = loadEnvFile;
+exports.loadEnvFiles = loadEnvFiles;
+const fs_1 = require("fs");
+/**
+ * Regular expression to validate environment variable keys.
+ * Keys must start with a letter or underscore, followed by alphanumeric characters or underscores.
+ */
+const KEY_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+// Variable interpolation pattern: ${VAR_NAME}
+const INTERPOLATION_REGEX = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+/**
+ * Creates an {@link EnvParseError} object.
+ * @param lineNumber - The line number where the error occurred.
+ * @param rawContent - The raw line content.
+ * @param message - Human‑readable error message.
+ * @param type - The type of parsing error.
+ * @returns An {@link EnvParseError} instance.
+ */
+function createError(lineNumber, rawContent, message, type) {
+    return { lineNumber, rawContent, message, type };
+}
+/**
+ * Processes escape sequences in double-quoted strings.
+ * @param value - The raw string containing escape sequences.
+ * @returns The string with escape sequences interpreted.
+ */
+function processEscapes(value) {
+    let result = "";
+    let i = 0;
+    while (i < value.length) {
+        if (value[i] === "\\" && i + 1 < value.length) {
+            const next = value[i + 1];
+            switch (next) {
+                case "n":
+                    result += "\n";
+                    i += 2;
+                    break;
+                case "t":
+                    result += "\t";
+                    i += 2;
+                    break;
+                case "r":
+                    result += "\r";
+                    i += 2;
+                    break;
+                case "\\":
+                    result += "\\";
+                    i += 2;
+                    break;
+                case '"':
+                    result += '"';
+                    i += 2;
+                    break;
+                default:
+                    // Unknown escape, keep as-is
+                    result += value[i];
+                    i += 1;
+            }
+        }
+        else {
+            result += value[i];
+            i += 1;
+        }
+    }
+    return result;
+}
+/**
+ * Detects circular references during variable interpolation.
+ * @param varName - The variable name being resolved.
+ * @param resolutionStack - Set of variable names already in the resolution chain.
+ * @returns An error message if a circular reference is found, otherwise null.
+ */
+function detectCircularReference(varName, resolutionStack) {
+    if (resolutionStack.has(varName)) {
+        return `Circular reference detected: ${[...resolutionStack, varName].join(" -> ")}`;
+    }
+    return null;
+}
+/**
+ * Expands variable interpolation in a value.
+ * Uses a two‑pass strategy: first checks local variables, then system environment variables.
+ * @param value - The string value to expand.
+ * @param variables - Map of local variables defined in the .env file.
+ * @param systemEnv - System environment variables.
+ * @param resolutionStack - Set tracking variables already visited to detect cycles.
+ * @param quiet - If true, suppresses warnings for undefined variables.
+ * @returns An object containing the expanded result and optionally a circular reference error.
+ */
+function expandVariables(value, variables, systemEnv, resolutionStack = new Set(), quiet = false) {
+    let result = value;
+    let match;
+    const regex = new RegExp(INTERPOLATION_REGEX.source, "g");
+    while ((match = regex.exec(value)) !== null) {
+        const fullMatch = match[0];
+        const varName = match[1];
+        if (!varName)
+            continue;
+        // Check for circular reference
+        const circularError = detectCircularReference(varName, resolutionStack);
+        if (circularError) {
+            return { result: value, circularError };
+        }
+        // Lookup order: local variables first, then system env
+        let replacement;
+        if (varName in variables) {
+            // Recursively expand the referenced variable
+            const newStack = new Set(resolutionStack);
+            newStack.add(varName);
+            const expanded = expandVariables(variables[varName], variables, systemEnv, newStack, quiet);
+            if (expanded.circularError) {
+                return expanded;
+            }
+            replacement = expanded.result;
+        }
+        else if (varName in systemEnv && systemEnv[varName] !== undefined) {
+            replacement = systemEnv[varName];
+        }
+        else {
+            // Variable not found - leave as empty string
+            if (!quiet) {
+                // eslint-disable-next-line no-console
+                console.warn(`[env-parser] Warning: Variable '${varName}' is not defined`);
+            }
+            replacement = "";
+        }
+        result = result.replace(fullMatch, replacement);
+    }
+    return { result };
+}
+/**
+ * Parses a single line from a .env file and extracts a key‑value pair.
+ * Returns `null` for comments or empty lines.
+ * @param line - The raw line text.
+ * @param lineNumber - The line number in the file (1‑based).
+ * @param buffer - Current multiline buffer state, if any.
+ * @returns An object describing the parsed result, any errors, and buffer state.
+ */
+function parseLine(line, lineNumber, buffer) {
+    var _a, _b, _c, _d;
+    // If we're in multiline mode, continue accumulating
+    if (buffer) {
+        if (buffer.quoteChar === "'") {
+            const closingIndex = line.indexOf("'");
+            if (closingIndex !== -1) {
+                // Found closing single quote
+                buffer.value += "\n" + line.substring(0, closingIndex);
+                return { key: buffer.key, value: buffer.value, isComplete: true, buffer: null };
+            }
+        }
+        else if (buffer.quoteChar === '"') {
+            // Double-quoted multiline - scan for non-escaped quote
+            let i = 0;
+            let collected = "";
+            while (i < line.length) {
+                if (line[i] === "\\" && i + 1 < line.length) {
+                    // Preserve escape sequence
+                    collected += ((_a = line[i]) !== null && _a !== void 0 ? _a : "") + ((_b = line[i + 1]) !== null && _b !== void 0 ? _b : "");
+                    i += 2;
+                }
+                else if (line[i] === '"') {
+                    // Found closing double quote
+                    buffer.value += "\n" + collected;
+                    return { key: buffer.key, value: processEscapes(buffer.value), isComplete: true, buffer: null };
+                }
+                else {
+                    collected += line[i];
+                    i++;
+                }
+            }
+            // Not found on this line, append entire line (literal including escapes)
+            buffer.value += "\n" + line;
+            return { isComplete: false, buffer };
+        }
+        // Continue accumulating for other cases (should be handled above but for safety)
+        buffer.value += "\n" + line;
+        return { isComplete: false, buffer };
+    }
+    // Trim leading whitespace (but preserve for error reporting)
+    const trimmedLine = line.trimStart();
+    // Skip empty lines and full-line comments
+    if (!trimmedLine || trimmedLine.startsWith("#")) {
+        return { isComplete: true, buffer: null };
+    }
+    // Strip 'export ' prefix if present
+    let workingLine = trimmedLine;
+    if (workingLine.startsWith("export ")) {
+        workingLine = workingLine.substring(7).trimStart();
+    }
+    // Find the equals sign
+    const equalsIndex = workingLine.indexOf("=");
+    if (equalsIndex === -1) {
+        return {
+            isComplete: true,
+            buffer: null,
+            error: createError(lineNumber, line, `Line ${lineNumber}: Missing '=' in assignment`, "MALFORMED_LINE"),
+        };
+    }
+    // Extract key and validate
+    const key = workingLine.substring(0, equalsIndex).trim();
+    if (!KEY_REGEX.test(key)) {
+        return {
+            isComplete: true,
+            buffer: null,
+            error: createError(lineNumber, line, `Line ${lineNumber}: Invalid key '${key}'. Keys must start with a letter or underscore and contain only alphanumeric characters and underscores.`, "INVALID_KEY"),
+        };
+    }
+    // Extract raw value (everything after =)
+    let rawValue = workingLine.substring(equalsIndex + 1);
+    // Determine value type based on first character
+    const firstChar = rawValue.charAt(0);
+    if (firstChar === "'") {
+        // Single-quoted value - raw literal
+        const closingIndex = rawValue.indexOf("'", 1);
+        if (closingIndex === -1) {
+            // Check if it's multiline or unterminated
+            return {
+                isComplete: false,
+                buffer: { key, value: rawValue.substring(1), quoteChar: "'", startLine: lineNumber },
+            };
+        }
+        const value = rawValue.substring(1, closingIndex);
+        return { key, value, isComplete: true, buffer: null };
+    }
+    else if (firstChar === '"') {
+        // Double-quoted value - supports escapes
+        // Find the closing quote, accounting for escaped quotes
+        let i = 1;
+        let value = "";
+        let foundClosing = false;
+        while (i < rawValue.length) {
+            if (rawValue[i] === "\\" && i + 1 < rawValue.length) {
+                // Escape sequence - keep it for later processing
+                value += ((_c = rawValue[i]) !== null && _c !== void 0 ? _c : "") + ((_d = rawValue[i + 1]) !== null && _d !== void 0 ? _d : "");
+                i += 2;
+            }
+            else if (rawValue[i] === '"') {
+                foundClosing = true;
+                break;
+            }
+            else {
+                value += rawValue[i];
+                i += 1;
+            }
+        }
+        if (!foundClosing) {
+            // Multiline double-quoted string
+            return {
+                isComplete: false,
+                buffer: { key, value, quoteChar: '"', startLine: lineNumber },
+            };
+        }
+        // Process escape sequences
+        const processedValue = processEscapes(value);
+        return { key, value: processedValue, isComplete: true, buffer: null };
+    }
+    else {
+        // Unquoted value - trim whitespace and stop at comment
+        rawValue = rawValue.trim();
+        // Find inline comment (# not inside quotes)
+        const commentIndex = rawValue.indexOf("#");
+        if (commentIndex !== -1) {
+            rawValue = rawValue.substring(0, commentIndex).trimEnd();
+        }
+        return { key, value: rawValue, isComplete: true, buffer: null };
+    }
+}
+/**
+ * Parses environment variables from a string.
+ * @param content - The .env file content as a string.
+ * @param options - Parsing options.
+ * @returns An {@link EnvParseResult} containing parsed variables, errors, and success flag.
+ * @throws {Error} If parsing fails and options.accumulate is false.
+ */
+function parseEnvString(content, options = {}) {
+    var _a;
+    const { accumulate = false, systemEnv = process.env, quiet = false } = options;
+    // Normalize line endings
+    const normalizedContent = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    const lines = normalizedContent.split("\n");
+    const variables = {};
+    const errors = [];
+    let buffer = null;
+    for (let i = 0; i < lines.length; i++) {
+        const lineNumber = i + 1;
+        const line = lines[i];
+        const result = parseLine(line !== null && line !== void 0 ? line : "", lineNumber, buffer);
+        if (result.error) {
+            if (accumulate) {
+                errors.push(result.error);
+            }
+            else {
+                throw new Error(result.error.message);
+            }
+        }
+        if (result.isComplete && result.key !== undefined) {
+            variables[result.key] = (_a = result.value) !== null && _a !== void 0 ? _a : "";
+        }
+        buffer = result.buffer;
+    }
+    // Check for unterminated multiline string
+    if (buffer) {
+        const error = createError(buffer.startLine, `Started at line ${buffer.startLine}`, `Unterminated ${buffer.quoteChar === '"' ? "double" : "single"}-quoted string starting at line ${buffer.startLine}`, "UNTERMINATED_QUOTE");
+        if (accumulate) {
+            errors.push(error);
+        }
+        else {
+            throw new Error(error.message);
+        }
+    }
+    // Second pass: variable interpolation
+    const expandedVariables = {};
+    for (const [key, value] of Object.entries(variables)) {
+        const { result, circularError } = expandVariables(value, variables, systemEnv, new Set([key]), quiet);
+        if (circularError) {
+            const error = createError(0, key, circularError, "CIRCULAR_REFERENCE");
+            if (accumulate) {
+                errors.push(error);
+                expandedVariables[key] = value; // Keep original value on error
+            }
+            else {
+                throw new Error(error.message);
+            }
+        }
+        else {
+            expandedVariables[key] = result;
+        }
+    }
+    return {
+        variables: expandedVariables,
+        errors,
+        success: errors.length === 0,
+    };
+}
+/**
+ * Parses a single .env file.
+ * @param filePath - Path to the .env file.
+ * @param options - Parsing options.
+ * @returns An {@link EnvParseResult} with variables, errors, and success status.
+ * @throws {Error} If file is missing or reading fails and options.accumulate is false.
+ */
+function parseEnvFile(filePath, options = {}) {
+    if (!(0, fs_1.existsSync)(filePath)) {
+        const error = createError(0, filePath, `File not found: ${filePath}`, "FILE_READ_ERROR");
+        if (options.accumulate) {
+            return { variables: {}, errors: [error], success: false };
+        }
+        throw new Error(error.message);
+    }
+    try {
+        const content = (0, fs_1.readFileSync)(filePath, "utf-8");
+        return parseEnvString(content, options);
+    }
+    catch (err) {
+        // parseEnvString throws for all parse errors (unterminated quotes, invalid keys, etc.)
+        if (err instanceof Error) {
+            // Check if this is a file-system error (not a parsing error)
+            const isFileSystemError = err.message.includes("ENOENT") ||
+                err.message.includes("EACCES") ||
+                err.message.includes("EPERM") ||
+                err.message.startsWith("Error reading file");
+            if (!isFileSystemError) {
+                throw err; // Re-throw parsing errors
+            }
+        }
+        const error = createError(0, filePath, `Error reading file ${filePath}: ${err instanceof Error ? err.message : String(err)}`, "FILE_READ_ERROR");
+        if (options.accumulate) {
+            return { variables: {}, errors: [error], success: false };
+        }
+        throw new Error(error.message);
+    }
+}
+/**
+ * Parses multiple .env files with cascading priority (later files override earlier ones).
+ * @param filePaths - Array of .env file paths in order of priority, last wins.
+ * @param options - Parsing options.
+ * @returns Combined {@link EnvParseResult} from all files.
+ * @throws {Error} If any file parsing fails and options.accumulate is false.
+ */
+function parseEnvFiles(filePaths, options = {}) {
+    const allVariables = {};
+    const allErrors = [];
+    for (const filePath of filePaths) {
+        if (!(0, fs_1.existsSync)(filePath)) {
+            continue; // Skip non-existent files in multi-file mode
+        }
+        const result = parseEnvFile(filePath, { ...options, accumulate: true });
+        // Merge variables (later files override)
+        Object.assign(allVariables, result.variables);
+        // Collect errors
+        allErrors.push(...result.errors);
+    }
+    if (!options.accumulate && allErrors.length > 0) {
+        throw new Error(allErrors[0].message);
+    }
+    return {
+        variables: allVariables,
+        errors: allErrors,
+        success: allErrors.length === 0,
+    };
+}
+/**
+ * Loads environment variables from a .env file into `process.env`.
+ * By default, existing system environment variables take precedence (they are NOT overwritten).
+ * Use `{ override: true }` to force overwrite.
+ * @param filePath - Path to the .env file (defaults to `.env`).
+ * @param options - Parsing and loading options.
+ * @throws {Error} If parsing fails and options.accumulate is false.
+ */
+function loadEnvFile(filePath = ".env", options = {}) {
+    const { override = false } = options;
+    if (!(0, fs_1.existsSync)(filePath)) {
+        // Silently skip if file doesn't exist (matches dotenv behavior)
+        return;
+    }
+    const result = parseEnvFile(filePath, options);
+    for (const [key, value] of Object.entries(result.variables)) {
+        // Respect immutable system env rule: don't overwrite existing vars unless override=true
+        if (override || !(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+}
+/**
+ * Loads multiple .env files into `process.env` with cascading priority.
+ * @param filePaths - Array of .env file paths.
+ * @param options - Parsing and loading options.
+ * @throws {Error} If any file parsing fails and options.accumulate is false.
+ */
+function loadEnvFiles(filePaths, options = {}) {
+    const { override = false } = options;
+    const result = parseEnvFiles(filePaths, options);
+    for (const [key, value] of Object.entries(result.variables)) {
+        if (override || !(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+}

package/dist/shared/utils/env-parser/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export { parseEnvString, parseEnvFile, parseEnvFiles, loadEnvFile, loadEnvFiles } from "./env-parser.utils";

package/dist/shared/utils/env-parser/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEnvFiles = exports.loadEnvFile = exports.parseEnvFiles = exports.parseEnvFile = exports.parseEnvString = void 0;
+__exportStar(require("./types"), exports);
+var env_parser_utils_1 = require("./env-parser.utils");
+Object.defineProperty(exports, "parseEnvString", { enumerable: true, get: function () { return env_parser_utils_1.parseEnvString; } });
+Object.defineProperty(exports, "parseEnvFile", { enumerable: true, get: function () { return env_parser_utils_1.parseEnvFile; } });
+Object.defineProperty(exports, "parseEnvFiles", { enumerable: true, get: function () { return env_parser_utils_1.parseEnvFiles; } });
+Object.defineProperty(exports, "loadEnvFile", { enumerable: true, get: function () { return env_parser_utils_1.loadEnvFile; } });
+Object.defineProperty(exports, "loadEnvFiles", { enumerable: true, get: function () { return env_parser_utils_1.loadEnvFiles; } });

package/dist/shared/utils/env-parser/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Options for parsing environment files.
+ */
+export interface EnvParseOptions {
+    /**
+     * If true, .env file values will override existing system environment variables.
+     * By default (false), system env takes precedence over .env file values.
+     * @default false
+     */
+    override?: boolean;
+    /**
+     * If true, collect all errors instead of throwing on first error.
+     * Useful for pre-flight validation of the entire file.
+     * @default false
+     */
+    accumulate?: boolean;
+    /**
+     * System environment variables to use for variable interpolation lookup.
+     * Defaults to process.env.
+     */
+    systemEnv?: Record<string, string | undefined>;
+    /**
+     * If true, suppress console warnings for undefined variable references.
+     * @default false
+     */
+    quiet?: boolean;
+}
+/**
+ * Represents a parsing error with context information.
+ */
+export interface EnvParseError {
+    /** Line number where the error occurred (1-indexed). */
+    lineNumber: number;
+    /** Raw content of the problematic line. */
+    rawContent: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Error type for programmatic handling. */
+    type: "UNTERMINATED_QUOTE" | "INVALID_KEY" | "MALFORMED_LINE" | "CIRCULAR_REFERENCE" | "FILE_READ_ERROR";
+}
+/**
+ * Result of parsing environment content.
+ */
+export interface EnvParseResult {
+    /** Parsed environment variables as key-value pairs. */
+    variables: Record<string, string>;
+    /** List of errors encountered during parsing (populated when accumulate=true). */
+    errors: EnvParseError[];
+    /** Whether parsing completed successfully (no errors). */
+    success: boolean;
+}

package/dist/shared/utils/env-parser/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/utils/index.d.ts

@@ -1 +1,2 @@
 export { isTimePeriod, parseTimePeriod } from "./time-period.utils";
+export * from "./env-parser";

package/dist/shared/utils/index.js

@@ -1,6 +1,21 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseTimePeriod = exports.isTimePeriod = void 0;
 var time_period_utils_1 = require("./time-period.utils");
 Object.defineProperty(exports, "isTimePeriod", { enumerable: true, get: function () { return time_period_utils_1.isTimePeriod; } });
 Object.defineProperty(exports, "parseTimePeriod", { enumerable: true, get: function () { return time_period_utils_1.parseTimePeriod; } });
+__exportStar(require("./env-parser"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "nestjs-env-getter",
-    "version": "1.0.0-beta.2",
+    "version": "1.0.0",
     "description": "Environment variables getter for Nestjs applications",
     "author": "Ivan Baha",
     "private": false,
@@ -37,28 +37,26 @@
     "peerDependencies": {
         "@nestjs/common": ">=9"
     },
-    "dependencies": {
-        "dotenv": "^17.2.3"
-    },
+    "dependencies": {},
     "devDependencies": {
-        "@eslint/js": "^9.26.0",
-        "@nestjs/cli": "^11.0.10",
-        "@nestjs/common": "^11.1.6",
-        "@nestjs/core": "^11.1.6",
-        "@nestjs/testing": "^11.1.6",
+        "@eslint/js": "^9.39.2",
+        "@nestjs/cli": "^11.0.16",
+        "@nestjs/common": "^11.1.12",
+        "@nestjs/core": "^11.1.12",
+        "@nestjs/testing": "^11.1.12",
         "@types/jest": "^30.0.0",
-        "@types/node": "^24.7.0",
-        "eslint": "^9.26.0",
-        "eslint-config-prettier": "^10.0.3",
-        "eslint-plugin-jsdoc": "^61.0.0",
-        "eslint-plugin-prettier": "^5.4.0",
-        "globals": "^16.1.0",
+        "@types/node": "^25.0.9",
+        "eslint": "^9.39.2",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-jsdoc": "^62.0.1",
+        "eslint-plugin-prettier": "^5.5.5",
+        "globals": "^17.0.0",
         "jest": "^30.2.0",
-        "prettier": "^3.5.3",
+        "prettier": "^3.8.0",
         "reflect-metadata": "^0.2.2",
         "rxjs": "^7.8.2",
-        "ts-jest": "^29.3.2",
-        "typescript": "^5.8.3",
-        "typescript-eslint": "^8.32.0"
+        "ts-jest": "^29.4.6",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.53.0"
     }
 }