@discover-cloud/shared 1.2.0 → 1.2.1

package/dist/utils/env.utils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ENVIRONMENT HELPERS  (@discover-cloud/shared)
+ * ───────────────────────────────────────────────
+ * Typed accessors for process.env values.
+ *
+ * Why not read process.env directly?
+ *   - process.env values are always string | undefined. Reading them inline
+ *     forces every callsite to handle undefined or cast — this pushes that
+ *     contract to one place.
+ *   - getEnv() fails fast at startup (before serving any traffic) if a
+ *     required variable is absent, surfacing misconfiguration immediately
+ *     rather than at runtime inside a request handler.
+ *   - Centralised access makes it straightforward to add validation, type
+ *     coercion, or secret-redaction logic later without touching callsites.
+ *
+ * Usage:
+ *   // Required — throws at startup if missing
+ *   const dbUrl     = getEnv("DATABASE_URL");
+ *   const jwtSecret = getEnv("JWT_SECRET");
+ *
+ *   // Optional — returns undefined (or a typed default) when absent
+ *   const logLevel  = getEnvOptional("LOG_LEVEL") ?? "info";
+ *   const port      = Number(getEnvOptional("PORT") ?? "3000");
+ */
+/**
+ * getEnv
+ * Returns the value of a required environment variable.
+ * Throws at call time (typically during service startup) if the variable
+ * is absent or empty — this is intentional: missing required config should
+ * crash the process before it begins serving traffic.
+ *
+ * Empty string ("") is treated as missing because it is almost always an
+ * accidental misconfiguration (e.g. `SECRET=` with no value in a .env file).
+ */
+export declare function getEnv(name: string): string;
+/**
+ * getEnvOptional
+ * Returns the value of an optional environment variable, or undefined
+ * if it is absent or empty. Use with a nullish coalescing default:
+ *
+ *   const logLevel = getEnvOptional("LOG_LEVEL") ?? "info";
+ *
+ * Returns undefined (not empty string) so callers can safely use `??`
+ * and `||` without needing to guard against empty strings separately.
+ */
+export declare function getEnvOptional(name: string): string | undefined;

package/dist/utils/env.utils.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * ENVIRONMENT HELPERS  (@discover-cloud/shared)
+ * ───────────────────────────────────────────────
+ * Typed accessors for process.env values.
+ *
+ * Why not read process.env directly?
+ *   - process.env values are always string | undefined. Reading them inline
+ *     forces every callsite to handle undefined or cast — this pushes that
+ *     contract to one place.
+ *   - getEnv() fails fast at startup (before serving any traffic) if a
+ *     required variable is absent, surfacing misconfiguration immediately
+ *     rather than at runtime inside a request handler.
+ *   - Centralised access makes it straightforward to add validation, type
+ *     coercion, or secret-redaction logic later without touching callsites.
+ *
+ * Usage:
+ *   // Required — throws at startup if missing
+ *   const dbUrl     = getEnv("DATABASE_URL");
+ *   const jwtSecret = getEnv("JWT_SECRET");
+ *
+ *   // Optional — returns undefined (or a typed default) when absent
+ *   const logLevel  = getEnvOptional("LOG_LEVEL") ?? "info";
+ *   const port      = Number(getEnvOptional("PORT") ?? "3000");
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEnv = getEnv;
+exports.getEnvOptional = getEnvOptional;
+/**
+ * getEnv
+ * Returns the value of a required environment variable.
+ * Throws at call time (typically during service startup) if the variable
+ * is absent or empty — this is intentional: missing required config should
+ * crash the process before it begins serving traffic.
+ *
+ * Empty string ("") is treated as missing because it is almost always an
+ * accidental misconfiguration (e.g. `SECRET=` with no value in a .env file).
+ */
+function getEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}. ` +
+            `Ensure it is set in your .env file or deployment environment.`);
+    }
+    return value;
+}
+/**
+ * getEnvOptional
+ * Returns the value of an optional environment variable, or undefined
+ * if it is absent or empty. Use with a nullish coalescing default:
+ *
+ *   const logLevel = getEnvOptional("LOG_LEVEL") ?? "info";
+ *
+ * Returns undefined (not empty string) so callers can safely use `??`
+ * and `||` without needing to guard against empty strings separately.
+ */
+function getEnvOptional(name) {
+    const value = process.env[name];
+    // Normalise empty string to undefined — same convention as getEnv.
+    return value === "" ? undefined : value;
+}

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./response.utils";
 export * from "./logger.utils";
 export * from "./date.utils";
+export * from "./env.utils";

package/dist/utils/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./response.utils"), exports);
 __exportStar(require("./logger.utils"), exports);
 __exportStar(require("./date.utils"), exports);
+__exportStar(require("./env.utils"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discover-cloud/shared",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "private": false,
   "type": "commonjs",
   "main": "dist/index.js",