@adonisjs/env 4.2.0-0 → 4.2.0-2

package/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2023 AdonisJS Framework
+Copyright (c) 2023 Harminder Virk
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -46,12 +46,7 @@ Following is the list of loaded files. The array is ordered by the priority of t
 The `EnvParser` class is responsible for parsing the contents of the `.env` file(s) and converting them into an object.
 
 ```ts
-import { EnvLoader, EnvParser } from '@adonisjs/env'
-
-const lookupPath = new URL('./', import.meta.url)
-const loader = new EnvLoader(lookupPath)
-const envFiles = await loader.load()
-
+import { EnvParser } from '@adonisjs/env'
 const envParser = new EnvParser(`
   PORT=3000
   HOST=localhost
@@ -92,6 +87,8 @@ The `Env.rules` method returns an instance of the validator to validate the envi
 validator.validate(process.env)
 ```
 
+## Complete example
+
 Following is a complete example of loading dot-env files and validating them in one go.
 
 > **Note**: Existing `process.env` variables have the top most priority over the variables defined in any of the files.

package/build/index.d.ts

@@ -4,3 +4,4 @@ export { EnvLoader } from './src/loader.js';
 export { EnvEditor } from './src/editor.js';
 export * as errors from './src/exceptions.js';
 export { EnvProcessor } from './src/processor.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA"}

package/build/src/debug.d.ts

@@ -1,3 +1,4 @@
 /// <reference types="node" resolution-mode="require"/>
 declare const _default: import("util").DebugLogger;
 export default _default;
+//# sourceMappingURL=debug.d.ts.map

package/build/src/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":";;AAUA,wBAAuC"}

package/build/src/editor.d.ts

@@ -11,3 +11,4 @@ export declare class EnvEditor {
     }[];
     save(): Promise<void>;
 }
+//# sourceMappingURL=editor.d.ts.map

package/build/src/editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../../src/editor.ts"],"names":[],"mappings":";AAeA,qBAAa,SAAS;;WASP,MAAM,CAAC,OAAO,EAAE,GAAG;gBAOpB,OAAO,EAAE,GAAG;IASlB,IAAI;IAoBV,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IASjD,MAAM;;;;IAOA,IAAI;CAOX"}

package/build/src/env.d.ts

@@ -25,3 +25,4 @@ export declare class Env<EnvValues extends Record<string, any>> {
     set<K extends keyof EnvValues>(key: K, value: EnvValues[K]): void;
     set(key: string, value: string): void;
 }
+//# sourceMappingURL=env.d.ts.map

package/build/src/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":";AASA,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAiB7C,qBAAa,GAAG,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;gBAMxC,MAAM,EAAE,SAAS;WAShB,MAAM,CAAC,MAAM,SAAS;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;KAAE,EACvE,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CACR,GAAG,CAAC;SACD,CAAC,IAAI,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;KAC3C,CAAC,CACH;IASD,MAAM,CAAC,MAAM;;;;;MAAY;IAOzB,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;KAAE,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;IAoB1F,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IACpD,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAC3B,GAAG,EAAE,CAAC,EACN,YAAY,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAoC9C,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAKtC"}

package/build/src/env.js

@@ -1,7 +1,7 @@
 import { schema as envSchema } from '@poppinss/validator-lite';
 import { EnvValidator } from './validator.js';
 import { EnvProcessor } from './processor.js';
-export class Env {
+class Env {
     #values;
     constructor(values) {
         this.#values = values;
@@ -31,3 +31,4 @@ export class Env {
         process.env[key] = value;
     }
 }
+export { Env };

package/build/src/exceptions.d.ts

@@ -22,3 +22,4 @@ export declare const E_INVALID_ENV_VARIABLES: {
     prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
     stackTraceLimit: number;
 };
+//# sourceMappingURL=exceptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/exceptions.ts"],"names":[],"mappings":";AAeA,eAAO,MAAM,uBAAuB;;;;;cAG5B,MAAM;;;;;;;;;;;;;;;;;CACb,CAAA"}

package/build/src/loader.d.ts

@@ -8,3 +8,4 @@ export declare class EnvLoader {
         fileExists: boolean;
     }[]>;
 }
+//# sourceMappingURL=loader.d.ts.map

package/build/src/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/loader.ts"],"names":[],"mappings":";AAqCA,qBAAa,SAAS;;gBAIR,OAAO,EAAE,MAAM,GAAG,GAAG,EAAE,eAAe,GAAE,OAAe;IA0B7D,IAAI,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAiFjF"}

package/build/src/parser.d.ts

@@ -6,3 +6,4 @@ export declare class EnvParser {
     });
     parse(): DotenvParseOutput;
 }
+//# sourceMappingURL=parser.d.ts.map

package/build/src/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser.ts"],"names":[],"mappings":"AASA,OAAe,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AA0ClD,qBAAa,SAAS;;gBAIR,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,gBAAgB,EAAE,OAAO,CAAA;KAAE;IAyHxE,KAAK,IAAI,iBAAiB;CAQ3B"}

package/build/src/processor.d.ts

@@ -4,3 +4,4 @@ export declare class EnvProcessor {
     constructor(appRoot: URL);
     process(): Promise<Record<string, any>>;
 }
+//# sourceMappingURL=processor.d.ts.map

package/build/src/processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../src/processor.ts"],"names":[],"mappings":";AAgBA,qBAAa,YAAY;;gBAMX,OAAO,EAAE,GAAG;IAyDlB,OAAO;CAGd"}

package/build/src/validator.d.ts

@@ -10,3 +10,4 @@ export declare class EnvValidator<Schema extends {
         [K in keyof Schema]: ReturnType<Schema[K]>;
     };
 }
+//# sourceMappingURL=validator.d.ts.map

package/build/src/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAUrD,qBAAa,YAAY,CAAC,MAAM,SAAS;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;CAAE;;gBAIjE,MAAM,EAAE,MAAM;IAY1B,QAAQ,CAAC,MAAM,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG;SACpD,CAAC,IAAI,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;KAC3C;CAwBF"}

package/index.ts

@@ -0,0 +1,15 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+export { Env } from './src/env.js'
+export { EnvParser } from './src/parser.js'
+export { EnvLoader } from './src/loader.js'
+export { EnvEditor } from './src/editor.js'
+export * as errors from './src/exceptions.js'
+export { EnvProcessor } from './src/processor.js'

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@adonisjs/env",
-  "version": "4.2.0-0",
+  "version": "4.2.0-2",
   "description": "Environment variable manager for Node.js",
   "main": "build/index.js",
   "type": "module",
   "files": [
+    "src",
+    "index.ts",
     "build/src",
     "build/index.d.ts",
+    "build/index.d.ts.map",
     "build/index.js"
   ],
   "exports": {
@@ -33,36 +36,33 @@
   "author": "virk,adonisjs",
   "license": "MIT",
   "devDependencies": {
-    "@commitlint/cli": "^17.4.2",
-    "@commitlint/config-conventional": "^17.4.2",
+    "@commitlint/cli": "^17.5.0",
+    "@commitlint/config-conventional": "^17.4.4",
     "@japa/assert": "^1.4.1",
     "@japa/expect-type": "^1.0.3",
     "@japa/file-system": "^1.0.1",
     "@japa/run-failed-tests": "^1.1.1",
-    "@japa/runner": "^2.3.0",
+    "@japa/runner": "^2.5.1",
     "@japa/spec-reporter": "^1.3.3",
-    "@poppinss/dev-utils": "^2.0.3",
-    "@swc/core": "^1.3.35",
-    "@types/fs-extra": "^11.0.1",
-    "@types/node": "^18.13.0",
-    "c8": "^7.12.0",
+    "@swc/core": "^1.3.42",
+    "@types/node": "^18.15.9",
+    "c8": "^7.13.0",
     "cross-env": "^7.0.3",
     "del-cli": "^5.0.0",
-    "eslint": "^8.34.0",
-    "eslint-config-prettier": "^8.6.0",
+    "eslint": "^8.36.0",
+    "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-adonis": "^3.0.3",
     "eslint-plugin-prettier": "^4.2.1",
-    "fs-extra": "^11.1.0",
-    "github-label-sync": "^2.2.0",
+    "github-label-sync": "^2.3.1",
     "husky": "^8.0.3",
-    "np": "^7.6.3",
-    "prettier": "^2.8.4",
+    "np": "^7.6.4",
+    "prettier": "^2.8.7",
     "ts-node": "^10.9.1",
-    "typescript": "^4.9.5"
+    "typescript": "^5.0.2"
   },
   "dependencies": {
-    "@poppinss/utils": "^6.5.0-0",
-    "@poppinss/validator-lite": "^1.0.2",
+    "@poppinss/utils": "^6.5.0-2",
+    "@poppinss/validator-lite": "^1.0.3",
     "dotenv": "^16.0.3",
     "split-lines": "^3.0.0"
   },

package/src/debug.ts

@@ -0,0 +1,11 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { debuglog } from 'node:util'
+export default debuglog('adonisjs:env')

package/src/editor.ts

@@ -0,0 +1,84 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import splitLines from 'split-lines'
+import lodash from '@poppinss/utils/lodash'
+import { writeFile } from 'node:fs/promises'
+
+import { EnvLoader } from './loader.js'
+
+export class EnvEditor {
+  #appRoot: URL
+  #loader: EnvLoader
+  #files: { contents: string[]; path: string }[] = []
+
+  /**
+   * Creates an instance of env editor and loads .env files
+   * contents.
+   */
+  static async create(appRoot: URL) {
+    const editor = new EnvEditor(appRoot)
+    await editor.load()
+
+    return editor
+  }
+
+  constructor(appRoot: URL) {
+    this.#appRoot = appRoot
+    this.#loader = new EnvLoader(this.#appRoot, true)
+  }
+
+  /**
+   * Loads .env files for editing. Only ".env" and ".env.example"
+   * files are picked for editing.
+   */
+  async load() {
+    const envFiles = await this.#loader.load()
+
+    this.#files = envFiles
+      .filter(
+        (envFile) =>
+          envFile.fileExists &&
+          (envFile.path.endsWith('.env') || envFile.path.endsWith('.env.example'))
+      )
+      .map((envFile) => {
+        return {
+          contents: splitLines(envFile.contents.trim()),
+          path: envFile.path,
+        }
+      })
+  }
+
+  /**
+   * Add key-value pair to the dot-env files.
+   */
+  add(key: string, value: string | number | boolean) {
+    this.#files.forEach((file) => {
+      let entryIndex = file.contents.findIndex((line) => line.startsWith(`${key}=`))
+
+      entryIndex = entryIndex === -1 ? file.contents.length : entryIndex
+      lodash.set(file.contents, entryIndex, `${key}=${String(value)}`)
+    })
+  }
+
+  toJSON() {
+    return this.#files
+  }
+
+  /**
+   * Save changes to the disk
+   */
+  async save() {
+    await Promise.all(
+      this.#files.map((file) => {
+        return writeFile(file.path, file.contents.join('\n'))
+      })
+    )
+  }
+}

package/src/env.ts

@@ -0,0 +1,134 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { schema as envSchema, type ValidateFn } from '@poppinss/validator-lite'
+import { EnvValidator } from './validator.js'
+import { EnvProcessor } from './processor.js'
+
+/**
+ * A wrapper over "process.env" with types information.
+ *
+ * ```ts
+ * const validate = Env.rules({
+ *   PORT: Env.schema.number()
+ * })
+ *
+ * const validatedEnvVars = validate(process.env)
+ *
+ * const env = new EnvValues(validatedEnvVars)
+ * env.get('PORT') // type === number
+ * ```
+ */
+export class Env<EnvValues extends Record<string, any>> {
+  /**
+   * A cache of env values
+   */
+  #values: EnvValues
+
+  constructor(values: EnvValues) {
+    this.#values = values
+  }
+
+  /**
+   * Create an instance of the env class by validating the
+   * environment variables. Also, the `.env` files are
+   * loaded from the appRoot
+   */
+  static async create<Schema extends { [key: string]: ValidateFn<unknown> }>(
+    appRoot: URL,
+    schema: Schema
+  ): Promise<
+    Env<{
+      [K in keyof Schema]: ReturnType<Schema[K]>
+    }>
+  > {
+    const values = await new EnvProcessor(appRoot).process()
+    const validator = this.rules(schema)
+    return new Env(validator.validate(values))
+  }
+
+  /**
+   * The schema builder for defining validation rules
+   */
+  static schema = envSchema
+
+  /**
+   * Define the validation rules for validating environment
+   * variables. The return value is an instance of the
+   * env validator
+   */
+  static rules<T extends { [key: string]: ValidateFn<unknown> }>(schema: T): EnvValidator<T> {
+    const validator = new EnvValidator<T>(schema)
+    return validator
+  }
+
+  /**
+   * Get the value of an environment variable by key. The values are
+   * lookedup inside the validated environment and "process.env"
+   * is used as a fallback.
+   *
+   * The second param is the default value, which is returned when
+   * the environment variable does not exist.
+   *
+   * ```ts
+   * Env.get('PORT')
+   *
+   * // With default value
+   * Env.get('PORT', 3000)
+   * ```
+   */
+  get<K extends keyof EnvValues>(key: K): EnvValues[K]
+  get<K extends keyof EnvValues>(
+    key: K,
+    defaultValue: Exclude<EnvValues[K], undefined>
+  ): Exclude<EnvValues[K], undefined>
+  get(key: string): string | undefined
+  get(key: string, defaultValue: string): string
+  get(key: string, defaultValue?: any): any {
+    /**
+     * Return cached value
+     */
+    if (this.#values[key] !== undefined) {
+      return this.#values[key]
+    }
+
+    /**
+     * Get value from "process.env" and update the cache
+     */
+    const envValue = process.env[key]
+    if (envValue) {
+      return envValue
+    }
+
+    /**
+     * Return default value when unable to lookup any other value
+     */
+    return defaultValue
+  }
+
+  /**
+   * Update/set value of an environment variable.
+   *
+   * The value is not casted/validated using the validator, so make sure
+   * to set the correct data type.
+   *
+   * ```ts
+   * Env.set('PORT', 3000)
+   *
+   * Env.get('PORT') === 3000 // true
+   * process.env.PORT === '3000' // true
+   * ```
+   */
+  set<K extends keyof EnvValues>(key: K, value: EnvValues[K]): void
+  set(key: string, value: string): void
+  set(key: string | keyof EnvValues, value: any): void {
+    this.#values[key] = value
+    process.env[key as string] = value
+  }
+}

package/src/exceptions.ts

@@ -0,0 +1,20 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Exception } from '@poppinss/utils'
+
+/**
+ * Exception raised when one or more env variables
+ * are invalid
+ */
+export const E_INVALID_ENV_VARIABLES = class EnvValidationException extends Exception {
+  static message = 'Validation failed for one or more environment variables'
+  static code = 'E_INVALID_ENV_VARIABLES'
+  help: string = ''
+}

package/src/loader.ts

@@ -0,0 +1,149 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { fileURLToPath } from 'node:url'
+import { readFile } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+
+import debug from './debug.js'
+
+/**
+ * Read the contents of one or more dot-env files. Following is how the files
+ * are read.
+ *
+ * - Load file from the "ENV_PATH" environment file.
+ *    (Raise error if file is missing)
+ *
+ * - If "ENV_PATH" is not defined, then find ".env" file in the app root.
+ *    (Ignore if file is missing)
+ *
+ * - Find ".env.[NODE_ENV]" file in the app root.
+ *    (Ignore if file is missing)
+ *
+ * ```ts
+ * const loader = new EnvLoader(new URL('./', import.meta.url))
+ *
+ * const { envContents, currentEnvContents } = await loader.load()
+ *
+ * // envContents: Contents of .env or file specified via ENV_PATH
+ * // currentEnvContents: Contents of .env.[NODE_ENV] file
+ * ```
+ */
+export class EnvLoader {
+  #appRoot: string
+  #loadExampleFile: boolean
+
+  constructor(appRoot: string | URL, loadExampleFile: boolean = false) {
+    this.#appRoot = typeof appRoot === 'string' ? appRoot : fileURLToPath(appRoot)
+    this.#loadExampleFile = loadExampleFile
+  }
+
+  /**
+   * Optionally read a file from the disk
+   */
+  async #loadFile(filePath: string | URL): Promise<{ fileExists: boolean; contents: string }> {
+    try {
+      const contents = await readFile(filePath, 'utf-8')
+      return { contents, fileExists: true }
+    } catch (error) {
+      /* c8 ignore next 3 */
+      if (error.code !== 'ENOENT') {
+        throw error
+      }
+
+      return { contents: '', fileExists: false }
+    }
+  }
+
+  /**
+   * Load contents of the main dot-env file and the current
+   * environment dot-env file
+   */
+  async load(): Promise<{ contents: string; path: string; fileExists: boolean }[]> {
+    const ENV_PATH = process.env.ENV_PATH
+    const NODE_ENV = process.env.NODE_ENV
+    const envFiles: { path: string; contents: string; fileExists: boolean }[] = []
+
+    if (debug.enabled) {
+      debug('ENV_PATH variable is %s', ENV_PATH ? 'set' : 'not set')
+      debug('NODE_ENV variable is %s', NODE_ENV ? 'set' : 'not set')
+    }
+
+    /**
+     * Base path to load .env files from
+     */
+    const baseEnvPath = ENV_PATH
+      ? isAbsolute(ENV_PATH)
+        ? ENV_PATH
+        : join(this.#appRoot, ENV_PATH)
+      : this.#appRoot
+
+    if (debug.enabled) {
+      debug('dot-env files base path "%s"', baseEnvPath)
+    }
+
+    /**
+     * 1st
+     * The top most priority is given to the ".env.[NODE_ENV].local" file
+     */
+    if (NODE_ENV) {
+      const nodeEnvLocalFile = join(baseEnvPath, `.env.${NODE_ENV}.local`)
+      envFiles.push({
+        path: nodeEnvLocalFile,
+        ...(await this.#loadFile(nodeEnvLocalFile)),
+      })
+    }
+
+    /**
+     * 2nd
+     * Next, we give priority to the ".env.local" file
+     */
+    if (!NODE_ENV || !['test', 'testing'].includes(NODE_ENV)) {
+      const envLocalFile = join(baseEnvPath, '.env.local')
+      envFiles.push({
+        path: envLocalFile,
+        ...(await this.#loadFile(envLocalFile)),
+      })
+    }
+
+    /**
+     * 3rd
+     * Next, we give priority to the ".env.[NODE_ENV]" file
+     */
+    if (NODE_ENV) {
+      const nodeEnvFile = join(baseEnvPath, `.env.${NODE_ENV}`)
+      envFiles.push({
+        path: nodeEnvFile,
+        ...(await this.#loadFile(nodeEnvFile)),
+      })
+    }
+
+    /**
+     * Finally, we push the contents of the ".env" file.
+     */
+    const envFile = join(baseEnvPath, '.env')
+    envFiles.push({
+      path: envFile,
+      ...(await this.#loadFile(envFile)),
+    })
+
+    /**
+     * Load example file
+     */
+    if (this.#loadExampleFile) {
+      const envExampleFile = join(baseEnvPath, '.env.example')
+      envFiles.push({
+        path: envExampleFile,
+        ...(await this.#loadFile(envExampleFile)),
+      })
+    }
+
+    return envFiles
+  }
+}

package/src/parser.ts

@@ -0,0 +1,185 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import dotenv, { DotenvParseOutput } from 'dotenv'
+
+/**
+ * Env parser parses the environment variables from a string formatted
+ * as a key-value pair seperated using an `=`. For example:
+ *
+ * ```dotenv
+ * PORT=3333
+ * HOST=127.0.0.1
+ * ```
+ *
+ * The variables can reference other environment variables as well using `$`.
+ * For example:
+ *
+ * ```dotenv
+ * PORT=3333
+ * REDIS_PORT=$PORT
+ * ```
+ *
+ * The variables using characters other than letters can wrap variable
+ * named inside a curly brace.
+ *
+ * ```dotenv
+ * APP-PORT=3333
+ * REDIS_PORT=${APP-PORT}
+ * ```
+ *
+ * You can escape the `$` sign with a backtick.
+ *
+ * ```dotenv
+ * REDIS_PASSWORD=foo\$123
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const parser = new EnvParser(envContents)
+ * const output = parser.parse()
+ *
+ * // The output is a key-value pair
+ * ```
+ */
+export class EnvParser {
+  #envContents: string
+  #preferProcessEnv: boolean = true
+
+  constructor(envContents: string, options?: { ignoreProcessEnv: boolean }) {
+    if (options?.ignoreProcessEnv) {
+      this.#preferProcessEnv = false
+    }
+
+    this.#envContents = envContents
+  }
+
+  /**
+   * Returns the value from the parsed object
+   */
+  #getValue(key: string, parsed: DotenvParseOutput): string {
+    if (this.#preferProcessEnv && process.env[key]) {
+      return process.env[key]!
+    }
+
+    if (parsed[key]) {
+      return this.#interpolate(parsed[key], parsed)
+    }
+
+    return process.env[key] || ''
+  }
+
+  /**
+   * Interpolating the token wrapped inside the mustache braces.
+   */
+  #interpolateMustache(token: string, parsed: DotenvParseOutput) {
+    /**
+     * Finding the closing brace. If closing brace is missing, we
+     * consider the block as a normal string
+     */
+    const closingBrace = token.indexOf('}')
+    if (closingBrace === -1) {
+      return token
+    }
+
+    /**
+     * Then we pull everything until the closing brace, except
+     * the opening brace and trim off all white spaces.
+     */
+    const varReference = token.slice(1, closingBrace).trim()
+
+    /**
+     * Getting the value of the reference inside the braces
+     */
+    return `${this.#getValue(varReference, parsed)}${token.slice(closingBrace + 1)}`
+  }
+
+  /**
+   * Interpolating the variable reference starting with a
+   * `$`. We only capture numbers,letter and underscore.
+   * For other characters, one can use the mustache
+   * braces.
+   */
+  #interpolateVariable(token: string, parsed: any) {
+    return token.replace(/[a-zA-Z0-9_]+/, (key) => {
+      return this.#getValue(key, parsed)
+    })
+  }
+
+  /**
+   * Interpolates the referenced values
+   */
+  #interpolate(value: string, parsed: DotenvParseOutput): string {
+    const tokens = value.split('$')
+
+    let newValue = ''
+    let skipNextToken = true
+
+    tokens.forEach((token) => {
+      /**
+       * If the value is an escaped sequence, then we replace it
+       * with a `$` and then skip the next token.
+       */
+      if (token === '\\') {
+        newValue += '$'
+        skipNextToken = true
+        return
+      }
+
+      /**
+       * Use the value as it is when "skipNextToken" is set to true.
+       */
+      if (skipNextToken) {
+        /**
+         * Replace the ending escape sequence with a $
+         */
+        newValue += token.replace(/\\$/, '$')
+        /**
+         *  and then skip the next token if it ends with escape sequence
+         */
+        if (token.endsWith('\\')) {
+          return
+        }
+      } else {
+        /**
+         * Handle mustache block
+         */
+        if (token.startsWith('{')) {
+          newValue += this.#interpolateMustache(token, parsed)
+          return
+        }
+
+        /**
+         * Process all words as variable
+         */
+        newValue += this.#interpolateVariable(token, parsed)
+      }
+
+      /**
+       * Process next token
+       */
+      skipNextToken = false
+    })
+
+    return newValue
+  }
+
+  /**
+   * Parse the env string to an object of environment variables.
+   */
+  parse(): DotenvParseOutput {
+    const envCollection = dotenv.parse(this.#envContents.trim())
+
+    return Object.keys(envCollection).reduce<DotenvParseOutput>((result, key) => {
+      result[key] = this.#getValue(key, envCollection)
+      return result
+    }, {})
+  }
+}

package/src/processor.ts

@@ -0,0 +1,83 @@
+/*
+ * @adonisjs/application
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import debug from './debug.js'
+import { EnvParser } from './parser.js'
+import { EnvLoader } from './loader.js'
+
+/**
+ * Env processors loads, parses and process environment variables.
+ */
+export class EnvProcessor {
+  /**
+   * App root is needed to load files
+   */
+  #appRoot: URL
+
+  constructor(appRoot: URL) {
+    this.#appRoot = appRoot
+  }
+
+  /**
+   * Parse env variables from raw contents
+   */
+  #processContents(envContents: string, store: Record<string, any>) {
+    /**
+     * Collected env variables
+     */
+    if (!envContents.trim()) {
+      return store
+    }
+
+    const values = new EnvParser(envContents).parse()
+    Object.keys(values).forEach((key) => {
+      let value = process.env[key]
+
+      if (!value) {
+        value = values[key]
+        process.env[key] = values[key]
+      }
+
+      if (!store[key]) {
+        store[key] = value
+      }
+    })
+
+    return store
+  }
+
+  /**
+   * Parse env variables by loading dot files.
+   */
+  async #loadAndProcessDotFiles() {
+    const loader = new EnvLoader(this.#appRoot)
+    const envFiles = await loader.load()
+
+    if (debug.enabled) {
+      debug(
+        'processing .env files (priority from top to bottom) %O',
+        envFiles.map((file) => file.path)
+      )
+    }
+
+    /**
+     * Collected env variables
+     */
+    const envValues: Record<string, any> = {}
+    envFiles.forEach(({ contents }) => this.#processContents(contents, envValues))
+    return envValues
+  }
+
+  /**
+   * Process env variables
+   */
+  async process() {
+    return this.#loadAndProcessDotFiles()
+  }
+}

package/src/validator.ts

@@ -0,0 +1,63 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { Exception } from '@poppinss/utils'
+import { ValidateFn } from '@poppinss/validator-lite'
+
+import { E_INVALID_ENV_VARIABLES } from './exceptions.js'
+
+/**
+ * Exposes the API to validate environment variables against a
+ * pre-defined schema.
+ *
+ * The class is not exported in the main API and used internally.
+ */
+export class EnvValidator<Schema extends { [key: string]: ValidateFn<unknown> }> {
+  #schema: Schema
+  #error: Exception
+
+  constructor(schema: Schema) {
+    this.#schema = schema
+    this.#error = new E_INVALID_ENV_VARIABLES()
+  }
+
+  /**
+   * Accepts an object of values to validate against the pre-defined
+   * schema.
+   *
+   * The return value is a merged copy of the original object and the
+   * values mutated by the schema validator.
+   */
+  validate(values: { [K: string]: string | undefined }): {
+    [K in keyof Schema]: ReturnType<Schema[K]>
+  } {
+    const help: string[] = []
+
+    const validated = Object.keys(this.#schema).reduce(
+      (result, key) => {
+        const value = process.env[key] || values[key]
+
+        try {
+          result[key] = this.#schema[key](key, value) as any
+        } catch (error) {
+          help.push(`- ${error.message}`)
+        }
+        return result
+      },
+      { ...values }
+    ) as { [K in keyof Schema]: ReturnType<Schema[K]> }
+
+    if (help.length) {
+      this.#error.help = help.join('\n')
+      throw this.#error
+    }
+
+    return validated
+  }
+}