cmpstr/dist/types/utils/Profiler.d.ts

CmpStr is a lightweight, fast and well performing package for calculating string similarity

/**
 * Profiler Utility
 * src/utils/Profiler.ts
 *
 * @see https://en.wikipedia.org/wiki/Profiling_(computer_programming)
 *
 * This class provides methods to run synchronous and asynchronous functions, capturing
 * their execution time and memory usage, and storing the results in a set of profiler
 * entries. It supports both Node.js and browser environments, detecting the environment
 * automatically.
 *
 * The class is optimized for minimal overhead and can be used for fine-grained
 * performance profiling.
 *
 * @module Utils
 * @name Profiler
 * @author Paul Köhler (komed3)
 * @license MIT
 */
import type { ProfilerEntry, ProfilerService } from './Types';
/**
 * Profiler class for measuring execution time and memory usage of functions.
 */
export declare class Profiler {
    private active;
    /** Environment detection */
    private static ENV;
    /** Singleton instance */
    private static instance;
    /** Pre-computed functions for time and memory retrieval */
    private nowFn;
    private memFn;
    /** Store for profiler entries */
    private store;
    /** Total time and memory consumption */
    private totalTime;
    private totalMem;
    /**
     * Sets the environment based on the available global objects.
     * Detects if running in Node.js or browser and sets the ENV property accordingly.
     */
    protected static detectEnv(): void;
    /**
     * Returns the singleton instance of the Profiler class.
     * If the instance does not exist, it creates a new one.
     *
     * @param {boolean} [enable=false] - Optional parameter to enable the profiler upon instantiation
     * @returns {Profiler} - Singleton Profiler instance
     */
    static getInstance(enable?: boolean): Profiler;
    /**
     * Private constructor to enforce singleton pattern.
     * Initializes the store for profiler entries.
     *
     * @param {boolean} [active=false] - Optional parameter to enable the profiler
     */
    private constructor();
    /**
     * Gets the current time based on the environment.
     *
     * Uses process.hrtime.bigint() for Node.js, performance.now() for browsers,
     * and Date.now() as a fallback.
     *
     * @returns {number} - Current time in milliseconds
     */
    private now;
    /**
     * Gets the current memory usage based on the environment.
     *
     * Uses process.memoryUsage().heapUsed for Node.js, performance.memory.usedJSHeapSize
     * for browsers, and returns 0 as a fallback.
     *
     * @returns {number} - Current memory usage in bytes
     */
    private mem;
    /**
     * Profiles a synchronous function by measuring its execution time and memory usage.
     *
     * @param {() => T} fn - Function to be executed and profiled
     * @param {Record< string, any >} meta - Metadata to be associated with the profiling entry
     * @returns {T} - The result of the executed function
     */
    private profile;
    /**
     * Enables the profiler.
     * Sets the active state to true, allowing profiling to occur.
     */
    enable: () => void;
    /**
     * Disables the profiler.
     * Sets the active state to false, preventing further profiling.
     */
    disable: () => void;
    /**
     * Resets the profiler by clearing the store, total time and memory consumption.
     * This method is useful for starting a new profiling session.
     */
    clear(): void;
    /**
     * Runs a synchronous function and profiles its execution time and memory usage.
     * If the profiler is not active, it simply executes the function without profiling.
     *
     * @param {() => T} fn - Function to be executed and profiled
     * @param {Record< string, any >} meta - Metadata to be associated with the profiling entry
     * @returns {T} - The result of the executed function
     */
    run<T>(fn: () => T, meta?: Record<string, any>): T;
    /**
     * Runs an asynchronous function and profiles its execution time and memory usage.
     * If the profiler is not active, it simply executes the function without profiling.
     *
     * @param {() => Promise< T >} fn - Asynchronous function to be executed and profiled
     * @param {Record< string, any >} meta - Metadata to be associated with the profiling entry
     * @returns {Promise< T >} - A promise that resolves to the result of the executed function
     */
    runAsync<T>(fn: () => Promise<T>, meta?: Record<string, any>): Promise<T>;
    /**
     * Retrieves all profiler entries stored in the profiler.
     *
     * @returns {ProfilerEntry< any >[]} - An array of profiler entries
     */
    getAll: () => ProfilerEntry<any>[];
    /**
     * Retrieves the last profiler entry stored in the profiler.
     *
     * @returns {ProfilerEntry< any > | undefined} - The last profiler entry or undefined if no entries exist
     */
    getLast: () => ProfilerEntry<any> | undefined;
    /**
     * Retrieves the total time and memory consumption recorded by the profiler.
     *
     * @returns {{ time: number, mem: number }} - An object containing total time and memory usage
     */
    getTotal: () => {
        time: number;
        mem: number;
    };
    /**
     * Returns the services provided by the Profiler class.
     * This allows for easy access to the profiler's methods.
     *
     * @returns {ProfilerService< any >} - An object containing methods to control the profiler
     */
    services: ProfilerService<any>;
}