feat: getTrimmedThrow and getValidatedThrow

Author: stopsopa

README.md

@@ -82,6 +82,8 @@ import {
   has,
   getDefault,
   getThrow,
+  getTrimmedThrow,
+  getValidatedThrow,
 
   getIntegerThrowInvalid, // equivalent to get
   getIntegerDefault,
@@ -228,6 +230,8 @@ import {
   has,
   getDefault,
   getThrow,
+  getTrimmedThrow,
+  getValidatedThrow,
 
   getIntegerThrowInvalid, // equivalent to get
   getIntegerDefault,
@@ -241,6 +245,8 @@ const {
   has,
   getDefault,
   getThrow,
+  getTrimmedThrow,
+  getValidatedThrow,
 
   getIntegerThrowInvalid, // equivalent to get
   getIntegerDefault,
@@ -249,5 +255,18 @@ const {
 
 console.log(`get('USER') >${get("USER")}`);
 
+# Methods description
+
+- `all()`: Returns a complete object containing all environment variables.
+- `get(key)`: Retrieves an environment variable if it exists, otherwise returns `undefined`.
+- `has(key)`: Checks if an environment variable exists.
+- `getDefault(key, defaultValue)`: Retrieves an environment variable or returns the specified `defaultValue` if not found.
+- `getThrow(key)`: Retrieves an environment variable or throws an error if it doesn't exist.
+- `getTrimmedThrow(key)`: Retrieves, trims, and throws an error if the variable is missing or empty after trimming.
+- `getValidatedThrow(key, validator)`: Retrieves and validates using a `RegExp` or a custom function. The validator function should return an error message `string` on failure, or `null`/`undefined` on success. It can also throw an error directly.
+- `getIntegerThrowInvalid(key)`: Retrieves and converts to an integer. Throws if it exists but is not a valid integer.
+- `getIntegerDefault(key, defaultValue)`: Retrieves as an integer, or returns `defaultValue` if not found or invalid.
+- `getIntegerThrow(key)`: Retrieves as an integer, throws if missing or invalid.
+
 ```
 

src/source/env.ts

@@ -26,34 +26,48 @@ if (isNode) {
 
 /**
  * For testing purposes, it is possible to substitute the object process.env with a custom object.
+ *
+ * @param map - A record of environment variable names and their values.
  */
 export function mockEnv(map: Record<string, string>): void {
   env = map;
 }
 
 /**
- * Returns a complete object containing all environment variables
+ * Returns a complete object containing all environment variables.
+ *
+ * @returns A record containing all environment variables.
  */
 export function all(): Record<string, string> {
   return env;
 }
 
 /**
- * Checks if an environment variable exists
+ * Checks if an environment variable exists.
+ *
+ * @param key - The name of the environment variable.
+ * @returns True if the variable exists as a string, false otherwise.
  */
 export function has(key: string): boolean {
   return typeof env[key] === "string";
 }
 
 /**
- * Retrieves an environment variable if it exists
+ * Retrieves an environment variable if it exists.
+ *
+ * @param key - The name of the environment variable.
+ * @returns The value of the environment variable if it exists, otherwise undefined.
  */
 export function get(key: string): string | undefined {
   return env[key];
 }
 
 /**
- * Retrieves an environment variable or returns the specified default value if not found
+ * Retrieves an environment variable or returns the specified default value if not found.
+ *
+ * @param key - The name of the environment variable.
+ * @param defaultValue - The value to return if the environment variable is not defined.
+ * @returns The environment variable value or the provided default value.
  */
 export function getDefault(key: string, defaultValue: string | number): string | number {
   if (has(key)) {
@@ -63,7 +77,12 @@ export function getDefault(key: string, defaultValue: string | number): string |
 }
 
 /**
- * Retrieves an environment variable or throws an error if it doesn't exist
+ * Retrieves an environment variable or throws an error if it doesn't exist.
+ *
+ * @param key - The name of the environment variable.
+ * @param msg - An optional custom error message to throw.
+ * @returns The value of the environment variable.
+ * @throws Will throw an error if the environment variable is not defined.
  */
 export function getThrow(key: string, msg?: string): string {
   if (has(key)) {
@@ -72,12 +91,59 @@ export function getThrow(key: string, msg?: string): string {
   throw th(msg || `env var ${key} is not defined`);
 }
 
+/**
+ * Retrieves an environment variable, trims it, and throws an error if it's missing or empty.
+ *
+ * @param key - The name of the environment variable.
+ * @returns The trimmed value of the environment variable.
+ * @throws Will throw if the variable is not defined or is an empty string after trimming.
+ */
+export function getTrimmedThrow(key: string): string {
+  const value = getThrow(key).trim();
+
+  if (value === "") {
+    throw th(`env var ${key} is defined but it is an empty string after trimming`);
+  }
+
+  return value;
+}
+
+/**
+ * Retrieves an environment variable and validates it using a regex or a custom function.
+ *
+ * @param key - The name of the environment variable.
+ * @param validator - A RegExp to test against or a function that returns an error message string (or throws) on failure.
+ * @returns The original value of the environment variable if validation passes.
+ * @throws Will throw if the variable is not defined, doesn't match the regex, or if the validator function returns a string or throws.
+ */
+export function getValidatedThrow(
+  key: string,
+  validator: RegExp | ((value: string) => string | null | undefined | void),
+): string {
+  const value = getThrow(key);
+
+  if (validator instanceof RegExp) {
+    if (!validator.test(value)) {
+      throw th(`env var ${key} value >${value}< does not match regex >${validator}<`);
+    }
+  } else if (typeof validator === "function") {
+    const result = validator(value);
+    if (typeof result === "string") {
+      throw th(result);
+    }
+  }
+
+  return value;
+}
+
 const intTest = /^-?\d+$/;
 
 /**
- * Retrieves an environment variable and converts it to an integer
- * Returns undefined if the variable doesn't exist
- * Throws an error if the variable exists but cannot be converted to a valid integer
+ * Retrieves an environment variable and converts it to an integer.
+ *
+ * @param key - The name of the environment variable.
+ * @returns The integer value if it exists and is valid, otherwise undefined.
+ * @throws Will throw an error if the variable exists but cannot be converted to a valid integer.
  */
 export function getIntegerThrowInvalid(key: string): number | undefined {
   if (has(key)) {
@@ -103,7 +169,11 @@ export function getIntegerThrowInvalid(key: string): number | undefined {
 }
 
 /**
- * If not defined or not able to cast to int, return defaultValue.
+ * Retrieves an environment variable as an integer, or returns a default value if not found or invalid.
+ *
+ * @param key - The name of the environment variable.
+ * @param defaultValue - The value to return if the environment variable is not defined or invalid.
+ * @returns The integer value or the default value.
  */
 export function getIntegerDefault(key: string, defaultValue: number): number {
   try {
@@ -121,7 +191,10 @@ export function getIntegerDefault(key: string, defaultValue: number): number {
 
 /**
  * Retrieves an environment variable, converts it to an integer, and returns the value.
- * Throws an error if the variable is not defined or cannot be converted to a valid integer.
+ *
+ * @param key - The name of the environment variable.
+ * @returns The integer value of the environment variable.
+ * @throws Will throw an error if the variable is not defined or cannot be converted to a valid integer.
  */
 export function getIntegerThrow(key: string): number {
   const val = getIntegerThrowInvalid(key);

tests/env.unit.js

@@ -8,6 +8,8 @@ import {
   getIntegerDefault,
   getIntegerThrow,
   getThrow,
+  getTrimmedThrow,
+  getValidatedThrow,
   all,
 } from "../src/source/env.ts";
 
@@ -110,3 +112,40 @@ it("all - returns all environment variables", async () => {
   expect(all()).toEqual(mockEnvironment);
   expect(all()).toBe(mockEnvironment); // Check that it returns the same object reference
 });
+
+it("getTrimmedThrow", async () => {
+  mockEnv({
+    ABC: "  DEF  ",
+    EMPTY: "   ",
+  });
+
+  expect(getTrimmedThrow("ABC")).toEqual("DEF");
+  expect(() => getTrimmedThrow("EMPTY")).toThrowError(
+    "env.js: env var EMPTY is defined but it is an empty string after trimming",
+  );
+  expect(() => getTrimmedThrow("GHI")).toThrowError("env.js: env var GHI is not defined");
+});
+
+it("getValidatedThrow", async () => {
+  mockEnv({
+    ABC: "123",
+    DEF: "abc",
+  });
+
+  expect(getValidatedThrow("ABC", /^\d+$/)).toEqual("123");
+  expect(() => getValidatedThrow("DEF", /^\d+$/)).toThrowError(
+    "env.js: env var DEF value >abc< does not match regex >/^\\d+$/<",
+  );
+
+  expect(getValidatedThrow("ABC", (v) => (v === "123" ? null : "must be 123"))).toEqual("123");
+  expect(() => getValidatedThrow("DEF", (v) => (v === "123" ? null : "must be 123"))).toThrowError(
+    "env.js: must be 123",
+  );
+
+  expect(() =>
+    getValidatedThrow("ABC", () => {
+      throw new Error("custom error");
+    }),
+  ).toThrowError("custom error");
+});
+