@react-hive/honey-utils/dist/file.d.ts

A lightweight TypeScript utility library providing a collection of helper functions for common programming tasks

import type { Nullable } from './types';
/**
 * 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: Nullable<FileList>) => 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;
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[];
}
/**
 * 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.
 *
 * @param directoryEntry - The starting directory entry to traverse.
 * @param options - Optional settings that control traversal behavior.
 *
 * @returns A promise resolving to a flat array of all collected `File` objects.
 */
export declare const traverseFileSystemDirectory: (directoryEntry: FileSystemDirectoryEntry, { skipFiles, }?: TraverseDirectoryOptions) => Promise<File[]>;
/**
 * Reads files from a `DataTransfer` object, supporting both individual files
 * and entire directories (when available through the non-standard `webkitGetAsEntry` API).
 *
 * This function is typically used in drag-and-drop or paste handlers to obtain
 * all `File` objects contained in the user's action. When directories are dropped,
 * they are traversed recursively using `traverseFileSystemDirectory`, returning a
 * fully flattened list of nested files.
 *
 * @param dataTransfer - The `DataTransfer` instance from a drop or paste event.
 *   If `null` or missing items, an empty array is returned.
 * @param traverseOptions - Optional settings passed to directory traversal.
 *
 * @returns A promise that resolves to a flat array of all extracted `File` objects.
 *   This includes:
 *   - direct files from the drag event,
 *   - files extracted from directory entries via `webkitGetAsEntry`,
 *   - and files found recursively within nested subdirectories.
 */
export declare const readFilesFromDataTransfer: (dataTransfer: Nullable<DataTransfer>, traverseOptions?: TraverseDirectoryOptions) => Promise<File[]>;
export {};