@catbee/utils 1.1.0 → 2.0.0-next.1

package/middleware/index.d.ts

@@ -0,0 +1,127 @@
+/*
+ * 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 { Request, Response, NextFunction } from 'express';
+
+type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+/**
+ * Attaches a unique request ID to each request.
+ * Useful for request tracing and correlation between logs.
+ *
+ * @param {object} [options] - Configuration options
+ * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID
+ * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response
+ * @param {() => string} [options.generator] - Custom ID generator function
+ * @returns {Middleware} Express-compatible middleware
+ */
+declare function requestId(options?: {
+    headerName?: string;
+    exposeHeader?: boolean;
+    generator?: () => string;
+}): Middleware;
+/**
+ * Measures request processing time and logs or adds it to response headers.
+ *
+ * @param {object} [options] - Configuration options
+ * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header
+ * @param {boolean} [options.logOnComplete=false] - Whether to log timing info
+ * @returns {Middleware} Express-compatible middleware
+ */
+declare function responseTime(options?: {
+    addHeader?: boolean;
+    logOnComplete?: boolean;
+}): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Request timeout middleware.
+ * Aborts requests that take too long to process.
+ *
+ * @param {number} [timeoutMs=30000] - Timeout in milliseconds
+ * @returns {Middleware} Express-compatible middleware
+ */
+declare function timeout(timeoutMs?: number): Middleware;
+/**
+ * Creates an Express middleware that initializes a per-request context.
+ *
+ * @param {object} [options] - Optional configuration
+ * @param {string} [options.headerName='x-request-id'] - Header to look for request ID
+ * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized
+ * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function
+ */
+declare function setupRequestContext(options?: {
+    headerName?: string;
+    autoLog?: boolean;
+}): Middleware;
+interface ErrorHandlerOptions {
+    /** Whether to log errors (default: true) */
+    logErrors?: boolean;
+    /** Whether to include error details in non-production (default: false) */
+    includeDetails?: boolean;
+}
+/**
+ * Global error handling middleware with enhanced features.
+ *
+ * @param {ErrorHandlerOptions} options - Error handler options
+ * @param {boolean} [options.logErrors=true] - Whether to log errors
+ * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production
+ * @returns Error middleware
+ *
+ * @example
+ * import express from 'express';
+ * import { errorHandler } from '@catbee/utils';
+ *
+ * const app = express();
+ *
+ * // Your routes
+ * app.get('/ping', (req, res) => {
+ *   throw new Error('Something went wrong');
+ * });
+ *
+ * // Error handler (must be last middleware)
+ * app.use(errorHandler({ includeDetails: true }));
+ *
+ * app.listen(3000, () => {
+ *   console.log('Server running on port 3000');
+ * });
+ */
+declare function errorHandler(options?: ErrorHandlerOptions): (err: any, req: Request, res: Response, _next: NextFunction) => Response<any, Record<string, any>>;
+/**
+ * Health check middleware for service status and custom checks.
+ *
+ * @param {object} [options] - Health check options
+ * @param {string} [options.path='/healthz'] - Health check endpoint path
+ * @param {Array<{name: string; check: () => Promise<boolean> | boolean}>} [options.checks] - Custom health checks
+ * @param {boolean} [options.detailed=true] - Show detailed check results
+ * @returns {Middleware} Express-compatible middleware
+ */
+declare function healthCheck(options?: {
+    path?: string;
+    checks?: Array<{
+        name: string;
+        check: () => Promise<boolean> | boolean;
+    }>;
+    detailed?: boolean;
+}): Middleware;
+
+export { errorHandler, healthCheck, requestId, responseTime, setupRequestContext, timeout };
+export type { ErrorHandlerOptions, Middleware };

package/middleware/index.mjs

@@ -0,0 +1,170 @@
+/*
+ * 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 { uuid } from '@catbee/utils/id';
+import { HttpStatusCodes } from '@catbee/utils/http-status-codes';
+import { ErrorResponse, createFinalErrorResponse } from '@catbee/utils/response';
+import { getLogger } from '@catbee/utils/logger';
+import { ContextStore, StoreKeys } from '@catbee/utils/context-store';
+import { RequestTimeoutException } from '@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 || 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", () => {
+        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 RequestTimeoutException("Request timed out");
+      res.status(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"] || uuid();
+    ContextStore.run({
+      [StoreKeys.REQUEST_ID]: requestId2
+    }, () => {
+      const childLogger = getLogger().child({
+        requestId: requestId2,
+        method: req.method,
+        url: req.originalUrl || req.url
+      });
+      req.logger = childLogger;
+      ContextStore.set(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.INTERNAL_SERVER_ERROR;
+    if (logErrors) {
+      getLogger().error({
+        err
+      }, `${err.message || "Unknown error"}`);
+    }
+    if (err instanceof ErrorResponse) {
+      const result = {
+        error: true,
+        message: err.message,
+        timestamp: err.timestamp,
+        requestId: err?.requestId || req?.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(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.OK : 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");
+
+export { errorHandler, healthCheck, requestId, responseTime, setupRequestContext, timeout };

package/obj/index.cjs

@@ -0,0 +1,305 @@
+/*
+ * 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 __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/obj/obj.utils.ts
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+__name(isObject, "isObject");
+function isObjEmpty(obj) {
+  return isObject(obj) && Object.keys(obj).length === 0;
+}
+__name(isObjEmpty, "isObjEmpty");
+function pick(obj, keys) {
+  return Object.fromEntries(keys.map((key) => [
+    key,
+    obj[key]
+  ]));
+}
+__name(pick, "pick");
+function omit(obj, keys) {
+  return Object.fromEntries(Object.entries(obj).filter(([key]) => !keys.includes(key)));
+}
+__name(omit, "omit");
+function deepObjMerge(target, ...sources) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  const mergeInto = /* @__PURE__ */ __name((t, s) => {
+    if (s === void 0) return t;
+    if (typeof s === "function" || typeof s === "symbol") return s;
+    if (Array.isArray(s)) {
+      const cloned = deepClone(s);
+      seen.set(s, cloned);
+      return cloned;
+    }
+    if (s && typeof s === "object") {
+      if (seen.has(s)) return seen.get(s);
+      if (s instanceof Date || s instanceof Map || s instanceof Set || s instanceof RegExp || s instanceof ArrayBuffer || ArrayBuffer.isView(s)) {
+        const cloned = deepClone(s);
+        seen.set(s, cloned);
+        return cloned;
+      }
+      if (!t || typeof t !== "object") {
+        t = Object.create(Object.getPrototypeOf(s));
+      }
+      seen.set(s, t);
+      for (const key of Reflect.ownKeys(s)) {
+        if (key === "__proto__") continue;
+        const sv = s[key];
+        if (sv === void 0) continue;
+        t[key] = mergeInto(t[key], sv);
+      }
+      return t;
+    }
+    return s;
+  }, "mergeInto");
+  for (const s of sources) {
+    target = mergeInto(target, s);
+  }
+  return target;
+}
+__name(deepObjMerge, "deepObjMerge");
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+__name(isPlainObject, "isPlainObject");
+function flattenObject(obj, prefix = "") {
+  return Object.entries(obj).reduce((acc, [key, value]) => {
+    const newKey = prefix ? `${prefix}.${key}` : key;
+    if (key === "__proto__") return acc;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      Object.assign(acc, flattenObject(value, newKey));
+    } else {
+      acc[newKey] = value;
+    }
+    return acc;
+  }, {});
+}
+__name(flattenObject, "flattenObject");
+function getValueByPath(obj, path) {
+  if (!obj || typeof obj !== "object") return void 0;
+  const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  return parts.reduce((acc, key) => acc?.[key], obj);
+}
+__name(getValueByPath, "getValueByPath");
+function ensureNextContainer(curr, nextIsIndex) {
+  if (curr === void 0 || typeof curr !== "object" || curr === null) {
+    return nextIsIndex ? [] : /* @__PURE__ */ Object.create(null);
+  }
+  return curr;
+}
+__name(ensureNextContainer, "ensureNextContainer");
+function setValueByPath(obj, path, value) {
+  if (!obj || typeof obj !== "object") return obj;
+  const clone = deepClone(obj);
+  const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  if (parts.length === 0) return clone;
+  const forbiddenKeys = /* @__PURE__ */ new Set([
+    "__proto__",
+    "prototype",
+    "constructor"
+  ]);
+  let current = clone;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    if (forbiddenKeys.has(key)) return clone;
+    const nextKey = parts[i + 1];
+    const nextIsIndex = !Number.isNaN(Number(nextKey));
+    current[key] = ensureNextContainer(current[key], nextIsIndex);
+    current = current[key];
+  }
+  const finalKey = parts.at(-1);
+  if (forbiddenKeys.has(finalKey)) return clone;
+  current[finalKey] = value;
+  return clone;
+}
+__name(setValueByPath, "setValueByPath");
+function isEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null || typeof a !== "object" || typeof b !== "object") return false;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (a instanceof RegExp && b instanceof RegExp) return a.source === b.source && a.flags === b.flags;
+  if (a instanceof Set && b instanceof Set) return a.size === b.size && [
+    ...a
+  ].every((v) => b.has(v));
+  if (a instanceof Map && b instanceof Map) return a.size === b.size && [
+    ...a
+  ].every(([k, v]) => isEqual(v, b.get(k)));
+  if (a instanceof ArrayBuffer && b instanceof ArrayBuffer) return isEqual(new Uint8Array(a), new Uint8Array(b));
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => isEqual(v, b[i]));
+  return Object.keys(a).length === Object.keys(b).length && Object.keys(a).every((key) => isEqual(a[key], b[key]));
+}
+__name(isEqual, "isEqual");
+function filterObject(obj, predicate) {
+  return Object.fromEntries(Object.entries(obj).filter(([key, value]) => predicate(value, key, obj)));
+}
+__name(filterObject, "filterObject");
+function mapObject(obj, mapFn) {
+  return Object.fromEntries(Object.entries(obj).map(([key, value]) => [
+    key,
+    mapFn(value, key, obj)
+  ]));
+}
+__name(mapObject, "mapObject");
+function _deepClone(value, seen) {
+  if (typeof value === "function" || typeof value === "symbol") {
+    return value;
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (seen.has(value)) {
+    return seen.get(value);
+  }
+  let result;
+  if (Array.isArray(value)) {
+    result = [];
+    seen.set(value, result);
+    for (const item of value) {
+      result.push(_deepClone(item, seen));
+    }
+    return result;
+  }
+  if (value instanceof Date) {
+    result = new Date(value.getTime());
+    seen.set(value, result);
+    return result;
+  }
+  if (value instanceof Map) {
+    result = /* @__PURE__ */ new Map();
+    seen.set(value, result);
+    for (const [k, v] of value) {
+      result.set(_deepClone(k, seen), _deepClone(v, seen));
+    }
+    return result;
+  }
+  if (value instanceof Set) {
+    result = /* @__PURE__ */ new Set();
+    seen.set(value, result);
+    for (const v of value) {
+      result.add(_deepClone(v, seen));
+    }
+    return result;
+  }
+  if (value instanceof RegExp) {
+    result = new RegExp(value.source, value.flags);
+    seen.set(value, result);
+    return result;
+  }
+  if (ArrayBuffer.isView(value)) {
+    if (value instanceof DataView) {
+      const buf2 = _deepClone(value.buffer, seen);
+      const clone2 = new DataView(buf2, value.byteOffset, value.byteLength);
+      seen.set(value, clone2);
+      return clone2;
+    }
+    const typed = value;
+    const buf = _deepClone(typed.buffer, seen);
+    const clone = new typed.constructor(buf, typed.byteOffset, typed.length);
+    seen.set(value, clone);
+    return clone;
+  }
+  if (value instanceof ArrayBuffer) {
+    result = value.slice(0);
+    seen.set(value, result);
+    return result;
+  }
+  result = Object.create(Object.getPrototypeOf(value));
+  seen.set(value, result);
+  for (const key of Reflect.ownKeys(value)) {
+    const desc = Object.getOwnPropertyDescriptor(value, key);
+    if (desc?.get || desc?.set) {
+      Object.defineProperty(result, key, {
+        get: desc.get,
+        set: desc.set,
+        enumerable: desc.enumerable,
+        configurable: desc.configurable
+      });
+    } else {
+      Object.defineProperty(result, key, {
+        value: _deepClone(value[key], seen),
+        writable: desc?.writable ?? true,
+        enumerable: desc?.enumerable ?? true,
+        configurable: desc?.configurable ?? true
+      });
+    }
+  }
+  return result;
+}
+__name(_deepClone, "_deepClone");
+function deepClone(value) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  return _deepClone(value, seen);
+}
+__name(deepClone, "deepClone");
+function deepFreeze(obj) {
+  Object.freeze(obj);
+  for (const key of Reflect.ownKeys(obj)) {
+    const val = obj[key];
+    if (isObject(val) && !Object.isFrozen(val)) {
+      deepFreeze(val);
+    }
+  }
+  return obj;
+}
+__name(deepFreeze, "deepFreeze");
+function getAllPaths(obj, parentPath = "") {
+  if (!isObject(obj)) return [];
+  return Object.entries(obj).flatMap(([key, value]) => {
+    const currentPath = parentPath ? `${parentPath}.${key}` : key;
+    if (isObject(value)) {
+      return [
+        currentPath,
+        ...getAllPaths(value, currentPath)
+      ];
+    }
+    return [
+      currentPath
+    ];
+  });
+}
+__name(getAllPaths, "getAllPaths");
+
+exports.deepClone = deepClone;
+exports.deepFreeze = deepFreeze;
+exports.deepObjMerge = deepObjMerge;
+exports.filterObject = filterObject;
+exports.flattenObject = flattenObject;
+exports.getAllPaths = getAllPaths;
+exports.getValueByPath = getValueByPath;
+exports.isEqual = isEqual;
+exports.isObjEmpty = isObjEmpty;
+exports.isObject = isObject;
+exports.isPlainObject = isPlainObject;
+exports.mapObject = mapObject;
+exports.omit = omit;
+exports.pick = pick;
+exports.setValueByPath = setValueByPath;