@catbee/utils 2.0.0-next.0 → 2.0.0-next.1

package/obj/index.mjs

@@ -26,8 +26,12 @@ 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 !!obj && typeof obj === "object" && Object.keys(obj).length === 0;
+  return isObject(obj) && Object.keys(obj).length === 0;
 }
 __name(isObjEmpty, "isObjEmpty");
 function pick(obj, keys) {
@@ -42,117 +46,38 @@ function omit(obj, keys) {
 }
 __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);
+  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 (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));
+    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;
       }
-    }
-    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]);
+      if (!t || typeof t !== "object") {
+        t = Object.create(Object.getPrototypeOf(s));
       }
-    });
-    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);
+      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;
-    }
-    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 t;
     }
+    return s;
+  }, "mergeInto");
+  for (const s of sources) {
+    target = mergeInto(target, s);
   }
   return target;
 }
@@ -167,6 +92,7 @@ __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 {
@@ -182,63 +108,52 @@ function getValueByPath(obj, path) {
   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 obj;
+  if (parts.length === 0) return clone;
   const forbiddenKeys = /* @__PURE__ */ new Set([
     "__proto__",
     "prototype",
     "constructor"
   ]);
-  let current = obj;
+  let current = clone;
   for (let i = 0; i < parts.length - 1; i++) {
     const key = parts[i];
-    if (forbiddenKeys.has(key)) {
-      return obj;
-    }
+    if (forbiddenKeys.has(key)) return clone;
     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);
-    }
+    const nextIsIndex = !Number.isNaN(Number(nextKey));
+    current[key] = ensureNextContainer(current[key], nextIsIndex);
     current = current[key];
   }
-  const finalKey = parts[parts.length - 1];
-  if (forbiddenKeys.has(finalKey)) {
-    return obj;
-  }
+  const finalKey = parts.at(-1);
+  if (forbiddenKeys.has(finalKey)) return clone;
   current[finalKey] = value;
-  return obj;
+  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 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]));
+  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) {
@@ -252,35 +167,108 @@ function mapObject(obj, mapFn) {
   ]));
 }
 __name(mapObject, "mapObject");
-function deepClone(value) {
-  try {
-    if (typeof globalThis.structuredClone === "function") {
-      return globalThis.structuredClone(value);
-    }
-  } catch (_) {
+function _deepClone(value, seen) {
+  if (typeof value === "function" || typeof value === "symbol") {
+    return value;
   }
-  try {
-    return JSON.parse(JSON.stringify(value));
-  } catch (_) {
+  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 prop of Object.getOwnPropertyNames(obj)) {
-    const value = obj[prop];
-    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
-      deepFreeze(value);
+  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 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]) => {

package/package.json

@@ -1,13 +1,10 @@
 {
   "name": "@catbee/utils",
-  "version": "2.0.0-next.0",
+  "version": "2.0.0-next.1",
   "description": "A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.",
   "publishConfig": {
     "access": "public"
   },
-  "main": "index.cjs",
-  "module": "index.mjs",
-  "types": "index.d.ts",
   "author": "Hari G <harig@catbee.in>",
   "maintainers": [
     "Hari G <harig@catbee.in>",
@@ -23,8 +20,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "pino": "^10.1.0",
-    "reflect-metadata": "^0.2.2"
+    "pino": "^10.1.0"
   },
   "optionalDependencies": {
     "@scalar/express-api-reference": "^0.8.30",
@@ -36,7 +32,8 @@
     "express-rate-limit": "^8.2.1",
     "helmet": "^8.1.0",
     "pino-pretty": "^13.1.3",
-    "prom-client": "^15.1.3"
+    "prom-client": "^15.1.3",
+    "reflect-metadata": "^0.2.2"
   },
   "peerDependencies": {
     "express": "^5.1.0"
@@ -49,6 +46,9 @@
   "engines": {
     "node": ">=18.4"
   },
+  "main": "index.cjs",
+  "module": "index.mjs",
+  "types": "index.d.ts",
   "files": [
     "**/*.mjs",
     "**/*.cjs",
@@ -193,10 +193,10 @@
       "require": "./url/index.cjs",
       "types": "./url/index.d.ts"
     },
-    "./validate": {
-      "import": "./validate/index.mjs",
-      "require": "./validate/index.cjs",
-      "types": "./validate/index.d.ts"
+    "./validation": {
+      "import": "./validation/index.mjs",
+      "require": "./validation/index.cjs",
+      "types": "./validation/index.d.ts"
     }
   }
 }

package/performance/index.cjs

@@ -193,8 +193,8 @@ function memoize(fn, options = {}) {
 __name(memoize, "memoize");
 function trackMemoryUsage(fn, options = {}) {
   const { log = false, label = fn.name || "anonymous function" } = options;
-  if (global.gc) {
-    global.gc();
+  if (globalThis.gc) {
+    globalThis.gc();
   }
   const beforeMemory = process.memoryUsage();
   const result = fn();

package/performance/index.d.ts

@@ -22,4 +22,141 @@
  * SOFTWARE.
  */
 
-export * from './performance.utils';
+/**
+ * Options for timing function execution.
+ */
+interface TimingOptions {
+    /** Optional label for the timing (defaults to function name) */
+    label?: string;
+    /** Whether to log the timing (default: false) */
+    log?: boolean;
+    /** Log level to use if logging is enabled (default: 'debug') */
+    logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * Result of a timing operation.
+ */
+interface TimingResult {
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Duration in seconds */
+    durationSec: number;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp */
+    endTime: number;
+    /** Label used for the timing */
+    label: string;
+}
+/**
+ * Measure the execution time of a synchronous function.
+ *
+ * @param fn - Function to measure
+ * @param options - Timing options
+ * @returns Result containing the return value and timing information
+ *
+ * @example
+ * ```typescript
+ * const { result, timing } = timeSync(() => {
+ *   // Some expensive operation
+ *   return computeResult();
+ * }, { label: 'Computation', log: true });
+ *
+ * console.log(`Result: ${result}, took ${timing.durationMs}ms`);
+ * ```
+ */
+declare function timeSync<T>(fn: () => T, options?: TimingOptions): {
+    result: T;
+    timing: TimingResult;
+};
+/**
+ * Measure the execution time of an asynchronous function.
+ *
+ * @param fn - Async function to measure
+ * @param options - Timing options
+ * @returns Promise resolving to result and timing information
+ *
+ * @example
+ * ```typescript
+ * const { result, timing } = await timeAsync(async () => {
+ *   // Some expensive async operation
+ *   const data = await fetchData();
+ *   return processData(data);
+ * }, { label: 'API Request', log: true });
+ *
+ * console.log(`Fetched ${result.length} items in ${timing.durationSec.toFixed(2)}s`);
+ * ```
+ */
+declare function timeAsync<T>(fn: () => Promise<T>, options?: TimingOptions): Promise<{
+    result: T;
+    timing: TimingResult;
+}>;
+/**
+ * Create a timing decorator for class methods.
+ *
+ * @param options - Timing options
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * class DataService {
+ *   @timed({ log: true, logLevel: 'info' })
+ *   async fetchData() {
+ *     // ...implementation
+ *   }
+ * }
+ * ```
+ */
+declare function timed(options?: TimingOptions): (target: any, propertyKeyOrContext: string | symbol | any, descriptor?: PropertyDescriptor) => void;
+/**
+ * Memoize function results with optional TTL and max cache size.
+ *
+ * @param fn - Function to memoize
+ * @param options - Memoization options
+ * @returns Memoized function
+ *
+ * @example
+ * ```typescript
+ * // Cache results for 30 seconds, with a maximum of 100 entries
+ * const cachedFetch = memoize(
+ *   async (url) => {
+ *     const response = await fetch(url);
+ *     return response.json();
+ *   },
+ *   { ttl: 30000, maxSize: 100, cacheKey: (url) => url }
+ * );
+ * ```
+ */
+declare function memoize<T, Args extends any[]>(fn: (...args: Args) => T, options?: {
+    /** Time-to-live in milliseconds (default: indefinite) */
+    ttl?: number;
+    /** Maximum cache size (default: unlimited) */
+    maxSize?: number;
+    /** Function to generate a cache key from arguments */
+    cacheKey?: (...args: Args) => string;
+    /** Auto-cleanup interval in milliseconds (default: disabled) */
+    autoCleanupMs?: number;
+}): (...args: Args) => T;
+/**
+ * Track memory usage for a function execution.
+ *
+ * @param fn - Function to track
+ * @param options - Memory tracking options
+ * @returns Result and memory usage information
+ */
+declare function trackMemoryUsage<T>(fn: () => T, options?: {
+    /** Whether to log the memory usage (default: false) */
+    log?: boolean;
+    /** Label for the memory tracking (default: function name) */
+    label?: string;
+}): {
+    result: T;
+    memoryUsage: {
+        before: NodeJS.MemoryUsage;
+        after: NodeJS.MemoryUsage;
+        diff: Record<string, number>;
+    };
+};
+
+export { memoize, timeAsync, timeSync, timed, trackMemoryUsage };
+export type { TimingOptions, TimingResult };

package/performance/index.mjs

@@ -191,8 +191,8 @@ function memoize(fn, options = {}) {
 __name(memoize, "memoize");
 function trackMemoryUsage(fn, options = {}) {
   const { log = false, label = fn.name || "anonymous function" } = options;
-  if (global.gc) {
-    global.gc();
+  if (globalThis.gc) {
+    globalThis.gc();
   }
   const beforeMemory = process.memoryUsage();
   const result = fn();

package/request/index.cjs

@@ -61,7 +61,7 @@ function parseNumberParam(value, options = {}) {
     };
   }
   const num = Number(value);
-  if (isNaN(num)) {
+  if (Number.isNaN(num)) {
     if (throwOnError) throw new exception.BadRequestException(errorMessage);
     return {
       isValid: false,