@react-hive/honey-utils 1.5.0 → 1.7.0

package/README.md

@@ -37,7 +37,7 @@ pnpm add @react-hive/honey-utils
 
 ### Importing
 
-```typescript
+```ts
 // Import specific utilities
 import { toKebabCase, isString, boolFilter } from '@react-hive/honey-utils';
 
@@ -47,67 +47,185 @@ 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
+/**
+ * Convert string to kebab-case
+ */
 toKebabCase('helloWorld'); // 'hello-world'
 
-// Convert camelCase to dash-case
+/**
+ * Convert camelCase to dash-case
+ */
 camelToDashCase('helloWorld'); // 'hello-world'
 
-// Split string into words
+/**
+ * Split string into words
+ */
 splitStringIntoWords('hello world'); // ['hello', 'world']
 
-// Generate a hash from a string
+/**
+ * Generate a hash from a string
+ */
 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,
+    pipe,
+    compose,
 } 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]
-
-// Remove duplicate values from an array
-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]]
-
-// Find common elements between arrays
-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]
+/**
+ * Filter out falsy values from an array
+ */
+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]
+
+/**
+ * Split an array into chunks of specified size
+ */
+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]
+
+/**
+ * Find elements in one array not in another
+ */
+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
+
+/**
+ * Compose functions from left to right
+ */
+const double = (n: number) => n * 2;
+const increment = (n: number) => n + 1;
+
+pipe(double, increment)(3);
+// ➜ 7  → increment(double(3)) → increment(6)
+
+/**
+ * Compose functions from right to left
+ */
+compose(increment, double)(3);
+// ➜ 7  → increment(double(3)) → increment(6)
 ```
 
 ### Function Utilities
 
-```typescript
+```ts
 import { noop, invokeIfFunction, delay, retry } from '@react-hive/honey-utils';
 
-// No-operation function
-noop(); // does nothing
+/**
+ * No-operation function. Does nothing
+ */
+noop();
 
-// Invoke if function, otherwise return value
+/**
+ * Invoke if function, otherwise return value
+ */
 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
+/**
+ * Waits for 1 second before continuing
+ */
+await delay(1000);
 
-// Retry an async function with configurable options
+/**
+ * Retry an async function with configurable options
+ */
 async function fetchData() {
   const response = await fetch('/api/data');
   
@@ -134,7 +252,7 @@ fetchWithRetry()
 
 ### Type Guards
 
-```typescript
+```ts
 import { 
   isString, 
   isNumber, 
@@ -156,105 +274,157 @@ import {
   isSet
 } from '@react-hive/honey-utils';
 
-// Check if value is a string
+/**
+ * Check if value is a string
+ */
 isString('hello'); // true
 isString(123); // false
 
-// Check if value is a number
+/**
+ * Check if value is a number
+ */
 isNumber(123); // true
 isNumber('123'); // false
 
-// Check if value is a boolean
+/**
+ * Check if value is a boolean
+ */
 isBool(true); // true
 isBool('true'); // false
 
-// Check if value is an object
+/**
+ * Check if value is an object
+ */
 isObject({}); // true
 isObject('object'); // false
 
-// Check if value is a function
+/**
+ * Check if value is a function
+ */
 isFunction(() => {}); // true
 isFunction({}); // false
 
-// Check if value is a Promise
+/**
+ * Check if value is a Promise
+ */
 isPromise(Promise.resolve()); // true
 isPromise({}); // false
 
-// Check if value is null or undefined
+/**
+ * Check if value is null or undefined
+ */
 isNil(null); // true
 isNil(undefined); // true
 isNil(''); // false
 
-// Check if value is null, undefined, or empty string
+/**
+ * Check if value is null, undefined, or empty string
+ */
 isNilOrEmptyString(''); // true
 isNilOrEmptyString(null); // true
 isNilOrEmptyString('hello'); // false
 
-// Check if value is an array
+/**
+ * Check if value is an array
+ */
 isArray([1, 2, 3]); // true
 isArray({}); // false
 
-// Check if value is an empty array
+/**
+ * Check if value is an empty array
+ */
 isEmptyArray([]); // true
 isEmptyArray([1, 2, 3]); // false
 
-// Check if value is an empty object
+/**
+ * Check if value is an empty object
+ */
 isEmptyObject({}); // true
 isEmptyObject({ key: 'value' }); // false
 
-// Check if value is a Date object
+/**
+ * Check if value is a Date object
+ */
 isDate(new Date()); // true
 isDate('2023-01-01'); // false
 
-// Check if value is a valid Date object
+/**
+ * Check if value is a valid Date object
+ */
 isValidDate(new Date()); // true
 isValidDate(new Date('invalid')); // false
 
-// Check if value is a RegExp
+/**
+ * Check if value is a RegExp
+ */
 isRegExp(/test/); // true
 isRegExp('test'); // false
 
-// Check if value is a Map or Set
+/**
+ * Check if value is a Map or Set
+ */
 isMap(new Map()); // true
 isSet(new Set()); // true
 ```
 
 ### Math Utilities
 
-```typescript
+```ts
 import { 
   calculateEuclideanDistance, 
   calculateMovingSpeed, 
   calculatePercentage 
 } from '@react-hive/honey-utils';
 
-// Calculate Euclidean distance between two points
+/**
+ * Calculate Euclidean distance between two points
+ */
 calculateEuclideanDistance(0, 0, 3, 4); // 5
 
-// Calculate moving speed
+/**
+ * Calculate moving speed
+ */
 calculateMovingSpeed(100, 5); // 20
 
-// Calculate percentage of a value
+/**
+ * Calculate percentage of a value
+ */
 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
@@ -268,64 +438,77 @@ function divide(a: number, b: number): number {
 
 ### 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`.
+- `pipe(...fns: Function[]): Function` - Composes unary functions left-to-right. Returns a new function that applies all given functions in a sequence.
+- `compose(...fns: Function[]): Function` - Composes unary functions **right-to-left**. Same as `pipe`, but applies functions in reverse order.
+
+#### Asynchronous Utilities
+
+- `forAsync<Item, Result>(array: Item[], predicate: (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[], predicate: (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[], predicate, 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[], predicate): Promise<Item[]>` - Runs an asynchronous filter operation. Only includes items where `predicate(item)` resolves to `true`.
+- `someAsync<Item>(array: Item[], predicate): Promise<boolean>` - Returns `true` if **any** item in the array passes the async predicate.
+- `everyAsync<Item>(array: Item[], predicate): Promise<boolean>` - Returns `true` if **all** items in the array pass the async predicate.
+- `findAsync<Item>(array: Item[], predicate): 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
-- **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
+- `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`.
+- `isDefined<T>(value: T): value is NonNullable<T>` - Checks if a value is neither `null` nor `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.
+- `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