@adonisjs/env 3.0.9 → 4.0.0-1

package/README.md

@@ -1,41 +1,141 @@
-<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 } = 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 precede 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 } = 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.
+
+## 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 } = 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]
+  }
+})
+
+/**
+ * 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]
+})
+
+// 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/index.d.ts

@@ -1,3 +1,3 @@
-export { Env } from './src/Env';
-export { EnvParser } from './src/Parser';
-export { envLoader } from './src/loader';
+export { Env } from './src/env.js';
+export { EnvParser } from './src/parser.js';
+export { EnvLoader } from './src/loader.js';

package/build/index.js

@@ -1,17 +1,3 @@
-"use strict";
-/*
- * @adonisjs/env
- *
- * (c) Harminder Virk <virk@adonisjs.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.envLoader = exports.EnvParser = exports.Env = void 0;
-var Env_1 = require("./src/Env");
-Object.defineProperty(exports, "Env", { enumerable: true, get: function () { return Env_1.Env; } });
-var Parser_1 = require("./src/Parser");
-Object.defineProperty(exports, "EnvParser", { enumerable: true, get: function () { return Parser_1.EnvParser; } });
-var loader_1 = require("./src/loader");
-Object.defineProperty(exports, "envLoader", { enumerable: true, get: function () { return loader_1.envLoader; } });
+export { Env } from './src/env.js';
+export { EnvParser } from './src/parser.js';
+export { EnvLoader } from './src/loader.js';

package/build/src/env.d.ts

@@ -0,0 +1,21 @@
+import { EnvValidator } from './validator.js';
+import { type ValidateFn } from '@poppinss/validator-lite';
+export declare class Env<EnvValues extends Record<string, any>> {
+    #private;
+    constructor(values: EnvValues);
+    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;
+        boolean: typeof import("@poppinss/validator-lite/build/src/schema/boolean.js").boolean;
+        enum: typeof import("@poppinss/validator-lite/build/src/schema/oneOf.js").oneOf;
+    };
+    static rules<T extends {
+        [key: string]: ValidateFn<unknown>;
+    }>(schema: T): EnvValidator<T>['validate'];
+    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;
+    set<K extends keyof EnvValues>(key: K, value: EnvValues[K]): void;
+    set(key: string, value: string): void;
+}

package/build/src/env.js

@@ -0,0 +1,27 @@
+import { EnvValidator } from './validator.js';
+import { schema as envSchema } from '@poppinss/validator-lite';
+export class Env {
+    #values;
+    constructor(values) {
+        this.#values = values;
+    }
+    static schema = envSchema;
+    static rules(schema) {
+        const validator = new EnvValidator(schema);
+        return validator.validate.bind(validator);
+    }
+    get(key, defaultValue) {
+        if (this.#values[key] !== undefined) {
+            return this.#values[key];
+        }
+        const envValue = process.env[key];
+        if (envValue) {
+            return envValue;
+        }
+        return defaultValue;
+    }
+    set(key, value) {
+        this.#values[key] = value;
+        process.env[key] = value;
+    }
+}

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/exceptions/missing_env_path_file.d.ts

@@ -0,0 +1,5 @@
+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

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

package/build/src/loader.d.ts

@@ -1,7 +1,9 @@
-/**
- * Reads `.env` file contents
- */
-export declare function envLoader(appRoot: string): {
-    envContents: string;
-    testEnvContent: string;
-};
+/// <reference types="node" resolution-mode="require"/>
+export declare class EnvLoader {
+    #private;
+    constructor(appRoot: string | URL);
+    load(): Promise<{
+        envContents: string;
+        currentEnvContents: string;
+    }>;
+}

package/build/src/loader.js

@@ -1,53 +1,34 @@
-"use strict";
-/*
- * @adonisjs/env
- *
- * (c) Harminder Virk <virk@adonisjs.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.envLoader = void 0;
-const fs_1 = require("fs");
-const path_1 = require("path");
-const utils_1 = require("@poppinss/utils");
-/**
- * Loads file from the disk and optionally ignores the missing
- * file errors
- */
-function loadFile(filePath, optional = false) {
-    try {
-        return (0, fs_1.readFileSync)(filePath, 'utf-8');
+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);
     }
-    catch (error) {
-        if (error.code !== 'ENOENT') {
-            throw error;
+    async #loadFile(filePath, optional = false) {
+        try {
+            return await readFile(filePath, 'utf-8');
         }
-        if (!optional) {
-            throw new utils_1.Exception(`The "${filePath}" file is missing`, 500, 'E_MISSING_ENV_FILE');
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+            if (optional) {
+                return '';
+            }
+            throw new MissingEnvPathFileException(`Cannot find env file from "ENV_PATH"`, {
+                cause: error,
+            });
         }
     }
-    return '';
-}
-/**
- * Reads `.env` file contents
- */
-function envLoader(appRoot) {
-    const envPath = process.env.ENV_PATH || '.env';
-    const absPath = (0, path_1.isAbsolute)(envPath) ? envPath : (0, path_1.join)(appRoot, envPath);
-    const envContents = loadFile(absPath, true);
-    /**
-     * Optionally load the `.env.test` and `.env.testing` files
-     * in test environment
-     */
-    let testEnvContent = '';
-    if (process.env.NODE_ENV === 'testing') {
-        testEnvContent = loadFile((0, path_1.join)(appRoot, '.env.testing'), true);
-    }
-    else if (process.env.NODE_ENV === 'test') {
-        testEnvContent = loadFile((0, path_1.join)(appRoot, '.env.test'), true);
+    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 };
     }
-    return { testEnvContent, envContents };
 }
-exports.envLoader = envLoader;

package/build/src/parser.d.ts

@@ -0,0 +1,6 @@
+import { DotenvParseOutput } from 'dotenv';
+export declare class EnvParser {
+    #private;
+    constructor(envContents: string);
+    parse(): DotenvParseOutput;
+}

package/build/src/parser.js

@@ -0,0 +1,60 @@
+import dotenv from 'dotenv';
+export class EnvParser {
+    #envContents;
+    constructor(envContents) {
+        this.#envContents = envContents;
+    }
+    #getValue(key, parsed) {
+        if (parsed[key]) {
+            return this.#interpolate(parsed[key], parsed);
+        }
+        return '';
+    }
+    #interpolateMustache(token, parsed) {
+        const closingBrace = token.indexOf('}');
+        if (closingBrace === -1) {
+            return token;
+        }
+        const varReference = token.slice(1, closingBrace).trim();
+        return `${this.#getValue(varReference, parsed)}${token.slice(closingBrace + 1)}`;
+    }
+    #interpolateVariable(token, parsed) {
+        return token.replace(/[a-zA-Z0-9_]+/, (key) => {
+            return this.#getValue(key, parsed);
+        });
+    }
+    #interpolate(value, parsed) {
+        const tokens = value.split('$');
+        let newValue = '';
+        let skipNextToken = true;
+        tokens.forEach((token) => {
+            if (token === '\\') {
+                newValue += '$';
+                skipNextToken = true;
+                return;
+            }
+            if (skipNextToken) {
+                newValue += token.replace(/\\$/, '$');
+                if (token.endsWith('\\')) {
+                    return;
+                }
+            }
+            else {
+                if (token.startsWith('{')) {
+                    newValue += this.#interpolateMustache(token, parsed);
+                    return;
+                }
+                newValue += this.#interpolateVariable(token, parsed);
+            }
+            skipNextToken = false;
+        });
+        return newValue;
+    }
+    parse() {
+        const envCollection = dotenv.parse(this.#envContents.trim());
+        return Object.keys(envCollection).reduce((result, key) => {
+            result[key] = this.#interpolate(envCollection[key], envCollection);
+            return result;
+        }, {});
+    }
+}

package/build/src/validator.d.ts

@@ -0,0 +1,12 @@
+import { ValidateFn } from '@poppinss/validator-lite';
+export declare class EnvValidator<Schema extends {
+    [key: string]: ValidateFn<unknown>;
+}> {
+    #private;
+    constructor(schema: Schema);
+    validate(values: {
+        [K: string]: string | undefined;
+    }): {
+        [K in keyof Schema]: ReturnType<Schema[K]>;
+    };
+}

package/build/src/validator.js

@@ -0,0 +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) {
+        const help = [];
+        const validated = Object.keys(this.#schema).reduce((result, key) => {
+            try {
+                result[key] = this.#schema[key](key, values[key]);
+            }
+            catch (error) {
+                help.push(`- ${error.message}`);
+            }
+            return result;
+        }, { ...values });
+        if (help.length) {
+            this.#error.help = help.join('\n');
+            throw this.#error;
+        }
+        return validated;
+    }
+}