@adonisjs/env 4.0.0-2 → 4.0.2-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 } = await 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 take precendence over 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,21 +50,22 @@ import { EnvLoader, EnvParser } from '@adonisjs/env'
 
 const lookupPath = new URL('./', import.meta.url)
 const loader = new EnvLoader(lookupPath)
-const { envContents, currentEnvContents } = await 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.
 
-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.
+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, { preferProcessEnv: true })
+new EnvParser(envContents, { ignoreProcessEnv: true })
 ```
 
 ## Validating environment variables
@@ -92,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 } = await loader.load()
-
-/**
- * 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 envFiles = await loader.load()
+
+let envValues = {}
 
-const envValues = new EnvParser(envContents, { preferProcessEnv: true }).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]
+envFiles.forEach(({ contents }) => {
+  if (!contents.trim()) {
+    return
   }
+
+  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
@@ -133,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
@@ -143,6 +141,21 @@ env.get('NODE_ENV') // is unknown, hence a string or undefined
 
 The above code may seem like a lot of work to set up environment variables. However, you have fine-grained control over each step. In the case of AdonisJS, all this boilerplate is hidden inside the framework's application bootstrapping logic.
 
+## Known Exceptions
+
+### E_INVALID_ENV_VARIABLES
+The exception is raised during environment variables validation exception. The exception is raised with `Validation failed for one or more environment variables` message.
+
+You can access the detailed error messages using the `error.cause` property.
+
+```ts
+try {
+  validate(envValues)
+} catch (error) {
+  console.log(error.cause)
+}
+```
+
 [gh-workflow-image]: https://img.shields.io/github/workflow/status/adonisjs/env/test?style=for-the-badge
 [gh-workflow-url]: https://github.com/adonisjs/env/actions/workflows/test.yml "Github action"
 

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

@@ -1,13 +1,12 @@
 import { fileURLToPath } from 'node:url';
 import { readFile } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
-import { MissingEnvPathFileException } from './exceptions/missing_env_path_file.js';
 export class EnvLoader {
     #appRoot;
     constructor(appRoot) {
         this.#appRoot = typeof appRoot === 'string' ? appRoot : fileURLToPath(appRoot);
     }
-    async #loadFile(filePath, optional = false) {
+    async #loadFile(filePath) {
         try {
             return await readFile(filePath, 'utf-8');
         }
@@ -15,20 +14,44 @@ export class EnvLoader {
             if (error.code !== 'ENOENT') {
                 throw error;
             }
-            if (optional) {
-                return '';
-            }
-            throw new MissingEnvPathFileException(`Cannot find env file from "ENV_PATH"`, {
-                cause: error,
-            });
+            return '';
         }
     }
     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

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

package/build/src/parser.js

@@ -1,10 +1,10 @@
 import dotenv from 'dotenv';
 export class EnvParser {
     #envContents;
-    #preferProcessEnv = false;
+    #preferProcessEnv = true;
     constructor(envContents, options) {
-        if (options?.preferProcessEnv) {
-            this.#preferProcessEnv = true;
+        if (options?.ignoreProcessEnv) {
+            this.#preferProcessEnv = false;
         }
         this.#envContents = envContents;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonisjs/env",
-  "version": "4.0.0-2",
+  "version": "4.0.2-0",
   "description": "Environment variable manager for Node.js",
   "main": "build/index.js",
   "type": "module",
@@ -14,7 +14,7 @@
   },
   "scripts": {
     "pretest": "npm run lint",
-    "test": "npm run vscode:test",
+    "test": "c8 npm run vscode:test",
     "clean": "del-cli build",
     "compile": "npm run lint && npm run clean && tsc",
     "build": "npm run compile",
@@ -41,9 +41,10 @@
     "@japa/runner": "^2.2.2",
     "@japa/spec-reporter": "^1.3.2",
     "@poppinss/dev-utils": "^2.0.3",
-    "@swc/core": "^1.3.9",
+    "@swc/core": "^1.3.14",
     "@types/fs-extra": "^9.0.13",
     "@types/node": "^18.11.0",
+    "c8": "^7.12.0",
     "del-cli": "^5.0.0",
     "eslint": "^8.25.0",
     "eslint-config-prettier": "^8.5.0",
@@ -114,5 +115,14 @@
     "tag": "next",
     "branch": "main",
     "anyBranch": false
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "html"
+    ],
+    "exclude": [
+      "tests/**"
+    ]
   }
 }

package/build/src/exceptions/missing_env_path_file.d.ts

@@ -1,5 +0,0 @@
-import { Exception } from '@poppinss/utils';
-export declare class MissingEnvPathFileException extends Exception {
-    static status: number;
-    static code: string;
-}

package/build/src/exceptions/missing_env_path_file.js

@@ -1,5 +0,0 @@
-import { Exception } from '@poppinss/utils';
-export class MissingEnvPathFileException extends Exception {
-    static status = 500;
-    static code = 'E_MISSING_ENV_PATH_FILE';
-}