@catbee/utils 1.1.0 → 2.0.0-next.1

package/logger/index.d.ts

@@ -0,0 +1,213 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import pino, { Logger as Logger$1 } from 'pino';
+
+/**
+ * Logger type for application-wide logging.
+ */
+type Logger = Logger$1;
+/**
+ * Logger levels for application-wide logging.
+ */
+type LoggerLevels = pino.Level;
+declare const defaultSensitiveFields: string[];
+/**
+ * Sets the global redaction censor function used throughout the application for log redaction.
+ *
+ * Use this function to customize how sensitive data is redacted in logs. The provided function
+ * will replace the default censor implementation.
+ *
+ * @example
+ * ```typescript
+ * // Custom censor that redacts only specific values
+ * setRedactCensor((value, path, sensitiveFields) => {
+ *   if (path.includes('password')) return '***';
+ *   return value;
+ * });
+ * ```
+ *
+ * @param fn - The redaction censor function to use globally. This function receives:
+ *   - value: The data value to potentially redact
+ *   - path: Array of strings representing the path to the value in the object
+ *   - sensitiveFields: Optional array of field names to consider sensitive
+ * @returns void
+ */
+declare function setRedactCensor(fn: (value: unknown, path: string[], sensitiveFields?: string[]) => string): void;
+/**
+ * Gets the current global redaction censor function used for log redaction.
+ *
+ * This function is called internally by the logger when determining how to redact
+ * sensitive information. It can also be used to access the current censor implementation
+ * for composition or extension.
+ *
+ * @example
+ * ```typescript
+ * const currentCensor = getRedactCensor();
+ * // Create an enhanced censor that extends the current one
+ * setRedactCensor((value, path, fields) => {
+ *   // Add custom logic before delegating to current censor
+ *   if (someCondition) return customHandling();
+ *   return currentCensor(value, path, fields);
+ * });
+ * ```
+ *
+ * @returns The current redaction censor function
+ */
+declare function getRedactCensor(): (value: unknown, path: string[], sensitiveFields?: string[]) => string;
+/**
+ * Convenience function to redact sensitive data using the current global redact censor.
+ *
+ * This is a direct wrapper around the global censor function that simplifies usage
+ * in application code without needing to access the censor function directly.
+ *
+ * @example
+ * ```typescript
+ * // Redact a potential sensitive value
+ * const safeValue = redact(value, ['user', 'apiKey']);
+ * ```
+ *
+ * @param value - The value to potentially redact
+ * @param path - Array of strings representing the path to the value in the object
+ * @param sensitiveFields - Optional array of field names to consider sensitive
+ * @returns The redacted string value or "***" for redacted content
+ */
+declare function redact(value: unknown, path: string[], sensitiveFields?: string[]): string;
+/**
+ * @deprecated Use addSensitiveFields instead.
+ *
+ * Extends the current redaction function with additional fields to redact.
+ *
+ * This function wraps the existing censor while adding more fields to be considered
+ * sensitive without replacing the entire redaction logic.
+ *
+ * @example
+ * ```typescript
+ * // Add custom fields to be redacted in all future redaction operations
+ * addRedactFields(['customerId', 'accountNumber']);
+ * ```
+ *
+ * @param fields - Array of additional field names to redact
+ */
+declare function addRedactFields(fields: string[]): void;
+/**
+ * Retrieves the expanded list of sensitive fields.
+ *
+ * This function expands the default sensitive fields into their various naming
+ * conventions (e.g., camelCase, snake_case) and caches the result for efficiency.
+ *
+ * @returns Array of expanded sensitive field names
+ */
+declare function getExpandedSensitiveFields(): string[];
+/**
+ * Replaces the default list of sensitive fields with a new list.
+ *
+ * This is useful when you want complete control over what fields are considered
+ * sensitive by default, rather than using the library's built-in list.
+ *
+ * @example
+ * ```typescript
+ * // Replace default sensitive fields with a custom list
+ * setSensitiveFields(['password', 'ssn', 'creditCard']);
+ * ```
+ *
+ * @param fields - Array of field names to set as the new default sensitive fields
+ */
+declare function setSensitiveFields(fields: string[]): void;
+/**
+ * Adds additional field names to the default sensitive fields list.
+ *
+ * This preserves the existing sensitive fields while adding new ones for
+ * application-specific sensitive data.
+ *
+ * @example
+ * ```typescript
+ * // Add domain-specific sensitive fields to the default list
+ * addSensitiveFields(['socialSecurityNumber', 'medicalRecordNumber']);
+ * ```
+ *
+ * @param fields - Array of additional field names to add to the sensitive fields list
+ */
+declare function addSensitiveFields(fields: string[]): void;
+/**
+ * Use an object compatible with either modern or legacy global scopes.
+ */
+declare const _globalThis: typeof globalThis;
+/**
+ * Retrieves the current logger instance:
+ * - Returns a request-scoped logger from AsyncLocalStorage if available
+ * - Falls back to the global (singleton) logger
+ * - Initializes the global logger if not created yet
+ * - If newInstance is true, returns a fresh logger without any context
+ *
+ * @param {boolean} newInstance - If true, returns a fresh logger without any context
+ * @returns {Logger} The logger instance (request-bound or global root logger or fresh instance)
+ */
+declare function getLogger(newInstance?: boolean): Logger$1;
+/**
+ * Creates a child logger with additional context.
+ *
+ * @param {Record<string, any>} bindings - Properties to attach to all log records
+ * @param {Logger} [parentLogger] - Parent logger (defaults to current context logger or global)
+ * @returns {Logger} Child logger with merged context
+ */
+declare function createChildLogger(bindings: Record<string, any>, parentLogger?: Logger$1): Logger$1;
+/**
+ * Creates a request-scoped logger with request ID and stores it in context
+ *
+ * @param {string} requestId - Unique request identifier
+ * @param {object} [additionalContext] - Additional context to include in logs
+ * @returns {Logger} Request-scoped logger instance
+ */
+declare function createRequestLogger(requestId: string, additionalContext?: Record<string, any>): Logger$1;
+/**
+ * Utility to safely log errors with proper stack trace extraction
+ *
+ * @param {Error|unknown} error - Error object to log
+ * @param {string} [message] - Optional message to include
+ * @param {Record<string, any>} [context] - Additional context properties
+ */
+declare function logError(error: Error | unknown, message?: string, context?: Record<string, any>): void;
+/**
+ * Expands multiple sensitive field names into their variants.
+ * Useful to match fields like `api_key`, `apiKey`, `apikey`, `APIKEY`, etc.
+ */
+declare function expandSensitiveFields(fields: string[]): string[];
+/**
+ * Generates multiple variants of a sensitive field name.
+ * Useful to match fields like `api_key`, `apiKey`, `apikey`, `APIKEY`, etc.
+ */
+declare function expandSensitiveField(field: string): string[];
+/**
+ * Generates wildcard paths up to the given depth.
+ *
+ * depth = 2 ->
+ *  password
+ *  *.password
+ *  *.*.password
+ */
+declare function generateDeepPaths(field: string, depth: number): string[];
+
+export { _globalThis, addRedactFields, addSensitiveFields, createChildLogger, createRequestLogger, defaultSensitiveFields, expandSensitiveField, expandSensitiveFields, generateDeepPaths, getExpandedSensitiveFields, getLogger, getRedactCensor, logError, redact, setRedactCensor, setSensitiveFields };
+export type { Logger, LoggerLevels };

package/logger/index.mjs

@@ -0,0 +1,313 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import pino, { stdTimeFunctions } from 'pino';
+import { getCatbeeGlobalConfig } from '@catbee/utils/config';
+import { ContextStore, StoreKeys } from '@catbee/utils/context-store';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var GLOBAL_LOGGER_KEY = Symbol.for("logger");
+var defaultSensitiveFields = [
+  "password",
+  "secret",
+  "token",
+  "api_key",
+  "auth",
+  "private_key",
+  "public_key",
+  "jwt",
+  "access_token",
+  "refresh_token",
+  "session_token",
+  "csrf_token",
+  "authorization",
+  "bearer",
+  "x-api-key",
+  "x-auth-token",
+  "x-access-token",
+  "client_secret",
+  "passphrase",
+  "otp",
+  "api_secret",
+  "token_secret"
+];
+var defaultRedactPaths = [
+  "req.authorization",
+  "req.headers.authorization",
+  "req.headers.cookie",
+  'req.headers["x-api-key"]',
+  'req.headers["x-auth-token"]',
+  'req.headers["x-access-token"]',
+  "req.body.password",
+  "req.body.token",
+  "req.body.secret",
+  "req.query.token",
+  "req.query.api_key",
+  "req.query.apiKey",
+  "res.authorization",
+  "res.headers.authorization",
+  'res.headers["set-cookie"]',
+  "headers.authorization",
+  "headers.cookies",
+  'headers["set-cookie"]',
+  'headers["x-api-key"]',
+  'headers["x-auth-token"]',
+  'headers["x-access-token"]',
+  "url",
+  "uri",
+  "href",
+  "redirect_uri",
+  "redirectUri"
+];
+var globalRedactCensor = /* @__PURE__ */ __name((value, path, sensitiveFields = getExpandedSensitiveFields()) => {
+  if (typeof value !== "string") return "***";
+  const lowerPath = path.filter((p) => typeof p === "string").map((p) => p.toLowerCase());
+  const lowerSensitiveFields = sensitiveFields.map((f) => f.toLowerCase());
+  if (lowerPath.some((p) => lowerSensitiveFields.includes(p))) return "***";
+  if (lowerPath[0] === "url" || lowerPath[0] === "uri" || lowerPath[0] === "href" || lowerPath.includes("redirect_uri") || lowerPath.includes("redirecturi")) {
+    return value.replace(new RegExp(`([?&](${lowerSensitiveFields.join("|")})=)[^&#]*`, "gi"), "$1***");
+  }
+  if (lowerPath.some((p) => p.includes("authorization") || p.includes("auth"))) {
+    return value.replace(/^(\S+)\s+.+$/, "$1 ***") || "***";
+  }
+  if (lowerPath.some((p) => lowerSensitiveFields.some((f) => p.includes(f)))) {
+    return "***";
+  }
+  if (path.length > 0 && ![
+    "req",
+    "res",
+    "headers"
+  ].includes(lowerPath[0])) {
+    return value;
+  }
+  return value;
+}, "globalRedactCensor");
+function setRedactCensor(fn) {
+  globalRedactCensor = fn;
+}
+__name(setRedactCensor, "setRedactCensor");
+function getRedactCensor() {
+  return globalRedactCensor;
+}
+__name(getRedactCensor, "getRedactCensor");
+function redact(value, path, sensitiveFields) {
+  return globalRedactCensor(value, path, sensitiveFields);
+}
+__name(redact, "redact");
+function addRedactFields(fields) {
+  const prev = globalRedactCensor;
+  globalRedactCensor = /* @__PURE__ */ __name((value, path, sensitiveFields = getExpandedSensitiveFields()) => prev(value, path, [
+    ...sensitiveFields || [],
+    ...fields
+  ]), "globalRedactCensor");
+  cachedExpandedFields = null;
+}
+__name(addRedactFields, "addRedactFields");
+var cachedExpandedFields = null;
+function getExpandedSensitiveFields() {
+  if (!cachedExpandedFields) {
+    cachedExpandedFields = expandSensitiveFields(defaultSensitiveFields);
+  }
+  return cachedExpandedFields;
+}
+__name(getExpandedSensitiveFields, "getExpandedSensitiveFields");
+function setSensitiveFields(fields) {
+  defaultSensitiveFields.splice(0, defaultSensitiveFields.length, ...fields);
+  cachedExpandedFields = null;
+}
+__name(setSensitiveFields, "setSensitiveFields");
+function addSensitiveFields(fields) {
+  defaultSensitiveFields.push(...fields);
+  cachedExpandedFields = null;
+}
+__name(addSensitiveFields, "addSensitiveFields");
+var _globalThis = typeof globalThis === "object" ? globalThis : global;
+var _global = _globalThis;
+function setupLogger(isGlobal = true) {
+  const sensitiveFields = getExpandedSensitiveFields();
+  const paths = /* @__PURE__ */ new Set([
+    ...defaultRedactPaths,
+    ...sensitiveFields.flatMap((field) => generateDeepPaths(field, 2))
+  ]);
+  const logParams = {
+    name: getCatbeeGlobalConfig().logger?.name || "@catbee/utils",
+    level: getCatbeeGlobalConfig().logger?.level || "info",
+    redact: {
+      paths: Array.from(paths),
+      censor: /* @__PURE__ */ __name((value, path) => redact(value, path), "censor")
+    },
+    serializers: {
+      req: pino.stdSerializers.req,
+      request: pino.stdSerializers.req,
+      res: pino.stdSerializers.res,
+      response: pino.stdSerializers.res,
+      err: pino.stdSerializers.err,
+      error: pino.stdSerializers.err
+    },
+    timestamp: stdTimeFunctions.isoTime
+  };
+  let logger;
+  const logDir = getCatbeeGlobalConfig().logger?.dir?.trim();
+  const hasFileLogging = Boolean(logDir);
+  if (hasFileLogging && getCatbeeGlobalConfig().logger?.pretty) {
+    logger = pino(logParams, pino.transport({
+      targets: [
+        {
+          target: "pino-pretty",
+          level: getCatbeeGlobalConfig().logger?.level ?? "info",
+          options: {
+            colorize: getCatbeeGlobalConfig().logger?.colorize,
+            translateTime: "SYS:standard",
+            ignore: "pid,hostname",
+            singleLine: getCatbeeGlobalConfig().logger?.singleLine,
+            levelFirst: true
+          }
+        },
+        {
+          target: "pino/file",
+          level: getCatbeeGlobalConfig().logger?.level ?? "info",
+          options: {
+            destination: `${logDir}/app.log`,
+            mkdir: true
+          }
+        }
+      ]
+    }));
+  } else if (hasFileLogging) {
+    logger = pino(logParams, pino.transport({
+      target: "pino/file",
+      options: {
+        destination: `${logDir}/app.log`,
+        mkdir: true
+      }
+    }));
+  } else if (getCatbeeGlobalConfig().logger?.pretty) {
+    logger = pino(logParams, pino.transport({
+      target: "pino-pretty",
+      options: {
+        colorize: getCatbeeGlobalConfig().logger?.colorize,
+        translateTime: "SYS:standard",
+        ignore: "pid,hostname",
+        singleLine: getCatbeeGlobalConfig().logger?.singleLine,
+        levelFirst: true
+      }
+    }));
+  } else {
+    logger = pino(logParams);
+  }
+  if (isGlobal) {
+    _global[GLOBAL_LOGGER_KEY] = logger;
+    _global[GLOBAL_LOGGER_KEY]?.debug({
+      logDir: logDir || "none"
+    }, "Global Logger Initialized");
+  }
+  return logger;
+}
+__name(setupLogger, "setupLogger");
+function getLogger(newInstance = false) {
+  if (newInstance) {
+    return setupLogger(false);
+  }
+  const logger = ContextStore.get(StoreKeys.LOGGER);
+  if (logger) return logger;
+  if (!_global[GLOBAL_LOGGER_KEY]) {
+    setupLogger();
+  }
+  return _global[GLOBAL_LOGGER_KEY];
+}
+__name(getLogger, "getLogger");
+function createChildLogger(bindings, parentLogger) {
+  const logger = parentLogger || getLogger();
+  return logger.child(bindings);
+}
+__name(createChildLogger, "createChildLogger");
+function createRequestLogger(requestId, additionalContext = {}) {
+  const logger = createChildLogger({
+    requestId,
+    ...additionalContext
+  });
+  try {
+    ContextStore.set(StoreKeys.LOGGER, logger);
+  } catch {
+    logger.debug("Failed to store logger in context - AsyncLocalStorage not initialized");
+  }
+  return logger;
+}
+__name(createRequestLogger, "createRequestLogger");
+function logError(error, message, context) {
+  const logger = getLogger();
+  const errObj = error instanceof Error ? error : new Error(String(error));
+  const logContext = {
+    ...context,
+    error: errObj
+  };
+  logger.error(logContext, message || errObj.message);
+}
+__name(logError, "logError");
+function expandSensitiveFields(fields) {
+  const set = /* @__PURE__ */ new Set();
+  for (const field of fields) {
+    for (const v of expandSensitiveField(field)) {
+      set.add(v);
+    }
+  }
+  return Array.from(set);
+}
+__name(expandSensitiveFields, "expandSensitiveFields");
+function expandSensitiveField(field) {
+  const parts = field.split(/[_-]/g).filter(Boolean);
+  const camel = parts[0].toLowerCase() + parts.slice(1).map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()).join("");
+  const mergedLower = parts.join("").toLowerCase();
+  const mergedUpper = parts.join("").toUpperCase();
+  const kebab = parts.map((p) => p.toLowerCase()).join("-");
+  const snakeLower = parts.map((p) => p.toLowerCase()).join("_");
+  const snakeUpper = parts.map((p) => p.toUpperCase()).join("_");
+  return Array.from(/* @__PURE__ */ new Set([
+    field,
+    camel,
+    mergedLower,
+    mergedUpper,
+    kebab,
+    snakeLower,
+    snakeUpper
+  ]));
+}
+__name(expandSensitiveField, "expandSensitiveField");
+function generateDeepPaths(field, depth) {
+  const set = /* @__PURE__ */ new Set([
+    field
+  ]);
+  let prefix = "";
+  for (let i = 1; i <= depth; i++) {
+    prefix = prefix ? `${prefix}.*` : "*";
+    set.add(`${prefix}.${field}`);
+  }
+  return [
+    ...set
+  ];
+}
+__name(generateDeepPaths, "generateDeepPaths");
+
+export { _globalThis, addRedactFields, addSensitiveFields, createChildLogger, createRequestLogger, defaultSensitiveFields, expandSensitiveField, expandSensitiveFields, generateDeepPaths, getExpandedSensitiveFields, getLogger, getRedactCensor, logError, redact, setRedactCensor, setSensitiveFields };

package/middleware/index.cjs

@@ -0,0 +1,177 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+'use strict';
+
+var id = require('@catbee/utils/id');
+var httpStatusCodes = require('@catbee/utils/http-status-codes');
+var response = require('@catbee/utils/response');
+var logger = require('@catbee/utils/logger');
+var contextStore = require('@catbee/utils/context-store');
+var exception = require('@catbee/utils/exception');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function requestId(options) {
+  const headerName = options?.headerName || "X-Request-ID";
+  const exposeHeader = options?.exposeHeader !== false;
+  const generateId = options?.generator || id.uuid;
+  return (req, res, next) => {
+    const existingId = req.headers[headerName.toLowerCase()];
+    const id = existingId || generateId();
+    req.id = id;
+    if (exposeHeader) {
+      res.setHeader(headerName, id);
+    }
+    next();
+  };
+}
+__name(requestId, "requestId");
+function responseTime(options) {
+  const addHeader = options?.addHeader !== false;
+  const logOnComplete = options?.logOnComplete === true;
+  return (req, res, next) => {
+    const start = process.hrtime();
+    const getDuration = /* @__PURE__ */ __name(() => {
+      const diff = process.hrtime(start);
+      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);
+    }, "getDuration");
+    if (addHeader) {
+      const originalWriteHead = res.writeHead;
+      res.writeHead = function(...args) {
+        res.setHeader("X-Response-Time", `${getDuration()}ms`);
+        return originalWriteHead.apply(this, args);
+      };
+    }
+    if (logOnComplete) {
+      res.on("finish", () => {
+        logger.getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);
+      });
+    }
+    next();
+  };
+}
+__name(responseTime, "responseTime");
+function timeout(timeoutMs = 3e4) {
+  return (_req, res, next) => {
+    const timer = setTimeout(() => {
+      const response = new exception.RequestTimeoutException("Request timed out");
+      res.status(httpStatusCodes.HttpStatusCodes.REQUEST_TIMEOUT).json(response);
+    }, timeoutMs);
+    res.on("finish", () => {
+      clearTimeout(timer);
+    });
+    next();
+  };
+}
+__name(timeout, "timeout");
+function setupRequestContext(options = {}) {
+  const { headerName = "x-request-id", autoLog = true } = options;
+  return (req, _res, next) => {
+    const requestId2 = req.headers[headerName] || req?.["id"] || id.uuid();
+    contextStore.ContextStore.run({
+      [contextStore.StoreKeys.REQUEST_ID]: requestId2
+    }, () => {
+      const childLogger = logger.getLogger().child({
+        requestId: requestId2,
+        method: req.method,
+        url: req.originalUrl || req.url
+      });
+      req.logger = childLogger;
+      contextStore.ContextStore.set(contextStore.StoreKeys.LOGGER, childLogger);
+      if (autoLog) {
+        req.logger.info("Request context initialized");
+      }
+      next();
+    });
+  };
+}
+__name(setupRequestContext, "setupRequestContext");
+function errorHandler(options) {
+  const logErrors = options?.logErrors !== false;
+  const includeDetails = options?.includeDetails === true;
+  return (err, req, res, _next) => {
+    const status = err?.status || err?.statusCode || httpStatusCodes.HttpStatusCodes.INTERNAL_SERVER_ERROR;
+    if (logErrors) {
+      logger.getLogger().error({
+        err
+      }, `${err.message || "Unknown error"}`);
+    }
+    if (err instanceof response.ErrorResponse) {
+      const result = {
+        error: true,
+        message: err.message,
+        timestamp: err.timestamp,
+        requestId: err?.requestId || req?.id || id.uuid(),
+        status,
+        path: req.originalUrl || req.url
+      };
+      if (includeDetails && err?.stack) {
+        result.stack = err.stack.split("\n").map((line) => line.trim());
+      }
+      return res.status(status).json(result);
+    }
+    return res.status(status).json(response.createFinalErrorResponse(req, status, err?.message || "Internal Server Error", err, {
+      includeDetails
+    }));
+  };
+}
+__name(errorHandler, "errorHandler");
+function healthCheck(options) {
+  const path = options?.path || "/healthz";
+  const checks = options?.checks || [];
+  const detailed = options?.detailed !== false;
+  return async (req, res, next) => {
+    if (req.path !== path) return next();
+    const results = {};
+    let allHealthy = true;
+    for (const check of checks) {
+      try {
+        const result = await Promise.resolve(check.check());
+        results[check.name] = !!result;
+        if (!result) allHealthy = false;
+      } catch {
+        results[check.name] = false;
+        allHealthy = false;
+      }
+    }
+    const status = allHealthy ? httpStatusCodes.HttpStatusCodes.OK : httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE;
+    const response = detailed ? {
+      status: allHealthy ? "ok" : "unhealthy",
+      checks: results,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    } : {
+      status: allHealthy ? "ok" : "unhealthy"
+    };
+    res.status(status).json(response);
+  };
+}
+__name(healthCheck, "healthCheck");
+
+exports.errorHandler = errorHandler;
+exports.healthCheck = healthCheck;
+exports.requestId = requestId;
+exports.responseTime = responseTime;
+exports.setupRequestContext = setupRequestContext;
+exports.timeout = timeout;