Function Utilities

Function utility functions provide a variety of methods for managing and enhancing function execution. These utilities help with tasks such as debouncing, throttling, function composition, and managing async behavior, making it easier to handle function flow and optimize performance.

Installation

To install the function utility functions, use one of the following commands, depending on your package manager:

npm install @utilify/function

yarn add @utilify/function

pnpm add @utilify/function

Once installed, you can import the functions into your project, using either ESM or CJS.

Usage

This library supports both the ESM and CJS module systems.

import { debounce } from '@utilify/function'; 

const { debounce } = require('@utilify/function');  

Overview

benchmark

async function benchmark(callback: () => void | Promise<void>, iterations: number = 1): Promise<number>;

Measures the average execution time (in milliseconds) of a given synchronous or asynchronous function over a specified number of iterations.

compose

function compose<T>(...callbacks: ((value: T) => T)[]): (value: T) => T;

A utility to compose functions, applying them from right to left to a value.

debounce

function debounce(callback: (...args: any[]) => void, delay: number = 300): (...args: any[]) => void;

Delays the execution of a function until a period of inactivity has occurred after the last invocation.

defer

function defer(callback: () => void): void;

Queues the execution of a function to run after the current event loop cycle.

fallback

function fallback<T>(callback: () => T, fallback: () => T): T;

Executes the callback function and, in case of an error, executes the fallback function.

guard

function guard<T, U = T>(validator: (value: T) => boolean, callback: (value: T) => U, fallback: (value: T) => U): (value: T) => U;

Executes a callback function if a value passes validation; otherwise, executes a fallback function.

identity

function identity<T>(value: T): T;

Returns the provided value, useful as an identity function.

lock

function lock(callback: (...args: any[]) => Promise<void>): (...args: any[]) => void;

Prevents simultaneous execution of a function, ensuring that one execution completes before allowing another.

memo

function memo(callback: (...args: any[]) => any, cacheTimeout?: number): (...args: any[]) => any;

Caches the results of a function based on its arguments and returns them immediately if the function is called again with the same arguments.

noop

function noop(): void;

A function that does nothing, used as a placeholder.

once

function once<T>(callback: (...args: any[]) => T): (...args: any[]) => T;

Ensures that a function is executed only once, regardless of how many times it is called.

parallel

function parallel(...callbacks: (() => Promise<any>)[]): Promise<any[]>;

Executes multiple asynchronous functions in parallel and waits for all promises to resolve.

partialLeft

function partialLeft<T>(callback: (...args: any[]) => T, ...partial: any[]): (...args: any[]) => T;

Creates a version of the provided function with the initial arguments pre-defined.

partialRight

function partialRight<T>(callback: (...args: any[]) => T, ...partial: any[]): (...args: any[]) => T;

Creates a version of the provided function with the final arguments pre-defined.

pipe

function pipe<T>(...callbacks: ((value: T) => T)[]): (value: T) => T;

A utility to compose functions, applying them from left to right to a value.

rate

function rate(callback: (...args: any[]) => void, limit: number, interval: number): (...args: any[]) => boolean;

Limits the number of times a function can be executed within a time interval.

sleep

function sleep(timeout: number): Promise<void>;

Pauses the execution of a function for a specified time, useful in asynchronous functions.

throttle

function throttle(callback: (...args: any[]) => void, wait: number = 300): (...args: any[]) => void;

Limits the frequency at which a function can be invoked, allowing it to run at most once every wait milliseconds.