@adonisjs/env 4.2.0-1 → 4.2.0-3

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

@@ -1,7 +1,7 @@
 # @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]
+[![gh-workflow-image]][gh-workflow-url] [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
 
 > **Note:** This package is framework agnostic and can also be used outside of AdonisJS.
 
@@ -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.
@@ -138,8 +135,8 @@ try {
 }
 ```
 
-[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/env/test.yml?style=for-the-badge
-[gh-workflow-url]: https://github.com/adonisjs/env/actions/workflows/test.yml "Github action"
+[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/env/checks.yml?style=for-the-badge
+[gh-workflow-url]: https://github.com/adonisjs/env/actions/workflows/checks.yml "Github action"
 
 [typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
 [typescript-url]:  "typescript"
@@ -149,6 +146,3 @@ try {
 
 [license-image]: https://img.shields.io/npm/l/@adonisjs/env?color=blueviolet&style=for-the-badge
 [license-url]: LICENSE.md "license"
-
-[synk-image]: https://img.shields.io/snyk/vulnerabilities/github/adonisjs/env?label=Synk%20Vulnerabilities&style=for-the-badge
-[synk-url]: https://snyk.io/test/github/adonisjs/env?targetFile=package.json "synk"

package/build/index.js

@@ -1,3 +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.
+ */
 export { Env } from './src/env.js';
 export { EnvParser } from './src/parser.js';
 export { EnvLoader } from './src/loader.js';

package/build/src/debug.d.ts

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

package/build/src/debug.js

@@ -1,2 +1,10 @@
+/*
+ * @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/build/src/editor.d.ts

@@ -1,13 +1,27 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
 export declare class EnvEditor {
     #private;
+    /**
+     * Creates an instance of env editor and loads .env files
+     * contents.
+     */
     static create(appRoot: URL): Promise<EnvEditor>;
     constructor(appRoot: URL);
+    /**
+     * Loads .env files for editing. Only ".env" and ".env.example"
+     * files are picked for editing.
+     */
     load(): Promise<void>;
+    /**
+     * Add key-value pair to the dot-env files.
+     */
     add(key: string, value: string | number | boolean): void;
     toJSON(): {
         contents: string[];
         path: string;
     }[];
+    /**
+     * Save changes to the disk
+     */
     save(): Promise<void>;
 }

package/build/src/editor.js

@@ -1,3 +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 splitLines from 'split-lines';
 import lodash from '@poppinss/utils/lodash';
 import { writeFile } from 'node:fs/promises';
@@ -6,6 +14,10 @@ export class EnvEditor {
     #appRoot;
     #loader;
     #files = [];
+    /**
+     * Creates an instance of env editor and loads .env files
+     * contents.
+     */
     static async create(appRoot) {
         const editor = new EnvEditor(appRoot);
         await editor.load();
@@ -15,6 +27,10 @@ export class EnvEditor {
         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
@@ -27,6 +43,9 @@ export class EnvEditor {
             };
         });
     }
+    /**
+     * Add key-value pair to the dot-env files.
+     */
     add(key, value) {
         this.#files.forEach((file) => {
             let entryIndex = file.contents.findIndex((line) => line.startsWith(`${key}=`));
@@ -37,6 +56,9 @@ export class EnvEditor {
     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/build/src/env.d.ts

@@ -1,27 +1,82 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
 import { type ValidateFn } from '@poppinss/validator-lite';
 import { EnvValidator } from './validator.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 declare class Env<EnvValues extends Record<string, any>> {
     #private;
     constructor(values: EnvValues);
+    /**
+     * Create an instance of the env class by validating the
+     * environment variables. Also, the `.env` files are
+     * loaded from the appRoot
+     */
     static create<Schema extends {
         [key: string]: ValidateFn<unknown>;
     }>(appRoot: URL, schema: Schema): Promise<Env<{
         [K in keyof Schema]: ReturnType<Schema[K]>;
     }>>;
+    /**
+     * The schema builder for defining validation rules
+     */
     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;
     };
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * 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;
 }

package/build/src/env.js

@@ -1,29 +1,76 @@
+/*
+ * @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 } 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 {
+    /**
+     * A cache of env values
+     */
     #values;
     constructor(values) {
         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(appRoot, schema) {
         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(schema) {
         const validator = new EnvValidator(schema);
         return validator;
     }
     get(key, defaultValue) {
+        /**
+         * 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;
     }
     set(key, value) {

package/build/src/exceptions.d.ts

@@ -1,4 +1,8 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
+/**
+ * Exception raised when one or more env variables
+ * are invalid
+ */
 export declare const E_INVALID_ENV_VARIABLES: {
     new (message?: string | undefined, options?: (ErrorOptions & {
         code?: string | undefined;

package/build/src/exceptions.js

@@ -1,4 +1,16 @@
+/*
+ * @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';

package/build/src/loader.d.ts

@@ -1,7 +1,33 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
+/**
+ * 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 declare class EnvLoader {
     #private;
     constructor(appRoot: string | URL, loadExampleFile?: boolean);
+    /**
+     * Load contents of the main dot-env file and the current
+     * environment dot-env file
+     */
     load(): Promise<{
         contents: string;
         path: string;

package/build/src/loader.js

@@ -1,7 +1,37 @@
+/*
+ * @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;
     #loadExampleFile;
@@ -9,18 +39,26 @@ export class EnvLoader {
         this.#appRoot = typeof appRoot === 'string' ? appRoot : fileURLToPath(appRoot);
         this.#loadExampleFile = loadExampleFile;
     }
+    /**
+     * Optionally read a file from the disk
+     */
     async #loadFile(filePath) {
         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() {
         const ENV_PATH = process.env.ENV_PATH;
         const NODE_ENV = process.env.NODE_ENV;
@@ -29,6 +67,9 @@ export class EnvLoader {
             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
@@ -37,6 +78,10 @@ export class EnvLoader {
         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({
@@ -44,6 +89,10 @@ export class EnvLoader {
                 ...(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({
@@ -51,6 +100,10 @@ export class EnvLoader {
                 ...(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({
@@ -58,11 +111,17 @@ export class EnvLoader {
                 ...(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({

package/build/src/parser.d.ts

@@ -1,8 +1,51 @@
 import { 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 declare class EnvParser {
     #private;
     constructor(envContents: string, options?: {
         ignoreProcessEnv: boolean;
     });
+    /**
+     * Parse the env string to an object of environment variables.
+     */
     parse(): DotenvParseOutput;
 }