@adonisjs/env - npm Package Compare versions

Comparing version 1.0.10 to 1.0.11

build/adonis-typings/env.d.ts

@@ -0,1 +1,4 @@
+/**
+ * @module @adonisjs/env
+ */
 declare module '@ioc:Adonis/Core/Env' {
@@ -5,3 +8,3 @@ export interface EnvContract {
         get(key: string, defaultValue?: any): string | boolean | null | undefined;
-        getOrFail(key: string, defaultValue?: any): string | boolean;
+        getOrFail(key: string): string | boolean;
         set(key: string, value: string): void;
@@ -8,0 +11,0 @@ }

build/providers/EnvProvider.d.ts

@@ -0,6 +1,15 @@
+/**
+ * @module @adonisjs/env
+ */
 import { IocContract } from '@adonisjs/fold';
+/**
+ * The AdonisJs provider to register the binding to the container
+ */
 export default class EnvProvider {
     protected $container: IocContract;
     constructor($container: IocContract);
+    /**
+     * Registers the binding to the AdonisJs container
+     */
     register(): void;
 }

build/providers/EnvProvider.js

 "use strict";
+/**
+ * @module @adonisjs/env
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 const Env_1 = require("../src/Env");
 const loader_1 = require("../src/loader");
+/**
+ * The AdonisJs provider to register the binding to the container
+ */
 class EnvProvider {
@@ -9,2 +15,5 @@ constructor($container) {
     }
+    /**
+     * Registers the binding to the AdonisJs container
+     */
     register() {
@@ -11,0 +20,0 @@ this.$container.singleton('Adonis/Core/Env', () => {

build/src/Env.d.ts

@@ -0,14 +1,114 @@
+/**
+ * @module @adonisjs/env
+ */
 /// <reference path="../adonis-typings/env.d.ts" />
 import { EnvContract } from '@ioc:Adonis/Core/Env';
+/**
+ * The ENV module enables the use of environment variables by parsing dotfiles syntax
+ * and updates the `process.env` object in Node.js.
+ *
+ * AdonisJs automatically reads and passes the contents of `.env` file to this class.
+ */
 export declare class Env implements EnvContract {
-    private _castValue;
-    private _getValue;
-    private _interpolateMustache;
-    private _interpolateEscapedSequence;
-    private _interpolateVariable;
-    private _interpolate;
+    /**
+     * Casts the string value to their native data type
+     * counter parts. Only done for `booleans` and
+     * `nulls`.
+     */
+    private castValue;
+    /**
+     * Returns value for a given key from the environment variables. Also
+     * the current parsed object is used to pull the reference.
+     */
+    private getValue;
+    /**
+     * Interpolating the token wrapped inside the mustache
+     * braces.
+     */
+    private interpolateMustache;
+    /**
+     * Interpolating the escaped sequence.
+     */
+    private interpolateEscapedSequence;
+    /**
+     * Interpolating the variable reference starting with a
+     * `$`. We only capture numbers,letter and underscore.
+     * For other characters, one can use the mustache
+     * braces.
+     */
+    private interpolateVariable;
+    /**
+     * Interpolates the referenced values
+     */
+    private interpolate;
+    /**
+     * Processes environment variables by parsing a string
+     * in `dotfile` syntax.
+     *
+     * @example
+     * ```ts
+     * Env.process(`
+     *  PORT=3000
+     *  HOST=127.0.0.1
+     * `)
+     * ```
+     *
+     * and then access it as follows
+     *
+     * ```ts
+     * Env.get('PORT')
+     *
+     * // or
+     * process.env.PORT
+     * ```
+     */
     process(envString: string, overwrite?: boolean): void;
+    /**
+     * Get value for a key from the process.env. Since `process.env` object stores all
+     * values as strings, this method will cast them to their counterpart datatypes.
+     *
+     * | Value | Casted value |
+     * |------|---------------|
+     * | 'true' | true |
+     * | '1' | true |
+     * | 'false' | false |
+     * | '0' | false |
+     * | 'null' | null |
+     *
+     * Everything else is returned as a string.
+     *
+     * A default value can also be defined which is returned when original value
+     * is undefined.
+     *
+     * @example
+     * ```ts
+     * Env.get('PORT', 3333)
+     * ```
+     */
     get(key: string, defaultValue?: any): string | boolean | null | undefined;
-    getOrFail(key: string, defaultValue?: any): string | boolean;
+    /**
+     * The method is similar to it's counter part [[get]] method. However, it will
+     * raise exception when the original value is non-existing.
+     *
+     * `undefined`, `null` and `empty strings` are considered as non-exisitng values.
+     *
+     * We recommended using this method for **environment variables** that are strongly
+     * required to run the application stably.
+     *
+     * @example
+     * ```ts
+     * Env.getOrFail('PORT')
+     * ```
+     */
+    getOrFail(key: string): string | boolean;
+    /**
+     * Update or set value for a given property
+     * inside `process.env`.
+     *
+     * @example
+     * ```ts
+     * Env.set('PORT', 3333)
+     * ```
+     */
     set(key: string, value: string): void;
 }

build/src/Env.js

 "use strict";
+/**
+ * @module @adonisjs/env
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
@@ -6,6 +9,26 @@ return (mod && mod.__esModule) ? mod : { "default": mod };
 Object.defineProperty(exports, "__esModule", { value: true });
+/*
+* @adonisjs/env
+*
+* (c) Harminder Virk <[e-mail]>
+*
+* For the full copyright and license information, please view the LICENSE
+* file that was distributed with this source code.
+*/
+/// <reference path="../adonis-typings/env.ts" />
 const dotenv_1 = __importDefault(require("dotenv"));
 const utils_1 = require("@poppinss/utils");
+/**
+ * The ENV module enables the use of environment variables by parsing dotfiles syntax
+ * and updates the `process.env` object in Node.js.
+ *
+ * AdonisJs automatically reads and passes the contents of `.env` file to this class.
+ */
 class Env {
-    _castValue(value) {
+    /**
+     * Casts the string value to their native data type
+     * counter parts. Only done for `booleans` and
+     * `nulls`.
+     */
+    castValue(value) {
         switch (value) {
@@ -24,3 +47,7 @@ case 'null':
     }
-    _getValue(key, parsed) {
+    /**
+     * Returns value for a given key from the environment variables. Also
+     * the current parsed object is used to pull the reference.
+     */
+    getValue(key, parsed) {
         if (process.env[key]) {
@@ -30,7 +57,15 @@ return process.env[key];
         if (parsed[key]) {
-            return this._interpolate(parsed[key], parsed);
+            return this.interpolate(parsed[key], parsed);
         }
         return '';
     }
-    _interpolateMustache(token, parsed) {
+    /**
+     * 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('}');
@@ -40,14 +75,33 @@ if (closingBrace === -1) {
         }
+        /**
+         * 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();
-        return `${this._getValue(varReference, parsed)}${token.slice(closingBrace + 1)}`;
+        /**
+         * Getting the value of the reference inside the braces
+         */
+        return `${this.getValue(varReference, parsed)}${token.slice(closingBrace + 1)}`;
     }
-    _interpolateEscapedSequence(value) {
+    /**
+     * Interpolating the escaped sequence.
+     */
+    interpolateEscapedSequence(value) {
         return `$${value}`;
     }
-    _interpolateVariable(token, parsed) {
+    /**
+     * 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);
+            return this.getValue(key, parsed);
         });
     }
-    _interpolate(value, parsed) {
+    /**
+     * Interpolates the referenced values
+     */
+    interpolate(value, parsed) {
         const tokens = value.split('$');
@@ -59,3 +113,3 @@ let newValue = '';
             if (token.indexOf('\\') === 0) {
-                newValue += this._interpolateEscapedSequence(tokens.shift());
+                newValue += this.interpolateEscapedSequence(tokens.shift());
             }
@@ -66,6 +120,6 @@ else if (isFirstToken) {
             else if (token.startsWith('{')) {
-                newValue += this._interpolateMustache(token, parsed);
+                newValue += this.interpolateMustache(token, parsed);
             }
             else {
-                newValue += this._interpolateVariable(token, parsed);
+                newValue += this.interpolateVariable(token, parsed);
             }
@@ -76,10 +130,57 @@ isFirstToken = false;
     }
+    /**
+     * Processes environment variables by parsing a string
+     * in `dotfile` syntax.
+     *
+     * @example
+     * ```ts
+     * Env.process(`
+     *  PORT=3000
+     *  HOST=127.0.0.1
+     * `)
+     * ```
+     *
+     * and then access it as follows
+     *
+     * ```ts
+     * Env.get('PORT')
+     *
+     * // or
+     * process.env.PORT
+     * ```
+     */
     process(envString, overwrite = false) {
         const envCollection = dotenv_1.default.parse(envString.trim());
+        /**
+         * Define/overwrite the process.env variables by looping
+         * over the collection
+         */
         Object.keys(envCollection).forEach((key) => {
             if (process.env[key] === undefined || overwrite) {
-                process.env[key] = this._interpolate(envCollection[key], envCollection);
+                process.env[key] = this.interpolate(envCollection[key], envCollection);
             }
         });
     }
+    /**
+     * Get value for a key from the process.env. Since `process.env` object stores all
+     * values as strings, this method will cast them to their counterpart datatypes.
+     *
+     * | Value | Casted value |
+     * |------|---------------|
+     * | 'true' | true |
+     * | '1' | true |
+     * | 'false' | false |
+     * | '0' | false |
+     * | 'null' | null |
+     *
+     * Everything else is returned as a string.
+     *
+     * A default value can also be defined which is returned when original value
+     * is undefined.
+     *
+     * @example
+     * ```ts
+     * Env.get('PORT', 3333)
+     * ```
+     */
     get(key, defaultValue) {
@@ -90,6 +191,20 @@ const value = process.env[key];
         }
-        return this._castValue(value);
+        return this.castValue(value);
     }
-    getOrFail(key, defaultValue) {
-        const value = this.get(key, defaultValue);
+    /**
+     * The method is similar to it's counter part [[get]] method. However, it will
+     * raise exception when the original value is non-existing.
+     *
+     * `undefined`, `null` and `empty strings` are considered as non-exisitng values.
+     *
+     * We recommended using this method for **environment variables** that are strongly
+     * required to run the application stably.
+     *
+     * @example
+     * ```ts
+     * Env.getOrFail('PORT')
+     * ```
+     */
+    getOrFail(key) {
+        const value = this.get(key);
         if (!value && value !== false) {
@@ -100,6 +215,15 @@ throw new utils_1.Exception(`Make sure to define environment variable ${key}`, 500, 'E_MISSING_ENV_KEY');
     }
+    /**
+     * Update or set value for a given property
+     * inside `process.env`.
+     *
+     * @example
+     * ```ts
+     * Env.set('PORT', 3333)
+     * ```
+     */
     set(key, value) {
-        process.env[key] = this._interpolate(value, {});
+        process.env[key] = this.interpolate(value, {});
     }
 }
 exports.Env = Env;

build/src/loader.d.ts

@@ -0,1 +1,7 @@
+/**
+ * @module @adonisjs/env
+ */
+/**
+ * Reads `.env` file contents
+ */
 export declare function envLoader(appRoot: string): {
@@ -2,0 +8,0 @@ envContents: string;

build/src/loader.js

 "use strict";
+/**
+ * @module @adonisjs/env
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+/*
+* @adonisjs/env
+*
+* (c) Harminder Virk <[e-mail]>
+*
+* For the full copyright and license information, please view the LICENSE
+* file that was distributed with this source code.
+*/
 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) {
@@ -20,2 +35,5 @@ try {
 }
+/**
+ * Reads `.env` file contents
+ */
 function envLoader(appRoot) {
@@ -25,2 +43,5 @@ const envPath = process.env.ENV_PATH || '.env';
     const envContents = loadFile(absPath, process.env.ENV_SILENT === 'true');
+    /**
+     * Optionally loading the `.env.testing` file in test environment
+     */
     let testEnvContent = '';
@@ -27,0 +48,0 @@ if (process.env.NODE_ENV === 'testing') {

build/standalone.d.ts

@@ -0,2 +1,8 @@
+/**
+ * @module @adonisjs/env
+ */
 import { Env } from './src/Env';
+/**
+ * Returns a singleton of `env` as named `Env` export.
+ */
 export declare const env: Env;

build/standalone.js

 "use strict";
+/**
+ * @module @adonisjs/env
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+/*
+* @adonisjs/env
+*
+* (c) Harminder Virk <[e-mail]>
+*
+* For the full copyright and license information, please view the LICENSE
+* file that was distributed with this source code.
+*/
 const Env_1 = require("./src/Env");
+/**
+ * Returns a singleton of `env` as named `Env` export.
+ */
 exports.env = new Env_1.Env();

package.json

 {
   "name": "@adonisjs/env",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "Environment variable manager for Node.js",
+  "main": "build/providers/EnvProvider.js",
   "files": [
@@ -16,3 +17,3 @@ "build/adonis-typings",
     "test": "node japaFile.js",
-    "lint": "tslint --project tsconfig.json",
+    "lint": "eslint . --ext=.ts",
     "clean": "del build",
@@ -32,7 +33,7 @@ "compile": "npm run lint && npm run clean && tsc",
   "devDependencies": {
-    "@adonisjs/fold": "^6.1.7",
-    "@adonisjs/mrm-preset": "^2.1.0",
-    "@poppinss/dev-utils": "^1.0.1",
-    "@types/dotenv": "^6.1.1",
-    "@types/node": "^12.7.4",
+    "@adonisjs/fold": "^6.2.3",
+    "@adonisjs/mrm-preset": "^2.2.3",
+    "@poppinss/dev-utils": "^1.0.3",
+    "@types/dotenv": "^8.2.0",
+    "@types/node": "^12.12.21",
     "commitizen": "^4.0.3",
@@ -42,13 +43,13 @@ "cz-conventional-changelog": "^3.0.2",
     "doctoc": "^1.4.0",
-    "husky": "^3.0.5",
+    "eslint": "^6.8.0",
+    "eslint-plugin-adonis": "^1.0.4",
+    "husky": "^3.1.0",
     "japa": "^3.0.1",
-    "mrm": "^1.2.2",
-    "np": "^5.0.3",
-    "ts-node": "^8.3.0",
-    "tslint": "^5.19.0",
-    "tslint-eslint-rules": "^5.4.0",
-    "typedoc": "^0.15.0",
+    "mrm": "^2.0.2",
+    "np": "^5.2.1",
+    "ts-node": "^8.5.4",
+    "typedoc": "^0.15.5",
     "typedoc-plugin-external-module-name": "^2.1.0",
-    "typedoc-plugin-markdown": "^2.1.11",
-    "typescript": "^3.6.2"
+    "typedoc-plugin-markdown": "^2.2.14",
+    "typescript": "^3.7.4"
   },
@@ -79,4 +80,4 @@ "nyc": {
   "dependencies": {
-    "@poppinss/utils": "^2.0.0",
-    "dotenv": "^8.1.0"
+    "@poppinss/utils": "^2.1.1",
+    "dotenv": "^8.2.0"
   },
@@ -83,0 +84,0 @@ "directories": {

README.md

@@ -22,3 +22,2 @@ <div align="center">
 - [API](#api)
-- [Maintainers](#maintainers)
 
@@ -67,4 +66,4 @@ <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 ```ts
-export const providers = [
-  '@adonisjs/env/build/providers/EnvProvider',
+"providers": [
+  "@adonisjs/env",
 ]
@@ -159,4 +158,2 @@ ```
 
-## Maintainers
-[Harminder virk](https://github.com/thetutlage)
 
@@ -166,8 +163,9 @@ [circleci-image]: https://img.shields.io/circleci/project/github/adonisjs/env/master.svg?style=for-the-badge&logo=circleci
 
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]:  "typescript"
+
 [npm-image]: https://img.shields.io/npm/v/@adonisjs/env.svg?style=for-the-badge&logo=npm
 [npm-url]: https://npmjs.org/package/@adonisjs/env "npm"
 
-[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
-
-[license-url]: LICENSE.md
-[license-image]: https://img.shields.io/aur/license/pac.svg?style=for-the-badge
+[license-image]: https://img.shields.io/npm/l/@adonisjs/env?color=blueviolet&style=for-the-badge
+[license-url]: LICENSE.md "license"

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

21954

increased by48.07%

Lines of code

481

increased by158.6%

Worsened metrics

Number of lines in readme file

168

decreased by-1.18%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• Updated@poppinss/utils@^2.1.1

• Updateddotenv@^8.2.0