@adonisjs/env 4.2.0-2 → 4.2.0-4

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.
 
@@ -135,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"
@@ -146,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.d.ts

@@ -1,7 +1,5 @@
 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';
-//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -1,6 +1,13 @@
+/*
+ * @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/build/src/debug.d.ts

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

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,14 +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>;
 }
-//# sourceMappingURL=editor.d.ts.map

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,28 +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;
 }
-//# sourceMappingURL=env.d.ts.map

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';
-class Env {
+/**
+ * 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) {
@@ -31,4 +78,3 @@ class Env {
         process.env[key] = value;
     }
 }
-export { Env };

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;
@@ -22,4 +26,3 @@ 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.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,11 +1,36 @@
-/// <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;
         fileExists: boolean;
     }[]>;
 }
-//# sourceMappingURL=loader.d.ts.map

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,9 +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;
 }
-//# sourceMappingURL=parser.d.ts.map