@sohanemon/utils 4.0.32 → 4.1.0

package/dist/functions/index.d.ts

@@ -60,3 +60,97 @@ export declare const copyToClipboard: (value: string, onSuccess?: () => void) =>
  * @returns - Normal Case
  */
 export declare function convertToNormalCase(inputString: string): string;
+/**
+ * Checks if the code is running in a server-side environment.
+ *
+ * @returns - True if the code is executed in SSR (Server-Side Rendering) context, false otherwise
+ */
+export declare const isSSR: boolean;
+/**
+ * Converts an SVG string to a Base64-encoded string.
+ *
+ * @param str - The SVG string to encode
+ * @returns - Base64-encoded string representation of the SVG
+ */
+export declare const svgToBase64: (str: string) => string;
+/**
+ * Pauses execution for the specified time.
+ *
+ * @param time - Time in milliseconds to sleep (default is 1000ms)
+ * @returns - A Promise that resolves after the specified time
+ */
+export declare const sleep: (time?: number) => Promise<unknown>;
+type DebouncedFunction<F extends (...args: any[]) => any> = {
+    (...args: Parameters<F>): ReturnType<F> | undefined;
+    readonly isPending: boolean;
+};
+/**
+ * Creates a debounced function that delays invoking the provided function until
+ * after the specified `wait` time has elapsed since the last invocation.
+ *
+ * If the `immediate` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the wait interval. Subsequent calls during the wait interval
+ * will reset the timer but not invoke the function until the interval elapses again.
+ *
+ * The returned function includes the `isPending` property to check if the debounce
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to debounce.
+ *
+ * @param function_ - The function to debounce.
+ * @param wait - The number of milliseconds to delay (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `immediate` (boolean): If `true`, invokes the function on the leading edge
+ *     of the wait interval instead of the trailing edge.
+ *
+ * @returns A debounced version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
+ *
+ * @example
+ * const log = debounce((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" after 200ms if no other call is made.
+ * console.log(log.isPending); // true if the timer is active.
+ */
+export declare function debounce<F extends (...args: any[]) => any>(function_: F, wait?: number, options?: {
+    immediate: boolean;
+}): DebouncedFunction<F>;
+type ThrottledFunction<F extends (...args: any[]) => any> = {
+    (...args: Parameters<F>): ReturnType<F> | undefined;
+    readonly isPending: boolean;
+};
+/**
+ * Creates a throttled function that invokes the provided function at most once
+ * every `wait` milliseconds.
+ *
+ * If the `leading` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the throttle interval. If the `trailing` option is set to `true`,
+ * the function will also be invoked at the end of the throttle interval if additional
+ * calls were made during the interval.
+ *
+ * The returned function includes the `isPending` property to check if the throttle
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to throttle.
+ *
+ * @param function_ - The function to throttle.
+ * @param wait - The number of milliseconds to wait between invocations (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `leading` (boolean): If `true`, invokes the function on the leading edge of the interval.
+ *   - `trailing` (boolean): If `true`, invokes the function on the trailing edge of the interval.
+ *
+ * @returns A throttled version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
+ *
+ * @example
+ * const log = throttle((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" immediately if leading is true.
+ * console.log(log.isPending); // true if the timer is active.
+ */
+export declare function throttle<F extends (...args: any[]) => any>(function_: F, wait?: number, options?: {
+    leading?: boolean;
+    trailing?: boolean;
+}): ThrottledFunction<F>;

package/dist/functions/index.js

@@ -105,7 +105,176 @@ export const copyToClipboard = (value, onSuccess = () => { }) => {
 export function convertToNormalCase(inputString) {
     const splittedString = inputString.split('.').pop();
     const string = splittedString || inputString;
-    const words = string.replace(/([a-z])([A-Z])/g, '$1 $2').split(/[-_|\s]+/);
+    const words = string.replace(/([a-z])([A-Z])/g, '$1 $2').split(/[-_|​\s]+/);
     const capitalizedWords = words.map((word) => word.charAt(0).toUpperCase() + word.slice(1));
     return capitalizedWords.join(' ');
 }
+/**
+ * Checks if the code is running in a server-side environment.
+ *
+ * @returns - True if the code is executed in SSR (Server-Side Rendering) context, false otherwise
+ */
+export const isSSR = typeof window === 'undefined';
+/**
+ * Converts an SVG string to a Base64-encoded string.
+ *
+ * @param str - The SVG string to encode
+ * @returns - Base64-encoded string representation of the SVG
+ */
+export const svgToBase64 = (str) => isSSR ? Buffer.from(str).toString('base64') : window.btoa(str);
+/**
+ * Pauses execution for the specified time.
+ *
+ * @param time - Time in milliseconds to sleep (default is 1000ms)
+ * @returns - A Promise that resolves after the specified time
+ */
+export const sleep = (time = 1000) => new Promise((resolve) => setTimeout(resolve, time));
+/**
+ * Creates a debounced function that delays invoking the provided function until
+ * after the specified `wait` time has elapsed since the last invocation.
+ *
+ * If the `immediate` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the wait interval. Subsequent calls during the wait interval
+ * will reset the timer but not invoke the function until the interval elapses again.
+ *
+ * The returned function includes the `isPending` property to check if the debounce
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to debounce.
+ *
+ * @param function_ - The function to debounce.
+ * @param wait - The number of milliseconds to delay (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `immediate` (boolean): If `true`, invokes the function on the leading edge
+ *     of the wait interval instead of the trailing edge.
+ *
+ * @returns A debounced version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
+ *
+ * @example
+ * const log = debounce((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" after 200ms if no other call is made.
+ * console.log(log.isPending); // true if the timer is active.
+ */
+export function debounce(function_, wait = 100, options) {
+    if (typeof function_ !== 'function') {
+        throw new TypeError(`Expected the first parameter to be a function, got \`${typeof function_}\`.`);
+    }
+    if (wait < 0) {
+        throw new RangeError('`wait` must not be negative.');
+    }
+    const immediate = options?.immediate ?? false;
+    let timeoutId;
+    let lastArgs;
+    let lastContext;
+    let result;
+    function run() {
+        result = function_.apply(lastContext, lastArgs);
+        lastArgs = undefined;
+        lastContext = undefined;
+        return result;
+    }
+    const debounced = function (...args) {
+        lastArgs = args;
+        lastContext = this;
+        if (timeoutId === undefined && immediate) {
+            result = run.call(this);
+        }
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(run.bind(this), wait);
+        return result;
+    };
+    Object.defineProperty(debounced, 'isPending', {
+        get() {
+            return timeoutId !== undefined;
+        },
+    });
+    return debounced;
+}
+/**
+ * Creates a throttled function that invokes the provided function at most once
+ * every `wait` milliseconds.
+ *
+ * If the `leading` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the throttle interval. If the `trailing` option is set to `true`,
+ * the function will also be invoked at the end of the throttle interval if additional
+ * calls were made during the interval.
+ *
+ * The returned function includes the `isPending` property to check if the throttle
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to throttle.
+ *
+ * @param function_ - The function to throttle.
+ * @param wait - The number of milliseconds to wait between invocations (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `leading` (boolean): If `true`, invokes the function on the leading edge of the interval.
+ *   - `trailing` (boolean): If `true`, invokes the function on the trailing edge of the interval.
+ *
+ * @returns A throttled version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
+ *
+ * @example
+ * const log = throttle((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" immediately if leading is true.
+ * console.log(log.isPending); // true if the timer is active.
+ */
+export function throttle(function_, wait = 100, options) {
+    if (typeof function_ !== 'function') {
+        throw new TypeError(`Expected the first parameter to be a function, got \`${typeof function_}\`.`);
+    }
+    if (wait < 0) {
+        throw new RangeError('`wait` must not be negative.');
+    }
+    const leading = options?.leading ?? true;
+    const trailing = options?.trailing ?? true;
+    let timeoutId;
+    let lastArgs;
+    let lastContext;
+    let lastCallTime;
+    let result;
+    function invoke() {
+        lastCallTime = Date.now();
+        result = function_.apply(lastContext, lastArgs);
+        lastArgs = undefined;
+        lastContext = undefined;
+    }
+    function later() {
+        timeoutId = undefined;
+        if (trailing && lastArgs) {
+            invoke();
+        }
+    }
+    const throttled = function (...args) {
+        const now = Date.now();
+        const timeSinceLastCall = lastCallTime
+            ? now - lastCallTime
+            : Number.POSITIVE_INFINITY;
+        lastArgs = args;
+        lastContext = this;
+        if (timeSinceLastCall >= wait) {
+            if (leading) {
+                invoke();
+            }
+            else {
+                timeoutId = setTimeout(later, wait);
+            }
+        }
+        else if (!timeoutId && trailing) {
+            timeoutId = setTimeout(later, wait - timeSinceLastCall);
+        }
+        return result;
+    };
+    Object.defineProperty(throttled, 'isPending', {
+        get() {
+            return timeoutId !== undefined;
+        },
+    });
+    return throttled;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohanemon/utils",
-  "version": "4.0.32",
+  "version": "4.1.0",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",