@adonisjs/env 4.0.0-0 → 4.0.0-2

package/README.md

@@ -1,41 +1,147 @@
-<div align="center">
-  <img src="https://res.cloudinary.com/adonisjs/image/upload/q_100/v1558612869/adonis-readme_zscycu.jpg" width="600px">
-</div>
-
-<br />
-
-<div align="center">
-  <h3>AdonisJS Env Provider</h3>
-  <p>Provider to parse and load environment variables from a local <code>.env</code> file. Comes with first class support for <strong>variables substitution</strong>.</p>
-</div>
-
-<br />
-
-<div align="center">
-
-[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url] [![synk-image]][synk-url]
-
-</div>
-
-<div align="center">
-  <h3>
-    <a href="https://adonisjs.com">
-      Website
-    </a>
-    <span> | </span>
-    <a href="https://docs.adonisjs.com/guides/environment-variables">
-      Guides
-    </a>
-    <span> | </span>
-    <a href="CONTRIBUTING.md">
-      Contributing
-    </a>
-  </h3>
-</div>
-
-<div align="center">
-  <sub>Built with ❤︎ by <a href="https://twitter.com/AmanVirk1">Harminder Virk</a>
-</div>
+# @adonisjs/env
+> Environment variables parser and validator used by the AdonisJS.
+
+[![gh-workflow-image]][gh-workflow-url] [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url] [![synk-image]][synk-url]
+
+> **Note:** This package is framework agnostic and can also be used outside of AdonisJS.
+
+The `@adonisjs/env` package encapsulates the workflow around loading, parsing, and validating environment variables.
+
+## Setup
+Install the package from the npm packages registry as follows.
+
+```sh
+npm i @adonisjs/env
+
+yarn add @adonisjs/env
+```
+
+## EnvLoader
+The `EnvLoader` class is responsible for loading the environment variable files from the disk and returning their contents as a string.
+
+```ts
+import { EnvLoader } from '@adonisjs/env'
+
+const lookupPath = new URL('./', import.meta.url)
+const loader = new EnvLoader(lookupPath)
+
+const { envContents, currentEnvContents } = await loader.load()
+```
+
+### `envContents`
+
+- 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.
+
+
+### `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.
+
+## EnvParser
+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 { envContents, currentEnvContents } = await loader.load()
+
+const envParser = new EnvParser(envContents)
+const currentEnvParser = new EnvParser(currentEnvContents)
+
+console.log(envParser.parse()) // { key: value }
+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.
+
+- Fail early if one or more environment variables are missing.
+- Cast values to specific data types. 
+- Have type safety alongside runtime safety.
+
+```ts
+import { Env } from '@adonisjs/env'
+
+const validate = Env.rules({
+  PORT: Env.schema.number(),
+  HOST: Env.schema.string({ format: 'host' })
+})
+```
+
+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.
+
+```ts
+validate(process.env)
+```
+
+Following is a complete example of using the `EnvLoader`, `EnvParser`, and the validator to set up environment variables.
+
+```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 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]
+  }
+})
+
+// Now perform the validation
+const validate = Env.rules({
+  PORT: Env.schema.number(),
+  HOST: Env.schema.string({ format: 'host' })
+})
+
+const validated = validate({ ...envValues, ...currentEnvValues })
+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.
 
 [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/exceptions/invalid_env_variables.d.ts

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

package/build/src/exceptions/invalid_env_variables.js

@@ -0,0 +1,6 @@
+import { Exception } from '@poppinss/utils';
+export class InvalidEnvVariablesException extends Exception {
+    static status = 500;
+    static code = 'E_INVALID_ENV_VARIABLES';
+    static message = 'Validation failed for one or more environment variables';
+}

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

@@ -1,12 +1,26 @@
+import { InvalidEnvVariablesException } from './exceptions/invalid_env_variables.js';
 export class EnvValidator {
     #schema;
+    #error;
     constructor(schema) {
         this.#schema = schema;
+        this.#error = new InvalidEnvVariablesException();
     }
     validate(values) {
-        return Object.keys(this.#schema).reduce((result, key) => {
-            result[key] = this.#schema[key](key, values[key]);
+        const cause = [];
+        const validated = Object.keys(this.#schema).reduce((result, key) => {
+            try {
+                result[key] = this.#schema[key](key, values[key]);
+            }
+            catch (error) {
+                cause.push(`- ${error.message}`);
+            }
             return result;
         }, { ...values });
+        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-0",
+  "version": "4.0.0-2",
   "description": "Environment variable manager for Node.js",
   "main": "build/index.js",
   "type": "module",