@adonisjs/env 4.0.3-0 → 4.1.0-0

package/README.md

@@ -78,7 +78,7 @@ Once you have the parsed objects, you can optionally validate them against a pre
 ```ts
 import { Env } from '@adonisjs/env'
 
-const validate = Env.rules({
+const validator = Env.rules({
   PORT: Env.schema.number(),
   HOST: Env.schema.string({ format: 'host' })
 })
@@ -86,61 +86,29 @@ const validate = Env.rules({
 
 The `Env.schema` is a reference to the [@poppinss/validator-lite](https://github.com/poppinss/validator-lite) `schema` object. Make sure to go through the package README to view all the available methods and options.
 
-The `Env.rules` method returns a function to validate the environment variables. The return value is the validated object with type information inferred from the schema.
+The `Env.rules` method returns an instance of the validator to validate the environment variables. The return value is the validated object with type information inferred from the schema.
 
 ```ts
-validate(process.env)
+validator.validate(process.env)
 ```
 
-Following is a complete example of using the `EnvLoader`, `EnvParser`, and the validator to set up environment variables.
+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.
 
 ```ts
-import { EnvLoader, EnvParser, Env } from '@adonisjs/env'
-
-const lookupPath = new URL('./', import.meta.url)
-const loader = new EnvLoader(lookupPath)
-const envFiles = await loader.load()
-
-let envValues = {}
-
-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
-    }
-  })
-})
+import { Env } from '@adonisjs/env'
 
-// Now perform the validation
-const validate = Env.rules({
+const env = await Env.create(new URL('./', import.meta.url), {
   PORT: Env.schema.number(),
   HOST: Env.schema.string({ format: 'host' })
 })
 
-const validated = validate(envValues)
-const env = new Env(validated)
-
 env.get('PORT') // is a number
 env.get('HOST') // is a string
 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

package/build/index.d.ts

@@ -1,4 +1,5 @@
 export { Env } from './src/env.js';
 export { EnvParser } from './src/parser.js';
 export { EnvLoader } from './src/loader.js';
+export { EnvProcessor } from './src/processor.js';
 export { InvalidEnvVariablesException } from './src/exceptions/invalid_env_variables.js';

package/build/index.js

@@ -1,4 +1,5 @@
 export { Env } from './src/env.js';
 export { EnvParser } from './src/parser.js';
 export { EnvLoader } from './src/loader.js';
+export { EnvProcessor } from './src/processor.js';
 export { InvalidEnvVariablesException } from './src/exceptions/invalid_env_variables.js';

package/build/src/debug.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="node" resolution-mode="require"/>
+declare const _default: import("util").DebugLogger;
+export default _default;

package/build/src/debug.js

@@ -0,0 +1,2 @@
+import { debuglog } from 'node:util';
+export default debuglog('adonisjs:env');

package/build/src/env.d.ts

@@ -1,8 +1,14 @@
-import { EnvValidator } from './validator.js';
+/// <reference types="node" resolution-mode="require"/>
 import { type ValidateFn } from '@poppinss/validator-lite';
+import { EnvValidator } from './validator.js';
 export declare class Env<EnvValues extends Record<string, any>> {
     #private;
     constructor(values: EnvValues);
+    static create<Schema extends {
+        [key: string]: ValidateFn<unknown>;
+    }>(appRoot: URL, schema: Schema): Promise<Env<{
+        [K in keyof Schema]: ReturnType<Schema[K]>;
+    }>>;
     static schema: {
         number: typeof import("@poppinss/validator-lite/build/src/schema/number.js").number;
         string: typeof import("@poppinss/validator-lite/build/src/schema/string.js").string;
@@ -11,7 +17,7 @@ export declare class Env<EnvValues extends Record<string, any>> {
     };
     static rules<T extends {
         [key: string]: ValidateFn<unknown>;
-    }>(schema: T): EnvValidator<T>['validate'];
+    }>(schema: T): EnvValidator<T>;
     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;

package/build/src/env.js

@@ -1,14 +1,20 @@
-import { EnvValidator } from './validator.js';
 import { schema as envSchema } from '@poppinss/validator-lite';
+import { EnvValidator } from './validator.js';
+import { EnvProcessor } from './processor.js';
 export class Env {
     #values;
     constructor(values) {
         this.#values = values;
     }
+    static async create(appRoot, schema) {
+        const values = await new EnvProcessor(appRoot).process();
+        const validator = this.rules(schema);
+        return new Env(validator.validate(values));
+    }
     static schema = envSchema;
     static rules(schema) {
         const validator = new EnvValidator(schema);
-        return validator.validate.bind(validator);
+        return validator;
     }
     get(key, defaultValue) {
         if (this.#values[key] !== undefined) {

package/build/src/loader.js

@@ -1,6 +1,7 @@
 import { fileURLToPath } from 'node:url';
 import { readFile } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
+import debug from './debug.js';
 export class EnvLoader {
     #appRoot;
     constructor(appRoot) {
@@ -21,11 +22,18 @@ export class EnvLoader {
         const ENV_PATH = process.env.ENV_PATH;
         const NODE_ENV = process.env.NODE_ENV;
         const envFiles = [];
+        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');
+        }
         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);
+        }
         if (NODE_ENV) {
             const nodeEnvLocalFile = join(baseEnvPath, `.env.${process.env.NODE_ENV}.local`);
             envFiles.push({

package/build/src/processor.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="node" resolution-mode="require"/>
+export declare class EnvProcessor {
+    #private;
+    constructor(appRoot: URL);
+    process(): Promise<Record<string, any>>;
+}

package/build/src/processor.js

@@ -0,0 +1,39 @@
+import debug from './debug.js';
+import { EnvParser } from './parser.js';
+import { EnvLoader } from './loader.js';
+export class EnvProcessor {
+    #appRoot;
+    constructor(appRoot) {
+        this.#appRoot = appRoot;
+    }
+    #processContents(envContents, store) {
+        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;
+    }
+    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));
+        }
+        const envValues = {};
+        envFiles.forEach(({ contents }) => this.#processContents(contents, envValues));
+        return envValues;
+    }
+    async process() {
+        return this.#loadAndProcessDotFiles();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonisjs/env",
-  "version": "4.0.3-0",
+  "version": "4.1.0-0",
   "description": "Environment variable manager for Node.js",
   "main": "build/index.js",
   "type": "module",
@@ -14,7 +14,7 @@
   },
   "scripts": {
     "pretest": "npm run lint",
-    "test": "c8 npm run vscode:test",
+    "test": "cross-env NODE_DEBUG=adonisjs:env c8 npm run vscode:test",
     "clean": "del-cli build",
     "compile": "npm run lint && npm run clean && tsc",
     "build": "npm run compile",
@@ -41,12 +41,13 @@
     "@japa/runner": "^2.2.2",
     "@japa/spec-reporter": "^1.3.2",
     "@poppinss/dev-utils": "^2.0.3",
-    "@swc/core": "^1.3.21",
+    "@swc/core": "^1.3.22",
     "@types/fs-extra": "^9.0.13",
-    "@types/node": "^18.11.10",
+    "@types/node": "^18.11.13",
     "c8": "^7.12.0",
+    "cross-env": "^7.0.3",
     "del-cli": "^5.0.0",
-    "eslint": "^8.28.0",
+    "eslint": "^8.29.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-adonis": "^3.0.3",
     "eslint-plugin-prettier": "^4.2.1",
@@ -54,9 +55,9 @@
     "github-label-sync": "^2.2.0",
     "husky": "^8.0.2",
     "np": "^7.6.2",
-    "prettier": "^2.8.0",
+    "prettier": "^2.8.1",
     "ts-node": "^10.9.1",
-    "typescript": "^4.9.3"
+    "typescript": "^4.9.4"
   },
   "dependencies": {
     "@poppinss/utils": "^6.1.0-0",