@discover-cloud/shared 1.0.10 → 1.2.0

package/dist/utils/env.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/logger.utils.d.ts

@@ -1,30 +1,35 @@
 /**
  * LOGGER INTERFACE  (@discover-cloud/shared)
  * ────────────────────────────────────────────
- * A minimal logger contract shared code can depend on.
- * Each service injects its own implementation (pino, winston, console).
+ * A minimal logger contract that shared code can depend on.
+ * Each service injects its own concrete implementation (pino, winston, etc.).
  *
- * Shared code (RequireAuthMiddleware, PermissionCacheService, etc.)
- * accepts this interface — it never imports a concrete logger directly.
+ * Shared classes (RequireAuthMiddleware, PermissionCacheService, etc.)
+ * accept ILogger via constructor injection — they never import a concrete
+ * logger directly, keeping the shared package dependency-free.
  *
  * ─── Usage in shared classes ────────────────────────────────────────
  *   class RequireAuthMiddleware {
  *     constructor(
  *       private readonly verifier: InternalJwtVerifier,
- *       private readonly logger:   ILogger = noopLogger,
+ *       private readonly logger: ILogger = noopLogger,
  *     ) {}
  *   }
  *
  * ─── Wiring in each service ─────────────────────────────────────────
- *   // auth-service / composition root:
  *   import pino from "pino";
- *   const pinoLogger = pino({ level: "info" });
+ *   const logger = pino({ level: "info" });
+ *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, logger);
  *
- *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, pinoLogger);
+ *   // pino satisfies ILogger — its method signatures are compatible.
  *
- * ─── noopLogger ─────────────────────────────────────────────────────
- *   The default when no logger is injected — silently drops all logs.
- *   Safe for tests and library consumers that don't want log noise.
+ * ─── Signature convention ───────────────────────────────────────────
+ *   Follows pino's overloaded signature:
+ *     logger.info({ userId }, "User logged in")  — object first, then message
+ *     logger.info("Simple message")              — string only
+ *
+ *   This matches pino natively and means a pino instance can be passed
+ *   directly without any wrapping.
  */
 export interface ILogger {
     debug(obj: object, msg?: string): void;
@@ -38,14 +43,24 @@ export interface ILogger {
 }
 /**
  * noopLogger
- * Silent default — used when no logger is injected.
- * Satisfies ILogger without importing any logging library.
+ * Silent no-op implementation — the safe default when no logger is injected.
+ * All log calls are discarded. Use in tests and library consumers that
+ * don't want log noise.
  */
 export declare const noopLogger: ILogger;
 /**
  * consoleLogger
- * Thin console wrapper — useful for local dev and simple services
- * that don't need structured logging.
- * Pass this when you want logs without wiring up pino/winston.
+ * Thin console wrapper that follows the pino (obj, msg?) calling convention.
+ * Useful for local development and simple services that don't need structured
+ * logging — pass this instead of wiring up pino.
+ *
+ * Output order mirrors pino: message first, then the context object on a
+ * separate argument so it appears as structured context in most terminals.
+ *
+ *   consoleLogger.info({ userId: "abc" }, "User logged in")
+ *   → console.info("User logged in", { userId: "abc" })
+ *
+ *   consoleLogger.info("Simple message")
+ *   → console.info("Simple message")
  */
 export declare const consoleLogger: ILogger;

package/dist/utils/logger.utils.js

@@ -2,37 +2,43 @@
 /**
  * LOGGER INTERFACE  (@discover-cloud/shared)
  * ────────────────────────────────────────────
- * A minimal logger contract shared code can depend on.
- * Each service injects its own implementation (pino, winston, console).
+ * A minimal logger contract that shared code can depend on.
+ * Each service injects its own concrete implementation (pino, winston, etc.).
  *
- * Shared code (RequireAuthMiddleware, PermissionCacheService, etc.)
- * accepts this interface — it never imports a concrete logger directly.
+ * Shared classes (RequireAuthMiddleware, PermissionCacheService, etc.)
+ * accept ILogger via constructor injection — they never import a concrete
+ * logger directly, keeping the shared package dependency-free.
  *
  * ─── Usage in shared classes ────────────────────────────────────────
  *   class RequireAuthMiddleware {
  *     constructor(
  *       private readonly verifier: InternalJwtVerifier,
- *       private readonly logger:   ILogger = noopLogger,
+ *       private readonly logger: ILogger = noopLogger,
  *     ) {}
  *   }
  *
  * ─── Wiring in each service ─────────────────────────────────────────
- *   // auth-service / composition root:
  *   import pino from "pino";
- *   const pinoLogger = pino({ level: "info" });
+ *   const logger = pino({ level: "info" });
+ *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, logger);
  *
- *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, pinoLogger);
+ *   // pino satisfies ILogger — its method signatures are compatible.
  *
- * ─── noopLogger ─────────────────────────────────────────────────────
- *   The default when no logger is injected — silently drops all logs.
- *   Safe for tests and library consumers that don't want log noise.
+ * ─── Signature convention ───────────────────────────────────────────
+ *   Follows pino's overloaded signature:
+ *     logger.info({ userId }, "User logged in")  — object first, then message
+ *     logger.info("Simple message")              — string only
+ *
+ *   This matches pino natively and means a pino instance can be passed
+ *   directly without any wrapping.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.consoleLogger = exports.noopLogger = void 0;
 /**
  * noopLogger
- * Silent default — used when no logger is injected.
- * Satisfies ILogger without importing any logging library.
+ * Silent no-op implementation — the safe default when no logger is injected.
+ * All log calls are discarded. Use in tests and library consumers that
+ * don't want log noise.
  */
 exports.noopLogger = {
     debug: () => { },
@@ -42,21 +48,50 @@ exports.noopLogger = {
 };
 /**
  * consoleLogger
- * Thin console wrapper — useful for local dev and simple services
- * that don't need structured logging.
- * Pass this when you want logs without wiring up pino/winston.
+ * Thin console wrapper that follows the pino (obj, msg?) calling convention.
+ * Useful for local development and simple services that don't need structured
+ * logging — pass this instead of wiring up pino.
+ *
+ * Output order mirrors pino: message first, then the context object on a
+ * separate argument so it appears as structured context in most terminals.
+ *
+ *   consoleLogger.info({ userId: "abc" }, "User logged in")
+ *   → console.info("User logged in", { userId: "abc" })
+ *
+ *   consoleLogger.info("Simple message")
+ *   → console.info("Simple message")
  */
 exports.consoleLogger = {
     debug: (objOrMsg, msg) => {
-        console.debug(msg ?? objOrMsg, typeof objOrMsg === "object" ? objOrMsg : "");
+        if (typeof objOrMsg === "string") {
+            console.debug(objOrMsg);
+        }
+        else {
+            console.debug(msg ?? "", objOrMsg);
+        }
     },
     info: (objOrMsg, msg) => {
-        console.info(msg ?? objOrMsg, typeof objOrMsg === "object" ? objOrMsg : "");
+        if (typeof objOrMsg === "string") {
+            console.info(objOrMsg);
+        }
+        else {
+            console.info(msg ?? "", objOrMsg);
+        }
     },
     warn: (objOrMsg, msg) => {
-        console.warn(msg ?? objOrMsg, typeof objOrMsg === "object" ? objOrMsg : "");
+        if (typeof objOrMsg === "string") {
+            console.warn(objOrMsg);
+        }
+        else {
+            console.warn(msg ?? "", objOrMsg);
+        }
     },
     error: (objOrMsg, msg) => {
-        console.error(msg ?? objOrMsg, typeof objOrMsg === "object" ? objOrMsg : "");
+        if (typeof objOrMsg === "string") {
+            console.error(objOrMsg);
+        }
+        else {
+            console.error(msg ?? "", objOrMsg);
+        }
     },
 };

package/dist/utils/response.utils.d.ts

@@ -1,12 +1,54 @@
 import { Response, Request } from "express";
 /**
- * RESPONSE HELPERS
- * ─────────────────
+ * RESPONSE HELPERS  (@discover-cloud/shared)
+ * ────────────────────────────────────────────
  * Typed wrappers around res.json() that enforce the ApiSuccessResponse
- * and ApiErrorResponse envelope shapes.
+ * and ApiErrorResponse envelope shapes across all services.
  *
- * Both require req explicitly — avoids the res.req cast anti-pattern
- * and makes the dependency clear at the call site.
+ * Both helpers accept req explicitly rather than reading res.req — this
+ * makes the dependency visible at the call site and avoids the res.req
+ * cast anti-pattern.
+ *
+ * requestId fallback:
+ *   req.id is set by requestId middleware. The randomUUID() fallback should
+ *   never fire in a correctly wired service — if it does, it means requestId
+ *   middleware was not registered before this helper was called. The fallback
+ *   keeps the response well-formed but the generated ID won't correlate with
+ *   any upstream trace. Check middleware registration order if you see UUIDs
+ *   in responses that don't match the x-request-id header.
+ */
+/**
+ * success
+ * Wraps data in an ApiSuccessResponse envelope and sends it.
+ *
+ * @param res        - Express response object
+ * @param req        - Express request object (for requestId + timestamp)
+ * @param data       - The response payload; typed as T for type inference
+ * @param statusCode - HTTP status code (default 200)
+ *
+ * Usage:
+ *   success<CloudAccountDto>(res, req, accountDto);
+ *   success<PaginatedResponseDto<CloudAccountDto>>(res, req, paginatedResult, 200);
+ *   success<MessageResponseDto>(res, req, { message: "Deleted" }, 200);
  */
 export declare const success: <T>(res: Response, req: Request, data: T, statusCode?: number) => void;
+/**
+ * failure
+ * Wraps an error in an ApiErrorResponse envelope and sends it.
+ *
+ * @param res        - Express response object
+ * @param req        - Express request object (for requestId + timestamp)
+ * @param message    - Human-readable error description
+ * @param code       - Machine-readable error code (maps to AppError.code)
+ * @param statusCode - HTTP status code (default 400)
+ * @param details    - Optional structured context (e.g. Zod flatten() output).
+ *                     Never put secrets, stack traces, or raw DB errors here.
+ *
+ * details is omitted from the response body when not provided — this avoids
+ * "details": null noise in responses and keeps the shape clean for clients.
+ *
+ * Usage:
+ *   failure(res, req, "Account not found", "NOT_FOUND", 404);
+ *   failure(res, req, "Validation failed", "VALIDATION_ERROR", 400, err.flatten());
+ */
 export declare const failure: (res: Response, req: Request, message: string, code: string, statusCode?: number, details?: unknown) => void;

package/dist/utils/response.utils.js

@@ -3,33 +3,76 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.failure = exports.success = void 0;
 const crypto_1 = require("crypto");
 /**
- * RESPONSE HELPERS
- * ─────────────────
+ * RESPONSE HELPERS  (@discover-cloud/shared)
+ * ────────────────────────────────────────────
  * Typed wrappers around res.json() that enforce the ApiSuccessResponse
- * and ApiErrorResponse envelope shapes.
+ * and ApiErrorResponse envelope shapes across all services.
  *
- * Both require req explicitly — avoids the res.req cast anti-pattern
- * and makes the dependency clear at the call site.
+ * Both helpers accept req explicitly rather than reading res.req — this
+ * makes the dependency visible at the call site and avoids the res.req
+ * cast anti-pattern.
+ *
+ * requestId fallback:
+ *   req.id is set by requestId middleware. The randomUUID() fallback should
+ *   never fire in a correctly wired service — if it does, it means requestId
+ *   middleware was not registered before this helper was called. The fallback
+ *   keeps the response well-formed but the generated ID won't correlate with
+ *   any upstream trace. Check middleware registration order if you see UUIDs
+ *   in responses that don't match the x-request-id header.
+ */
+/**
+ * success
+ * Wraps data in an ApiSuccessResponse envelope and sends it.
+ *
+ * @param res        - Express response object
+ * @param req        - Express request object (for requestId + timestamp)
+ * @param data       - The response payload; typed as T for type inference
+ * @param statusCode - HTTP status code (default 200)
+ *
+ * Usage:
+ *   success<CloudAccountDto>(res, req, accountDto);
+ *   success<PaginatedResponseDto<CloudAccountDto>>(res, req, paginatedResult, 200);
+ *   success<MessageResponseDto>(res, req, { message: "Deleted" }, 200);
  */
 const success = (res, req, data, statusCode = 200) => {
     const response = {
         success: true,
         data,
         meta: {
-            requestId: req.id ?? (0, crypto_1.randomUUID)(), // randomUUID fallback — "unknown" breaks log search
+            requestId: req.id ?? (0, crypto_1.randomUUID)(),
             timestamp: new Date().toISOString(),
         },
     };
     res.status(statusCode).json(response);
 };
 exports.success = success;
+/**
+ * failure
+ * Wraps an error in an ApiErrorResponse envelope and sends it.
+ *
+ * @param res        - Express response object
+ * @param req        - Express request object (for requestId + timestamp)
+ * @param message    - Human-readable error description
+ * @param code       - Machine-readable error code (maps to AppError.code)
+ * @param statusCode - HTTP status code (default 400)
+ * @param details    - Optional structured context (e.g. Zod flatten() output).
+ *                     Never put secrets, stack traces, or raw DB errors here.
+ *
+ * details is omitted from the response body when not provided — this avoids
+ * "details": null noise in responses and keeps the shape clean for clients.
+ *
+ * Usage:
+ *   failure(res, req, "Account not found", "NOT_FOUND", 404);
+ *   failure(res, req, "Validation failed", "VALIDATION_ERROR", 400, err.flatten());
+ */
 const failure = (res, req, message, code, statusCode = 400, details) => {
     const response = {
         success: false,
         error: {
             code,
             message,
-            // Omit details entirely when not provided — avoids "details": null noise
+            // Spread details only when present — omitting the key entirely is
+            // cleaner than sending "details": undefined (which JSON.stringify drops anyway).
             ...(details !== undefined ? { details } : {}),
         },
         meta: {

package/package.json

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