@adonisjs/env 4.2.0-2 → 4.2.0-4

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

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,13 +1,25 @@
 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;
     }): {
         [K in keyof Schema]: ReturnType<Schema[K]>;
     };
 }
-//# sourceMappingURL=validator.d.ts.map

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/package.json

@@ -1,24 +1,26 @@
 {
   "name": "@adonisjs/env",
-  "version": "4.2.0-2",
+  "version": "4.2.0-4",
   "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"
+    ".": "./build/index.js",
+    "./editor": "./build/src/editor.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",
@@ -27,7 +29,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",
@@ -36,34 +38,32 @@
   "author": "virk,adonisjs",
   "license": "MIT",
   "devDependencies": {
-    "@commitlint/cli": "^17.5.0",
-    "@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",
-    "@swc/core": "^1.3.42",
-    "@types/node": "^18.15.9",
-    "c8": "^7.13.0",
+    "@adonisjs/eslint-config": "^1.1.8",
+    "@adonisjs/prettier-config": "^1.1.8",
+    "@adonisjs/tsconfig": "^1.1.8",
+    "@commitlint/cli": "^17.6.7",
+    "@commitlint/config-conventional": "^17.6.7",
+    "@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.71",
+    "@types/node": "^20.4.5",
+    "c8": "^8.0.1",
     "cross-env": "^7.0.3",
     "del-cli": "^5.0.0",
-    "eslint": "^8.36.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-adonis": "^3.0.3",
-    "eslint-plugin-prettier": "^4.2.1",
+    "eslint": "^8.45.0",
     "github-label-sync": "^2.3.1",
     "husky": "^8.0.3",
-    "np": "^7.6.4",
-    "prettier": "^2.8.7",
+    "np": "^8.0.4",
+    "prettier": "^3.0.0",
     "ts-node": "^10.9.1",
-    "typescript": "^5.0.2"
+    "typescript": "^5.1.6"
   },
   "dependencies": {
-    "@poppinss/utils": "^6.5.0-2",
+    "@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 +74,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 +97,9 @@
     "exclude": [
       "tests/**"
     ]
-  }
+  },
+  "eslintConfig": {
+    "extends": "@adonisjs/eslint-config/package"
+  },
+  "prettier": "@adonisjs/prettier-config"
 }

package/build/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA"}

package/build/src/debug.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":";;AAUA,wBAAuC"}

package/build/src/editor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../../src/editor.ts"],"names":[],"mappings":";AAeA,qBAAa,SAAS;;WASP,MAAM,CAAC,OAAO,EAAE,GAAG;gBAOpB,OAAO,EAAE,GAAG;IASlB,IAAI;IAoBV,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IASjD,MAAM;;;;IAOA,IAAI;CAOX"}

package/build/src/env.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":";AASA,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAiB7C,qBAAa,GAAG,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;gBAMxC,MAAM,EAAE,SAAS;WAShB,MAAM,CAAC,MAAM,SAAS;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;KAAE,EACvE,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CACR,GAAG,CAAC;SACD,CAAC,IAAI,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;KAC3C,CAAC,CACH;IASD,MAAM,CAAC,MAAM;;;;;MAAY;IAOzB,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;KAAE,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;IAoB1F,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IACpD,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAC3B,GAAG,EAAE,CAAC,EACN,YAAY,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAoC9C,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAKtC"}

package/build/src/exceptions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/exceptions.ts"],"names":[],"mappings":";AAeA,eAAO,MAAM,uBAAuB;;;;;cAG5B,MAAM;;;;;;;;;;;;;;;;;CACb,CAAA"}

package/build/src/loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/loader.ts"],"names":[],"mappings":";AAqCA,qBAAa,SAAS;;gBAIR,OAAO,EAAE,MAAM,GAAG,GAAG,EAAE,eAAe,GAAE,OAAe;IA0B7D,IAAI,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAiFjF"}

package/build/src/parser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser.ts"],"names":[],"mappings":"AASA,OAAe,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AA0ClD,qBAAa,SAAS;;gBAIR,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,gBAAgB,EAAE,OAAO,CAAA;KAAE;IAyHxE,KAAK,IAAI,iBAAiB;CAQ3B"}

package/build/src/processor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../src/processor.ts"],"names":[],"mappings":";AAgBA,qBAAa,YAAY;;gBAMX,OAAO,EAAE,GAAG;IAyDlB,OAAO;CAGd"}

package/build/src/validator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAUrD,qBAAa,YAAY,CAAC,MAAM,SAAS;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;CAAE;;gBAIjE,MAAM,EAAE,MAAM;IAY1B,QAAQ,CAAC,MAAM,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG;SACpD,CAAC,IAAI,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;KAC3C;CAwBF"}

package/index.ts

@@ -1,15 +0,0 @@
-/*
- * @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/src/debug.ts

@@ -1,11 +0,0 @@
-/*
- * @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

@@ -1,84 +0,0 @@
-/*
- * @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'))
-      })
-    )
-  }
-}