@adonisjs/env 4.0.0-1 → 4.0.1-0

package/README.md

@@ -25,21 +25,22 @@ import { EnvLoader } from '@adonisjs/env'
 const lookupPath = new URL('./', import.meta.url)
 const loader = new EnvLoader(lookupPath)
 
-const { envContents, currentEnvContents } = loader.load()
+const envFiles = await loader.load()
 ```
 
-### `envContents`
+The return value is an array of objects with following properties.
 
-- The `envContents` is read from the `.env` file from the root of the `lookupPath`.
-- No exceptions are raised if the `.env` file is missing. In brief, it is optional to have a `.env` file.
-- If the `ENV_PATH` environment variable is set, the loader will use that instead of the `.env` file. This allows overwriting the location of the dot-env file.
+- `path`: The path to the loaded dot-env file.
+- `contents`: The contents of the file.
 
+Following is the list of loaded files. The array is ordered by the priority of the files. The first file has the highest priority and must override the variables from the last file.
 
-### `currentEnvContents`
-
-- 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.
+| Priority | File name | Environment | Should I `.gitignore` it | Notes |
+|----------|-----------|-------------|--------------------------|-------|
+| 1st | `.env.[NODE_ENV].local` | Current environment | Yes | Loaded when `NODE_ENV` is set |
+| 2nd | `.env.local` | All | Yes | Loaded in all the environments except `test` or `testing` environments |
+| 3rd | `.env.[NODE_ENV]` | Current environment | No | Loaded when `NODE_ENV` is set |
+| 4th | `.env` | All | Depends | Loaded in all the environments. You should `.gitignore` it when storing secrets in this file |
 
 ## EnvParser
 The `EnvParser` class is responsible for parsing the contents of the `.env` file(s) and converting them into an object.
@@ -49,17 +50,24 @@ import { EnvLoader, EnvParser } from '@adonisjs/env'
 
 const lookupPath = new URL('./', import.meta.url)
 const loader = new EnvLoader(lookupPath)
-const { envContents, currentEnvContents } = loader.load()
+const envFiles = await loader.load()
 
-const envParser = new EnvParser(envContents)
-const currentEnvParser = new EnvParser(currentEnvContents)
+const envParser = new EnvParser(`
+  PORT=3000
+  HOST=localhost
+`)
 
-console.log(envParser.parse()) // { key: value }
-console.log(currentEnvParser.parse()) // { key: value }
+console.log(envParser.parse()) // { PORT: '3000', HOST: 'localhost' }
 ```
 
 The return value of `parser.parse` is an object with key-value pair. The parser also has support for interpolation.
 
+By default, the parser prefers existing `process.env` values when they exist. However, you can instruct the parser to ignore existing `process.env` files as follows.
+
+```ts
+new EnvParser(envContents, { ignoreProcessEnv: 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.
 
@@ -86,39 +94,35 @@ validate(process.env)
 
 Following is a complete example of using the `EnvLoader`, `EnvParser`, and the validator to set up environment variables.
 
+> **Note**: Existing `process.env` variables have the top most priority over the variables defined in any of the files.
+
 ```ts
 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 envValues = new EnvParser(envContents).parse()
-const currentEnvValues = new EnvParser(currentEnvContents).parse()
-
-/**
- * Loop over all the parsed env values and set
- * them on "process.env"
- * 
- * However, if the value already exists on "process.env", then
- * do not overwrite it, instead update the envValues
- * object.
- */
-Object.keys(envValues).forEach((key) => {
-  if (process.env[key]) {
-    envValues[key] = process.env[key]
-  } else {
-    process.env[key] = envValues[key]
+const envFiles = await loader.load()
+
+let envValues = {}
+
+envFiles.forEach(({ contents }) => {
+  if (!contents.trim()) {
+    return
   }
-})
 
-/**
- * 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]
+  const values = new EnvParser(contents).parse()
+  Object.keys(values).forEach((key) => {
+    let value = process.env[key]
+
+    if (!value) {
+      value = values[key]
+      process.env[key] = values[key]
+    }
+
+    if (!envValues[key]) {
+      envValues[key] = value
+    }
+  })
 })
 
 // Now perform the validation
@@ -127,7 +131,7 @@ const validate = Env.rules({
   HOST: Env.schema.string({ format: 'host' })
 })
 
-const validated = validate({ ...envValues, ...currentEnvValues })
+const validated = validate(envValues)
 const env = new Env(validated)
 
 env.get('PORT') // is a number

package/build/src/loader.d.ts

@@ -3,7 +3,7 @@ export declare class EnvLoader {
     #private;
     constructor(appRoot: string | URL);
     load(): Promise<{
-        envContents: string;
-        currentEnvContents: string;
-    }>;
+        path: string;
+        contents: string;
+    }[]>;
 }

package/build/src/loader.js

@@ -7,7 +7,7 @@ export class EnvLoader {
     constructor(appRoot) {
         this.#appRoot = typeof appRoot === 'string' ? appRoot : fileURLToPath(appRoot);
     }
-    async #loadFile(filePath, optional = false) {
+    async #loadFile(filePath, optional = true) {
         try {
             return await readFile(filePath, 'utf-8');
         }
@@ -24,11 +24,40 @@ export class EnvLoader {
         }
     }
     async load() {
-        const envFile = process.env.ENV_PATH || '.env';
-        const envPath = isAbsolute(envFile) ? envFile : join(this.#appRoot, envFile);
-        const envContents = await this.#loadFile(envPath, !process.env.ENV_PATH);
-        const currentEnvPath = join(this.#appRoot, `.env.${process.env.NODE_ENV}`);
-        const currentEnvContents = await this.#loadFile(currentEnvPath, true);
-        return { envContents, currentEnvContents };
+        const ENV_PATH = process.env.ENV_PATH;
+        const NODE_ENV = process.env.NODE_ENV;
+        const envFiles = [];
+        const baseEnvPath = ENV_PATH
+            ? isAbsolute(ENV_PATH)
+                ? ENV_PATH
+                : join(this.#appRoot, ENV_PATH)
+            : this.#appRoot;
+        if (NODE_ENV) {
+            const nodeEnvLocalFile = join(baseEnvPath, `.env.${process.env.NODE_ENV}.local`);
+            envFiles.push({
+                path: nodeEnvLocalFile,
+                contents: await this.#loadFile(nodeEnvLocalFile),
+            });
+        }
+        if (!NODE_ENV || !['test', 'testing'].includes(NODE_ENV)) {
+            const envLocalFile = join(baseEnvPath, '.env.local');
+            envFiles.push({
+                path: envLocalFile,
+                contents: await this.#loadFile(envLocalFile),
+            });
+        }
+        if (NODE_ENV) {
+            const nodeEnvFile = join(baseEnvPath, `.env.${process.env.NODE_ENV}`);
+            envFiles.push({
+                path: nodeEnvFile,
+                contents: await this.#loadFile(nodeEnvFile),
+            });
+        }
+        const envFile = join(baseEnvPath, '.env');
+        envFiles.push({
+            path: envFile,
+            contents: await this.#loadFile(envFile),
+        });
+        return envFiles;
     }
 }

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?: {
+        ignoreProcessEnv: boolean;
+    });
     parse(): DotenvParseOutput;
 }

package/build/src/parser.js

@@ -1,14 +1,21 @@
 import dotenv from 'dotenv';
 export class EnvParser {
     #envContents;
-    constructor(envContents) {
+    #preferProcessEnv = true;
+    constructor(envContents, options) {
+        if (options?.ignoreProcessEnv) {
+            this.#preferProcessEnv = false;
+        }
         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.1-0",
   "description": "Environment variable manager for Node.js",
   "main": "build/index.js",
   "type": "module",