@gzl10/ts-helpers 4.2.1

package/dist/types/data.d.ts

@@ -0,0 +1,1561 @@
+/**
+ * Data manipulation utilities for multiple formats with automatic detection
+ * Consolidated from data/index module
+ */
+/**
+ * Type for data - array of objects or array of arrays (for CSV, etc.)
+ */
+type ExportData = Record<string, any>[] | string[][];
+/**
+ * Type for imported data - can include string for .tree files
+ */
+type ImportData = ExportData | string | any;
+/**
+ * Type for CSV data (backward compatibility)
+ */
+type CSVData = ExportData;
+/**
+ * Supported format types
+ */
+type ExportFormat = 'csv' | 'json' | 'tree' | 'txt';
+/**
+ * Universal file format detection - detects any file extension
+ */
+type FileFormat = string;
+/**
+ * Reads a file as text in any environment (Node.js or Browser)
+ *
+ * Universal file reading utility that adapts to the runtime environment.
+ * In Node.js, reads from filesystem. In Browser, reads from File object.
+ *
+ * Environment behavior:
+ * - **Node.js**: Pass file path as string, reads from filesystem
+ * - **Browser**: Pass File object (from input[type="file"]), reads with FileReader API
+ *
+ * @param fileOrPath - File path string (Node.js) or File object (Browser)
+ * @param encoding - Text encoding for Node.js filesystem read (default: 'utf8')
+ * @returns Promise<string> File contents as text
+ *
+ * @example
+ * ```typescript
+ * // Node.js - Read from filesystem
+ * const config = await readFileAsText('./config.json')
+ * const data = JSON.parse(config)
+ *
+ * // Browser - Read from File input
+ * // HTML: <input type="file" id="fileInput">
+ * const input = document.getElementById('fileInput') as HTMLInputElement
+ * input.addEventListener('change', async (e) => {
+ *   const file = e.target.files[0]
+ *   const content = await readFileAsText(file)
+ *   console.log('File content:', content)
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Load and parse CSV from user upload (Browser)
+ * async function handleCSVUpload(file: File) {
+ *   const csvText = await readFileAsText(file)
+ *   const rows = csvText.split('\n').map(row => row.split(';'))
+ *   console.log(`Loaded ${rows.length} rows`)
+ *   return rows
+ * }
+ * ```
+ *
+ * @throws {DataError} If called with invalid parameter for current environment
+ * @see {@link importData} for format-aware file importing
+ */
+declare const readFileAsText: (fileOrPath: string | File, encoding?: BufferEncoding) => Promise<string>;
+/**
+ * Validates that data is exportable (array of objects or array of arrays)
+ *
+ * Ensures data structure is compatible with export formats (CSV, JSON).
+ * Validates consistency: all elements must be same type, arrays must have equal length.
+ *
+ * Validation rules:
+ * - Must be non-empty array
+ * - If first element is object → all must be objects (no arrays/primitives)
+ * - If first element is array → all must be arrays with equal length
+ * - Null/undefined not allowed
+ *
+ * @param data - Data to validate for export
+ * @returns `true` if data is valid (type guard for ExportData)
+ *
+ * @example
+ * ```typescript
+ * // Valid: Array of objects (typical use case)
+ * const users = [
+ *   { id: 1, name: 'Alice', role: 'Admin' },
+ *   { id: 2, name: 'Bob', role: 'User' }
+ * ]
+ * validateExportData(users) // ✅ true
+ * await exportData(users, 'users.csv')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Valid: Array of arrays (matrix/tabular data)
+ * const matrix = [
+ *   ['Name', 'Age', 'City'],
+ *   ['Alice', 25, 'Madrid'],
+ *   ['Bob', 30, 'Barcelona']
+ * ]
+ * validateExportData(matrix) // ✅ true
+ * await exportData(matrix, 'data.csv')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Invalid: Mixed types - throws ValidationError
+ * const mixed = [
+ *   { id: 1, name: 'Alice' },
+ *   ['Bob', 30] // ❌ Array mixed with object
+ * ]
+ * try {
+ *   validateExportData(mixed)
+ * } catch (error) {
+ *   console.error(error.message)
+ *   // 'All elements must be objects if first one is an object'
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Invalid: Inconsistent array lengths - throws ValidationError
+ * const uneven = [
+ *   ['Alice', 25, 'Madrid'],
+ *   ['Bob', 30] // ❌ Missing city
+ * ]
+ * try {
+ *   validateExportData(uneven)
+ * } catch (error) {
+ *   console.error(error.message)
+ *   // 'Row 1 has 2 columns, but first has 3'
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Pre-export validation with error handling
+ * async function safeExportUsers(users: any[], filename: string) {
+ *   try {
+ *     // Validate before export
+ *     validateExportData(users)
+ *     await exportData(users, filename)
+ *     console.log(`✅ Exported ${users.length} users to ${filename}`)
+ *   } catch (error) {
+ *     console.error('Export failed:', error.message)
+ *     // Log validation errors for debugging
+ *     if (error.code === 'VALIDATION_ERROR') {
+ *       console.error('Invalid data structure:', error.details)
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @throws {ValidationError} If data is not an array
+ * @throws {ValidationError} If array is empty
+ * @throws {ValidationError} If elements have inconsistent types
+ * @throws {ValidationError} If array rows have different lengths
+ *
+ * @see {@link exportData} for universal export using validated data
+ * @see {@link ExportData} for type definition
+ */
+declare function validateExportData(data: any): data is ExportData;
+/**
+ * Alias for validateExportData for CSV backward compatibility
+ */
+declare const validateCSVData: typeof validateExportData;
+/**
+ * Detects file format based on filename extension
+ *
+ * Analyzes filename to determine export format for automatic format selection.
+ * Supports CSV, JSON, Tree, and TXT formats. Case-insensitive.
+ *
+ * @param filename - Filename with extension
+ * @returns Detected format ('csv' | 'json' | 'tree' | 'txt')
+ *
+ * @example
+ * ```typescript
+ * // CSV detection
+ * detectFormatFromFilename('users.csv') // 'csv'
+ * detectFormatFromFilename('DATA.CSV') // 'csv' (case-insensitive)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // JSON detection
+ * detectFormatFromFilename('config.json') // 'json'
+ * detectFormatFromFilename('data.JSON') // 'json'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Tree structure detection
+ * detectFormatFromFilename('structure.tree') // 'tree'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Plain text detection
+ * detectFormatFromFilename('notes.txt') // 'txt'
+ * detectFormatFromFilename('log.TXT') // 'txt'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Dynamic export routing
+ * async function smartExport(data: any[], filename: string) {
+ *   const format = detectFormatFromFilename(filename)
+ *   console.log(`Exporting as ${format.toUpperCase()}...`)
+ *
+ *   await exportData(data, filename)
+ *   console.log(`✅ Export completed: ${filename}`)
+ * }
+ *
+ * smartExport(users, 'users.csv')   // Exports as CSV
+ * smartExport(config, 'config.json') // Exports as JSON
+ * ```
+ *
+ * @throws {DataError} If filename has no extension
+ * @throws {DataError} If extension is not supported (.csv, .json, .tree, .txt)
+ *
+ * @see {@link detectFileExtension} for universal extension detection (any file type)
+ * @see {@link detectUniversalFormat} for detailed format metadata
+ * @see {@link exportData} for universal export using detected format
+ *
+ * @deprecated Use detectFileExtension for universal detection, or use exportData directly (auto-detects)
+ */
+declare function detectFormatFromFilename(filename: string): ExportFormat;
+/**
+ * Universal file extension detector - detects any file extension
+ *
+ * Extracts file extension from filename (without dot) for any file type.
+ * Returns last extension for compound extensions (e.g., '.tar.gz' → 'gz').
+ * Case-insensitive, trims whitespace, returns null if no extension found.
+ *
+ * @param filename - Filename with extension
+ * @returns File extension (lowercase, without dot) or `null` if no extension
+ *
+ * @example
+ * ```typescript
+ * // Common file types
+ * detectFileExtension('document.pdf')    // 'pdf'
+ * detectFileExtension('image.jpg')       // 'jpg'
+ * detectFileExtension('data.json')       // 'json'
+ * detectFileExtension('styles.css')      // 'css'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Compound extensions (returns last extension)
+ * detectFileExtension('archive.tar.gz')  // 'gz'
+ * detectFileExtension('backup.sql.bz2')  // 'bz2'
+ * detectFileExtension('file.test.ts')    // 'ts'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Edge cases
+ * detectFileExtension('noextension')     // null
+ * detectFileExtension('.hidden')         // 'hidden' (Unix hidden files)
+ * detectFileExtension('file.')           // '' (empty string)
+ * detectFileExtension('  file.txt  ')    // 'txt' (trims whitespace)
+ * detectFileExtension('FILE.PDF')        // 'pdf' (case-insensitive)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Conditional file processing
+ * async function processUploadedFile(filename: string, data: any) {
+ *   const ext = detectFileExtension(filename)
+ *
+ *   switch (ext) {
+ *     case 'csv':
+ *       return await importCSV(filename)
+ *     case 'json':
+ *       return await importJSON(filename)
+ *     case 'pdf':
+ *       return await extractPdfText(filename)
+ *     case null:
+ *       throw new Error('File must have an extension')
+ *     default:
+ *       throw new Error(`Unsupported file type: .${ext}`)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: File type validation
+ * function validateUpload(file: File) {
+ *   const ext = detectFileExtension(file.name)
+ *   const allowedExtensions = ['jpg', 'jpeg', 'png', 'gif']
+ *
+ *   if (!ext) {
+ *     return { valid: false, error: 'File must have an extension' }
+ *   }
+ *
+ *   if (!allowedExtensions.includes(ext)) {
+ *     return {
+ *       valid: false,
+ *       error: `Invalid file type .${ext}. Allowed: ${allowedExtensions.join(', ')}`
+ *     }
+ *   }
+ *
+ *   return { valid: true }
+ * }
+ * ```
+ *
+ * @see {@link detectUniversalFormat} for detailed format metadata (category, MIME type)
+ * @see {@link detectFormatFromFilename} for export format detection (csv/json/tree/txt only)
+ */
+declare function detectFileExtension(filename: string): FileFormat | null;
+/**
+ * Universal filename format detection with comprehensive extension support
+ *
+ * Analyzes filename extension and returns detailed format metadata including:
+ * category, MIME type, text/binary classification. Supports 80+ file formats
+ * across data, code, documents, images, audio, video, archives, and fonts.
+ *
+ * @param filename - Filename with extension
+ * @returns Object with extension, category, isText, isBinary, mimeType properties
+ *
+ * @example
+ * ```typescript
+ * // Data formats
+ * detectUniversalFormat('config.json')
+ * // { extension: 'json', category: 'data', isText: true, isBinary: false, mimeType: 'application/json' }
+ *
+ * detectUniversalFormat('users.csv')
+ * // { extension: 'csv', category: 'data', isText: true, isBinary: false, mimeType: 'text/csv' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Programming languages
+ * detectUniversalFormat('app.ts')
+ * // { extension: 'ts', category: 'code', isText: true, isBinary: false, mimeType: 'application/typescript' }
+ *
+ * detectUniversalFormat('main.py')
+ * // { extension: 'py', category: 'code', isText: true, isBinary: false, mimeType: 'text/x-python' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Documents
+ * detectUniversalFormat('report.pdf')
+ * // { extension: 'pdf', category: 'document', isText: false, isBinary: true, mimeType: 'application/pdf' }
+ *
+ * detectUniversalFormat('doc.docx')
+ * // { extension: 'docx', category: 'document', isText: false, isBinary: true, mimeType: '...' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Images
+ * detectUniversalFormat('photo.jpg')
+ * // { extension: 'jpg', category: 'image', isText: false, isBinary: true, mimeType: 'image/jpeg' }
+ *
+ * detectUniversalFormat('icon.svg')
+ * // { extension: 'svg', category: 'image', isText: true, isBinary: false, mimeType: 'image/svg+xml' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Archives
+ * detectUniversalFormat('backup.zip')
+ * // { extension: 'zip', category: 'archive', isText: false, isBinary: true, mimeType: 'application/zip' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Smart file processing routing
+ * async function processFile(filename: string, content: any) {
+ *   const format = detectUniversalFormat(filename)
+ *
+ *   console.log(`Processing ${format.extension} file (${format.category})`)
+ *
+ *   if (format.isText) {
+ *     // Can read as text
+ *     const text = await readFileAsText(filename)
+ *     return parseTextFormat(text, format.extension)
+ *   } else if (format.isBinary) {
+ *     // Needs binary processing
+ *     return processBinaryFile(filename, format.mimeType)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Content-Type header generation
+ * function getResponseHeaders(filename: string) {
+ *   const format = detectUniversalFormat(filename)
+ *
+ *   return {
+ *     'Content-Type': format.mimeType || 'application/octet-stream',
+ *     'Content-Disposition': `attachment; filename="${filename}"`,
+ *     'X-File-Category': format.category
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link detectFileExtension} for simple extension extraction
+ * @see {@link detectFormatFromFilename} for export format detection
+ */
+declare function detectUniversalFormat(filename: string): {
+    extension: null;
+    category: string;
+    isText: boolean;
+    isBinary: boolean;
+    mimeType: null;
+} | {
+    category: "data";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/json";
+    extension: string;
+} | {
+    category: "data";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/csv";
+    extension: string;
+} | {
+    category: "data";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/xml";
+    extension: string;
+} | {
+    category: "data";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/yaml";
+    extension: string;
+} | {
+    category: "data";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/plain";
+    extension: string;
+} | {
+    category: "data";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/tab-separated-values";
+    extension: string;
+} | {
+    category: "data";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/sql";
+    extension: string;
+} | {
+    category: "data";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/x-sqlite3";
+    extension: string;
+} | {
+    category: "text";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/plain";
+    extension: string;
+} | {
+    category: "text";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/markdown";
+    extension: string;
+} | {
+    category: "text";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-rst";
+    extension: string;
+} | {
+    category: "text";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/rtf";
+    extension: string;
+} | {
+    category: "web";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/html";
+    extension: string;
+} | {
+    category: "web";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/css";
+    extension: string;
+} | {
+    category: "web";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-scss";
+    extension: string;
+} | {
+    category: "web";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-sass";
+    extension: string;
+} | {
+    category: "web";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-less";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/javascript";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/jsx";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/typescript";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/tsx";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-python";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-java-source";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/x-httpd-php";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-ruby";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-go";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-rust";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-c";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-c++";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/x-csharp";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/x-sh";
+    extension: string;
+} | {
+    category: "code";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/x-powershell";
+    extension: string;
+} | {
+    category: "document";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/msword";
+    extension: string;
+} | {
+    category: "document";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    extension: string;
+} | {
+    category: "spreadsheet";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.ms-excel";
+    extension: string;
+} | {
+    category: "spreadsheet";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    extension: string;
+} | {
+    category: "presentation";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.ms-powerpoint";
+    extension: string;
+} | {
+    category: "presentation";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+    extension: string;
+} | {
+    category: "document";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.oasis.opendocument.text";
+    extension: string;
+} | {
+    category: "spreadsheet";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.oasis.opendocument.spreadsheet";
+    extension: string;
+} | {
+    category: "presentation";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.oasis.opendocument.presentation";
+    extension: string;
+} | {
+    category: "document";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/pdf";
+    extension: string;
+} | {
+    category: "document";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/epub+zip";
+    extension: string;
+} | {
+    category: "document";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/x-mobipocket-ebook";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/jpeg";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/png";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/gif";
+    extension: string;
+} | {
+    category: "image";
+    isText: true;
+    isBinary: false;
+    mimeType: "image/svg+xml";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/webp";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/avif";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/bmp";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/tiff";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/x-icon";
+    extension: string;
+} | {
+    category: "image";
+    isText: false;
+    isBinary: true;
+    mimeType: "image/vnd.adobe.photoshop";
+    extension: string;
+} | {
+    category: "audio";
+    isText: false;
+    isBinary: true;
+    mimeType: "audio/mpeg";
+    extension: string;
+} | {
+    category: "audio";
+    isText: false;
+    isBinary: true;
+    mimeType: "audio/wav";
+    extension: string;
+} | {
+    category: "audio";
+    isText: false;
+    isBinary: true;
+    mimeType: "audio/flac";
+    extension: string;
+} | {
+    category: "audio";
+    isText: false;
+    isBinary: true;
+    mimeType: "audio/ogg";
+    extension: string;
+} | {
+    category: "audio";
+    isText: false;
+    isBinary: true;
+    mimeType: "audio/aac";
+    extension: string;
+} | {
+    category: "audio";
+    isText: false;
+    isBinary: true;
+    mimeType: "audio/m4a";
+    extension: string;
+} | {
+    category: "audio";
+    isText: false;
+    isBinary: true;
+    mimeType: "audio/x-ms-wma";
+    extension: string;
+} | {
+    category: "video";
+    isText: false;
+    isBinary: true;
+    mimeType: "video/mp4";
+    extension: string;
+} | {
+    category: "video";
+    isText: false;
+    isBinary: true;
+    mimeType: "video/x-msvideo";
+    extension: string;
+} | {
+    category: "video";
+    isText: false;
+    isBinary: true;
+    mimeType: "video/quicktime";
+    extension: string;
+} | {
+    category: "video";
+    isText: false;
+    isBinary: true;
+    mimeType: "video/x-ms-wmv";
+    extension: string;
+} | {
+    category: "video";
+    isText: false;
+    isBinary: true;
+    mimeType: "video/x-flv";
+    extension: string;
+} | {
+    category: "video";
+    isText: false;
+    isBinary: true;
+    mimeType: "video/webm";
+    extension: string;
+} | {
+    category: "video";
+    isText: false;
+    isBinary: true;
+    mimeType: "video/x-matroska";
+    extension: string;
+} | {
+    category: "video";
+    isText: false;
+    isBinary: true;
+    mimeType: "video/3gpp";
+    extension: string;
+} | {
+    category: "archive";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/zip";
+    extension: string;
+} | {
+    category: "archive";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/x-rar-compressed";
+    extension: string;
+} | {
+    category: "archive";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/x-7z-compressed";
+    extension: string;
+} | {
+    category: "archive";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/x-tar";
+    extension: string;
+} | {
+    category: "archive";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/gzip";
+    extension: string;
+} | {
+    category: "archive";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/x-bzip2";
+    extension: string;
+} | {
+    category: "archive";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/x-xz";
+    extension: string;
+} | {
+    category: "config";
+    isText: true;
+    isBinary: false;
+    mimeType: "text/plain";
+    extension: string;
+} | {
+    category: "config";
+    isText: true;
+    isBinary: false;
+    mimeType: "application/toml";
+    extension: string;
+} | {
+    category: "font";
+    isText: false;
+    isBinary: true;
+    mimeType: "font/ttf";
+    extension: string;
+} | {
+    category: "font";
+    isText: false;
+    isBinary: true;
+    mimeType: "font/otf";
+    extension: string;
+} | {
+    category: "font";
+    isText: false;
+    isBinary: true;
+    mimeType: "font/woff";
+    extension: string;
+} | {
+    category: "font";
+    isText: false;
+    isBinary: true;
+    mimeType: "font/woff2";
+    extension: string;
+} | {
+    category: "font";
+    isText: false;
+    isBinary: true;
+    mimeType: "application/vnd.ms-fontobject";
+    extension: string;
+};
+interface TreeExportOptions {
+    /** Property to display as node name (default: 'name') */
+    labelField?: string;
+    /** Characters for vertical line (default: '│   ') */
+    verticalLine?: string;
+    /** Characters for middle branch (default: '├── ') */
+    middleBranch?: string;
+    /** Characters for last branch (default: '└── ') */
+    lastBranch?: string;
+    /** Spacing for nodes without vertical line (default: '    ') */
+    emptySpace?: string;
+    /** Custom function to get node label */
+    labelFunction?: (node: any) => string;
+}
+/**
+ * Exports a tree structure as a text file with visual format
+ *
+ * Converts hierarchical data (nodes with `children` arrays) into ASCII/Unicode tree
+ * visualization and saves as .tree file. Supports Node.js (filesystem) and Browser (download).
+ *
+ * @param data - Array of root nodes (each with optional `children` property)
+ * @param filePath - Output file path (Node.js) or filename (Browser)
+ * @param options - Tree rendering options (labelField, box-drawing characters, labelFunction)
+ *
+ * @example
+ * ```typescript
+ * // Basic tree export - File structure
+ * const fileTree = [
+ *   {
+ *     name: 'src',
+ *     children: [
+ *       { name: 'index.ts' },
+ *       { name: 'utils.ts' },
+ *       {
+ *         name: 'components',
+ *         children: [
+ *           { name: 'Button.tsx' },
+ *           { name: 'Input.tsx' }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * ]
+ *
+ * await exportTree(fileTree, 'structure.tree')
+ * // Creates file:
+ * // └── src
+ * //     ├── index.ts
+ * //     ├── utils.ts
+ * //     └── components
+ * //         ├── Button.tsx
+ * //         └── Input.tsx
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom label field - Organization chart
+ * const orgChart = [
+ *   {
+ *     title: 'CEO',
+ *     children: [
+ *       {
+ *         title: 'CTO',
+ *         children: [
+ *           { title: 'Dev Lead' },
+ *           { title: 'QA Lead' }
+ *         ]
+ *       },
+ *       { title: 'CFO' }
+ *     ]
+ *   }
+ * ]
+ *
+ * await exportTree(orgChart, 'org-chart.tree', { labelField: 'title' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // ASCII characters - Better terminal compatibility
+ * await exportTree(data, 'structure.tree', {
+ *   verticalLine: '|   ',
+ *   middleBranch: '+-- ',
+ *   lastBranch: '`-- ',
+ *   emptySpace: '    '
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom label function - Rich formatting
+ * const tasks = [
+ *   {
+ *     name: 'Backend',
+ *     status: 'in-progress',
+ *     assignee: 'Alice',
+ *     children: [
+ *       { name: 'API', status: 'done', assignee: 'Bob' },
+ *       { name: 'Database', status: 'pending', assignee: 'Charlie' }
+ *     ]
+ *   }
+ * ]
+ *
+ * await exportTree(tasks, 'tasks.tree', {
+ *   labelFunction: (node) => `[${node.status}] ${node.name} (@${node.assignee})`
+ * })
+ * // Output:
+ * // └── [in-progress] Backend (@Alice)
+ * //     ├── [done] API (@Bob)
+ * //     └── [pending] Database (@Charlie)
+ * ```
+ *
+ * @throws {ValidationError} If data is not an array of nodes
+ *
+ * @see {@link importTree} for importing .tree files as text
+ * @see {@link renderTreeAsText} for tree rendering without file export
+ * @see {@link TreeExportOptions} for configuration options
+ */
+declare function exportTree(data: any[], filePath: string, options?: TreeExportOptions): Promise<void>;
+/**
+ * Imports a .tree file as plain text (Node.js only)
+ *
+ * Reads tree structure visualization files created with exportTree() as plain text.
+ * Returns the ASCII/Unicode tree diagram as string. Only supported in Node.js environment.
+ *
+ * @param filePath - Path to .tree file (Node.js only)
+ * @param _options - Reserved for future use
+ * @returns Promise<string> Tree structure as text
+ *
+ * @example
+ * ```typescript
+ * // Import tree structure
+ * const treeText = await importTree('./structure.tree')
+ * console.log(treeText)
+ * // Output:
+ * // └── src
+ * //     ├── index.ts
+ * //     ├── utils.ts
+ * //     └── components
+ * //         ├── Button.tsx
+ * //         └── Input.tsx
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Display tree structure in terminal
+ * async function showProjectStructure(filePath: string) {
+ *   try {
+ *     const structure = await importTree(filePath)
+ *     console.log('📁 Project Structure:')
+ *     console.log(structure)
+ *   } catch (error) {
+ *     console.error('Failed to load structure:', error.message)
+ *   }
+ * }
+ * ```
+ *
+ * @throws {DataError} If called in Browser environment (use readFileAsText with File object instead)
+ *
+ * @see {@link exportTree} for creating .tree files
+ * @see {@link readFileAsText} for browser-compatible file reading
+ */
+declare function importTree(filePath: string, _options?: any): Promise<string>;
+interface TxtExportOptions {
+    /** Separator between array elements (default: '\n') */
+    separator?: string;
+    /** Custom function to convert objects to string */
+    stringify?: (obj: any) => string;
+    /** Indentation for JSON objects (default: 2) */
+    indent?: number;
+}
+/**
+ * Exports any type of data as plain text file
+ *
+ * Universal text file exporter supporting strings, arrays, objects, and primitives.
+ * Automatically formats data based on type. Supports Node.js (filesystem) and Browser (download).
+ *
+ * Features:
+ * - **Strings**: Direct output
+ * - **Arrays**: One element per line (or custom separator)
+ * - **Objects**: Formatted JSON with indentation
+ * - **Primitives**: String conversion
+ * - **Custom stringify**: Optional transform function
+ *
+ * @param data - Data to export (string, array, object, or primitive)
+ * @param filePath - Output file path (Node.js) or filename (Browser)
+ * @param options - Export options (separator, stringify function, indent)
+ *
+ * @example
+ * ```typescript
+ * // Export string - Direct output
+ * await exportTxt('Hello, World!', 'message.txt')
+ * // Creates: Hello, World!
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Export array - One per line
+ * const logs = [
+ *   '[INFO] Server started',
+ *   '[WARN] High memory usage',
+ *   '[ERROR] Connection failed'
+ * ]
+ * await exportTxt(logs, 'server.log')
+ * // Creates:
+ * // [INFO] Server started
+ * // [WARN] High memory usage
+ * // [ERROR] Connection failed
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Export object - Formatted JSON
+ * const config = {
+ *   server: { host: 'localhost', port: 3000 },
+ *   database: { url: 'mongodb://localhost' }
+ * }
+ * await exportTxt(config, 'config.txt', { indent: 2 })
+ * // Creates formatted JSON
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom separator - Comma-separated list
+ * const tags = ['typescript', 'nodejs', 'express', 'mongodb']
+ * await exportTxt(tags, 'tags.txt', { separator: ', ' })
+ * // Creates: typescript, nodejs, express, mongodb
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom stringify function - Markdown list
+ * const tasks = [
+ *   { id: 1, title: 'Setup project', done: true },
+ *   { id: 2, title: 'Write tests', done: false }
+ * ]
+ * await exportTxt(tasks, 'tasks.txt', {
+ *   stringify: (tasks) =>
+ *     tasks.map(t => `- [${t.done ? 'x' : ' '}] ${t.title}`).join('\n')
+ * })
+ * // Creates:
+ * // - [x] Setup project
+ * // - [ ] Write tests
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Export error log with timestamps
+ * async function exportErrorLog(errors: Error[]) {
+ *   const timestamp = new Date().toISOString()
+ *   const filename = `errors-${timestamp}.txt`
+ *
+ *   await exportTxt(errors, filename, {
+ *     stringify: (errors) =>
+ *       errors.map(e => `[${new Date().toISOString()}] ${e.message}\n${e.stack}`).join('\n\n')
+ *   })
+ *
+ *   console.log(`✅ Exported ${errors.length} errors to ${filename}`)
+ * }
+ * ```
+ *
+ * @see {@link importTxt} for importing text files with security validations
+ * @see {@link TxtExportOptions} for configuration options
+ */
+declare function exportTxt(data: any, filePath: string, options?: TxtExportOptions): Promise<void>;
+interface TxtImportOptions {
+    /** Maximum file size in bytes (default: 10MB) */
+    maxFileSize?: number;
+    /** Maximum content length in characters (default: 1M characters) */
+    maxLength?: number;
+    /** Whether to validate content for security (default: true) */
+    validateSecurity?: boolean;
+    /** Whether to sanitize content (default: true) */
+    sanitize?: boolean;
+}
+/**
+ * Imports a .txt file as plain text with security validations (Node.js only)
+ *
+ * Reads text files with comprehensive security checks: file size limits, content length validation,
+ * path traversal prevention, and dangerous character sanitization. Only supported in Node.js.
+ *
+ * Security features:
+ * - **File size limit**: Default 10MB (configurable)
+ * - **Content length limit**: Default 1M characters (configurable)
+ * - **Path validation**: Prevents directory traversal attacks
+ * - **Content sanitization**: Removes dangerous control characters
+ * - **Line break normalization**: Standardizes to \n
+ *
+ * @param filePath - Path to .txt file (Node.js only)
+ * @param options - Security and sanitization options
+ *
+ * @example
+ * ```typescript
+ * // Basic import - Default security settings
+ * const content = await importTxt('./notes.txt')
+ * console.log(content)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom size limits - Large file support
+ * const largeFile = await importTxt('./large-log.txt', {
+ *   maxFileSize: 50 * 1024 * 1024,  // 50MB
+ *   maxLength: 10_000_000            // 10M characters
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Disable sanitization - Raw content
+ * const rawContent = await importTxt('./data.txt', {
+ *   sanitize: false,
+ *   validateSecurity: false
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Safe log file reader with error handling
+ * async function readServerLog(logPath: string) {
+ *   try {
+ *     const log = await importTxt(logPath, {
+ *       maxFileSize: 100 * 1024 * 1024,  // 100MB logs
+ *       maxLength: 50_000_000,            // 50M chars
+ *       sanitize: true,
+ *       validateSecurity: true
+ *     })
+ *
+ *     const lines = log.split('\n')
+ *     const errors = lines.filter(line => line.includes('[ERROR]'))
+ *
+ *     console.log(`📊 Log stats:`)
+ *     console.log(`   Total lines: ${lines.length}`)
+ *     console.log(`   Errors: ${errors.length}`)
+ *
+ *     return { lines, errors }
+ *   } catch (error) {
+ *     if (error.message.includes('too large')) {
+ *       console.error('Log file exceeds size limit')
+ *     } else if (error.message.includes('not found')) {
+ *       console.error('Log file does not exist')
+ *     } else {
+ *       console.error('Failed to read log:', error.message)
+ *     }
+ *     throw error
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Secure user file upload processing
+ * async function processUserUpload(uploadedFilePath: string) {
+ *   // Enforce strict limits for user-uploaded files
+ *   const content = await importTxt(uploadedFilePath, {
+ *     maxFileSize: 5 * 1024 * 1024,   // 5MB max
+ *     maxLength: 1_000_000,            // 1M chars max
+ *     validateSecurity: true,          // Check for dangerous content
+ *     sanitize: true                   // Remove control chars
+ *   })
+ *
+ *   // Process sanitized content safely
+ *   return analyzeText(content)
+ * }
+ * ```
+ *
+ * @throws {Error} If file exceeds maxFileSize
+ * @throws {Error} If content exceeds maxLength
+ * @throws {Error} If file path is invalid or unsafe
+ * @throws {Error} If file not found
+ * @throws {Error} If called in Browser environment
+ *
+ * @see {@link exportTxt} for creating text files
+ * @see {@link TxtImportOptions} for configuration options
+ * @see {@link readFileAsText} for browser-compatible file reading
+ */
+declare function importTxt(filePath: string, options?: TxtImportOptions): Promise<string>;
+/**
+ * Exports data in specified format based on file extension (Universal dispatcher)
+ *
+ * Universal export function that automatically detects format from filename extension
+ * and delegates to specialized exporters (CSV, JSON, Tree, TXT). Simplifies data export
+ * with a single unified API for all formats.
+ *
+ * Automatic format detection:
+ * - **.csv** → exportCSV (PapaParse, UTF-8 BOM, semicolon delimiter)
+ * - **.json** → exportJSON (pretty-printed JSON)
+ * - **.tree** → exportTree (ASCII/Unicode tree visualization)
+ * - **.txt** → exportTxt (plain text with auto-formatting)
+ *
+ * Environment support:
+ * - **Node.js**: Writes to filesystem
+ * - **Browser**: Triggers download
+ *
+ * @param data - Data to export (structure depends on format)
+ * @param filePath - Output file path with extension (determines format)
+ * @param options - Format-specific options (passed to specialized exporter)
+ *
+ * @example
+ * ```typescript
+ * // CSV export - Array of objects
+ * const users = [
+ *   { id: 1, name: 'Alice', email: 'alice@example.com' },
+ *   { id: 2, name: 'Bob', email: 'bob@example.com' }
+ * ]
+ * await exportData(users, 'users.csv')
+ * // Auto-detects CSV format, exports with semicolon delimiter
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // JSON export - Any data structure
+ * const config = {
+ *   server: { host: 'localhost', port: 3000 },
+ *   database: { url: 'mongodb://localhost' },
+ *   features: { auth: true, cache: false }
+ * }
+ * await exportData(config, 'config.json', { indent: 2 })
+ * // Auto-detects JSON format, pretty-prints with 2-space indent
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Tree export - Hierarchical structure
+ * const fileTree = [
+ *   {
+ *     name: 'src',
+ *     children: [
+ *       { name: 'index.ts' },
+ *       { name: 'utils.ts' },
+ *       {
+ *         name: 'components',
+ *         children: [
+ *           { name: 'Button.tsx' },
+ *           { name: 'Input.tsx' }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * ]
+ * await exportData(fileTree, 'structure.tree')
+ * // Auto-detects tree format, renders as ASCII tree
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Text export - Logs/strings
+ * const logs = [
+ *   '[2024-01-15 10:30:00] Server started',
+ *   '[2024-01-15 10:30:15] Connected to database',
+ *   '[2024-01-15 10:31:00] Ready to accept connections'
+ * ]
+ * await exportData(logs, 'server.log')
+ * // Auto-detects txt format, one line per array element
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Multi-format export function
+ * async function exportReport(data: any[], format: 'csv' | 'json' | 'txt') {
+ *   const timestamp = new Date().toISOString().split('T')[0]
+ *   const filename = `report-${timestamp}.${format}`
+ *
+ *   try {
+ *     await exportData(data, filename)
+ *     console.log(`✅ Report exported: ${filename}`)
+ *     return { success: true, filename }
+ *   } catch (error) {
+ *     console.error(`❌ Export failed:`, error.message)
+ *     return { success: false, error: error.message }
+ *   }
+ * }
+ *
+ * // Usage
+ * exportReport(users, 'csv')   // users-2024-01-15.csv
+ * exportReport(stats, 'json')  // report-2024-01-15.json
+ * exportReport(logs, 'txt')    // report-2024-01-15.txt
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: User-selected format export
+ * async function exportWithUserChoice(data: any[], filename: string) {
+ *   // User provides filename with desired extension
+ *   // exportData automatically routes to correct exporter
+ *
+ *   await exportData(data, filename)
+ *
+ *   const format = detectFormatFromFilename(filename)
+ *   console.log(`Exported as ${format.toUpperCase()}`)
+ * }
+ *
+ * // Works with any supported extension
+ * exportWithUserChoice(data, 'data.csv')
+ * exportWithUserChoice(data, 'data.json')
+ * exportWithUserChoice(data, 'data.txt')
+ * ```
+ *
+ * @throws {DataError} If file extension is not supported
+ * @throws {ValidationError} If data structure is invalid for format (e.g., CSV requires array)
+ *
+ * @see {@link importData} for universal import
+ * @see {@link exportCSV} for CSV-specific export
+ * @see {@link exportJSON} for JSON-specific export
+ * @see {@link exportTree} for tree-specific export
+ * @see {@link exportTxt} for text-specific export
+ */
+declare function exportData(data: any, filePath: string, options?: any): Promise<void>;
+/**
+ * Imports data from specified file based on extension (Universal dispatcher)
+ *
+ * Universal import function that automatically detects format from filename extension
+ * and delegates to specialized importers (CSV, JSON, Tree, TXT). Simplifies data import
+ * with a single unified API for all formats. Node.js only.
+ *
+ * Automatic format detection:
+ * - **.csv** → importCSV (PapaParse with header detection)
+ * - **.json** → importJSON (native JSON.parse)
+ * - **.tree** → importTree (plain text tree visualization)
+ * - **.txt** → importTxt (plain text with security validations)
+ *
+ * @param filePath - Input file path with extension (determines format)
+ * @param options - Format-specific options (passed to specialized importer)
+ * @returns Promise<ImportData> Imported data (type depends on format)
+ *
+ * @example
+ * ```typescript
+ * // CSV import - Returns array of objects
+ * const users = await importData('./users.csv')
+ * // [
+ * //   { id: '1', name: 'Alice', email: 'alice@example.com' },
+ * //   { id: '2', name: 'Bob', email: 'bob@example.com' }
+ * // ]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // JSON import - Returns original data structure
+ * const config = await importData('./config.json')
+ * console.log(config.server.host)  // 'localhost'
+ * console.log(config.server.port)  // 3000
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Tree import - Returns plain text visualization
+ * const treeText = await importData('./structure.tree')
+ * console.log(treeText)
+ * // └── src
+ * //     ├── index.ts
+ * //     ├── utils.ts
+ * //     └── components
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Text import - Returns file content as string
+ * const log = await importData('./server.log')
+ * const lines = log.split('\n')
+ * const errors = lines.filter(line => line.includes('[ERROR]'))
+ * console.log(`Found ${errors.length} errors`)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Dynamic file processor
+ * async function processFile(filePath: string) {
+ *   const ext = detectFileExtension(filePath)
+ *   console.log(`Processing ${ext} file...`)
+ *
+ *   const data = await importData(filePath)
+ *
+ *   switch (ext) {
+ *     case 'csv':
+ *       return processCSVData(data as any[])
+ *     case 'json':
+ *       return processJSONData(data)
+ *     case 'txt':
+ *       return processTextData(data as string)
+ *     default:
+ *       throw new Error(`Unsupported format: ${ext}`)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Batch file import with error handling
+ * async function importAllFiles(directory: string) {
+ *   const files = await fs.readdir(directory)
+ *   const results = []
+ *
+ *   for (const file of files) {
+ *     const filePath = path.join(directory, file)
+ *     const ext = detectFileExtension(file)
+ *
+ *     // Skip unsupported formats
+ *     if (!['csv', 'json', 'txt', 'tree'].includes(ext || '')) {
+ *       console.log(`⏭️  Skipping unsupported file: ${file}`)
+ *       continue
+ *     }
+ *
+ *     try {
+ *       const data = await importData(filePath)
+ *       results.push({ file, data, success: true })
+ *       console.log(`✅ Imported: ${file}`)
+ *     } catch (error) {
+ *       results.push({ file, error: error.message, success: false })
+ *       console.error(`❌ Failed: ${file} - ${error.message}`)
+ *     }
+ *   }
+ *
+ *   return results
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Import with custom options per format
+ * async function smartImport(filePath: string) {
+ *   const format = detectFormatFromFilename(filePath)
+ *
+ *   let options: any = {}
+ *
+ *   if (format === 'csv') {
+ *     options = { delimiter: ';', header: true }
+ *   } else if (format === 'json') {
+ *     options = { reviver: (key, value) => key === 'date' ? new Date(value) : value }
+ *   } else if (format === 'txt') {
+ *     options = { maxFileSize: 50 * 1024 * 1024, sanitize: true }
+ *   }
+ *
+ *   return await importData(filePath, options)
+ * }
+ * ```
+ *
+ * @throws {DataError} If file extension is not supported
+ * @throws {Error} If file not found or cannot be read
+ * @throws {Error} If file format is invalid
+ * @throws {DataError} If called in Browser environment (use readFileAsText with File object instead)
+ *
+ * @see {@link exportData} for universal export
+ * @see {@link importCSV} for CSV-specific import
+ * @see {@link importJSON} for JSON-specific import
+ * @see {@link importTree} for tree-specific import
+ * @see {@link importTxt} for text-specific import
+ */
+declare function importData(filePath: string, options?: any): Promise<ImportData>;
+
+export { type CSVData, type ExportData, type ExportFormat, type FileFormat, type ImportData, type TreeExportOptions, type TxtExportOptions, type TxtImportOptions, detectFileExtension, detectFormatFromFilename, detectUniversalFormat, exportData, exportTree, exportTxt, importData, importTree, importTxt, readFileAsText, validateCSVData, validateExportData };