@catbee/utils 1.1.0 → 2.0.0-next.0

package/performance/index.cjs

@@ -0,0 +1,231 @@
+/*
+ * 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 cache = require('@catbee/utils/cache');
+var logger = require('@catbee/utils/logger');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function timeSync(fn, options = {}) {
+  const { label = fn.name || "anonymous function", log = false, logLevel = "debug" } = options;
+  const startTime = performance.now();
+  const result = fn();
+  const endTime = performance.now();
+  const durationMs = endTime - startTime;
+  const durationSec = durationMs / 1e3;
+  const timing = {
+    durationMs,
+    durationSec,
+    startTime,
+    endTime,
+    label
+  };
+  if (log) {
+    const logger$1 = logger.getLogger();
+    const message = `${label} completed in ${durationMs.toFixed(2)}ms`;
+    switch (logLevel) {
+      case "trace":
+        logger$1.trace({
+          timing
+        }, message);
+        break;
+      case "debug":
+        logger$1.debug({
+          timing
+        }, message);
+        break;
+      case "info":
+        logger$1.info({
+          timing
+        }, message);
+        break;
+      case "warn":
+        logger$1.warn({
+          timing
+        }, message);
+        break;
+      case "error":
+        logger$1.error({
+          timing
+        }, message);
+        break;
+      default:
+        logger$1.debug({
+          timing
+        }, message);
+        break;
+    }
+  }
+  return {
+    result,
+    timing
+  };
+}
+__name(timeSync, "timeSync");
+async function timeAsync(fn, options = {}) {
+  const { label = fn.name || "anonymous async function", log = false, logLevel = "debug" } = options;
+  const startTime = performance.now();
+  const result = await fn();
+  const endTime = performance.now();
+  const durationMs = endTime - startTime;
+  const durationSec = durationMs / 1e3;
+  const timing = {
+    durationMs,
+    durationSec,
+    startTime,
+    endTime,
+    label
+  };
+  if (log) {
+    const logger$1 = logger.getLogger();
+    const message = `${label} completed in ${durationMs.toFixed(2)}ms`;
+    switch (logLevel) {
+      case "trace":
+        logger$1.trace({
+          timing
+        }, message);
+        break;
+      case "debug":
+        logger$1.debug({
+          timing
+        }, message);
+        break;
+      case "info":
+        logger$1.info({
+          timing
+        }, message);
+        break;
+      case "warn":
+        logger$1.warn({
+          timing
+        }, message);
+        break;
+      case "error":
+        logger$1.error({
+          timing
+        }, message);
+        break;
+      default:
+        logger$1.debug({
+          timing
+        }, message);
+        break;
+    }
+  }
+  return {
+    result,
+    timing
+  };
+}
+__name(timeAsync, "timeAsync");
+function timed(options = {}) {
+  return function(target, propertyKeyOrContext, descriptor) {
+    let propertyKey;
+    let actualDescriptor;
+    if (typeof propertyKeyOrContext === "object" && propertyKeyOrContext !== null && "name" in propertyKeyOrContext) {
+      propertyKey = propertyKeyOrContext.name;
+      actualDescriptor = descriptor ?? Object.getOwnPropertyDescriptor(target, propertyKey);
+    } else {
+      propertyKey = propertyKeyOrContext;
+      actualDescriptor = descriptor ?? Object.getOwnPropertyDescriptor(target, propertyKey);
+    }
+    const originalMethod = actualDescriptor.value;
+    actualDescriptor.value = function(...args) {
+      const methodOptions = {
+        ...options,
+        label: options.label || `${target.constructor.name}.${String(propertyKey)}`
+      };
+      if (originalMethod.constructor.name === "AsyncFunction") {
+        return timeAsync(() => originalMethod.apply(this, args), methodOptions).then(({ result }) => result);
+      } else {
+        return timeSync(() => originalMethod.apply(this, args), methodOptions).result;
+      }
+    };
+    if (descriptor) {
+      descriptor.value = actualDescriptor.value;
+    } else {
+      Object.defineProperty(target, propertyKey, actualDescriptor);
+    }
+  };
+}
+__name(timed, "timed");
+function memoize(fn, options = {}) {
+  const { ttl, maxSize, autoCleanupMs, cacheKey = /* @__PURE__ */ __name((...args) => JSON.stringify(args), "cacheKey") } = options;
+  const cache$1 = new cache.TTLCache({
+    ttlMs: ttl,
+    maxSize,
+    autoCleanupMs
+  });
+  return function(...args) {
+    const key = cacheKey(...args);
+    const cachedValue = cache$1.get(key);
+    if (cachedValue !== void 0) {
+      return cachedValue;
+    }
+    const value = fn(...args);
+    cache$1.set(key, value);
+    return value;
+  };
+}
+__name(memoize, "memoize");
+function trackMemoryUsage(fn, options = {}) {
+  const { log = false, label = fn.name || "anonymous function" } = options;
+  if (global.gc) {
+    global.gc();
+  }
+  const beforeMemory = process.memoryUsage();
+  const result = fn();
+  const afterMemory = process.memoryUsage();
+  const diff = {};
+  for (const key in afterMemory) {
+    if (Object.prototype.hasOwnProperty.call(afterMemory, key)) {
+      diff[key] = afterMemory[key] - beforeMemory[key];
+    }
+  }
+  if (log) {
+    logger.getLogger().info({
+      label,
+      memoryBefore: beforeMemory,
+      memoryAfter: afterMemory,
+      memoryDiff: diff
+    }, `Memory usage for ${label}`);
+  }
+  return {
+    result,
+    memoryUsage: {
+      before: beforeMemory,
+      after: afterMemory,
+      diff
+    }
+  };
+}
+__name(trackMemoryUsage, "trackMemoryUsage");
+
+exports.memoize = memoize;
+exports.timeAsync = timeAsync;
+exports.timeSync = timeSync;
+exports.timed = timed;
+exports.trackMemoryUsage = trackMemoryUsage;

package/performance/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 './performance.utils';

package/performance/index.mjs

@@ -0,0 +1,225 @@
+/*
+ * 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 { TTLCache } from '@catbee/utils/cache';
+import { getLogger } from '@catbee/utils/logger';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function timeSync(fn, options = {}) {
+  const { label = fn.name || "anonymous function", log = false, logLevel = "debug" } = options;
+  const startTime = performance.now();
+  const result = fn();
+  const endTime = performance.now();
+  const durationMs = endTime - startTime;
+  const durationSec = durationMs / 1e3;
+  const timing = {
+    durationMs,
+    durationSec,
+    startTime,
+    endTime,
+    label
+  };
+  if (log) {
+    const logger = getLogger();
+    const message = `${label} completed in ${durationMs.toFixed(2)}ms`;
+    switch (logLevel) {
+      case "trace":
+        logger.trace({
+          timing
+        }, message);
+        break;
+      case "debug":
+        logger.debug({
+          timing
+        }, message);
+        break;
+      case "info":
+        logger.info({
+          timing
+        }, message);
+        break;
+      case "warn":
+        logger.warn({
+          timing
+        }, message);
+        break;
+      case "error":
+        logger.error({
+          timing
+        }, message);
+        break;
+      default:
+        logger.debug({
+          timing
+        }, message);
+        break;
+    }
+  }
+  return {
+    result,
+    timing
+  };
+}
+__name(timeSync, "timeSync");
+async function timeAsync(fn, options = {}) {
+  const { label = fn.name || "anonymous async function", log = false, logLevel = "debug" } = options;
+  const startTime = performance.now();
+  const result = await fn();
+  const endTime = performance.now();
+  const durationMs = endTime - startTime;
+  const durationSec = durationMs / 1e3;
+  const timing = {
+    durationMs,
+    durationSec,
+    startTime,
+    endTime,
+    label
+  };
+  if (log) {
+    const logger = getLogger();
+    const message = `${label} completed in ${durationMs.toFixed(2)}ms`;
+    switch (logLevel) {
+      case "trace":
+        logger.trace({
+          timing
+        }, message);
+        break;
+      case "debug":
+        logger.debug({
+          timing
+        }, message);
+        break;
+      case "info":
+        logger.info({
+          timing
+        }, message);
+        break;
+      case "warn":
+        logger.warn({
+          timing
+        }, message);
+        break;
+      case "error":
+        logger.error({
+          timing
+        }, message);
+        break;
+      default:
+        logger.debug({
+          timing
+        }, message);
+        break;
+    }
+  }
+  return {
+    result,
+    timing
+  };
+}
+__name(timeAsync, "timeAsync");
+function timed(options = {}) {
+  return function(target, propertyKeyOrContext, descriptor) {
+    let propertyKey;
+    let actualDescriptor;
+    if (typeof propertyKeyOrContext === "object" && propertyKeyOrContext !== null && "name" in propertyKeyOrContext) {
+      propertyKey = propertyKeyOrContext.name;
+      actualDescriptor = descriptor ?? Object.getOwnPropertyDescriptor(target, propertyKey);
+    } else {
+      propertyKey = propertyKeyOrContext;
+      actualDescriptor = descriptor ?? Object.getOwnPropertyDescriptor(target, propertyKey);
+    }
+    const originalMethod = actualDescriptor.value;
+    actualDescriptor.value = function(...args) {
+      const methodOptions = {
+        ...options,
+        label: options.label || `${target.constructor.name}.${String(propertyKey)}`
+      };
+      if (originalMethod.constructor.name === "AsyncFunction") {
+        return timeAsync(() => originalMethod.apply(this, args), methodOptions).then(({ result }) => result);
+      } else {
+        return timeSync(() => originalMethod.apply(this, args), methodOptions).result;
+      }
+    };
+    if (descriptor) {
+      descriptor.value = actualDescriptor.value;
+    } else {
+      Object.defineProperty(target, propertyKey, actualDescriptor);
+    }
+  };
+}
+__name(timed, "timed");
+function memoize(fn, options = {}) {
+  const { ttl, maxSize, autoCleanupMs, cacheKey = /* @__PURE__ */ __name((...args) => JSON.stringify(args), "cacheKey") } = options;
+  const cache = new TTLCache({
+    ttlMs: ttl,
+    maxSize,
+    autoCleanupMs
+  });
+  return function(...args) {
+    const key = cacheKey(...args);
+    const cachedValue = cache.get(key);
+    if (cachedValue !== void 0) {
+      return cachedValue;
+    }
+    const value = fn(...args);
+    cache.set(key, value);
+    return value;
+  };
+}
+__name(memoize, "memoize");
+function trackMemoryUsage(fn, options = {}) {
+  const { log = false, label = fn.name || "anonymous function" } = options;
+  if (global.gc) {
+    global.gc();
+  }
+  const beforeMemory = process.memoryUsage();
+  const result = fn();
+  const afterMemory = process.memoryUsage();
+  const diff = {};
+  for (const key in afterMemory) {
+    if (Object.prototype.hasOwnProperty.call(afterMemory, key)) {
+      diff[key] = afterMemory[key] - beforeMemory[key];
+    }
+  }
+  if (log) {
+    getLogger().info({
+      label,
+      memoryBefore: beforeMemory,
+      memoryAfter: afterMemory,
+      memoryDiff: diff
+    }, `Memory usage for ${label}`);
+  }
+  return {
+    result,
+    memoryUsage: {
+      before: beforeMemory,
+      after: afterMemory,
+      diff
+    }
+  };
+}
+__name(trackMemoryUsage, "trackMemoryUsage");
+
+export { memoize, timeAsync, timeSync, timed, trackMemoryUsage };

package/performance/performance.utils.d.ts

@@ -0,0 +1,159 @@
+/*
+ * 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.
+ */
+
+/**
+ * Options for timing function execution.
+ */
+export 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.
+ */
+export 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`);
+ * ```
+ */
+export 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`);
+ * ```
+ */
+export 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
+ *   }
+ * }
+ * ```
+ */
+export 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 }
+ * );
+ * ```
+ */
+export 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
+ */
+export 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>;
+    };
+};