@humanwhocodes/env - npm Package Compare versions

Comparing version 2.2.2 to 3.0.1

dist/env.cjs.js

@@ -35,20 +35,58 @@ 'use strict';
 
+//-----------------------------------------------------------------------------
+// Errors
+//-----------------------------------------------------------------------------
+
 /**
- * Throws an error saying that the key was not found.
- * @param {PropertyKey} key The key to report as missing.
- * @returns {void}
- * @throws {Error} Always. 
+ * The error thrown when a required key is not found.
  */
-function keyNotFound(key) {
-    throw new Error(`Required environment variable '${String(key)}' not found.`);
+class EnvKeyNotFoundError extends Error {
+
+    /**
+     * Creates a new instance.
+     * @param {PropertyKey} key The key that wasn't found. 
+     */
+    constructor(key) {
+
+        super(`Required environment variable '${String(key)}' not found.`);
+
+        /**
+         * The key that wasn't found.
+         * @type {PropertyKey}
+         */
+        this.key = key;
+
+        /**
+         * Easily identifiable name for this error type.
+         * @type {string}
+         */
+        this.name = "EnvKeyNotFoundError";
+    }
 }
 
 /**
- * Throws an error saying that the key was an empty string.
- * @param {PropertyKey} key The key to report as an empty string.
- * @returns {void}
- * @throws {Error} Always.
+ * The error thrown when a required key is present but is an empty string.
  */
-function emptyString(key) {
-    throw new Error(`Required environment variable '${String(key)}' is an empty string.`);
+class EnvEmptyStringError extends Error {
+
+    /**
+     * Creates a new instance.
+     * @param {PropertyKey} key The key that wasn't found. 
+     */
+    constructor(key) {
+
+        super(`Required environment variable '${String(key)}' is an empty string.`);
+
+        /**
+         * The key that wasn't found.
+         * @type {PropertyKey}
+         */
+        this.key = key;
+
+        /**
+         * Easily identifiable name for this error type.
+         * @type {string}
+         */
+        this.name = "EnvEmptyStringError";
+    }
 }
@@ -151,5 +189,5 @@
         if (typeof value === "undefined") {
-            keyNotFound(key);
+            throw new Env.KeyNotFoundError(key);
         } else if (value === "") {
-            emptyString(key);
+            throw new Env.EmptyStringError(key);
         } else {
@@ -173,5 +211,5 @@ return value;
         if (typeof value === "undefined") {
-            keyNotFound(`[${keys}]`);
+            throw new Env.KeyNotFoundError(`[${keys}]`);
         } else if (value === "") {
-            emptyString(`[${keys}]`);
+            throw new Env.EmptyStringError(`[${keys}]`);
         } else {
@@ -196,3 +234,3 @@ return value;
                 
-                keyNotFound(key);
+                throw new Env.KeyNotFoundError(key);
             }
@@ -225,3 +263,3 @@ });
                     if (target[key] === "") {
-                        emptyString(key);
+                        throw new Env.EmptyStringError(key);
                     }
@@ -232,3 +270,3 @@
                 
-                keyNotFound(key);
+                throw new Env.KeyNotFoundError(key);
             }
@@ -251,2 +289,16 @@ });
 
+/**
+ * The error to use when a key isn't found.
+ * @type {new (key: PropertyKey) => Error}
+ */
+Env.KeyNotFoundError = EnvKeyNotFoundError;
+
+/**
+ * The error to use when a key isn't found.
+ * @type {new (key: PropertyKey) => Error}
+ */
+Env.EmptyStringError = EnvEmptyStringError;
+
 exports.Env = Env;
+exports.EnvEmptyStringError = EnvEmptyStringError;
+exports.EnvKeyNotFoundError = EnvKeyNotFoundError;

dist/env.d.ts

 /**
+ * The error thrown when a required key is not found.
+ */
+export class EnvKeyNotFoundError extends Error {
+    /**
+     * Creates a new instance.
+     * @param {string} key The key that wasn't found.
+     */
+    constructor(key: string);
+    /**
+     * The key that wasn't found.
+     * @type {string}
+     */
+    key: string;
+}
+/**
+ * The error thrown when a required key is present but is an empty string.
+ */
+export class EnvEmptyStringError extends Error {
+    /**
+     * Creates a new instance.
+     * @param {string} key The key that wasn't found.
+     */
+    constructor(key: string);
+    /**
+     * The key that wasn't found.
+     * @type {string}
+     */
+    key: string;
+}
+/**
  * A utility for interacting with environment variables
@@ -80,1 +110,5 @@ */
 }
+export namespace Env {
+    export { EnvKeyNotFoundError as KeyNotFoundError };
+    export { EnvEmptyStringError as EmptyStringError };
+}

dist/env.js

@@ -31,20 +31,58 @@ /**
 
+//-----------------------------------------------------------------------------
+// Errors
+//-----------------------------------------------------------------------------
+
 /**
- * Throws an error saying that the key was not found.
- * @param {PropertyKey} key The key to report as missing.
- * @returns {void}
- * @throws {Error} Always. 
+ * The error thrown when a required key is not found.
  */
-function keyNotFound(key) {
-    throw new Error(`Required environment variable '${String(key)}' not found.`);
+class EnvKeyNotFoundError extends Error {
+
+    /**
+     * Creates a new instance.
+     * @param {string} key The key that wasn't found. 
+     */
+    constructor(key) {
+
+        super(`Required environment variable '${key}' not found.`);
+
+        /**
+         * The key that wasn't found.
+         * @type {string}
+         */
+        this.key = key;
+
+        /**
+         * Easily identifiable name for this error type.
+         * @type {string}
+         */
+        this.name = "EnvKeyNotFoundError";
+    }
 }
 
 /**
- * Throws an error saying that the key was an empty string.
- * @param {PropertyKey} key The key to report as an empty string.
- * @returns {void}
- * @throws {Error} Always.
+ * The error thrown when a required key is present but is an empty string.
  */
-function emptyString(key) {
-    throw new Error(`Required environment variable '${String(key)}' is an empty string.`);
+class EnvEmptyStringError extends Error {
+
+    /**
+     * Creates a new instance.
+     * @param {string} key The key that wasn't found. 
+     */
+    constructor(key) {
+
+        super(`Required environment variable '${key}' is an empty string.`);
+
+        /**
+         * The key that wasn't found.
+         * @type {string}
+         */
+        this.key = key;
+
+        /**
+         * Easily identifiable name for this error type.
+         * @type {string}
+         */
+        this.name = "EnvEmptyStringError";
+    }
 }
@@ -147,5 +185,5 @@
         if (typeof value === "undefined") {
-            keyNotFound(key);
+            throw new Env.KeyNotFoundError(key);
         } else if (value === "") {
-            emptyString(key);
+            throw new Env.EmptyStringError(key);
         } else {
@@ -169,5 +207,5 @@ return value;
         if (typeof value === "undefined") {
-            keyNotFound(`[${keys}]`);
+            throw new Env.KeyNotFoundError(`[${keys}]`);
         } else if (value === "") {
-            emptyString(`[${keys}]`);
+            throw new Env.EmptyStringError(`[${keys}]`);
         } else {
@@ -192,3 +230,3 @@ return value;
                 
-                keyNotFound(key);
+                throw new Env.KeyNotFoundError(key);
             }
@@ -221,3 +259,3 @@ });
                     if (target[key] === "") {
-                        emptyString(key);
+                        throw new Env.EmptyStringError(key);
                     }
@@ -228,3 +266,3 @@
                 
-                keyNotFound(key);
+                throw new Env.KeyNotFoundError(key);
             }
@@ -247,2 +285,14 @@ });
 
-export { Env };
+/**
+ * The error to use when a key isn't found.
+ * @type {new (key: PropertyKey) => Error}
+ */
+Env.KeyNotFoundError = EnvKeyNotFoundError;
+
+/**
+ * The error to use when a key isn't found.
+ * @type {new (key: PropertyKey) => Error}
+ */
+Env.EmptyStringError = EnvEmptyStringError;
+
+export { Env, EnvEmptyStringError, EnvKeyNotFoundError };

dist/env.min.js

@@ -1,1 +0,1 @@
-const defaultEnvSource=(()=>"object"==typeof process?process.env:"undefined"==typeof Deno?{}:Deno.env.toObject())();function keyNotFound(a){throw new Error(`Required environment variable '${a+""}' not found.`)}function emptyString(a){throw new Error(`Required environment variable '${a+""}' is an empty string.`)}class Env{constructor(a=defaultEnvSource){this.source=a}get(a,b){let c;return"undefined"!=typeof b&&(c=b+""),a in this.source?this.source[a]:c}has(a){return a in this.source}first(a,b){if(!Array.isArray(a)||1>a.length)throw new TypeError("First argument must be an array of one or more strings.");for(const c of a)if(c in this.source)return this.source[c];let c;return"undefined"!=typeof b&&(c=b+""),c}require(a){const b=this.get(a);if("undefined"==typeof b)keyNotFound(a);else if(""===b)emptyString(a);else return b}requireFirst(a){const b=this.first(a);if("undefined"==typeof b)keyNotFound(`[${a}]`);else if(""===b)emptyString(`[${a}]`);else return b}get exists(){const a=new Proxy(this.source,{get(a,b){return b in a?a[b]:void keyNotFound(b)}});return Object.defineProperty(this,"exists",{value:a,writable:!1,enumerable:!1,configurable:!1}),a}get required(){const a=new Proxy(this.source,{get(a,b){return b in a?(""===a[b]&&emptyString(b),a[b]):void keyNotFound(b)}});return Object.defineProperty(this,"required",{value:a,writable:!1,enumerable:!1,configurable:!1}),a}}export{Env};
+const defaultEnvSource=(()=>"object"==typeof process?process.env:"undefined"==typeof Deno?{}:Deno.env.toObject())();class EnvKeyNotFoundError extends Error{constructor(a){super(`Required environment variable '${a}' not found.`),this.key=a,this.name="EnvKeyNotFoundError"}}class EnvEmptyStringError extends Error{constructor(a){super(`Required environment variable '${a}' is an empty string.`),this.key=a,this.name="EnvEmptyStringError"}}class Env{constructor(a=defaultEnvSource){this.source=a}get(a,b){let c;return"undefined"!=typeof b&&(c=b+""),a in this.source?this.source[a]:c}has(a){return a in this.source}first(a,b){if(!Array.isArray(a)||1>a.length)throw new TypeError("First argument must be an array of one or more strings.");for(const c of a)if(c in this.source)return this.source[c];let c;return"undefined"!=typeof b&&(c=b+""),c}require(a){const b=this.get(a);if("undefined"==typeof b)throw new Env.KeyNotFoundError(a);else if(""===b)throw new Env.EmptyStringError(a);else return b}requireFirst(a){const b=this.first(a);if("undefined"==typeof b)throw new Env.KeyNotFoundError(`[${a}]`);else if(""===b)throw new Env.EmptyStringError(`[${a}]`);else return b}get exists(){const a=new Proxy(this.source,{get(a,b){if(b in a)return a[b];throw new Env.KeyNotFoundError(b)}});return Object.defineProperty(this,"exists",{value:a,writable:!1,enumerable:!1,configurable:!1}),a}get required(){const a=new Proxy(this.source,{get(a,b){if(b in a){if(""===a[b])throw new Env.EmptyStringError(b);return a[b]}throw new Env.KeyNotFoundError(b)}});return Object.defineProperty(this,"required",{value:a,writable:!1,enumerable:!1,configurable:!1}),a}}Env.KeyNotFoundError=EnvKeyNotFoundError,Env.EmptyStringError=EnvEmptyStringError;export{Env,EnvEmptyStringError,EnvKeyNotFoundError};

package.json

 {
   "name": "@humanwhocodes/env",
-  "version": "2.2.2",
+  "version": "3.0.1",
   "description": "A utility to verify that environment variables exist.",
-  "main": "dist/env.cjs.js",
-  "module": "dist/env.mjs",
+  "type": "module",
+  "main": "dist/env.cjs",
+  "module": "dist/env.js",
   "types": "dist/env.d.ts",
   "exports": {
-    "require": "./dist/env.cjs.js",
-    "import": "./dist/env.mjs"
+    "require": {
+      "default": "./dist/env.cjs",
+      "types": "./dist/env.d.ts"
+    },
+    "import": {
+      "default": "./dist/env.js",
+      "types": "./dist/env.d.ts"
+    }
   },
@@ -35,3 +42,3 @@ "files": [
     "pretest": "npm run build",
-    "test:unit": "mocha -r esm tests/env.test.js",
+    "test:unit": "mocha tests/env.test.js",
     "test:build": "node tests/pkg.test.cjs && node tests/pkg.test.mjs",
@@ -54,12 +61,12 @@ "test:types": "node tests/types.test.js",
   "devDependencies": {
-    "chai": "4.3.6",
+    "@eslint/js": "^8.49.0",
+    "chai": "4.3.8",
     "eslint": "^8.21.0",
-    "esm": "3.2.25",
-    "lint-staged": "10.5.4",
+    "lint-staged": "14.0.1",
     "mocha": "8.4.0",
     "rollup": "1.32.1",
     "rollup-plugin-babel-minify": "9.0.0",
-    "typescript": "4.7.4",
+    "typescript": "5.2.2",
     "yorkie": "2.0.0"
   }
 }

README.md

@@ -146,2 +146,23 @@ # Env utility
 
+Last, you can specify custom error classes to throw for the two different types of errors: key not found and empty string. Each error constructor is passed the string key that caused the error. Here's an example:
+
+```js
+class MyKeyNotFoundError extends Error {
+    constructor(key) {
+        super(`Yo this key isn't here: ${key}.`);
+    }
+}
+
+class MyEmptyStringError extends Error {
+    constructor(key) {
+        super(`Hey! This key is empty: ${key}.`);
+    }
+}
+
+Env.KeyNotFoundError = MyKeyNotFoundError;
+Env.EmptyStringError = MyEmptyStringError;
+```
+
+Note that changing the error classes affects all instances of `Env`, both those that are already created and those that will be created within the same lifetime.
+
 ## Developer Setup
@@ -148,0 +169,0 @@

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

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

49517

increased by46.42%

Number of package files

10

increased by25%

Lines of code

1104

increased by57.26%

Number of lines in readme file

180

increased by13.21%

Is type module

Yes

No dependency changes