@adonisjs/env 4.0.0-1 → 4.0.0-2

package/README.md

@@ -25,7 +25,7 @@ import { EnvLoader } from '@adonisjs/env'
 const lookupPath = new URL('./', import.meta.url)
 const loader = new EnvLoader(lookupPath)
 
-const { envContents, currentEnvContents } = loader.load()
+const { envContents, currentEnvContents } = await loader.load()
 ```
 
 ### `envContents`
@@ -39,7 +39,7 @@ const { envContents, currentEnvContents } = loader.load()
 
 - The `currentEnvContents` contents are read from the `.env.[NODE_ENV]` file. 
 - If the current `NODE_ENV = 'development'`, then the contents of this variable will be from the `.env.development` file and so on.
-- The contents of this file should precede the `.env` file.
+- The contents of this file should take precendence over the `.env` file.
 
 ## EnvParser
 The `EnvParser` class is responsible for parsing the contents of the `.env` file(s) and converting them into an object.
@@ -49,7 +49,7 @@ import { EnvLoader, EnvParser } from '@adonisjs/env'
 
 const lookupPath = new URL('./', import.meta.url)
 const loader = new EnvLoader(lookupPath)
-const { envContents, currentEnvContents } = loader.load()
+const { envContents, currentEnvContents } = await loader.load()
 
 const envParser = new EnvParser(envContents)
 const currentEnvParser = new EnvParser(currentEnvContents)
@@ -60,6 +60,12 @@ console.log(currentEnvParser.parse()) // { key: value }
 
 The return value of `parser.parse` is an object with key-value pair. The parser also has support for interpolation.
 
+You can also instruct the parser to prefer existing `process.env` values when they exist. When `preferProcessEnv` is set to `true`, the value from the env contents will be discarded in favor of existing `process.env` value.
+
+```ts
+new EnvParser(envContents, { preferProcessEnv: true })
+```
+
 ## Validating environment variables
 Once you have the parsed objects, you can optionally validate them against a pre-defined schema. We recommend validation for the following reasons.
 
@@ -91,10 +97,19 @@ import { EnvLoader, EnvParser, Env } from '@adonisjs/env'
 
 const lookupPath = new URL('./', import.meta.url)
 const loader = new EnvLoader(lookupPath)
-const { envContents, currentEnvContents } = loader.load()
+const { envContents, currentEnvContents } = await loader.load()
 
-const envValues = new EnvParser(envContents).parse()
+/**
+ * Loop over all the current env parsed values and let
+ * them take precedence over the existing process.env
+ * values.
+ */
 const currentEnvValues = new EnvParser(currentEnvContents).parse()
+Object.keys(currentEnvValues).forEach((key) => {
+  process.env[key] = currentEnvValues[key]
+})
+
+const envValues = new EnvParser(envContents, { preferProcessEnv: true }).parse()
 
 /**
  * Loop over all the parsed env values and set
@@ -112,15 +127,6 @@ Object.keys(envValues).forEach((key) => {
   }
 })
 
-/**
- * Loop over all the current env parsed values and make
- * them take precedence over the existing process.env
- * values.
- */
-Object.keys(currentEnvValues).forEach((key) => {
-  process.env[key] = envValues[key]
-})
-
 // Now perform the validation
 const validate = Env.rules({
   PORT: Env.schema.number(),

package/build/src/parser.d.ts

@@ -1,6 +1,8 @@
 import { DotenvParseOutput } from 'dotenv';
 export declare class EnvParser {
     #private;
-    constructor(envContents: string);
+    constructor(envContents: string, options?: {
+        preferProcessEnv: boolean;
+    });
     parse(): DotenvParseOutput;
 }

package/build/src/parser.js

@@ -1,14 +1,21 @@
 import dotenv from 'dotenv';
 export class EnvParser {
     #envContents;
-    constructor(envContents) {
+    #preferProcessEnv = false;
+    constructor(envContents, options) {
+        if (options?.preferProcessEnv) {
+            this.#preferProcessEnv = true;
+        }
         this.#envContents = envContents;
     }
     #getValue(key, parsed) {
+        if (this.#preferProcessEnv && process.env[key]) {
+            return process.env[key];
+        }
         if (parsed[key]) {
             return this.#interpolate(parsed[key], parsed);
         }
-        return '';
+        return process.env[key] || '';
     }
     #interpolateMustache(token, parsed) {
         const closingBrace = token.indexOf('}');
@@ -53,7 +60,7 @@ export class EnvParser {
     parse() {
         const envCollection = dotenv.parse(this.#envContents.trim());
         return Object.keys(envCollection).reduce((result, key) => {
-            result[key] = this.#interpolate(envCollection[key], envCollection);
+            result[key] = this.#getValue(key, envCollection);
             return result;
         }, {});
     }

package/build/src/validator.js

@@ -7,18 +7,18 @@ export class EnvValidator {
         this.#error = new InvalidEnvVariablesException();
     }
     validate(values) {
-        const help = [];
+        const cause = [];
         const validated = Object.keys(this.#schema).reduce((result, key) => {
             try {
                 result[key] = this.#schema[key](key, values[key]);
             }
             catch (error) {
-                help.push(`- ${error.message}`);
+                cause.push(`- ${error.message}`);
             }
             return result;
         }, { ...values });
-        if (help.length) {
-            this.#error.help = help.join('\n');
+        if (cause.length) {
+            this.#error.cause = cause.join('\n');
             throw this.#error;
         }
         return validated;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonisjs/env",
-  "version": "4.0.0-1",
+  "version": "4.0.0-2",
   "description": "Environment variable manager for Node.js",
   "main": "build/index.js",
   "type": "module",