@react-hive/honey-utils 1.4.0 → 1.6.0

package/dist/README.md

@@ -3,10 +3,16 @@
 [![npm version](https://img.shields.io/npm/v/@react-hive/honey-utils.svg)](https://www.npmjs.com/package/@react-hive/honey-utils)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<p align="center">
+  <img src="./logo.png" alt="honey-utils logo" width="200" height="200">
+</p>
+
 A lightweight TypeScript utility library providing a collection of helper functions for common programming tasks.
 
 ## Features
 
+---
+
 - 🔍 **Type Guards** - Functions for runtime type checking
 - 🧵 **String Utilities** - String manipulation and transformation
 - 🔢 **Array Utilities** - Array filtering and manipulation
@@ -18,6 +24,8 @@ A lightweight TypeScript utility library providing a collection of helper functi
 
 ## Installation
 
+---
+
 ```bash
 # Using npm
 npm install @react-hive/honey-utils
@@ -31,9 +39,11 @@ pnpm add @react-hive/honey-utils
 
 ## Usage
 
+---
+
 ### Importing
 
-```typescript
+```ts
 // Import specific utilities
 import { toKebabCase, isString, boolFilter } from '@react-hive/honey-utils';
 
@@ -43,7 +53,7 @@ import * as HoneyUtils from '@react-hive/honey-utils';
 
 ### String Utilities
 
-```typescript
+```ts
 import { toKebabCase, camelToDashCase, splitStringIntoWords, hashString } from '@react-hive/honey-utils';
 
 // Convert string to kebab-case
@@ -61,35 +71,103 @@ const hash = hashString('background-color: red;'); // 'e4k1z0x'
 
 ### Array Utilities
 
-```typescript
-import { 
-  boolFilter, 
-  unique, 
-  chunk, 
-  intersection, 
-  difference 
+```ts
+import {
+  boolFilter,
+  unique,
+  chunk,
+  intersection,
+  difference,
+  mapAsync,
+  forAsync,
+  reduceAsync,
+  filterAsync,
+  someAsync,
+  everyAsync,
+  findAsync,
 } from '@react-hive/honey-utils';
 
 // Filter out falsy values from an array
-boolFilter([0, 1, false, 2, '', 3, null, undefined, true]); // [1, 2, 3, true]
+boolFilter([0, 1, false, 2, '', 3, null, undefined, true]); 
+// ➜ [1, 2, 3, true]
 
 // Remove duplicate values from an array
-unique([1, 2, 2, 3, 1, 4]); // [1, 2, 3, 4]
+unique([1, 2, 2, 3, 1, 4]); 
+// ➜ [1, 2, 3, 4]
 
 // Split an array into chunks of specified size
-chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+chunk([1, 2, 3, 4, 5], 2); 
+// ➜ [[1, 2], [3, 4], [5]]
 
 // Find common elements between arrays
-intersection([1, 2, 3], [2, 3, 4]); // [2, 3]
+intersection([1, 2, 3], [2, 3, 4]); 
+// ➜ [2, 3]
 
 // Find elements in one array not in another
-difference([1, 2, 3, 4], [2, 4]); // [1, 3]
+difference([1, 2, 3, 4], [2, 4]); 
+// ➜ [1, 3]
+
+// Run async operations in parallel and collect results
+await mapAsync([1, 2, 3], async (n) => {
+  await delay(100);
+  
+  return n * 2;
+});
+// ➜ [2, 4, 6]
+
+// Run async operations sequentially and collect results
+await forAsync([1, 2, 3], async (n, i) => {
+  await delay(100);
+  
+  return n * i;
+});
+// ➜ [0, 2, 6]
+
+// Reduce array asynchronously
+await reduceAsync([1, 2, 3], async (acc, n) => {
+  await delay(50);
+  
+  return acc + n;
+}, 0);
+// ➜ 6
+
+// Filter array asynchronously
+await filterAsync([1, 2, 3, 4], async (n) => {
+  await delay(30);
+  
+  return n % 2 === 0;
+});
+// ➜ [2, 4]
+
+// Check if some items match condition asynchronously
+await someAsync([1, 3, 5], async (n) => {
+  await delay(10);
+  
+  return n % 2 === 0;
+});
+// ➜ false
+
+// Check if all items match condition asynchronously
+await everyAsync([2, 4, 6], async (n) => {
+  await delay(10);
+  
+  return n % 2 === 0;
+});
+// ➜ true
+
+// Find first matching item asynchronously
+await findAsync([1, 3, 4, 5], async (n) => {
+  await delay(20);
+  
+  return n % 2 === 0;
+});
+// ➜ 4
 ```
 
 ### Function Utilities
 
-```typescript
-import { noop, invokeIfFunction } from '@react-hive/honey-utils';
+```ts
+import { noop, invokeIfFunction, delay, retry } from '@react-hive/honey-utils';
 
 // No-operation function
 noop(); // does nothing
@@ -99,11 +177,38 @@ const fn = (x: number) => x * 2;
 
 invokeIfFunction(fn, 5); // 10
 invokeIfFunction('not a function', 5); // 'not a function'
+
+// Create a promise that resolves after a specified delay
+await delay(1000); // Waits for 1 second before continuing
+
+// Retry an async function with configurable options
+async function fetchData() {
+  const response = await fetch('/api/data');
+  
+  if (!response.ok) {
+    throw new Error('Network error');
+  }
+  
+  return await response.json();
+}
+
+const fetchWithRetry = retry(fetchData, {
+  maxAttempts: 5,
+  delayMs: 500,
+  backoff: true,
+  onRetry: (attempt, error) => {
+    console.warn(`Attempt ${attempt} failed:`, error);
+  }
+});
+
+fetchWithRetry()
+  .then(data => console.log('Success:', data))
+  .catch(error => console.error('Failed after retries:', error));
 ```
 
 ### Type Guards
 
-```typescript
+```ts
 import { 
   isString, 
   isNumber, 
@@ -190,7 +295,7 @@ isSet(new Set()); // true
 
 ### Math Utilities
 
-```typescript
+```ts
 import { 
   calculateEuclideanDistance, 
   calculateMovingSpeed, 
@@ -209,21 +314,37 @@ calculatePercentage(200, 25); // 50
 
 ### DOM Utilities
 
-```typescript
-import { getTransformationValues } from '@react-hive/honey-utils';
+```ts
+import { parse2DMatrix, cloneBlob, convertBlobToFile } from '@react-hive/honey-utils';
 
-// Get transformation values from an HTML element
+// Extract transformation values from an HTML element's 2D matrix
 const element = document.getElementById('my-element');
 if (element) {
-  const { translateX, translateY } = getTransformationValues(element);
+  const { translateX, translateY, scaleX, scaleY, skewX, skewY } = parse2DMatrix(element);
   
   console.log(`Element is translated by ${translateX}px horizontally and ${translateY}px vertically`);
+  console.log(`Element is scaled by ${scaleX} horizontally and ${scaleY} vertically`);
+  console.log(`Element is skewed by ${skewX} horizontally and ${skewY} vertically`);
 }
+
+// Clone a Blob object
+const originalBlob = new Blob(['Hello World'], { type: 'text/plain' });
+const clonedBlob = cloneBlob(originalBlob);
+
+console.log(clonedBlob.type); // 'text/plain'
+
+// Convert a Blob to a File
+const blob = new Blob(['Hello world'], { type: 'text/plain' });
+const file = convertBlobToFile(blob, 'hello.txt');
+
+console.log(file instanceof File); // true
+console.log(file.name); // 'hello.txt'
+console.log(file.type); // 'text/plain'
 ```
 
 ### Assert Function
 
-```typescript
+```ts
 import { assert } from '@react-hive/honey-utils';
 
 // Assert a condition
@@ -235,64 +356,78 @@ function divide(a: number, b: number): number {
 
 ## API Documentation
 
+---
+
 ### String Utilities
 
-- **toKebabCase(input: string): string** - Converts a string to kebab-case
-- **camelToDashCase(input: string): string** - Converts camelCase to dash-case
-- **splitStringIntoWords(input: string): string[]** - Splits a string into an array of words
-- **hashString(input: string): string** - Generates a short hash from a string
+- `toKebabCase(input: string): string` - Converts a string to kebab-case.
+- `camelToDashCase(input: string): string` - Converts camelCase to dash-case.
+- `splitStringIntoWords(input: string): string[]` - Splits a string into an array of words.
+- `hashString(input: string): string` - Generates a short hash from a string.
 
 ### Array Utilities
 
-- **boolFilter<T>(array: (T | false | null | undefined)[]): T[]** - Filters out falsy values from an array
-- **unique<T>(array: T[]): T[]** - Returns a new array with duplicate values removed
-- **chunk<T>(array: T[], size: number): T[][]** - Splits an array into chunks of the specified size
-- **intersection<T>(...arrays: T[][]): T[]** - Returns an array containing elements that exist in all provided arrays
-- **difference<T>(array: T[], exclude: T[]): T[]** - Returns elements from the first array that don't exist in the second array
+#### Synchronous Utilities
+
+- `boolFilter<T>(array: (T | false | null | undefined)[]): T[]` - Filters out falsy values (`false`, `null`, `undefined`) from an array while keeping valid items.
+- `unique<T>(array: T[]): T[]` - Returns a new array with all duplicate elements removed. Keeps only the first occurrence of each value.
+- `chunk<T>(array: T[], size: number): T[][]` - Splits an array into smaller arrays ("chunks") of the specified size.
+- `intersection<T>(...arrays: T[][]): T[]` - Returns an array of elements that exist in all provided arrays.
+- `difference<T>(array: T[], exclude: T[]): T[]` - Returns a new array that contains items from `array` that are not present in `exclude`.
+
+#### Asynchronous Utilities
+
+- `forAsync<Item, Result>(array: Item[], callbackFn: (item, index, array) => Promise<Result>): Promise<Result[]>` - Runs asynchronous operations on each array item *sequentially* and returns the results in the original order.
+- `mapAsync<Item, Return>(array: Item[], callbackFn: (item, index, array) => Promise<Return>): Promise<Return[]>` - Executes an asynchronous function for each array item *in parallel* and returns a promise of all results.
+- `reduceAsync<Item, Accumulator>(array: Item[], callbackFn, initialValue): Promise<Accumulator>` - Asynchronously reduces an array to a single accumulated value. Each step waits for the previous promise to resolve.
+- `filterAsync<Item>(array: Item[], callbackFn): Promise<Item[]>` - Runs an asynchronous filter operation. Only includes items where `callbackFn(item)` resolves to `true`.
+- `someAsync<Item>(array: Item[], callbackFn): Promise<boolean>` - Returns `true` if **any** item in the array passes the async predicate.
+- `everyAsync<Item>(array: Item[], callbackFn): Promise<boolean>` - Returns `true` if **all** items in the array pass the async predicate.
+- `findAsync<Item>(array: Item[], callbackFn): Promise<Item | null>` - Returns the first array item that passes the async predicate, or `null` if no match is found.
 
 ### Function Utilities
 
-- **noop(): void** - A no-operation function
-- **invokeIfFunction<Args extends any[], Result>(input: ((...args: Args) => Result) | Result, ...args: Args): Result** - Invokes the input if it's a function, otherwise returns it as-is
+- `noop(): void` - A no-operation function.
+- `invokeIfFunction<Args extends any[], Result>(input: ((...args: Args) => Result) | Result, ...args: Args): Result` - Invokes the input if it's a function, otherwise returns it as-is.
+- `delay(delayMs: number): Promise<void>` - Creates a promise that resolves after the specified delay in milliseconds.
+- `retry<Task, TaskResult>(task: Task, options?: RetryOptions): Function` - Wraps an asynchronous function with retry logic, with configurable max attempts, delay between retries, exponential backoff, and retry callbacks.
 
 ### Type Guards
 
-- **isString(value: unknown): value is string** - Checks if a value is a string
-- **isNumber(value: unknown): value is number** - Checks if a value is a number
-- **isBool(value: unknown): value is boolean** - Checks if a value is a boolean
-- **isObject(value: unknown): value is object** - Checks if a value is an object
-- **isFunction(value: unknown): value is Function** - Checks if a value is a function
-- **isPromise<T = unknown>(value: unknown): value is Promise<T>** - Checks if a value is a Promise
-- **isNil(value: unknown): value is null | undefined** - Checks if a value is null or undefined
-- **isNilOrEmptyString(value: unknown): value is null | undefined** - Checks if a value is null, undefined, or an empty string
-- **isArray(value: unknown): value is unknown[]** - Checks if a value is an array
-- **isEmptyArray(value: unknown): value is []** - Checks if a value is an empty array
-- **isEmptyObject(value: unknown): value is Record<string, never>** - Checks if a value is an empty object
-- **isNull(value: unknown): value is null** - Checks if a value is null
-- **isUndefined(value: unknown): value is undefined** - Checks if a value is undefined
-- **isFiniteNumber(value: unknown): value is number** - Checks if a value is a finite number
-- **isInteger(value: unknown): value is number** - Checks if a value is an integer
-- **isNaN(value: unknown): boolean** - Checks if a value is NaN
-- **isDate(value: unknown): value is Date** - Checks if a value is a Date object
-- **isValidDate(value: unknown): value is Date** - Checks if a value is a valid Date object (not Invalid Date)
-- **isRegExp(value: unknown): value is RegExp** - Checks if a value is a RegExp object
-- **isMap(value: unknown): value is Map<unknown, unknown>** - Checks if a value is a Map
-- **isSet(value: unknown): value is Set<unknown>** - Checks if a value is a Set
-- **isSymbol(value: unknown): value is symbol** - Checks if a value is a Symbol
+- `assert(condition: any, message: string): asserts condition` - Asserts that a condition is truthy, throwing an error with the provided message if it's not.
+- `isString(value: unknown): value is string` - Checks if a value is a string.
+- `isNumber(value: unknown): value is number` - Checks if a value is a number.
+- `isBool(value: unknown): value is boolean` - Checks if a value is a boolean.
+- `isObject(value: unknown): value is object` - Checks if a value is an object.
+- `isFunction(value: unknown): value is Function` - Checks if a value is a function.
+- `isPromise<T = unknown>(value: unknown): value is Promise<T>` - Checks if a value is a Promise.
+- `isNil(value: unknown): value is null | undefined` - Checks if a value is null or undefined.
+- `isNilOrEmptyString(value: unknown): value is null | undefined` - Checks if a value is null, undefined, or an empty string.
+- `isArray(value: unknown): value is unknown[]` - Checks if a value is an array.
+- `isEmptyArray(value: unknown): value is []` - Checks if a value is an empty array.
+- `isEmptyObject(value: unknown): value is Record<string, never>` - Checks if a value is an empty object.
+- `isNull(value: unknown): value is null` - Checks if a value is null.
+- `isUndefined(value: unknown): value is undefined` - Checks if a value is undefined.
+- `isFiniteNumber(value: unknown): value is number` - Checks if a value is a finite number.
+- `isInteger(value: unknown): value is number` - Checks if a value is an integer.
+- `isDate(value: unknown): value is Date` - Checks if a value is a Date object.
+- `isValidDate(value: unknown): value is Date` - Checks if a value is a valid Date object (not Invalid Date).
+- `isRegExp(value: unknown): value is RegExp` - Checks if a value is a RegExp object.
+- `isMap(value: unknown): value is Map<unknown, unknown>` - Checks if a value is a Map.
+- `isSet(value: unknown): value is Set<unknown>` - Checks if a value is a Set.
+- `isSymbol(value: unknown): value is symbol` - Checks if a value is a Symbol.
 
 ### Math Utilities
 
-- **calculateEuclideanDistance(startX: number, startY: number, endX: number, endY: number): number** - Calculates the Euclidean distance between two points
-- **calculateMovingSpeed(delta: number, elapsedTime: number): number** - Calculates moving speed
-- **calculatePercentage(value: number, percentage: number): number** - Calculates the specified percentage of a value
+- `calculateEuclideanDistance(startX: number, startY: number, endX: number, endY: number): number` - Calculates the Euclidean distance between two points.
+- `calculateMovingSpeed(delta: number, elapsedTime: number): number` - Calculates moving speed.
+- `calculatePercentage(value: number, percentage: number): number` - Calculates the specified percentage of a value.
 
 ### DOM Utilities
 
-- **getTransformationValues(element: HTMLElement): { translateX: number, translateY: number }** - Gets transformation values from an HTML element
-
-### Other Utilities
-
-- **assert(condition: any, message: string): asserts condition** - Asserts that a condition is truthy, throwing an error with the provided message if it's not
+- `parse2DMatrix(element: HTMLElement): { translateX: number, translateY: number, scaleX: number, scaleY: number, skewX: number, skewY: number }` - Extracts transformation values (translate, scale, skew) from the 2D transformation matrix of a given HTML element.
+- `cloneBlob(blob: Blob): Blob` - Creates a clone of a Blob object with the same content and type as the original.
+- `convertBlobToFile(blob: Blob, fileName: string): File` - Converts a Blob object into a File object with the specified name.
 
 ## Contributing
 

package/dist/array.d.ts

@@ -82,3 +82,89 @@ export declare const intersection: <T>(...arrays: T[][]) => T[];
  * ```
  */
 export declare const difference: <T>(array: T[], exclude: T[]) => T[];
+/**
+ * Asynchronously iterates over an array and executes an async function on each item sequentially,
+ * collecting the results.
+ *
+ * Unlike `Promise.all`, this runs each promise one after another (not in parallel).
+ * Useful when order or timing matters (e.g., rate limits, UI updates, animations).
+ *
+ * @param array - The array of items to iterate over.
+ * @param callbackFn - An async function to execute for each item. Must return a value.
+ *
+ * @returns A promise that resolves with an array of results from each callback call.
+ *
+ * @example
+ * ```ts
+ * const results = await forAsync([1, 2, 3], async (item) => {
+ *   await delay(100);
+ *
+ *   return item * 2;
+ * });
+ *
+ * console.log(results); // [2, 4, 6]
+ * ```
+ */
+export declare const forAsync: <Item, Result>(array: Item[], callbackFn: (item: Item, index: number, array: Item[]) => Promise<Result>) => Promise<Result[]>;
+/**
+ * Executes an asynchronous operation on each element of an array and waits for all promises to resolve.
+ *
+ * @param array - The array of items to operate on.
+ * @param callbackFn - The asynchronous operation to perform on each item.
+ *
+ * @returns A promise that resolves with an array of results after all operations are completed.
+ */
+export declare const mapAsync: <Item, Return>(array: Item[], callbackFn: (item: Item, index: number, array: Item[]) => Promise<Return>) => Promise<Return[]>;
+/**
+ * A generic function that processes an array asynchronously and filters the results
+ * based on the provided async condition.
+ *
+ * @template Item - The type of the items in the array.
+ * @template Return - The type of the items returned by the condition.
+ *
+ * @param array - An array of items to be processed.
+ * @param callbackFn - An async function that returns a condition for each item.
+ *
+ * @returns A Promise that resolves to an array of items that match the condition.
+ */
+export declare const filterAsync: <Item>(array: Item[], callbackFn: (item: Item, index: number, array: Item[]) => Promise<boolean>) => Promise<Item[]>;
+/**
+ * Asynchronously checks if at least one element in the array satisfies the async condition.
+ *
+ * @param array - The array of items to check.
+ * @param callbackFn - An async function that returns a boolean.
+ *
+ * @returns A promise that resolves to true if any item passes the condition.
+ */
+export declare const someAsync: <Item>(array: Item[], callbackFn: (item: Item, index: number, array: Item[]) => Promise<boolean>) => Promise<boolean>;
+/**
+ * Asynchronously checks if all elements in the array satisfy the async condition.
+ *
+ * @param array - The array of items to check.
+ * @param callbackFn - An async function that returns a boolean.
+ *
+ * @returns A promise that resolves to true if all items pass the condition.
+ */
+export declare const everyAsync: <Item>(array: Item[], callbackFn: (item: Item, index: number, array: Item[]) => Promise<boolean>) => Promise<boolean>;
+/**
+ * Asynchronously reduces an array to a single accumulated value.
+ *
+ * @template Item - The type of items in the array.
+ * @template Accumulator - The type of the accumulated result.
+ *
+ * @param array - The array to reduce.
+ * @param callbackFn - The async reducer function that processes each item and returns the updated accumulator.
+ * @param initialValue - The initial accumulator value.
+ *
+ * @returns A promise that resolves to the final accumulated result.
+ */
+export declare const reduceAsync: <Item, Accumulator>(array: Item[], callbackFn: (accumulator: Accumulator, item: Item, index: number, array: Item[]) => Promise<Accumulator>, initialValue: Accumulator) => Promise<Accumulator>;
+/**
+ * Asynchronously finds the first element that satisfies the async condition.
+ *
+ * @param array - The array of items to search.
+ * @param callbackFn - An async function that returns a boolean.
+ *
+ * @returns A promise that resolves to the found item or null if none match.
+ */
+export declare const findAsync: <Item>(array: Item[], callbackFn: (item: Item, index: number, array: Item[]) => Promise<boolean>) => Promise<Item | null>;

package/dist/dom.d.ts

@@ -1,13 +1,53 @@
 interface HTMLElementTransformationValues {
     translateX: number;
     translateY: number;
+    scaleX: number;
+    scaleY: number;
+    skewX: number;
+    skewY: number;
 }
 /**
- * Get various transformation values from the transformation matrix of an element.
+ * Extracts transformation values (translate, scale, skew) from the 2D transformation matrix of a given HTML element.
  *
- * @param element - The element with a transformation applied.
+ * Only works with 2D transforms (i.e., `matrix(a, b, c, d, e, f)`).
  *
- * @returns An object containing transformation values.
+ * @param element - The element with a CSS transform applied.
+ * @returns An object with parsed transformation values.
+ *
+ * @example
+ * ```ts
+ * const values = parse2DMatrix(myElement);
+ * console.log(values.translateX);
+ * console.log(values.scaleX);
+ * ```
+ */
+export declare const parse2DMatrix: (element: HTMLElement) => HTMLElementTransformationValues;
+/**
+ * Creates a clone of a Blob object.
+ *
+ * @param blob - The Blob object to clone.
+ *
+ * @returns A new Blob with the same content and type as the original.
+ */
+export declare const cloneBlob: (blob: Blob) => Blob;
+/**
+ * Converts a `Blob` object into a `File` object with the specified name.
+ *
+ * This is useful when you receive a `Blob` (e.g., from canvas, fetch, or file manipulation)
+ * and need to convert it into a `File` to upload via `FormData` or file inputs.
+ *
+ * @param blob - The `Blob` to convert.
+ * @param fileName - The desired name for the resulting file (including extension).
+ *
+ * @returns A `File` instance with the same content and MIME type as the input `Blob`.
+ *
+ * @example
+ * ```ts
+ * const blob = new Blob(['Hello world'], { type: 'text/plain' });
+ * const file = convertBlobToFile(blob, 'hello.txt');
+ *
+ * console.log(file instanceof File); // true
+ * ```
  */
-export declare const getTransformationValues: (element: HTMLElement) => HTMLElementTransformationValues;
+export declare const convertBlobToFile: (blob: Blob, fileName: string) => File;
 export {};

package/dist/function.d.ts

@@ -11,4 +11,102 @@ export declare const noop: () => void;
  *
  * @returns The result of invoking the function, or the original value if it's not a function.
  */
-export declare const invokeIfFunction: <Args extends any[], Result>(input: ((...args: Args) => Result) | Result, ...args: Args) => Result;
+export declare const invokeIfFunction: <Args extends unknown[], Result>(input: ((...args: Args) => Result) | Result, ...args: Args) => Result;
+/**
+ * Creates a promise that resolves after the specified delay.
+ *
+ * Useful for creating artificial delays, implementing timeouts, or spacing operations.
+ *
+ * @param delayMs - The delay in milliseconds.
+ *
+ * @returns A promise that resolves after the specified delay.
+ *
+ * @example
+ * ```ts
+ * // Wait for 1 second
+ * await delay(1000);
+ * console.log('This logs after 1 second');
+ *
+ * // Use with other async operations
+ * async function fetchWithTimeout() {
+ *   const timeoutPromise = delay(5000).then(() => {
+ *     throw new Error('Request timed out');
+ *   });
+ *
+ *   return Promise.race([fetchData(), timeoutPromise]);
+ * }
+ * ```
+ */
+export declare const delay: (delayMs: number) => Promise<void>;
+interface RetryOptions {
+    /**
+     * Maximum number of retry attempts before failing.
+     *
+     * @default 3
+     */
+    maxAttempts?: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     * If `backoff` is true, this is the base delay for exponential backoff.
+     *
+     * @default 300
+     */
+    delayMs?: number;
+    /**
+     * Whether to use exponential backoff for delays between attempts.
+     * When enabled, the delay is multiplied by 2 ^ (`attempt` - 1).
+     *
+     * @default true
+     */
+    backoff?: boolean;
+    /**
+     * Optional callback triggered before each retry attempt.
+     *
+     * @param attempt - The current attempt number (starting from 1).
+     * @param error - The error that caused the retry.
+     */
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/**
+ * Wraps an asynchronous function with retry logic.
+ *
+ * The returned function will attempt to call the original function up to `maxAttempts` times,
+ * with a delay between retries. If all attempts fail, the last encountered error is thrown.
+ *
+ * Useful for operations that may fail intermittently, such as network requests.
+ *
+ * @template Task - The type of the async function to wrap.
+ * @template TaskResult - The result type of the async function.
+ *
+ * @param task - The async function to wrap with retry logic.
+ * @param options - Configuration options for retry behavior.
+ *
+ * @returns A function that wraps the original function with retry support.
+ *
+ * @example
+ * ```ts
+ * async function fetchData() {
+ *   const response = await fetch('/api/data');
+ *
+ *   if (!response.ok) {
+ *    throw new Error('Network error');
+ *   }
+ *
+ *   return await response.json();
+ * }
+ *
+ * const fetchWithRetry = retry(fetchData, {
+ *   maxAttempts: 5,
+ *   delayMs: 500,
+ *   onRetry: (attempt, error) => {
+ *     console.warn(`Attempt ${attempt} failed:`, error);
+ *   }
+ * });
+ *
+ * fetchWithRetry()
+ *   .then(data => console.log('Success:', data))
+ *   .catch(error => console.error('Failed after retries:', error));
+ * ```
+ */
+export declare const retry: <Task extends (...args: unknown[]) => Promise<TaskResult>, TaskResult>(task: Task, { maxAttempts, delayMs, backoff, onRetry }?: RetryOptions) => ((...args: Parameters<Task>) => Promise<TaskResult>);
+export {};

package/dist/index.cjs

@@ -1,2 +1,2 @@
-(()=>{"use strict";var e={d:(t,r)=>{for(var n in r)e.o(r,n)&&!e.o(t,n)&&Object.defineProperty(t,n,{enumerable:!0,get:r[n]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},t={};e.r(t),e.d(t,{assert:()=>a,boolFilter:()=>E,calculateEuclideanDistance:()=>I,calculateMovingSpeed:()=>$,calculatePercentage:()=>B,camelToDashCase:()=>n,chunk:()=>P,difference:()=>T,getTransformationValues:()=>L,hashString:()=>o,intersection:()=>D,invokeIfFunction:()=>x,isArray:()=>g,isBool:()=>u,isDate:()=>S,isEmptyArray:()=>y,isEmptyObject:()=>p,isFiniteNumber:()=>M,isFunction:()=>b,isInteger:()=>N,isMap:()=>O,isNil:()=>d,isNilOrEmptyString:()=>h,isNull:()=>s,isNumber:()=>c,isObject:()=>f,isPromise:()=>m,isRegExp:()=>A,isSet:()=>j,isString:()=>l,isSymbol:()=>v,isUndefined:()=>C,isValidDate:()=>w,noop:()=>k,splitStringIntoWords:()=>i,toKebabCase:()=>r,unique:()=>F});const r=e=>e.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase(),n=e=>{const t=e.charAt(0),r=e.slice(1);return t.toLowerCase()+r.replace(/[A-Z]/g,e=>`-${e.toLowerCase()}`)},i=e=>e.split(" ").filter(Boolean),o=e=>{let t=5381;for(let r=0;r<e.length;r++)t=33*t^e.charCodeAt(r);return(t>>>0).toString(36)};function a(e,t){if(!e)throw new Error(t)}const s=e=>null===e,l=e=>"string"==typeof e,c=e=>"number"==typeof e,u=e=>"boolean"==typeof e,f=e=>"object"==typeof e,p=e=>f(e)&&!s(e)&&0===Object.keys(e).length,g=e=>Array.isArray(e),y=e=>g(e)&&0===e.length,b=e=>"function"==typeof e,m=e=>b(e?.then),d=e=>null==e,h=e=>""===e||d(e),S=e=>e instanceof Date,w=e=>S(e)&&!isNaN(e.getTime()),A=e=>e instanceof RegExp,O=e=>e instanceof Map,j=e=>e instanceof Set,v=e=>"symbol"==typeof e,C=e=>void 0===e,M=e=>c(e)&&isFinite(e),N=e=>c(e)&&Number.isInteger(e),E=e=>e.filter(Boolean),F=e=>[...new Set(e)],P=(e,t)=>(a(t>0,"Chunk size must be greater than 0"),Array.from({length:Math.ceil(e.length/t)},(r,n)=>e.slice(n*t,(n+1)*t))),D=(...e)=>{if(0===e.length)return[];if(1===e.length)return[...e[0]];const[t,...r]=e;return F(t).filter(e=>r.every(t=>t.includes(e)))},T=(e,t)=>e.filter(e=>!t.includes(e)),k=()=>{},x=(e,...t)=>"function"==typeof e?e(...t):e,I=(e,t,r,n)=>{const i=r-e,o=n-t;return Math.sqrt(i**2+o**2)},$=(e,t)=>Math.abs(e/t),B=(e,t)=>e*t/100,L=e=>{const t=window.getComputedStyle(e).getPropertyValue("transform").match(/^matrix\((.+)\)$/);if(!t)return{translateX:0,translateY:0};const r=t[1].split(", ");return{translateX:parseFloat(r[4]),translateY:parseFloat(r[5])}};module.exports=t})();
+(()=>{"use strict";var e={d:(t,r)=>{for(var n in r)e.o(r,n)&&!e.o(t,n)&&Object.defineProperty(t,n,{enumerable:!0,get:r[n]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},t={};e.r(t),e.d(t,{assert:()=>i,boolFilter:()=>C,calculateEuclideanDistance:()=>V,calculateMovingSpeed:()=>Z,calculatePercentage:()=>_,camelToDashCase:()=>n,chunk:()=>N,cloneBlob:()=>U,convertBlobToFile:()=>W,delay:()=>q,difference:()=>x,everyAsync:()=>Y,filterAsync:()=>T,findAsync:()=>$,forAsync:()=>B,hashString:()=>s,intersection:()=>E,invokeIfFunction:()=>R,isArray:()=>p,isBool:()=>y,isDate:()=>w,isEmptyArray:()=>g,isEmptyObject:()=>f,isFiniteNumber:()=>P,isFunction:()=>m,isInteger:()=>j,isMap:()=>v,isNil:()=>b,isNilOrEmptyString:()=>d,isNull:()=>o,isNumber:()=>c,isObject:()=>u,isPromise:()=>h,isRegExp:()=>S,isSet:()=>M,isString:()=>l,isSymbol:()=>k,isUndefined:()=>O,isValidDate:()=>A,mapAsync:()=>D,noop:()=>L,parse2DMatrix:()=>K,reduceAsync:()=>I,retry:()=>z,someAsync:()=>X,splitStringIntoWords:()=>a,toKebabCase:()=>r,unique:()=>F});const r=e=>e.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase(),n=e=>{const t=e.charAt(0),r=e.slice(1);return t.toLowerCase()+r.replace(/[A-Z]/g,e=>`-${e.toLowerCase()}`)},a=e=>e.split(" ").filter(Boolean),s=e=>{let t=5381;for(let r=0;r<e.length;r++)t=33*t^e.charCodeAt(r);return(t>>>0).toString(36)};function i(e,t){if(!e)throw new Error(t)}const o=e=>null===e,l=e=>"string"==typeof e,c=e=>"number"==typeof e,y=e=>"boolean"==typeof e,u=e=>"object"==typeof e,f=e=>u(e)&&!o(e)&&0===Object.keys(e).length,p=e=>Array.isArray(e),g=e=>p(e)&&0===e.length,m=e=>"function"==typeof e,h=e=>m(e?.then),b=e=>null==e,d=e=>""===e||b(e),w=e=>e instanceof Date,A=e=>w(e)&&!isNaN(e.getTime()),S=e=>e instanceof RegExp,v=e=>e instanceof Map,M=e=>e instanceof Set,k=e=>"symbol"==typeof e,O=e=>void 0===e,P=e=>c(e)&&isFinite(e),j=e=>c(e)&&Number.isInteger(e),C=e=>e.filter(Boolean),F=e=>[...new Set(e)],N=(e,t)=>(i(t>0,"Chunk size must be greater than 0"),Array.from({length:Math.ceil(e.length/t)},(r,n)=>e.slice(n*t,(n+1)*t))),E=(...e)=>{if(0===e.length)return[];if(1===e.length)return[...e[0]];const[t,...r]=e;return F(t).filter(e=>r.every(t=>t.includes(e)))},x=(e,t)=>e.filter(e=>!t.includes(e)),B=async(e,t)=>{const r=[];for(let n=0;n<e.length;n++)r.push(await t(e[n],n,e));return r},D=async(e,t)=>Promise.all(e.map(t)),T=async(e,t)=>{const r=await D(e,async(e,r,n)=>!!await t(e,r,n)&&e);return C(r)},X=async(e,t)=>{for(let r=0;r<e.length;r++)if(await t(e[r],r,e))return!0;return!1},Y=async(e,t)=>{for(let r=0;r<e.length;r++)if(!await t(e[r],r,e))return!1;return!0},I=async(e,t,r)=>{let n=r;for(let r=0;r<e.length;r++)n=await t(n,e[r],r,e);return n},$=async(e,t)=>{for(let r=0;r<e.length;r++)if(await t(e[r],r,e))return e[r];return null},L=()=>{},R=(e,...t)=>"function"==typeof e?e(...t):e,q=e=>new Promise(t=>setTimeout(t,e)),z=(e,{maxAttempts:t=3,delayMs:r=300,backoff:n=!0,onRetry:a}={})=>async(...s)=>{let i;for(let o=1;o<=t;o++)try{return await e(...s)}catch(e){if(i=e,o<t){a?.(o,e);const t=n?r*2**(o-1):r;await q(t)}}throw i},V=(e,t,r,n)=>{const a=r-e,s=n-t;return Math.sqrt(a**2+s**2)},Z=(e,t)=>Math.abs(e/t),_=(e,t)=>e*t/100,K=e=>{const t=window.getComputedStyle(e).getPropertyValue("transform").match(/^matrix\((.+)\)$/);if(!t)return{translateX:0,translateY:0,scaleX:1,scaleY:1,skewX:0,skewY:0};const[r,n,a,s,i,o]=t[1].split(", ").map(parseFloat);return{translateX:i,translateY:o,scaleX:r,scaleY:s,skewX:a,skewY:n}},U=e=>new Blob([e],{type:e.type}),W=(e,t)=>new File([e],t,{type:e.type});module.exports=t})();
 //# sourceMappingURL=index.cjs.map