@adonisjs/env 4.2.0-1 → 4.2.0-3

package/build/src/parser.js

@@ -1,4 +1,52 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import dotenv 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 class EnvParser {
     #envContents;
     #preferProcessEnv = true;
@@ -8,6 +56,9 @@ export class EnvParser {
         }
         this.#envContents = envContents;
     }
+    /**
+     * Returns the value from the parsed object
+     */
     #getValue(key, parsed) {
         if (this.#preferProcessEnv && process.env[key]) {
             return process.env[key];
@@ -17,46 +68,94 @@ export class EnvParser {
         }
         return process.env[key] || '';
     }
+    /**
+     * Interpolating the token wrapped inside the mustache braces.
+     */
     #interpolateMustache(token, parsed) {
+        /**
+         * Finding the closing brace. If closing brace is missing, we
+         * consider the block as a normal string
+         */
         const closingBrace = token.indexOf('}');
         if (closingBrace === -1) {
             return token;
         }
+        /**
+         * Then we pull everything until the closing brace, except
+         * the opening brace and trim off all white spaces.
+         */
         const varReference = token.slice(1, closingBrace).trim();
+        /**
+         * Getting the value of the reference inside the braces
+         */
         return `${this.#getValue(varReference, parsed)}${token.slice(closingBrace + 1)}`;
     }
+    /**
+     * Interpolating the variable reference starting with a
+     * `$`. We only capture numbers,letter and underscore.
+     * For other characters, one can use the mustache
+     * braces.
+     */
     #interpolateVariable(token, parsed) {
         return token.replace(/[a-zA-Z0-9_]+/, (key) => {
             return this.#getValue(key, parsed);
         });
     }
+    /**
+     * Interpolates the referenced values
+     */
     #interpolate(value, parsed) {
         const tokens = value.split('$');
         let newValue = '';
         let skipNextToken = true;
         tokens.forEach((token) => {
+            /**
+             * If the value is an escaped sequence, then we replace it
+             * with a `$` and then skip the next token.
+             */
             if (token === '\\') {
                 newValue += '$';
                 skipNextToken = true;
                 return;
             }
+            /**
+             * Use the value as it is when "skipNextToken" is set to true.
+             */
             if (skipNextToken) {
+                /**
+                 * Replace the ending escape sequence with a $
+                 */
                 newValue += token.replace(/\\$/, '$');
+                /**
+                 *  and then skip the next token if it ends with escape sequence
+                 */
                 if (token.endsWith('\\')) {
                     return;
                 }
             }
             else {
+                /**
+                 * Handle mustache block
+                 */
                 if (token.startsWith('{')) {
                     newValue += this.#interpolateMustache(token, parsed);
                     return;
                 }
+                /**
+                 * Process all words as variable
+                 */
                 newValue += this.#interpolateVariable(token, parsed);
             }
+            /**
+             * Process next token
+             */
             skipNextToken = false;
         });
         return newValue;
     }
+    /**
+     * Parse the env string to an object of environment variables.
+     */
     parse() {
         const envCollection = dotenv.parse(this.#envContents.trim());
         return Object.keys(envCollection).reduce((result, key) => {

package/build/src/processor.d.ts

@@ -1,6 +1,12 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
+/**
+ * Env processors loads, parses and process environment variables.
+ */
 export declare class EnvProcessor {
     #private;
     constructor(appRoot: URL);
+    /**
+     * Process env variables
+     */
     process(): Promise<Record<string, any>>;
 }

package/build/src/processor.js

@@ -1,12 +1,32 @@
+/*
+ * @adonisjs/application
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import debug from './debug.js';
 import { EnvParser } from './parser.js';
 import { EnvLoader } from './loader.js';
+/**
+ * Env processors loads, parses and process environment variables.
+ */
 export class EnvProcessor {
+    /**
+     * App root is needed to load files
+     */
     #appRoot;
     constructor(appRoot) {
         this.#appRoot = appRoot;
     }
+    /**
+     * Parse env variables from raw contents
+     */
     #processContents(envContents, store) {
+        /**
+         * Collected env variables
+         */
         if (!envContents.trim()) {
             return store;
         }
@@ -23,16 +43,25 @@ export class EnvProcessor {
         });
         return store;
     }
+    /**
+     * Parse env variables by loading dot files.
+     */
     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));
         }
+        /**
+         * Collected env variables
+         */
         const envValues = {};
         envFiles.forEach(({ contents }) => this.#processContents(contents, envValues));
         return envValues;
     }
+    /**
+     * Process env variables
+     */
     async process() {
         return this.#loadAndProcessDotFiles();
     }

package/build/src/validator.d.ts

@@ -1,9 +1,22 @@
 import { ValidateFn } from '@poppinss/validator-lite';
+/**
+ * Exposes the API to validate environment variables against a
+ * pre-defined schema.
+ *
+ * The class is not exported in the main API and used internally.
+ */
 export declare class EnvValidator<Schema extends {
     [key: string]: ValidateFn<unknown>;
 }> {
     #private;
     constructor(schema: Schema);
+    /**
+     * Accepts an object of values to validate against the pre-defined
+     * schema.
+     *
+     * The return value is a merged copy of the original object and the
+     * values mutated by the schema validator.
+     */
     validate(values: {
         [K: string]: string | undefined;
     }): {

package/build/src/validator.js

@@ -1,4 +1,18 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { E_INVALID_ENV_VARIABLES } from './exceptions.js';
+/**
+ * Exposes the API to validate environment variables against a
+ * pre-defined schema.
+ *
+ * The class is not exported in the main API and used internally.
+ */
 export class EnvValidator {
     #schema;
     #error;
@@ -6,6 +20,13 @@ export class EnvValidator {
         this.#schema = schema;
         this.#error = new E_INVALID_ENV_VARIABLES();
     }
+    /**
+     * Accepts an object of values to validate against the pre-defined
+     * schema.
+     *
+     * The return value is a merged copy of the original object and the
+     * values mutated by the schema validator.
+     */
     validate(values) {
         const help = [];
         const validated = Object.keys(this.#schema).reduce((result, key) => {

package/index.ts

@@ -0,0 +1,15 @@
+/*
+ * @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/package.json

@@ -1,21 +1,28 @@
 {
   "name": "@adonisjs/env",
-  "version": "4.2.0-1",
+  "version": "4.2.0-3",
   "description": "Environment variable manager for Node.js",
   "main": "build/index.js",
   "type": "module",
   "files": [
+    "src",
+    "index.ts",
     "build/src",
     "build/index.d.ts",
+    "build/index.d.ts.map",
     "build/index.js"
   ],
   "exports": {
     ".": "./build/index.js"
   },
+  "engines": {
+    "node": ">=18.16.0"
+  },
   "scripts": {
     "pretest": "npm run lint",
-    "test": "cross-env NODE_DEBUG=adonisjs:env c8 npm run vscode:test",
+    "test": "cross-env NODE_DEBUG=adonisjs:env c8 npm run quick:test",
     "clean": "del-cli build",
+    "typecheck": "tsc --noEmit",
     "compile": "npm run lint && npm run clean && tsc",
     "build": "npm run compile",
     "release": "np",
@@ -24,7 +31,7 @@
     "lint": "eslint . --ext=.ts",
     "format": "prettier --write .",
     "sync-labels": "github-label-sync --labels .github/labels.json adonisjs/env",
-    "vscode:test": "node --loader=ts-node/esm bin/test.ts"
+    "quick:test": "node --loader=ts-node/esm bin/test.ts"
   },
   "keywords": [
     "env",
@@ -33,37 +40,32 @@
   "author": "virk,adonisjs",
   "license": "MIT",
   "devDependencies": {
-    "@commitlint/cli": "^17.4.4",
-    "@commitlint/config-conventional": "^17.4.4",
-    "@japa/assert": "^1.4.1",
-    "@japa/expect-type": "^1.0.3",
-    "@japa/file-system": "^1.0.1",
-    "@japa/run-failed-tests": "^1.1.1",
-    "@japa/runner": "^2.5.1",
-    "@japa/spec-reporter": "^1.3.3",
-    "@poppinss/dev-utils": "^2.0.3",
-    "@swc/core": "^1.3.40",
-    "@types/fs-extra": "^11.0.1",
-    "@types/node": "^18.15.3",
-    "c8": "^7.13.0",
+    "@adonisjs/eslint-config": "^1.1.7",
+    "@adonisjs/prettier-config": "^1.1.7",
+    "@adonisjs/tsconfig": "^1.1.7",
+    "@commitlint/cli": "^17.6.6",
+    "@commitlint/config-conventional": "^17.6.6",
+    "@japa/assert": "^2.0.0-1",
+    "@japa/expect-type": "^2.0.0-0",
+    "@japa/file-system": "^2.0.0-1",
+    "@japa/runner": "^3.0.0-3",
+    "@swc/core": "^1.3.67",
+    "@types/node": "^20.3.3",
+    "c8": "^8.0.0",
     "cross-env": "^7.0.3",
     "del-cli": "^5.0.0",
-    "eslint": "^8.36.0",
-    "eslint-config-prettier": "^8.7.0",
-    "eslint-plugin-adonis": "^3.0.3",
-    "eslint-plugin-prettier": "^4.2.1",
-    "fs-extra": "^11.1.0",
+    "eslint": "^8.44.0",
     "github-label-sync": "^2.3.1",
     "husky": "^8.0.3",
-    "np": "^7.6.3",
-    "prettier": "^2.8.4",
+    "np": "^8.0.4",
+    "prettier": "^2.8.8",
     "ts-node": "^10.9.1",
-    "typescript": "^4.9.5"
+    "typescript": "^5.1.6"
   },
   "dependencies": {
-    "@poppinss/utils": "^6.5.0-1",
+    "@poppinss/utils": "^6.5.0-3",
     "@poppinss/validator-lite": "^1.0.3",
-    "dotenv": "^16.0.3",
+    "dotenv": "^16.3.1",
     "split-lines": "^3.0.0"
   },
   "repository": {
@@ -74,36 +76,6 @@
     "url": "https://github.com/adonisjs/env/issues"
   },
   "homepage": "https://github.com/adonisjs/env#readme",
-  "eslintConfig": {
-    "extends": [
-      "plugin:adonis/typescriptPackage",
-      "prettier"
-    ],
-    "plugins": [
-      "prettier"
-    ],
-    "rules": {
-      "prettier/prettier": [
-        "error",
-        {
-          "endOfLine": "auto"
-        }
-      ]
-    }
-  },
-  "eslintIgnore": [
-    "build"
-  ],
-  "prettier": {
-    "trailingComma": "es5",
-    "semi": false,
-    "singleQuote": true,
-    "useTabs": false,
-    "quoteProps": "consistent",
-    "bracketSpacing": true,
-    "arrowParens": "always",
-    "printWidth": 100
-  },
   "commitlint": {
     "extends": [
       "@commitlint/config-conventional"
@@ -127,5 +99,9 @@
     "exclude": [
       "tests/**"
     ]
-  }
+  },
+  "eslintConfig": {
+    "extends": "@adonisjs/eslint-config/package"
+  },
+  "prettier": "@adonisjs/prettier-config"
 }

package/src/debug.ts

@@ -0,0 +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 { debuglog } from 'node:util'
+export default debuglog('adonisjs:env')

package/src/editor.ts

@@ -0,0 +1,84 @@
+/*
+ * @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'
+
+import { EnvLoader } from './loader.js'
+
+export class EnvEditor {
+  #appRoot: URL
+  #loader: EnvLoader
+  #files: { contents: string[]; path: string }[] = []
+
+  /**
+   * Creates an instance of env editor and loads .env files
+   * contents.
+   */
+  static async create(appRoot: URL) {
+    const editor = new EnvEditor(appRoot)
+    await editor.load()
+
+    return editor
+  }
+
+  constructor(appRoot: URL) {
+    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
+      .filter(
+        (envFile) =>
+          envFile.fileExists &&
+          (envFile.path.endsWith('.env') || envFile.path.endsWith('.env.example'))
+      )
+      .map((envFile) => {
+        return {
+          contents: splitLines(envFile.contents.trim()),
+          path: envFile.path,
+        }
+      })
+  }
+
+  /**
+   * Add key-value pair to the dot-env files.
+   */
+  add(key: string, value: string | number | boolean) {
+    this.#files.forEach((file) => {
+      let entryIndex = file.contents.findIndex((line) => line.startsWith(`${key}=`))
+
+      entryIndex = entryIndex === -1 ? file.contents.length : entryIndex
+      lodash.set(file.contents, entryIndex, `${key}=${String(value)}`)
+    })
+  }
+
+  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/src/env.ts

@@ -0,0 +1,134 @@
+/*
+ * @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, type ValidateFn } 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<EnvValues extends Record<string, any>> {
+  /**
+   * A cache of env values
+   */
+  #values: EnvValues
+
+  constructor(values: EnvValues) {
+    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<Schema extends { [key: string]: ValidateFn<unknown> }>(
+    appRoot: URL,
+    schema: Schema
+  ): Promise<
+    Env<{
+      [K in keyof Schema]: ReturnType<Schema[K]>
+    }>
+  > {
+    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<T extends { [key: string]: ValidateFn<unknown> }>(schema: T): EnvValidator<T> {
+    const validator = new EnvValidator<T>(schema)
+    return validator
+  }
+
+  /**
+   * 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
+  get(key: string, defaultValue?: any): any {
+    /**
+     * 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
+  }
+
+  /**
+   * 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
+  set(key: string | keyof EnvValues, value: any): void {
+    this.#values[key] = value
+    process.env[key as string] = value
+  }
+}

package/src/exceptions.ts

@@ -0,0 +1,20 @@
+/*
+ * @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'
+  help: string = ''
+}