@gzl10/ts-helpers 4.2.1

package/dist/types/async-C8gvbSG-.d.ts

@@ -0,0 +1,453 @@
+/**
+ * Asynchronous utilities and operations
+ * Consolidated from core/async module
+ */
+/**
+ * Creates an asynchronous delay for the specified number of milliseconds
+ *
+ * Pauses async execution without blocking the event loop. Uses Promise with setTimeout
+ * internally to schedule resumption after the specified delay.
+ *
+ * Common use cases:
+ * - Rate limiting API calls
+ * - Retry delays with exponential backoff
+ * - Animation/transition timing
+ * - Polling intervals
+ * - Debouncing operations
+ *
+ * @param ms - Milliseconds to sleep (delay duration)
+ * @returns Promise that resolves after the specified delay
+ *
+ * @example
+ * ```typescript
+ * // Basic delay
+ * console.log('Starting...')
+ * await sleep(2000)  // Wait 2 seconds
+ * console.log('Done!')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Rate-limited API calls
+ * async function fetchAllUsers(userIds: string[]): Promise<User[]> {
+ *   const users: User[] = []
+ *
+ *   for (const id of userIds) {
+ *     const user = await api.getUser(id)
+ *     users.push(user)
+ *
+ *     // Rate limit: 100ms between requests (max 10 req/sec)
+ *     await sleep(100)
+ *   }
+ *
+ *   return users
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Exponential backoff retry
+ * async function fetchWithRetry(url: string, maxRetries = 3): Promise<Response> {
+ *   let lastError: Error | null = null
+ *
+ *   for (let attempt = 0; attempt < maxRetries; attempt++) {
+ *     try {
+ *       return await fetch(url)
+ *     } catch (error) {
+ *       lastError = error as Error
+ *       const delay = Math.pow(2, attempt) * 1000  // 1s, 2s, 4s
+ *       console.log(`Retry ${attempt + 1}/${maxRetries} in ${delay}ms`)
+ *       await sleep(delay)
+ *     }
+ *   }
+ *
+ *   throw lastError
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Polling with timeout
+ * async function pollUntilReady(
+ *   checkFn: () => Promise<boolean>,
+ *   timeoutMs = 30000
+ * ): Promise<boolean> {
+ *   const startTime = Date.now()
+ *
+ *   while (Date.now() - startTime < timeoutMs) {
+ *     if (await checkFn()) {
+ *       return true
+ *     }
+ *     await sleep(1000)  // Poll every second
+ *   }
+ *
+ *   throw new Error('Timeout waiting for ready state')
+ * }
+ *
+ * // Usage: Wait for service to be ready
+ * await pollUntilReady(async () => {
+ *   const response = await fetch('/health')
+ *   return response.ok
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Animated progress bar
+ * async function animateProgress(element: HTMLElement): Promise<void> {
+ *   for (let i = 0; i <= 100; i += 5) {
+ *     element.style.width = `${i}%`
+ *     await sleep(50)  // 50ms per step = 1 second total
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link wait} for alias with same functionality
+ * @see {@link runBatch} for controlled concurrent execution
+ */
+declare const sleep: (ms: number) => Promise<void>;
+/**
+ * Simple alias for sleep - Pauses execution for specified milliseconds
+ *
+ * Identical to {@link sleep}, provided for semantic clarity in code.
+ * Use `wait` when the context emphasizes waiting for a condition or event.
+ *
+ * @param ms - Milliseconds to wait
+ * @returns Promise that resolves after the specified delay
+ *
+ * @example
+ * ```typescript
+ * // Semantically clearer in some contexts
+ * await wait(1000)  // Wait 1 second before continuing
+ *
+ * // vs sleep (implies intentional delay)
+ * await sleep(1000)  // Sleep for 1 second
+ * ```
+ *
+ * @see {@link sleep} for full documentation and examples
+ */
+declare const wait: (ms: number) => Promise<void>;
+/**
+ * Executes an array of Promises in batches to control concurrency
+ *
+ * Processes promises in sequential batches, waiting for each batch to complete before
+ * starting the next. Prevents overwhelming systems with too many concurrent requests.
+ *
+ * Algorithm:
+ * 1. Divide promises into batches of size `batchSize`
+ * 2. Execute each batch with Promise.all (parallel within batch)
+ * 3. Wait for batch completion before starting next batch
+ * 4. Collect and return all results in original order
+ *
+ * Use cases:
+ * - Rate-limited API calls (respect API quotas)
+ * - Database bulk operations (avoid connection pool exhaustion)
+ * - File system operations (prevent file descriptor limits)
+ * - Memory-intensive operations (control memory usage)
+ *
+ * @param jobs - Array of Promises to execute
+ * @param batchSize - Number of promises to execute concurrently per batch (default: 50)
+ * @returns Promise resolving to array of all results in original order
+ *
+ * @example
+ * ```typescript
+ * // Basic batch processing
+ * const urls = ['url1', 'url2', ..., 'url100']  // 100 URLs
+ * const fetchPromises = urls.map(url => fetch(url))
+ *
+ * // Execute 10 at a time instead of all 100 simultaneously
+ * const responses = await runBatch(fetchPromises, 10)
+ * // Batch 1: urls 0-9 (parallel)
+ * // Batch 2: urls 10-19 (parallel) - starts after batch 1 completes
+ * // ... 10 batches total
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Bulk user data fetch respecting API rate limits
+ * async function fetchUsersInBatches(userIds: string[]): Promise<User[]> {
+ *   console.log(`Fetching ${userIds.length} users in batches of 20...`)
+ *
+ *   const fetchPromises = userIds.map(id =>
+ *     fetch(`/api/users/${id}`).then(res => res.json())
+ *   )
+ *
+ *   const users = await runBatch(fetchPromises, 20)
+ *
+ *   console.log(`✅ Fetched ${users.length} users`)
+ *   return users
+ * }
+ *
+ * // Fetches 1000 users: 50 batches of 20, not 1000 simultaneous requests
+ * const allUsers = await fetchUsersInBatches(userIdArray)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Database bulk insert with connection pool limits
+ * async function bulkInsertUsers(users: User[]): Promise<void> {
+ *   // Database pool has 10 connections, use batch size of 5 for safety
+ *   const insertPromises = users.map(user =>
+ *     db.query('INSERT INTO users VALUES ($1, $2)', [user.name, user.email])
+ *   )
+ *
+ *   await runBatch(insertPromises, 5)
+ *   console.log(`✅ Inserted ${users.length} users`)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Image processing pipeline
+ * async function processImages(imagePaths: string[]): Promise<Buffer[]> {
+ *   console.log(`Processing ${imagePaths.length} images...`)
+ *
+ *   const processingPromises = imagePaths.map(async path => {
+ *     const img = await loadImage(path)
+ *     const resized = await resize(img, { width: 800, height: 600 })
+ *     const compressed = await compress(resized, { quality: 80 })
+ *     return compressed
+ *   })
+ *
+ *   // Process 3 images at a time to avoid memory exhaustion
+ *   const processed = await runBatch(processingPromises, 3)
+ *
+ *   console.log(`✅ Processed ${processed.length} images`)
+ *   return processed
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Parallel file uploads with progress tracking
+ * async function uploadFilesWithProgress(
+ *   files: File[]
+ * ): Promise<UploadResult[]> {
+ *   let completed = 0
+ *
+ *   const uploadPromises = files.map(async file => {
+ *     const result = await uploadToS3(file)
+ *     completed++
+ *     console.log(`Progress: ${completed}/${files.length} (${((completed/files.length)*100).toFixed(1)}%)`)
+ *     return result
+ *   })
+ *
+ *   // Upload 5 files at a time
+ *   return await runBatch(uploadPromises, 5)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Scraping with politeness delay
+ * async function scrapeWebsites(urls: string[]): Promise<ScrapedData[]> {
+ *   const scrapePromises = urls.map(async url => {
+ *     const html = await fetch(url).then(r => r.text())
+ *     const data = parseHTML(html)
+ *
+ *     // Polite delay between requests in same batch
+ *     await sleep(200)
+ *
+ *     return data
+ *   })
+ *
+ *   // Only 3 concurrent requests to avoid overwhelming target server
+ *   return await runBatch(scrapePromises, 3)
+ * }
+ * ```
+ *
+ * @see {@link sleep} for adding delays between operations
+ * @see {@link handleOperation} for dynamic operation execution
+ */
+declare function runBatch<T>(jobs: Promise<T>[], batchSize?: number): Promise<T[]>;
+/**
+ * Dynamically executes an operation on a target object by name
+ *
+ * Invokes methods on objects using string-based operation names. Supports nested
+ * method access using 'parent/child' slash notation for organized operation namespacing.
+ *
+ * Features:
+ * - Dynamic method invocation by string name
+ * - Nested method access with '/' separator (e.g., 'api/getUser')
+ * - Automatic error handling with descriptive messages
+ * - Type-safe return value with generics
+ *
+ * Use cases:
+ * - Dynamic API route handlers
+ * - Plugin architectures with string-based commands
+ * - RPC (Remote Procedure Call) implementations
+ * - Command pattern implementations
+ * - Configuration-driven operations
+ *
+ * @param target - Object containing methods to execute
+ * @param operation - Method name or 'parent/child' path to execute
+ * @param args - Arguments to pass to the operation
+ * @returns Promise resolving to operation result
+ * @throws {TsHelpersError} If operation doesn't exist on target
+ *
+ * @example
+ * ```typescript
+ * // Basic operation execution
+ * const api = {
+ *   getUser: async (id: string) => ({ id, name: 'John' }),
+ *   createUser: async (data: any) => ({ id: '123', ...data })
+ * }
+ *
+ * const user = await handleOperation<User>(api, 'getUser', 'user-123')
+ * // { id: 'user-123', name: 'John' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Nested operations with slash notation
+ * const service = {
+ *   users: {
+ *     list: async () => [{ id: '1' }, { id: '2' }],
+ *     create: async (data: any) => ({ id: 'new', ...data }),
+ *     delete: async (id: string) => ({ success: true })
+ *   },
+ *   posts: {
+ *     list: async () => [{ id: 'post-1' }],
+ *     create: async (data: any) => ({ id: 'new-post', ...data })
+ *   }
+ * }
+ *
+ * // Execute nested operation
+ * const users = await handleOperation(service, 'users/list')
+ * const newUser = await handleOperation(service, 'users/create', { name: 'Alice' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Dynamic API router
+ * interface ApiRequest {
+ *   operation: string
+ *   params: any[]
+ * }
+ *
+ * const apiHandlers = {
+ *   user: {
+ *     get: async (id: string) => db.users.findById(id),
+ *     create: async (data: UserInput) => db.users.create(data),
+ *     update: async (id: string, data: Partial<UserInput>) =>
+ *       db.users.update(id, data),
+ *     delete: async (id: string) => db.users.delete(id)
+ *   },
+ *   product: {
+ *     search: async (query: string) => db.products.search(query),
+ *     list: async (page: number) => db.products.list(page)
+ *   }
+ * }
+ *
+ * async function handleApiRequest(req: ApiRequest): Promise<any> {
+ *   try {
+ *     return await handleOperation(
+ *       apiHandlers,
+ *       req.operation,
+ *       ...req.params
+ *     )
+ *   } catch (error) {
+ *     console.error(`Failed to execute ${req.operation}:`, error)
+ *     throw error
+ *   }
+ * }
+ *
+ * // Usage
+ * await handleApiRequest({ operation: 'user/get', params: ['user-123'] })
+ * await handleApiRequest({ operation: 'product/search', params: ['laptop'] })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Plugin system with dynamic commands
+ * interface Plugin {
+ *   name: string
+ *   commands: Record<string, (...args: any[]) => Promise<any>>
+ * }
+ *
+ * class PluginManager {
+ *   private plugins: Map<string, Plugin> = new Map()
+ *
+ *   register(plugin: Plugin): void {
+ *     this.plugins.set(plugin.name, plugin)
+ *   }
+ *
+ *   async executeCommand(
+ *     pluginName: string,
+ *     command: string,
+ *     ...args: any[]
+ *   ): Promise<any> {
+ *     const plugin = this.plugins.get(pluginName)
+ *     if (!plugin) throw new Error(`Plugin ${pluginName} not found`)
+ *
+ *     return handleOperation(plugin.commands, command, ...args)
+ *   }
+ * }
+ *
+ * // Register plugins
+ * const manager = new PluginManager()
+ * manager.register({
+ *   name: 'fileOps',
+ *   commands: {
+ *     read: async (path: string) => fs.readFile(path, 'utf-8'),
+ *     write: async (path: string, content: string) =>
+ *       fs.writeFile(path, content)
+ *   }
+ * })
+ *
+ * // Execute plugin commands dynamically
+ * await manager.executeCommand('fileOps', 'read', './config.json')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: RPC-style service calls
+ * const rpcService = {
+ *   math: {
+ *     add: async (a: number, b: number) => a + b,
+ *     multiply: async (a: number, b: number) => a * b
+ *   },
+ *   string: {
+ *     reverse: async (s: string) => s.split('').reverse().join(''),
+ *     uppercase: async (s: string) => s.toUpperCase()
+ *   }
+ * }
+ *
+ * async function rpcCall(method: string, ...params: any[]): Promise<any> {
+ *   console.log(`RPC Call: ${method}(${params.join(', ')})`)
+ *   const result = await handleOperation(rpcService, method, ...params)
+ *   console.log(`RPC Result: ${result}`)
+ *   return result
+ * }
+ *
+ * await rpcCall('math/add', 5, 3)           // RPC Result: 8
+ * await rpcCall('string/reverse', 'hello')  // RPC Result: olleh
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error handling
+ * try {
+ *   await handleOperation(api, 'nonexistent/method')
+ * } catch (error) {
+ *   console.error(error.message)
+ *   // "Operation [nonexistent/method] does not exist"
+ *   console.error(error.code)
+ *   // TsHelpersErrorCode.INVALID_OPERATION
+ * }
+ * ```
+ *
+ * @see {@link TsHelpersError} for error structure
+ * @see {@link TsHelpersErrorCode} for error codes
+ */
+declare function handleOperation<T>(target: Record<string, any>, operation: string, ...args: any[]): Promise<T>;
+
+declare const async_handleOperation: typeof handleOperation;
+declare const async_runBatch: typeof runBatch;
+declare const async_sleep: typeof sleep;
+declare const async_wait: typeof wait;
+declare namespace async {
+  export { async_handleOperation as handleOperation, async_runBatch as runBatch, async_sleep as sleep, async_wait as wait };
+}
+
+export { async as a, handleOperation as h, runBatch as r, sleep as s, wait as w };

package/dist/types/async.d.ts

@@ -0,0 +1 @@
+export { h as handleOperation, r as runBatch, s as sleep, w as wait } from './async-C8gvbSG-.js';

package/dist/types/csv.d.ts

@@ -0,0 +1,226 @@
+/**
+ * CSV Import/Export utilities
+ *
+ * Provides reliable CSV operations for both Node.js and Browser environments using PapaParse.
+ * Features:
+ * - UTF-8 BOM encoding for Excel compatibility
+ * - Semicolon delimiter by default (European standard)
+ * - Automatic header detection
+ * - Dual-mode: filesystem (Node.js) vs download trigger (Browser)
+ *
+ * @module csv
+ */
+/**
+ * Exports data as CSV file with UTF-8 BOM encoding
+ *
+ * Works in both Node.js (writes to filesystem) and Browser (triggers download).
+ * Uses PapaParse library for reliable CSV generation with proper escaping and formatting.
+ *
+ * Features:
+ * - UTF-8 BOM prepended (\\ufeff) for Excel compatibility
+ * - Semicolon delimiter by default (European/Spanish standard)
+ * - Automatic header row from object keys
+ * - Custom delimiters and options via PapaParse config
+ *
+ * Environment behavior:
+ * - **Node.js**: Writes file to filesystem at specified path
+ * - **Browser**: Triggers automatic download with filename extracted from path
+ *
+ * @param data - Array of objects or array of arrays to export as CSV
+ * @param filePath - File path (Node.js) or download filename (Browser)
+ * @param options - PapaParse unparse options (optional)
+ * @param options.delimiter - Column separator (default: ';' semicolon)
+ * @param options.header - Include header row (default: true)
+ * @param options.quotes - Quote all fields (default: false)
+ * @param options.newline - Line ending (default: '\\r\\n')
+ * @returns Promise that resolves when export completes
+ *
+ * @example
+ * ```typescript
+ * // Basic export - Array of objects
+ * const users = [
+ *   { name: 'Alice', age: 30, city: 'Madrid' },
+ *   { name: 'Bob', age: 25, city: 'Barcelona' },
+ *   { name: 'Carlos', age: 35, city: 'Valencia' }
+ * ]
+ *
+ * // Node.js - Write to file
+ * await exportCSV(users, './reports/users.csv')
+ * // Creates: ./reports/users.csv with BOM and semicolon delimiter
+ *
+ * // Browser - Trigger download
+ * await exportCSV(users, 'users.csv')
+ * // Downloads: users.csv to browser's download folder
+ *
+ * // Custom delimiter (comma for international)
+ * await exportCSV(users, 'users_intl.csv', { delimiter: ',' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Array of arrays (no header auto-detection)
+ * const matrix = [
+ *   ['Name', 'Age', 'City'],       // Header row
+ *   ['Alice', 30, 'Madrid'],
+ *   ['Bob', 25, 'Barcelona']
+ * ]
+ * await exportCSV(matrix, 'matrix.csv')
+ *
+ * // Without header row
+ * const data = [['A1', 'B1'], ['A2', 'B2']]
+ * await exportCSV(data, 'no_header.csv', { header: false })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Export sales report
+ * async function exportSalesReport(sales: Sale[]) {
+ *   const reportData = sales.map(sale => ({
+ *     Fecha: formatDate(sale.date),
+ *     Cliente: sale.customerName,
+ *     Producto: sale.productName,
+ *     Cantidad: sale.quantity,
+ *     Total: `${sale.total.toFixed(2)}€`
+ *   }))
+ *
+ *   const filename = `ventas_${new Date().toISOString().split('T')[0]}.csv`
+ *   await exportCSV(reportData, filename)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom PapaParse options
+ * await exportCSV(data, 'quotes.csv', {
+ *   delimiter: ',',
+ *   quotes: true,        // Quote all fields
+ *   quoteChar: '"',
+ *   escapeChar: '"',
+ *   newline: '\\n'       // Unix line endings
+ * })
+ * ```
+ *
+ * @throws {Error} If file write fails in Node.js
+ * @see {@link importCSV} for importing CSV files
+ * @see {@link https://www.papaparse.com/docs#unparse PapaParse Unparse Documentation}
+ */
+declare function exportCSV(data: any[], filePath: string, options?: any): Promise<void>;
+/**
+ * Imports CSV file and parses it to array of objects
+ *
+ * Reads CSV file from filesystem (Node.js only) and parses using PapaParse.
+ * Automatically detects headers and converts rows to objects.
+ *
+ * Features:
+ * - Automatic header detection from first row
+ * - Semicolon delimiter by default (European standard)
+ * - Empty line skipping
+ * - Type inference for numbers and booleans
+ * - UTF-8 BOM handling
+ *
+ * ⚠️ BROWSER LIMITATION: File reading from filesystem is not supported in browsers
+ * for security reasons. For browser file uploads, use `readFileAsText()` with a File object
+ * obtained from an input[type="file"] element.
+ *
+ * @param filePath - Path to CSV file (Node.js only)
+ * @param options - PapaParse parse options (optional)
+ * @param options.delimiter - Column separator (default: ';' semicolon)
+ * @param options.header - Parse first row as headers (default: true)
+ * @param options.skipEmptyLines - Skip empty rows (default: true)
+ * @param options.dynamicTyping - Convert numeric/boolean values (default: false)
+ * @returns Promise<Array<Object>> Array of objects with keys from header row
+ *
+ * @example
+ * ```typescript
+ * // Basic import - Node.js only
+ * const users = await importCSV('./data/users.csv')
+ * // Returns: [
+ * //   { name: 'Alice', age: '30', city: 'Madrid' },
+ * //   { name: 'Bob', age: '25', city: 'Barcelona' }
+ * // ]
+ *
+ * // Custom delimiter (comma)
+ * const intlData = await importCSV('./data/users_intl.csv', {
+ *   delimiter: ','
+ * })
+ *
+ * // With type conversion
+ * const typed = await importCSV('./data/sales.csv', {
+ *   dynamicTyping: true  // Converts '123' → 123, 'true' → true
+ * })
+ * // Returns: { quantity: 10, total: 299.99, active: true }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Import and process sales data
+ * async function importSalesReport(filePath: string) {
+ *   try {
+ *     const sales = await importCSV(filePath, {
+ *       delimiter: ';',
+ *       dynamicTyping: true,
+ *       skipEmptyLines: true
+ *     })
+ *
+ *     // Process imported data
+ *     const totalSales = sales.reduce((sum, sale) =>
+ *       sum + (sale.total || 0), 0
+ *     )
+ *
+ *     console.log(`Imported ${sales.length} sales, total: €${totalSales}`)
+ *     return sales
+ *   } catch (error) {
+ *     console.error('Failed to import CSV:', error)
+ *     throw error
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Browser alternative using File API
+ * // HTML: <input type="file" id="csvFile" accept=".csv">
+ *
+ * document.getElementById('csvFile').addEventListener('change', async (e) => {
+ *   const file = e.target.files[0]
+ *
+ *   // Read file content
+ *   const content = await readFileAsText(file)
+ *
+ *   // Parse with PapaParse
+ *   const parsed = Papa.parse(content, {
+ *     header: true,
+ *     delimiter: ';',
+ *     skipEmptyLines: true
+ *   })
+ *
+ *   const data = parsed.data
+ *   console.log('Imported data:', data)
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle parsing errors
+ * const result = await importCSV('./malformed.csv')
+ *   .catch(error => {
+ *     if (error.message.includes('not supported in browser')) {
+ *       console.error('Use File API for browser uploads')
+ *     } else if (error.code === 'ENOENT') {
+ *       console.error('File not found')
+ *     } else {
+ *       console.error('CSV parsing failed:', error)
+ *     }
+ *     return []  // Return empty array as fallback
+ *   })
+ * ```
+ *
+ * @throws {Error} 'CSV import not supported in browser' when called in browser environment
+ * @throws {Error} File system errors (ENOENT, EACCES, etc.) in Node.js
+ * @see {@link exportCSV} for exporting CSV files
+ * @see {@link readFileAsText} for browser file reading
+ * @see {@link https://www.papaparse.com/docs#parse PapaParse Parse Documentation}
+ */
+declare function importCSV(filePath: string, options?: any): Promise<any[]>;
+
+export { exportCSV, importCSV };