@catbee/utils 1.0.5 → 2.0.0-next.0

package/middleware/middleware.utils.d.ts

@@ -0,0 +1,123 @@
+/*
+ * 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 type { Request, Response, NextFunction } from 'express';
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export declare function setupRequestContext(options?: {
+    headerName?: string;
+    autoLog?: boolean;
+}): Middleware;
+export 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');
+ * });
+ */
+export 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
+ */
+export declare function healthCheck(options?: {
+    path?: string;
+    checks?: Array<{
+        name: string;
+        check: () => Promise<boolean> | boolean;
+    }>;
+    detailed?: boolean;
+}): Middleware;

package/obj/index.cjs

@@ -0,0 +1,317 @@
+/*
+ * 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 isObjEmpty(obj) {
+  return !!obj && typeof obj === "object" && 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) {
+  if (!sources.length) return target;
+  const seen = /* @__PURE__ */ new WeakMap();
+  seen.set(target, target);
+  for (const s of sources) {
+    if (s && typeof s === "object") {
+      seen.set(s, target);
+    }
+  }
+  function deepClone2(value) {
+    if (value === null || typeof value !== "object") return value;
+    if (seen.has(value)) return seen.get(value);
+    if (value instanceof Date) {
+      return new Date(value.getTime());
+    }
+    if (Array.isArray(value)) {
+      const clone2 = [];
+      seen.set(value, clone2);
+      value.forEach((item, i) => clone2[i] = deepClone2(item));
+      return clone2;
+    }
+    if (value instanceof Set) {
+      const clone2 = /* @__PURE__ */ new Set();
+      seen.set(value, clone2);
+      value.forEach((item) => clone2.add(deepClone2(item)));
+      return clone2;
+    }
+    if (value instanceof Map) {
+      const clone2 = /* @__PURE__ */ new Map();
+      seen.set(value, clone2);
+      value.forEach((val, key) => clone2.set(key, deepClone2(val)));
+      return clone2;
+    }
+    if (value instanceof RegExp) {
+      return new RegExp(value.source, value.flags);
+    }
+    if (value instanceof ArrayBuffer) {
+      return value.slice(0);
+    }
+    if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+      const typed = value;
+      const ctor = typed.constructor;
+      const typedArrayCtors = [
+        Int8Array,
+        Uint8Array,
+        Uint8ClampedArray,
+        Int16Array,
+        Uint16Array,
+        Int32Array,
+        Uint32Array,
+        Float32Array,
+        Float64Array,
+        BigInt64Array,
+        BigUint64Array
+      ].filter(Boolean);
+      const typedArrayCtorSet = new Set(typedArrayCtors);
+      if (typeof ctor === "function" && typedArrayCtorSet.has(ctor)) {
+        const buffer = typed.buffer && typeof typed.buffer.slice === "function" ? typed.buffer.slice(0) : typed.buffer;
+        const clone2 = new ctor(buffer, typed.byteOffset, typed.length);
+        seen.set(value, clone2);
+        return clone2;
+      } else if (typeof typed.slice === "function") {
+        const clone2 = typed.slice();
+        seen.set(value, clone2);
+        return clone2;
+      } else {
+        throw new Error("Cannot deep clone unknown TypedArray type: " + (typed && typed.constructor && typed.constructor.name));
+      }
+    }
+    const clone = Object.create(Object.getPrototypeOf(value));
+    seen.set(value, clone);
+    Reflect.ownKeys(value).forEach((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor.get || descriptor.set) {
+        Object.defineProperty(clone, key, descriptor);
+      } else {
+        clone[key] = deepClone2(value[key]);
+      }
+    });
+    return clone;
+  }
+  __name(deepClone2, "deepClone");
+  function mergeProp(target2, source, key) {
+    const targetValue = target2[key];
+    const sourceValue = source[key];
+    if (sourceValue === void 0) return;
+    if (sourceValue === null || typeof sourceValue !== "object") {
+      target2[key] = sourceValue;
+      return;
+    }
+    if (Array.isArray(sourceValue)) {
+      target2[key] = deepClone2(sourceValue);
+      return;
+    }
+    if (sourceValue instanceof Date || sourceValue instanceof RegExp || sourceValue instanceof Set || sourceValue instanceof Map || sourceValue instanceof ArrayBuffer || ArrayBuffer.isView(sourceValue) && !(sourceValue instanceof DataView)) {
+      target2[key] = deepClone2(sourceValue);
+      return;
+    }
+    if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
+      for (const k of Reflect.ownKeys(sourceValue)) {
+        mergeProp(targetValue, sourceValue, k);
+      }
+      return;
+    }
+    target2[key] = deepClone2(sourceValue);
+  }
+  __name(mergeProp, "mergeProp");
+  for (const source of sources) {
+    if (source == null) continue;
+    for (const key of Reflect.ownKeys(source)) {
+      mergeProp(target, source, key);
+    }
+  }
+  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 (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 setValueByPath(obj, path, value) {
+  if (!obj || typeof obj !== "object") return obj;
+  const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  if (parts.length === 0) return obj;
+  const forbiddenKeys = /* @__PURE__ */ new Set([
+    "__proto__",
+    "prototype",
+    "constructor"
+  ]);
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    if (forbiddenKeys.has(key)) {
+      return obj;
+    }
+    const nextKey = parts[i + 1];
+    const isArrayIndex = !isNaN(Number(nextKey));
+    if (current[key] === void 0) {
+      current[key] = isArrayIndex ? [] : /* @__PURE__ */ Object.create(null);
+    } else if (typeof current[key] !== "object" || current[key] === null) {
+      current[key] = isArrayIndex ? [] : /* @__PURE__ */ Object.create(null);
+    }
+    current = current[key];
+  }
+  const finalKey = parts[parts.length - 1];
+  if (forbiddenKeys.has(finalKey)) {
+    return obj;
+  }
+  current[finalKey] = value;
+  return obj;
+}
+__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 Date || b instanceof Date) {
+    return false;
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!isEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((key) => Object.prototype.hasOwnProperty.call(b, 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) {
+  try {
+    if (typeof globalThis.structuredClone === "function") {
+      return globalThis.structuredClone(value);
+    }
+  } catch (_) {
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (_) {
+    return value;
+  }
+}
+__name(deepClone, "deepClone");
+function deepFreeze(obj) {
+  Object.freeze(obj);
+  for (const prop of Object.getOwnPropertyNames(obj)) {
+    const value = obj[prop];
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+  return obj;
+}
+__name(deepFreeze, "deepFreeze");
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+__name(isObject, "isObject");
+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;

package/obj/index.d.ts

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+
+export * from './obj.utils';