@gzl10/ts-helpers 4.2.1

package/USAGE-GUIDE.md

@@ -0,0 +1,800 @@
+# @g10/ts-helpers v4.1.x - Guía Técnica Completa
+
+🚀 **v4.1.0** - Nuevas funciones para manejo de configuración, parsing de env
+vars y manipulación de objetos anidados.
+
+## 📦 Instalación y Configuración
+
+```bash
+# Instalación
+pnpm add @g10/ts-helpers  # Recomendado
+npm install @g10/ts-helpers
+
+# Requisitos
+Node.js >=18.0.0
+TypeScript >=5.0.0
+pnpm >=8.0.0 (recomendado)
+```
+
+## 🎯 Patrones de Uso v4.0.0
+
+### 1. API Plana (Recomendado - 150+ funciones)
+
+```typescript
+import g from '@g10/ts-helpers'
+
+// 🔐 Validación Española (30+ funciones)
+g.validateNIF('12345678Z') // Validador NIF
+g.validateNIE('X0000000T') // Validador NIE
+g.validateCIF('A12345674') // Validador CIF
+g.isValidSpanishIBAN('ES...') // IBAN español
+g.isValidSpanishPhone('+34612345678') // Teléfono móvil
+g.isValidSpanishPostalCode('28001') // Código postal
+
+// 🔧 Generadores Españoles (15+ funciones)
+g.generateSpanishNIF() // '12345678Z'
+g.generateSpanishNIE() // 'X1234567L'
+g.generateSpanishCIF() // 'A12345674'
+g.generateSpanishIBAN() // 'ES9121000418450200051332'
+g.generateSpanishPostalCode() // '28001'
+g.generatePassword({ length: 12 }) // Contraseña segura
+
+// 📝 String Manipulation (25+ funciones)
+g.toCamelCase('hello-world') // 'helloWorld'
+g.toKebabCase('HelloWorld') // 'hello-world'
+g.toSnakeCase('HelloWorld') // 'hello_world'
+g.toPascalCase('hello-world') // 'HelloWorld'
+g.capitalizeFirst('hello') // 'Hello'
+g.sanitizeString('<script>alert</script>') // ''
+g.removeAccents('café') // 'cafe'
+g.truncateString('long text', 10) // 'long te...'
+
+// 🗂️ Objects & Arrays (20+ funciones)
+g.deepEqual(obj1, obj2) // Comparación profunda
+g.setDeepValue(config, 'database.host', 'localhost') // 🆕 v4.1.0
+g.getDeepValue(config, 'database.port', 5432) // 🆕 v4.1.0
+g.updateArrayElementsBy(array, criteria, updates)
+g.deleteArrayElementsBy(array, criteria)
+g.getShallowProperties(obj) // Solo propiedades primitivas
+g.calculateDifferences(oldObj, newObj)
+g.generateCrcHash(data) // Hash CRC32
+
+// 📅 Fechas con dayjs (25+ funciones)
+g.formatNow('DD/MM/YYYY') // '15/01/2025'
+g.format(date, 'DD/MM/YYYY HH:mm') // Formato personalizado
+g.addDays(date, 7) // Añadir días
+g.diffDays(date1, date2) // Diferencia en días
+g.diffBusinessDays(date1, date2) // Días laborables
+g.isWeekday(date) // true si es día laborable
+g.fromNow(date) // 'hace 2 horas'
+
+// 🔢 Math & Statistics (30+ funciones)
+g.calculateMedian([1, 2, 3, 4, 5]) // 3
+g.calculateMode([1, 1, 2, 3]) // [1]
+g.calculateStandardDeviation(data) // Desviación estándar
+g.calculatePercentile(data, 95) // Percentil 95
+g.calculateNPV([-1000, 300, 400], 0.1) // NPV financiero
+g.calculateIRR(cashFlows) // Tasa interna retorno
+g.simpleKMeans(points, 3) // Clustering K-means
+
+// ⏱️ Async Operations (5+ funciones)
+await g.sleep(1000) // Pausa 1 segundo
+await g.wait(1000) // Alias de sleep
+await g.runBatch(promises, 5) // Ejecuta en lotes de 5
+
+// 📊 Data Import/Export (17+ funciones)
+await g.exportData(data, 'file.csv') // Auto-detecta formato
+await g.exportData(data, 'file.json')
+await g.importData('file.xlsx') // Importa automáticamente
+g.detectFormatFromFilename('file.csv') // 'csv'
+
+// 📁 Detección Universal de Formatos (80+ tipos)
+g.detectFileExtension('report.xlsx') // 'xlsx'
+g.detectFileExtension('presentation.pptx') // 'pptx'
+g.detectUniversalFormat('document.pdf')
+// { extension: 'pdf', category: 'document', mimeType: 'application/pdf', isText: false, isBinary: true }
+
+// 🌍 Environment Detection (15+ funciones)
+g.isNode // true en Node.js
+g.isBrowser // true en browser
+g.isDevelopment() // true en desarrollo
+g.isDevelopment(req) // Con soporte Express
+g.isProduction() // true en producción
+g.parseEnvValue('true') // true (boolean) 🆕 v4.1.0
+g.parseEnvValue('[1,2,3]') // [1,2,3] (array) 🆕 v4.1.0
+g.parseEnvValue('{"key":"val"}') // {key: 'val'} 🆕 v4.1.0
+g.detectProtocol(req) // 'https' con headers proxy
+g.detectHostname(req) // Hostname con X-Forwarded-Host
+g.isLocalhost('localhost') // true
+g.isPrivateIP('192.168.1.1') // true
+
+// ⚙️ Path & Config Utilities (5+ funciones) 🆕 v4.1.0
+g.matchPathPattern('features.auth', 'features.*') // true
+g.matchPathPattern('features.auth.enabled', 'features.*.enabled') // true
+g.isValidDotNotationPath('database.host') // true
+g.isValidDotNotationPath('.invalid') // false
+g.envKeyToPath('NX_FEATURES_AUTH') // 'features.auth'
+g.pathToEnvKey('features.auth', 'APP') // 'APP_FEATURES_AUTH'
+g.getEnvironmentInfo(req) // Info completa con criterios
+```
+
+### 2. Importaciones Específicas (Tree-shaking)
+
+```typescript
+// Módulos específicos para bundles mínimos
+import {
+  validateNIF,
+  generateSpanishNIF,
+  isValidCIF,
+} from '@g10/ts-helpers/validation'
+import {
+  toCamelCase,
+  sanitizeString,
+  removeAccents,
+} from '@g10/ts-helpers/strings'
+import { deepEqual, updateArrayElementsBy } from '@g10/ts-helpers/objects'
+import { formatNow, addDays, diffDays } from '@g10/ts-helpers/dates'
+import { calculateNPV, calculateMedian } from '@g10/ts-helpers/math'
+import { sleep, runBatch } from '@g10/ts-helpers/async'
+import { exportData, importData } from '@g10/ts-helpers/data'
+import {
+  isDevelopment,
+  detectProtocol,
+  getEnvironmentInfo,
+  parseEnvValue, // 🆕 v4.1.0
+} from '@g10/ts-helpers/environment'
+import {
+  setDeepValue, // 🆕 v4.1.0
+  getDeepValue, // 🆕 v4.1.0
+  deepEqual,
+  updateArrayElementsBy,
+} from '@g10/ts-helpers/objects'
+import {
+  matchPathPattern, // 🆕 v4.1.0
+  envKeyToPath, // 🆕 v4.1.0
+  pathToEnvKey, // 🆕 v4.1.0
+  toCamelCase,
+  sanitizeString,
+} from '@g10/ts-helpers/strings'
+import {
+  isValidDotNotationPath, // 🆕 v4.1.0
+  validateNIF,
+} from '@g10/ts-helpers/validation'
+```
+
+## 🆕 Novedades v4.1.0: Casos de Uso Prácticos
+
+### Caso 1: Configuración desde Variables de Entorno
+
+```typescript
+import g from '@g10/ts-helpers'
+
+// Parsing automático de env vars a tipos nativos
+const config = {
+  debug: g.parseEnvValue(process.env.DEBUG), // 'true' → true
+  port: g.parseEnvValue(process.env.PORT), // '3000' → 3000
+  features: g.parseEnvValue(process.env.FEATURES), // 'auth,api' → ['auth','api']
+  database: g.parseEnvValue(process.env.DB_CONFIG), // '{"host":"localhost"}' → object
+}
+
+// Construir config anidada desde env vars planas
+const appConfig = {}
+Object.entries(process.env).forEach(([key, value]) => {
+  if (key.startsWith('APP_')) {
+    const path = g.envKeyToPath(key, 'APP') // 'APP_DATABASE_HOST' → 'database.host'
+    g.setDeepValue(appConfig, path, g.parseEnvValue(value))
+  }
+})
+// Resultado: { database: { host: 'localhost', port: 5432 }, cache: { ttl: 3600 } }
+```
+
+### Caso 2: Sistema de Permisos con Wildcards
+
+```typescript
+import g from '@g10/ts-helpers'
+
+const userPermissions = [
+  'admin.users.read',
+  'admin.users.write',
+  'reports.view',
+]
+
+// Verificar permisos con patrones
+function hasPermission(requiredPermission: string): boolean {
+  return userPermissions.some(perm =>
+    g.matchPathPattern(perm, requiredPermission)
+  )
+}
+
+hasPermission('admin.users.*') // true (tiene read y write)
+hasPermission('admin.*.write') // true (tiene admin.users.write)
+hasPermission('admin.products.*') // false (no tiene permisos de productos)
+
+// Feature flags con wildcards
+const enabledFeatures = [
+  'features.auth.oauth',
+  'features.auth.saml',
+  'features.payments.stripe',
+]
+
+const hasAuthFeature = enabledFeatures.some(f =>
+  g.matchPathPattern(f, 'features.auth.*')
+)
+// true
+```
+
+### Caso 3: Configuración Dinámica con Validación
+
+```typescript
+import g from '@g10/ts-helpers'
+
+class ConfigManager {
+  private config: Record<string, any> = {}
+
+  set(path: string, value: any): void {
+    // Validar path antes de establecer
+    if (!g.isValidDotNotationPath(path)) {
+      throw new Error(`Invalid config path: ${path}`)
+    }
+    g.setDeepValue(this.config, path, value)
+  }
+
+  get<T = any>(path: string, defaultValue?: T): T | undefined {
+    if (!g.isValidDotNotationPath(path)) {
+      throw new Error(`Invalid config path: ${path}`)
+    }
+    return g.getDeepValue(this.config, path, defaultValue)
+  }
+}
+
+const config = new ConfigManager()
+config.set('database.host', 'localhost')
+config.set('database.port', 5432)
+config.get('database.host') // 'localhost'
+config.get('database.timeout', 5000) // 5000 (default)
+config.set('.invalid', 'value') // throws Error
+```
+
+### Caso 4: Generación de .env desde Configuración
+
+```typescript
+import g from '@g10/ts-helpers'
+
+const config = {
+  database: { host: 'localhost', port: 5432 },
+  cache: { ttl: 3600, enabled: true },
+  features: { auth: true, payments: false },
+}
+
+function generateEnvFile(obj: any, prefix = 'APP', currentPath = ''): string[] {
+  const lines: string[] = []
+
+  for (const [key, value] of Object.entries(obj)) {
+    const path = currentPath ? `${currentPath}.${key}` : key
+
+    if (typeof value === 'object' && !Array.isArray(value)) {
+      // Recursivo para objetos anidados
+      lines.push(...generateEnvFile(value, prefix, path))
+    } else {
+      const envKey = g.pathToEnvKey(path, prefix)
+      const envValue = Array.isArray(value)
+        ? JSON.stringify(value)
+        : String(value)
+      lines.push(`${envKey}=${envValue}`)
+    }
+  }
+
+  return lines
+}
+
+const envFile = generateEnvFile(config).join('\n')
+console.log(envFile)
+// APP_DATABASE_HOST=localhost
+// APP_DATABASE_PORT=5432
+// APP_CACHE_TTL=3600
+// APP_CACHE_ENABLED=true
+// APP_FEATURES_AUTH=true
+// APP_FEATURES_PAYMENTS=false
+```
+
+## 📋 Catálogo Completo de Funciones
+
+### 🔐 Validation Module (validation.ts)
+
+**Validadores Españoles:**
+
+- `validateNIF(nif)` - Valida NIF español
+- `validateNIE(nie)` - Valida NIE español
+- `validateCIF(cif)` - Valida CIF español
+- `isValidSpanishIBAN(iban)` - IBAN español
+- `isValidSpanishPhone(phone)` - Teléfono español
+- `isValidSpanishPostalCode(code)` - Código postal
+
+**Validadores Generales:**
+
+- `isValidEmail(email)` - Email válido
+- `isValidURL(url)` - URL válida (incluye localhost)
+- `isValidJSON(str)` - JSON válido
+- `isValidBase64(str)` - Base64 válido
+- `isValidJWTFormat(token)` - Formato JWT
+- `validatePassword(password, options)` - Contraseña segura
+
+**Generadores:**
+
+- `generateSpanishNIF()` - NIF aleatorio válido
+- `generateSpanishNIE()` - NIE aleatorio válido
+- `generateSpanishCIF()` - CIF aleatorio válido
+- `generateSpanishIBAN()` - IBAN español válido
+- `generateSpanishPostalCode()` - Código postal español
+- `generatePassword(options)` - Contraseña segura
+- `generateSecureToken(length)` - Token criptográfico
+- `generateNonce(length)` - Nonce único
+
+### 📝 Strings Module (strings.ts)
+
+**Transformaciones de Caso:**
+
+- `toCamelCase(str)` - camelCase
+- `toKebabCase(str)` - kebab-case
+- `toSnakeCase(str)` - snake_case
+- `toPascalCase(str)` - PascalCase
+- `toLowerCase(str)` - minúsculas
+- `toUpperCase(str)` - MAYÚSCULAS
+
+**Capitalización:**
+
+- `capitalizeFirst(str)` - Primera letra mayúscula
+- `capitalizeEachWord(str)` - Cada palabra capitalizada
+
+**Seguridad:**
+
+- `sanitizeString(str)` - Elimina caracteres peligrosos
+- `sanitizeHtml(html)` - Sanitiza HTML
+- `escapeHtmlChars(str)` - Escapa caracteres HTML
+- `unescapeHtmlChars(str)` - Desescapa HTML
+- `removeDangerousChars(str)` - Elimina caracteres peligrosos
+- `escapeShellCommand(cmd)` - Escapa comandos shell
+
+**Manipulación:**
+
+- `removeAccents(str)` - Elimina acentos y tildes
+- `truncateString(str, length)` - Trunca con '...'
+- `padStart(str, length, char)` - Rellena al inicio
+- `padEnd(str, length, char)` - Rellena al final
+- `repeatString(str, times)` - Repite string
+- `reverseString(str)` - Invierte string
+- `trim/trimStart/trimEnd(str)` - Elimina espacios
+
+### 🗂️ Objects Module (objects.ts)
+
+**Comparación:**
+
+- `deepEqual(obj1, obj2)` - Comparación profunda
+- `comparator(obj1, obj2, options)` - Comparador personalizable
+- `hasSameType(obj1, obj2)` - Mismo tipo incluyendo typed arrays
+
+**Manipulación de Arrays:**
+
+- `updateArrayElementsBy(array, criteria, updates)` - Actualiza elementos
+- `updateArrayElementById(array, id, updates)` - Actualiza por ID
+- `deleteArrayElementsBy(array, criteria)` - Elimina elementos
+
+**Análisis de Objetos:**
+
+- `getShallowProperties(obj)` - Solo propiedades primitivas
+- `calculateDifferences(oldObj, newObj, tolerance)` - Diferencias con tolerancia
+- `formatToReadableString(obj)` - String legible del objeto
+
+**Hash y Utilidades:**
+
+- `generateCrcHash(data)` - Hash CRC32 de datos
+- `hashString(str)` - Hash simple de string
+
+### 📅 Dates Module (dates.ts)
+
+**Formato:**
+
+- `formatNow(format)` - Fecha actual formateada
+- `format(date, format)` - Formato personalizado
+- `toISO(date)` - Formato ISO
+- `fromNow(date)` - Tiempo relativo ('hace 2 horas')
+
+**Manipulación:**
+
+- `addDays/addMonths/addYears(date, amount)` - Añadir tiempo
+- `addNowDays/addNowMonths/addNowYears(amount)` - Añadir a fecha actual
+
+**Cálculos:**
+
+- `diffDays/diffMonths/diffYears(date1, date2)` - Diferencias
+- `diffBusinessDays(date1, date2)` - Días laborables
+- `diffMilliseconds(date1, date2)` - Diferencia en ms
+
+**Utilidades:**
+
+- `isWeekday(date)` - Es día laborable
+- `dayOfWeek(date)` - Día de la semana
+- `weekOfYear(date)` - Semana del año
+- `getFirstDayOfYear/getLastDayOfYear(year)` - Primer/último día
+
+### 🔢 Math Module (math.ts)
+
+**Estadísticas Básicas:**
+
+- `calculateMedian(numbers)` - Mediana
+- `calculateMode(numbers)` - Moda (valores más frecuentes)
+- `calculateStandardDeviation(numbers)` - Desviación estándar
+- `calculateVariance(numbers)` - Varianza
+- `calculatePercentile(numbers, percentile)` - Percentil específico
+
+**Estadísticas Avanzadas:**
+
+- `calculateQuartiles(numbers)` - Q1, Q2, Q3
+- `calculateIQR(numbers)` - Rango intercuartílico
+- `detectOutliers(numbers, multiplier)` - Detección de outliers
+- `calculateCorrelation(x, y)` - Correlación de Pearson
+
+**Finanzas:**
+
+- `calculateNPV(cashFlows, discountRate)` - Valor presente neto
+- `calculateIRR(cashFlows)` - Tasa interna de retorno
+- `calculateFutureValue(pv, rate, periods)` - Valor futuro
+- `calculatePresentValue(fv, rate, periods)` - Valor presente
+- `calculateAnnuityPayment(pv, rate, periods)` - Pago de anualidad
+
+**Machine Learning:**
+
+- `simpleKMeans(points, k, maxIterations)` - Clustering K-means
+- `calculateEuclideanDistance(point1, point2)` - Distancia euclidiana
+- `calculateManhattanDistance(point1, point2)` - Distancia Manhattan
+
+### ⏱️ Async Module (async.ts)
+
+- `sleep(ms)` - Pausa asíncrona
+- `wait(ms)` - Alias de sleep
+- `runBatch(promises, batchSize)` - Ejecuta promesas en lotes
+- `handleOperation(operation, options)` - Manejo con retry
+
+### 📊 Data Module (data.ts)
+
+**Detección de Formato:**
+
+- `detectFormatFromFilename(filename)` - Auto-detecta por extensión
+
+**Export/Import:**
+
+- `exportData(data, filename)` - Exporta con auto-detección
+- `importData(filename)` - Importa con auto-detección
+- `exportTree(data, filename)` - Exporta estructura de árbol
+- `importTree(filename)` - Importa estructura de árbol
+- `exportTxt(data, filename, options)` - Exporta como texto
+- `importTxt(filename, options)` - Importa texto con validación
+
+**Validación:**
+
+- `validateExportData(data)` - Valida datos para export
+- `validateCSVData(data)` - Alias para validación CSV
+
+### 🌍 Environment Module (environment.ts)
+
+**Detección de Plataforma:**
+
+- `isNodeEnvironment()` - Detecta runtime Node.js
+- `isBrowserEnvironment()` - Detecta runtime browser
+- `isNode` - Alias para isNodeEnvironment
+- `isBrowser` - Alias para isBrowserEnvironment
+
+**Detección de Entorno:**
+
+- `isDevelopment(req?)` - Detecta desarrollo (NODE_ENV, puertos, localhost)
+- `isProduction()` - Detecta producción
+- `getEnvironmentInfo(req?)` - Info completa con criterios debugging
+
+**Detección de Red:**
+
+- `detectProtocol(req?)` - Protocolo HTTP/HTTPS con soporte proxy
+- `detectHostname(req?)` - Hostname con headers X-Forwarded-Host
+- `isLocalhost(hostname)` - Es localhost o .local/.localhost
+- `isPrivateIP(hostname)` - Es IP privada (RFC 1918) o IPv6 local
+
+## 🔄 Migración Detallada desde v3.x
+
+### Cambios en la API
+
+```typescript
+// ❌ v3.x - Estructura anidada redundante
+import g from '@g10/ts-helpers'
+
+// Validación
+g.validation.validators.validateNIF('12345678Z')
+g.validation.generators.generateSpanishNIF()
+
+// Strings
+g.primitives.string.toCamelCase('hello-world')
+g.primitives.string.capitalizeFirst('hello')
+
+// Objetos
+g.primitives.object.deepEqual(obj1, obj2)
+g.primitives.array.updateArrayElementsBy(array, criteria, updates)
+
+// Async
+g.core.async.sleep(1000)
+g.core.async.runBatch(promises, 5)
+
+// Data
+g.data.exportData(data, 'file.csv')
+g.data.importData('file.json')
+```
+
+```typescript
+// ✅ v4.0.0 - API completamente plana
+import g from '@g10/ts-helpers'
+
+// Validación - acceso directo
+g.validateNIF('12345678Z')
+g.generateSpanishNIF()
+
+// Strings - acceso directo
+g.toCamelCase('hello-world')
+g.capitalizeFirst('hello')
+
+// Objetos - acceso directo
+g.deepEqual(obj1, obj2)
+g.updateArrayElementsBy(array, criteria, updates)
+
+// Async - acceso directo
+g.sleep(1000)
+g.runBatch(promises, 5)
+
+// Data - acceso directo
+g.exportData(data, 'file.csv')
+g.importData('file.json')
+
+// Environment - acceso directo
+g.isDevelopment()
+g.detectProtocol(req)
+g.getEnvironmentInfo(req)
+```
+
+### Re-exportaciones Eliminadas
+
+```typescript
+// ❌ v3.x - Re-exportaciones incluidas
+import g from '@g10/ts-helpers'
+g.lodash.isNull(value)        // Eliminado
+g.axios.get('/api/data')      // Eliminado
+g.dayjs().format('DD/MM/YYYY') // Eliminado
+g.numeral(1234).format('0,0') // Eliminado
+
+// ✅ v4.0.0 - Instalar dependencias por separado
+npm install lodash axios dayjs numeral
+
+import _ from 'lodash'
+import axios from 'axios'
+import dayjs from 'dayjs'
+import numeral from 'numeral'
+
+_.isNull(value)
+axios.get('/api/data')
+dayjs().format('DD/MM/YYYY')
+numeral(1234).format('0,0')
+
+// O usar implementaciones nativas de @g10/ts-helpers
+import g from '@g10/ts-helpers'
+g.formatNow('DD/MM/YYYY')     // Reemplazo nativo para dayjs
+g.deepEqual(obj1, obj2)       // Reemplazo nativo para lodash
+```
+
+## ⚡ Optimización de Bundle
+
+### Tree-shaking Efectivo
+
+```typescript
+// Bundle mínimo - solo importa funciones específicas
+import { validateNIF, isValidEmail } from '@g10/ts-helpers/validation'
+import { toCamelCase } from '@g10/ts-helpers/strings'
+import { sleep } from '@g10/ts-helpers/async'
+
+// Resultado: ~5KB vs ~185KB completo
+```
+
+### Comparación de Tamaños
+
+```
+v3.x: 603KB (con re-exportaciones)
+v4.0.0: 185KB (-69% reducción)
+Tree-shaking específico: ~5-20KB según funciones usadas
+```
+
+## 🧪 Testing y Calidad
+
+La librería incluye **270 tests** que cubren todas las funciones:
+
+```bash
+pnpm test                 # Ejecuta todos los tests
+pnpm test:watch          # Modo watch
+pnpm test:coverage       # Cobertura de código
+```
+
+**Cobertura actual: 100% de funciones principales**
+
+## 🔧 Configuración de Desarrollo
+
+```bash
+# Instalación para desarrollo
+git clone https://gitlab.gzl10.com/g10libs/ts-helpers.git
+cd ts-helpers
+pnpm install
+
+# Comandos disponibles
+pnpm run build          # Build completo (~40ms)
+pnpm run typecheck       # Verificación TypeScript
+pnpm run lint           # ESLint con auto-fix
+pnpm run format         # Prettier con auto-fix
+pnpm run quality        # Todo junto (sin tests)
+
+# Gestión de versiones con Changeset
+pnpm release:prepare    # Crear changeset
+pnpm release:version    # Actualizar versión y CHANGELOG
+pnpm release:publish    # Publicar a npm
+```
+
+## 📁 Universal Format Detection
+
+### Detección Simple de Extensiones
+
+```typescript
+import g from '@g10/ts-helpers'
+
+// Extrae solo la extensión del archivo
+g.detectFileExtension('report.xlsx') // 'xlsx'
+g.detectFileExtension('image.png') // 'png'
+g.detectFileExtension('archive.tar.gz') // 'gz' (última extensión)
+g.detectFileExtension('filename') // null (sin extensión)
+```
+
+### Detección Inteligente con Categorización
+
+```typescript
+// Análisis completo con 80+ formatos soportados
+const analysis = g.detectUniversalFormat('presentation.pptx')
+// {
+//   extension: 'pptx',
+//   category: 'presentation',
+//   mimeType: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+//   isText: false,
+//   isBinary: true
+// }
+
+// Microsoft Office
+g.detectUniversalFormat('report.xlsx') // { category: 'spreadsheet' }
+g.detectUniversalFormat('document.docx') // { category: 'document' }
+g.detectUniversalFormat('slides.pptx') // { category: 'presentation' }
+
+// Programación
+g.detectUniversalFormat('app.ts') // { category: 'code', isText: true }
+g.detectUniversalFormat('script.py') // { category: 'code', isText: true }
+g.detectUniversalFormat('Main.java') // { category: 'code', isText: true }
+
+// Media
+g.detectUniversalFormat('video.mp4') // { category: 'video', isBinary: true }
+g.detectUniversalFormat('song.mp3') // { category: 'audio', isBinary: true }
+g.detectUniversalFormat('photo.jpg') // { category: 'image', isBinary: true }
+
+// Archivos
+g.detectUniversalFormat('backup.zip') // { category: 'archive' }
+g.detectUniversalFormat('package.7z') // { category: 'archive' }
+
+// Fuentes
+g.detectUniversalFormat('font.ttf') // { category: 'font' }
+g.detectUniversalFormat('webfont.woff2') // { category: 'font' }
+```
+
+### Formatos Soportados (80+)
+
+#### Microsoft Office
+
+- **Documentos**: doc, docx, odt (LibreOffice)
+- **Hojas de cálculo**: xls, xlsx, ods
+- **Presentaciones**: ppt, pptx, odp
+
+#### Programación
+
+- **JavaScript/TypeScript**: js, mjs, jsx, ts, tsx
+- **Backend**: py, java, php, rb, go, rs, c, cpp, cs
+- **Shell**: sh, bash, ps1
+
+#### Web Development
+
+- **Estilos**: css, scss, sass, less
+- **Markup**: html, htm, xml, svg
+
+#### Media
+
+- **Imágenes**: jpg, jpeg, png, gif, svg, webp, avif, bmp, tiff, ico, psd
+- **Audio**: mp3, wav, flac, ogg, aac, m4a, wma
+- **Video**: mp4, avi, mov, wmv, flv, webm, mkv, 3gp
+
+#### Archivos y Configuración
+
+- **Archivos**: zip, rar, 7z, tar, gz, bz2, xz
+- **Configuración**: ini, cfg, conf, toml, env, yaml, yml
+- **Fuentes**: ttf, otf, woff, woff2, eot
+
+#### Datos
+
+- **Estructurados**: json, csv, xml, yaml, sql
+- **Base de datos**: db, sqlite
+- **Documentos**: pdf, epub, mobi, rtf
+
+### Casos de Uso
+
+```typescript
+// Validación de uploads
+const uploadValidator = (filename: string) => {
+  const format = g.detectUniversalFormat(filename)
+
+  if (format.category === 'image' && format.extension !== 'svg') {
+    return { allowed: true, type: 'image' }
+  }
+
+  if (format.category === 'document') {
+    return { allowed: true, type: 'document' }
+  }
+
+  return { allowed: false, reason: 'Formato no permitido' }
+}
+
+// Content-Type automático
+const getContentType = (filename: string) => {
+  const format = g.detectUniversalFormat(filename)
+  return format.mimeType || 'application/octet-stream'
+}
+
+// Procesamiento condicional
+const processFile = (filename: string, content: string | Buffer) => {
+  const format = g.detectUniversalFormat(filename)
+
+  if (format.isText) {
+    return content.toString('utf-8') // Procesar como texto
+  } else {
+    return content // Mantener como binario
+  }
+}
+```
+
+## 📈 Performance
+
+### Build Performance
+
+```
+TypeScript Compiler: ~45s
+tsup (v4.0.0): ~40ms
+Mejora: 70-90% más rápido
+```
+
+### Bundle Optimization
+
+```
+Antes (v3.x): 603KB
+Después (v4.0.0): 185KB
+Reducción: 69%
+Tree-shaking: 5-20KB según uso
+```
+
+### Runtime Performance
+
+- **Funciones nativas**: Sin overhead de dependencias externas
+- **Tree-shaking preservado**: Solo código usado en bundle final
+- **TypeScript strict**: Optimización máxima del compilador
+
+---
+
+**🎉 @g10/ts-helpers v4.0.4 - Ready for Production**
+
+Para más información, consulta:
+
+- [README.md](README.md) - Overview y instalación
+- [CHANGELOG.md](CHANGELOG.md) - Historial de cambios
+- [GitLab Issues](https://gitlab.gzl10.com/g10libs/ts-helpers/-/issues) -
+  Reportar bugs