feat: add url parser from env

A.P.A. Slaa · A.P.A. Slaa · commit 93d0f3522c03 · 2025-12-29T11:40:22.000+01:00
diff --git a/README.md b/README.md
@@ -124,6 +124,7 @@ const mode = env.utils.select("FEATURE_X", "enabled", "disabled");
 | `env.string(key, default?)`                      | Return the variable as a string (or default).                                                       |
 | `env.number(key, default?)`                      | Parse variable to number (or default).                                                              |
 | `env.boolean(key, default?)`                     | Parse variable to boolean (or default).                                                             |
+| `env.url(key, default?)`                         | Parse variable to URL object (or default(http://localhost)).                                        |
 | `env.has(key)`                                   | Returns true if key exists in `process.env`.                                                        |
 | `env.assert([keys], error_builder?)`             | Throws an error if one or more keys doesn't exists in `process.env`.                                |
 | `env.defined(key)`                               | Returns true if key exists and value is not `undefined`.                                            |
diff --git a/src/index.ts b/src/index.ts
@@ -1,4 +1,5 @@
 import {readFileSync, existsSync} from "fs";
+import {T} from "vitest/dist/chunks/global.d.MAmajcmJ";
 
 function loadDotEnv(file = ".env") {
     if (!existsSync(file)) return {};
@@ -41,7 +42,6 @@ export const env = Object.freeze({
         if (!(key in process.env)) process.env[key] = _default ?? "";
         return process.env[key] as T;
     },
-
     number(key: Uppercase<string>, _default = 0): number {
         const raw = process.env[key];
         if (raw === undefined) {
@@ -51,7 +51,6 @@ export const env = Object.freeze({
         const val = Number(raw);
         return Number.isFinite(val) ? val : _default;
     },
-
     boolean(key: Uppercase<string>, _default = false): boolean {
         const raw = process.env[key];
         if (raw === undefined) {
@@ -61,13 +60,20 @@ export const env = Object.freeze({
         const val = raw.toLowerCase();
         return val === "true" || val === "1";
     },
-
+    url(key: Uppercase<string>, _default = new URL("http://localhost")): URL {
+        const raw = process.env[key];
+        if (raw === undefined || !URL.canParse(raw)) {
+            process.env[key] = _default.toString();
+            return _default;
+        }
+        return URL.parse(raw)!;
+    },
     has(key: Uppercase<string>): boolean {
         return Object.prototype.hasOwnProperty.call(process.env, key);
     },
     assert(keys: Uppercase<string>[], error_builder: (missing_keys: string[]) => string | Error = ((missing_keys) => new Error(`Missing required keys(${missing_keys.join()}) in environment`)),) {
         const missing_keys: string[] = [];
-        keys.forEach((key) => this.has(key) ? void 0: missing_keys.push(key));
+        keys.forEach((key) => this.has(key) ? void 0 : missing_keys.push(key));
         if (missing_keys.length > 0) {
             const result = error_builder(missing_keys);
             if (typeof result === "string") throw new Error(result);
@@ -113,5 +119,5 @@ export const env = Object.freeze({
     }),
     get raw() {
         return Object.freeze(dotEnvVars)
-    }
+    },
 });
diff --git a/tests/env.test.ts b/tests/env.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import {beforeEach, describe, expect, it, vi} from "vitest";
 import * as fs from "fs";
 
 vi.mock("fs");
@@ -39,7 +39,8 @@ describe("env library", () => {
         mockReadFileSync.mockImplementation(() => {
             throw new Error("File read failed");
         });
-        const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+        const spy = vi.spyOn(console, "warn").mockImplementation(() => {
+        });
         env = (await import("../src")).env;
         expect(spy).toHaveBeenCalledWith("File read failed");
     });
@@ -81,13 +82,20 @@ describe("env library", () => {
         expect(env.boolean("FLAG_FALSE")).toBe(false);
     });
 
+    it("handles URL parsing correctly", async () => {
+        mockExistsSync.mockReturnValue(false);
+        env = (await import("../src")).env;
+        (process.env as any).API_ENDPOINT = "http://localhost:8080/";
+        expect(env.url("API_ENDPOINT")).toBeInstanceOf(URL);
+    });
+
     it("creates collection with and without prefix removal", async () => {
         mockExistsSync.mockReturnValue(false);
         (process.env as any).APP_FOO = "bar";
         (process.env as any).APP_BAR = "baz";
         env = (await import("../src")).env;
         const all = env.collection("APP_");
-        const stripped = env.collection("APP_", { removePrefix: true });
+        const stripped = env.collection("APP_", {removePrefix: true});
         expect(all.APP_FOO).toBe("bar");
         expect(stripped.FOO).toBe("bar");
     });
