@react-hive/honey-utils 2.4.0 → 3.1.0

package/dist/README.md

@@ -48,33 +48,64 @@ import * as HoneyUtils from '@react-hive/honey-utils';
 ### String Utilities
 
 ```ts
-import { toKebabCase, camelToDashCase, splitStringIntoWords, hashString } from '@react-hive/honey-utils';
+import {
+    isString,
+    isNilOrEmptyString,
+    toKebabCase,
+    camelToDashCase,
+    splitStringIntoWords,
+    hashString
+} from '@react-hive/honey-utils';
+
+/**
+ * Check if value is a string
+ */
+isString('hello');
+// ➜ true
+isString(123);
+// ➜ false
+
+/**
+ * Check if value is null, undefined, or empty string
+ */
+isNilOrEmptyString('');
+// ➜ true
+isNilOrEmptyString(null);
+// ➜ true
+isNilOrEmptyString('hello');
+// ➜ false
 
 /**
  * Convert string to kebab-case
  */
-toKebabCase('helloWorld'); // 'hello-world'
+toKebabCase('helloWorld');
+// ➜ 'hello-world'
 
 /**
  * Convert camelCase to dash-case
  */
-camelToDashCase('helloWorld'); // 'hello-world'
+camelToDashCase('helloWorld');
+// ➜ 'hello-world'
 
 /**
  * Split string into words
  */
-splitStringIntoWords('hello world'); // ['hello', 'world']
+splitStringIntoWords('hello world');
+// ➜ ['hello', 'world']
 
 /**
  * Generate a hash from a string
  */
-const hash = hashString('background-color: red;'); // 'e4k1z0x'
+const hash = hashString('background-color: red;');
+// ➜ 'e4k1z0x'
 ```
 
 ### Array Utilities
 
 ```ts
 import {
+    isArray,
+    isEmptyArray,
     compact,
     unique,
     chunk,
@@ -84,6 +115,22 @@ import {
     compose,
 } from '@react-hive/honey-utils';
 
+/**
+ * Check if value is an array
+ */
+isArray([1, 2, 3]);
+// ➜ true
+isArray({});
+// ➜ false
+
+/**
+ * Check if value is an empty array
+ */
+isEmptyArray([]);
+// ➜ true
+isEmptyArray([1, 2, 3]);
+// ➜ false
+
 /**
  * Filter out falsy values from an array
  */
@@ -134,6 +181,7 @@ compose(increment, double)(3);
 
 ```ts
 import {
+    isPromise,
     runParallel,
     runSequential,
     reduceAsync,
@@ -143,6 +191,14 @@ import {
     findAsync,
 } from '@react-hive/honey-utils';
 
+/**
+ * Check if value is a Promise
+ */
+isPromise(Promise.resolve());
+// ➜ true
+isPromise({});
+// ➜ false
+
 /**
  * Run async operations in parallel and collect results
  */
@@ -210,20 +266,35 @@ await findAsync([1, 3, 4, 5], async (n) => {
 ### Function Utilities
 
 ```ts
-import { noop, invokeIfFunction, delay, retry } from '@react-hive/honey-utils';
+import {
+    noop,
+    isFunction,
+    invokeIfFunction,
+    delay,
+    retry
+} from '@react-hive/honey-utils';
 
 /**
  * No-operation function. Does nothing
  */
 noop();
 
+/**
+ * Check if value is a function
+ */
+isFunction(() => {});
+// ➜ true
+isFunction({});
+// ➜ false
+
 /**
  * Invoke if function, otherwise return value
  */
 const fn = (x: number) => x * 2;
 
 invokeIfFunction(fn, 5); // 10
-invokeIfFunction('not a function', 5); // 'not a function'
+invokeIfFunction('not a function', 5);
+// ➜ 'not a function'
 
 /**
  * Waits for 1 second before continuing
@@ -260,151 +331,132 @@ fetchWithRetry()
 ### Type Guards
 
 ```ts
-import { 
-  isString, 
-  isNumber, 
-  isBool, 
-  isObject, 
-  isFunction, 
-  isPromise, 
-  isNil, 
-  isNilOrEmptyString,
-  isArray,
-  isEmptyArray,
-  isEmptyObject,
-  isNull,
-  isUndefined,
-  isDate,
-  isValidDate,
-  isRegExp,
-  isMap,
-  isSet
+import {
+    isNumber,
+    isBool,
+    isObject,
+    isNil,
+    isEmptyObject,
+    isNull,
+    isUndefined,
+    isDate,
+    isValidDate,
+    isRegExp,
+    isMap,
+    isSet
 } from '@react-hive/honey-utils';
 
-/**
- * Check if value is a string
- */
-isString('hello'); // true
-isString(123); // false
-
 /**
  * Check if value is a number
  */
-isNumber(123); // true
-isNumber('123'); // false
+isNumber(123);
+// ➜ true
+isNumber('123');
+// ➜ false
 
 /**
  * Check if value is a boolean
  */
-isBool(true); // true
-isBool('true'); // false
+isBool(true);
+// ➜ true
+isBool('true');
+// ➜ false
 
 /**
  * Check if value is an object
  */
-isObject({}); // true
-isObject('object'); // false
-
-/**
- * Check if value is a function
- */
-isFunction(() => {}); // true
-isFunction({}); // false
-
-/**
- * Check if value is a Promise
- */
-isPromise(Promise.resolve()); // true
-isPromise({}); // false
+isObject({});
+// ➜ true
+isObject('object');
+// ➜ false
 
 /**
  * Check if value is null or undefined
  */
-isNil(null); // true
-isNil(undefined); // true
-isNil(''); // false
-
-/**
- * Check if value is null, undefined, or empty string
- */
-isNilOrEmptyString(''); // true
-isNilOrEmptyString(null); // true
-isNilOrEmptyString('hello'); // false
-
-/**
- * Check if value is an array
- */
-isArray([1, 2, 3]); // true
-isArray({}); // false
-
-/**
- * Check if value is an empty array
- */
-isEmptyArray([]); // true
-isEmptyArray([1, 2, 3]); // false
+isNil(null);
+// ➜ true
+isNil(undefined);
+// ➜ true
+isNil('');
+// ➜ false
 
 /**
  * Check if value is an empty object
  */
-isEmptyObject({}); // true
-isEmptyObject({ key: 'value' }); // false
+isEmptyObject({});
+// ➜ true
+isEmptyObject({ key: 'value' });
+// ➜ false
 
 /**
  * Check if value is a Date object
  */
-isDate(new Date()); // true
-isDate('2023-01-01'); // false
+isDate(new Date());
+// ➜ true
+isDate('2023-01-01');
+// ➜ false
 
 /**
  * Check if value is a valid Date object
  */
-isValidDate(new Date()); // true
-isValidDate(new Date('invalid')); // false
+isValidDate(new Date());
+// ➜ true
+isValidDate(new Date('invalid'));
+// ➜ false
 
 /**
  * Check if value is a RegExp
  */
-isRegExp(/test/); // true
-isRegExp('test'); // false
+isRegExp(/test/);
+// ➜ true
+isRegExp('test');
+// ➜ false
 
 /**
  * Check if value is a Map or Set
  */
-isMap(new Map()); // true
-isSet(new Set()); // true
+isMap(new Map());
+// ➜ true
+isSet(new Set());
+// ➜ true
 ```
 
 ### Math Utilities
 
 ```ts
-import { 
-  calculateEuclideanDistance, 
-  calculateMovingSpeed, 
-  calculatePercentage 
+import {
+    calculateEuclideanDistance,
+    calculateMovingSpeed,
+    calculatePercentage 
 } from '@react-hive/honey-utils';
 
 /**
  * Calculate Euclidean distance between two points
  */
-calculateEuclideanDistance(0, 0, 3, 4); // 5
+calculateEuclideanDistance(0, 0, 3, 4);
+// ➜ 5
 
 /**
  * Calculate moving speed
  */
-calculateMovingSpeed(100, 5); // 20
+calculateMovingSpeed(100, 5);
+// ➜ 20
 
 /**
  * Calculate percentage of a value
  */
-calculatePercentage(200, 25); // 50
+calculatePercentage(200, 25);
+// ➜ 50
 ```
 
 ### DOM Utilities
 
 ```ts
-import { parse2DMatrix, cloneBlob, convertBlobToFile } from '@react-hive/honey-utils';
+import { parse2DMatrix, cloneBlob } from '@react-hive/honey-utils';
 
-// Extract transformation values from an HTML element's 2D matrix
+/**
+ * Extract transformation values from an HTML element's 2D matrix
+ */
 const element = document.getElementById('my-element');
 if (element) {
   const { translateX, translateY, scaleX, scaleY, skewX, skewY } = parse2DMatrix(element);
@@ -414,19 +466,68 @@ if (element) {
   console.log(`Element is skewed by ${skewX} horizontally and ${skewY} vertically`);
 }
 
-// Clone a Blob object
+/**
+ * Clone a Blob object
+ */
 const originalBlob = new Blob(['Hello World'], { type: 'text/plain' });
 const clonedBlob = cloneBlob(originalBlob);
 
-console.log(clonedBlob.type); // 'text/plain'
+console.log(clonedBlob.type);
+// ➜ 'text/plain'
+```
+
+### File Utilities
+
+```ts
+import { parseFileName, fileListToFile, blobToFile } from '@react-hive/honey-utils';
+
+/**
+ * Parse a file name into base name + extension
+ */
+const [base, ext] = parseFileName('archive.tar.gz');
+
+console.log(base);
+// ➜ 'archive.tar'
+console.log(ext);
+// ➜ 'gz'
+
+/**
+ * Hidden file (no name)
+ */
+parseFileName('.gitignore');
+// ➜ ['.gitignore', '']
+
+/**
+ * No file extension
+ */
+parseFileName('README');
+// ➜ ['README', '']
+
+/**
+ * Convert a FileList to an array
+ */
+const input = document.querySelector('input[type="file"]')!;
+input.addEventListener('change', () => {
+    const files = fileListToFiles(input.files);
+    
+    console.log(Array.isArray(files));
+    // ➜ true
+    console.log(files[0] instanceof File);
+    // ➜ true
+});
 
-// Convert a Blob to a File
+/**
+ * Convert a Blob to a File
+ */
 const blob = new Blob(['Hello world'], { type: 'text/plain' });
-const file = convertBlobToFile(blob, 'hello.txt');
+const file = blobToFile(blob, 'hello.txt');
 
-console.log(file instanceof File); // true
-console.log(file.name); // 'hello.txt'
-console.log(file.type); // 'text/plain'
+console.log(file instanceof File);
+// ➜ true
+console.log(file.name);
+// ➜ 'hello.txt'
+console.log(file.type);
+// ➜ 'text/plain'
 ```
 
 ### Assert Function
@@ -445,6 +546,8 @@ function divide(a: number, b: number): number {
 
 ### String Utilities
 
+- `isString(value: unknown): value is string` - Checks if a value is a `string`.
+- `isNilOrEmptyString(value: unknown): value is null | undefined` - Checks if a value is `null`, `undefined`, or an empty 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.
@@ -452,6 +555,8 @@ function divide(a: number, b: number): number {
 
 ### Array Utilities
 
+- `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.
 - `compact<T>(array: (T | Falsy)[]): T[]` – Returns a new array with all falsy values (false, null, undefined, 0, '', NaN) removed, preserving only truthy items of type `T`.
 - `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.
@@ -462,6 +567,7 @@ function divide(a: number, b: number): number {
 
 ### Function Utilities
 
+- `isFunction(value: unknown): value is Function` - Checks if a value is a `function`.
 - `noop(): void` - A no-operation function.
 - `not<Args extends any[]>(fn: (...args: Args) => any): (...args: Args) => boolean` - Creates a new function that negates the result of the given predicate function. Useful for logical inversions, e.g., turning `isEven` into `isOdd`.
 - `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.
@@ -472,16 +578,10 @@ function divide(a: number, b: number): number {
 ### Type Guards
 
 - `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`.
@@ -505,7 +605,6 @@ function divide(a: number, b: number): number {
 
 - `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.
 - `getDOMRectIntersectionRatio(sourceRect: DOMRect, targetRect: DOMRect): number` - Calculates the ratio of the `targetRect` that is overlapped by the `sourceRect`. Returns a number between `0` (no overlap) and `1` (fully covered).
 - `getElementOffsetRect(element: HTMLElement): DOMRect` - Returns a `DOMRect` representing the element's layout position using `offsetLeft`, `offsetTop`, and `clientWidth`/`clientHeight`.
 - `isAnchorHtmlElement(element: HTMLElement): element is HTMLAnchorElement` - Determines whether the provided element is an `<a>` tag. Acts as a type guard that narrows the element to `HTMLAnchorElement`.
@@ -513,8 +612,17 @@ function divide(a: number, b: number): number {
 - `isHtmlElementFocusable(element: Nullable<HTMLElement>): boolean` - Checks whether an element is considered focusable according to browser rules. Factors include: visibility, `display`, `disabled`, `tabindex`, native focusable tags, `contenteditable`, and presence of a non-null `tabindex`.
 - `getFocusableHtmlElements(container: HTMLElement): HTMLElement[]` - Returns all focusable descendant elements within a container, using `isHtmlElementFocusable` to filter them.
 
+### File Utilities
+
+- `isFile(value: unknown): value is File` - Checks if a value is a `File`.
+- `parseFileName(fileName: string): [baseName: string, extension: string]` - Splits a file name into its base name and extension using the last `.` as the separator. Handles edge cases such as hidden files (`.gitignore`), multi-dot names (`archive.tar.gz`), and names ending with a dot (`"file."`). The extension is returned in lowercase.
+- `fileListToFiles(fileList: FileList | null): File[]` - Converts a `FileList` object (such as the one returned from an `<input type="file">`) into a standard array of `File` objects. Returns an empty array when the input is `null`.
+- `blobToFile(blob: Blob, fileName: string): File` - Converts a Blob object into a File object with the specified name.
+- `traverseFileSystemDirectory(directoryEntry: FileSystemDirectoryEntry, options?: TraverseDirectoryOptions): Promise<File[]>` — Recursively scans a directory using the File System API and returns all nested files as `File` objects. Supports skipping system files and reporting progress through an optional `onProgress` callback.
+
 ### Asynchronous Utilities
 
+- `isPromise<T = unknown>(value: unknown): value is Promise<T>` - Checks if a value is a `Promise`.
 - `runSequential<Item, Result>(array: Item[], fn: (item, index, array) => Promise<Result>): Promise<Result[]>` - Runs asynchronous operations on each array item *sequentially* and returns the results in the original order.
 - `runParallel<Item, Result>(array: Item[], fn: (item, index, array) => Promise<Result>): Promise<Result[]>` - Executes an asynchronous function for each array item *in parallel* and returns a promise of all results.
 - `reduceAsync<Item, Accumulator>(array: Item[], fn, initialValue): Promise<Accumulator>` - Asynchronously reduces an array to a single accumulated value. Each step waits for the previous promise to resolve.

package/dist/array.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Checks if a value is an array.
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is an array; otherwise, `false`.
+ */
+export declare const isArray: (value: unknown) => value is unknown[];
+/**
+ * Checks if a value is an empty array.
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is an empty array; otherwise, `false`.
+ */
+export declare const isEmptyArray: (value: unknown) => value is [];
 /**
  * Represents all falsy values.
  */

package/dist/async.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Checks if a value is a Promise.
+ *
+ * @template T - The type of the value that the Promise resolves to.
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is a Promise; otherwise, `false`.
+ */
+export declare const isPromise: <T = unknown>(value: unknown) => value is Promise<T>;
 /**
  * Asynchronously iterates over an array and executes an async function on each item sequentially,
  * collecting the results.

package/dist/dom.d.ts

@@ -31,26 +31,6 @@ export declare const parse2DMatrix: (element: HTMLElement) => HTMLElementTransfo
  * @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 convertBlobToFile: (blob: Blob, fileName: string) => File;
 /**
  * Calculates the intersection ratio between two DOM rectangles.
  *

package/dist/file.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Checks if a value is a `File` object.
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is a `File` object; otherwise, `false`.
+ */
+export declare const isFile: (value: unknown) => value is File;
+/**
+ * Splits a file name into its base name and extension.
+ *
+ * Special cases:
+ * - Files without a dot return `[fileName, ""]`
+ * - Hidden files like `.gitignore` return `[".gitignore", ""]`
+ * - Names ending with a trailing dot (e.g., `"file."`) return `["file.", ""]`
+ * - Multi-dot names (e.g., `"archive.tar.gz"`) split on the last dot
+ *
+ * @param fileName - The full file name to parse.
+ *
+ * @returns A tuple where:
+ *  - index 0 is the base name
+ *  - index 1 is the file extension (lowercased), or an empty string if none exists
+ */
+export declare const parseFileName: (fileName: string) => string[];
+/**
+ * Converts a `FileList` object to an array of `File` objects.
+ *
+ * @param fileList - The `FileList` object to convert.
+ *
+ * @returns An array of `File` objects.
+ */
+export declare const fileListToFiles: (fileList: FileList | null) => File[];
+/**
+ * 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 = blobToFile(blob, 'hello.txt');
+ *
+ * console.log(file instanceof File); // true
+ * ```
+ */
+export declare const blobToFile: (blob: Blob, fileName: string) => File;
+/**
+ * A callback function invoked whenever a file is discovered during directory traversal.
+ *
+ * @param progress - An object containing details about the current traversal state.
+ * @param progress.processed - The total number of files processed so far.
+ * @param progress.currentFile - The `File` object for the file just discovered (if available).
+ * @param progress.path - The full path of the file relative to the traversed directory (if available).
+ */
+type TraverseDirectoryOnProgressHandler = (progress: {
+    processed: number;
+    currentFile?: File;
+    path?: string;
+}) => void;
+interface TraverseDirectoryOptions {
+    /**
+     * A list of file names that should be ignored during traversal.
+     * Any file whose name matches an entry will be skipped entirely.
+     *
+     * Common values include OS-generated metadata files such as:
+     * `.DS_Store`, `Thumbs.db`, `desktop.ini`, `.Spotlight-V100`, etc.
+     */
+    skipFiles?: string[];
+    /**
+     * Optional callback invoked each time a file is discovered.
+     * Useful for progress tracking when traversing large or deeply nested directories.
+     */
+    onProgress?: TraverseDirectoryOnProgressHandler;
+}
+/**
+ * Recursively scans a directory using the File System API and collects all nested files.
+ *
+ * This function walks through all subdirectories, resolving each file into a `File` object.
+ * Directories themselves are not returned. To avoid unnecessary noise, certain system or
+ * OS-generated files can be excluded via the `skipFiles` option.
+ *
+ * A progress callback (`onProgress`) may be provided to receive updates each time a file
+ * is discovered. This is useful when working with large folders or deeply nested structures.
+ *
+ * @param directoryEntry - The starting directory entry to traverse.
+ * @param options - Optional settings that control traversal behavior.
+ * @param processed - Internal counter used to track the number of processed files
+ *   during recursive traversal. Not intended to be provided manually.
+ *
+ * @returns A promise resolving to a flat array of all collected `File` objects.
+ */
+export declare const traverseFileSystemDirectory: (directoryEntry: FileSystemDirectoryEntry, { skipFiles, onProgress, }?: TraverseDirectoryOptions, processed?: number) => Promise<File[]>;
+export {};

package/dist/function.d.ts

@@ -1,4 +1,12 @@
 export declare const noop: () => void;
+/**
+ * Checks if a value is a function.
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is a function; otherwise, `false`.
+ */
+export declare const isFunction: (value: unknown) => value is Function;
 /**
  * Creates a function that negates the result of the given predicate function.
  *