tipazo/README.md

libreria-multiform

# 🧠 Tipazo

**Tipazo** es una librería CLI y módulo en TypeScript que permite generar archivos Excel (`.xlsx`) de forma rápida y sencilla, ya sea con listas de países o con datos personalizados en formato JSON. Además, incluye utilidades para manipular datos como filtrado, agrupamiento y detección de duplicados. Ideal para automatizar reportes, pruebas o simplemente jugar con datos geográficos y estadísticos.

---


```ts
import {
  generarExcel,
  generarExcelConGrafico,
  eliminarDuplicadosPorNumero,
  encontrarDuplicados,
  contarDuplicados,
  agruparPorClave,
  resumenNumerico,
  filtrarPorRangoDeFechas,
  exportarMultiplesHojas,
  removeAdvancedDuplicates,
  findDuplicates,
  countDuplicates,
  countTotalDuplicates,
  detectarOutliers,
} from 'tipazo';
```

---


## 🚀 Instalación

Puedes instalarla globalmente con npm:

```bash
npm install -g tipazo
```

O usarla directamente con `npx`:

```bash
npx tipazo Venezuela Colombia Argentina
```

También puedes instalarla como dependencia en tu proyecto:

```bash
npm install tipazo
```

---


## 🧪 Uso como CLI

Una vez instalada, puedes ejecutar el comando `tipazo` desde la terminal:

```bash
tipazo México Perú Chile
```

Esto generará un archivo llamado `paises.xlsx` en el directorio actual, con una hoja que contiene los países listados.

---


## 📦 Uso como módulo en TypeScript

### 📊 Generación de Excel

#### 1. `generarExcel`

Genera un archivo Excel a partir de un array de objetos JSON.

```ts
generarExcel(registros, 'archivo.xlsx', 'Datos');
```

- `registros`: Array de objetos
- `'archivo.xlsx'`: Nombre del archivo
- `'Datos'`: Nombre de la hoja

---


#### 2. `generarExcelConGrafico`

Genera un archivo Excel con datos preparados para gráficos (usando ExcelJS).

```ts
await generarExcelConGrafico(datos, 'grafico.xlsx');
```

---


#### 3. `exportarMultiplesHojas`

Genera un archivo Excel con varias hojas, cada una con su grupo de datos.

```ts
exportarMultiplesHojas(agrupados, 'reporte.xlsx');
```

---


### 🧠 Manipulación de datos

#### 4. `eliminarDuplicadosPorNumero`

Elimina objetos duplicados según una clave numérica.

```ts
const sinDuplicados = eliminarDuplicadosPorNumero(registros, 'valor');
```

---


#### 5. `encontrarDuplicados`

Devuelve los objetos que tienen valores duplicados en una clave.

```ts
const duplicados = encontrarDuplicados(registros, 'valor');
```

---


#### 6. `contarDuplicados`

Cuenta cuántos elementos están duplicados en una clave.

```ts
const total = contarDuplicados(registros, 'valor');
console.log(`Hay ${total} duplicados.`);
```

---


### 🔁 Nuevas funciones genéricas

#### 7. `removeAdvancedDuplicates`

Elimina objetos duplicados comparando por contenido completo.

```ts
const únicos = removeAdvancedDuplicates(registros);
```

---


#### 8. `findDuplicates`

Devuelve los objetos duplicados comparando por contenido completo.

```ts
const duplicados = findDuplicates(registros);
```

---


#### 9. `countDuplicates`

Devuelve un `Map` con el conteo de cada objeto duplicado.

```ts
const mapa = countDuplicates(registros);
mapa.forEach((count, key) => {
  console.log(`${key} → ${count}`);
});
```

---


#### 10. `countTotalDuplicates`

Devuelve el número total de duplicados como `number`.

```ts
const total = countTotalDuplicates(registros);
console.log(`Total de duplicados: ${total}`);
```

---


#### 11. `agruparPorClave`

Agrupa los objetos por una propiedad común.

```ts
const agrupados = agruparPorClave(registros, 'categoria');
```

**Resultado:**

```ts
{
  Frutas: [{...}, {...}],
  Verduras: [{...}]
}
```

---


#### 12. `resumenNumerico`

Calcula estadísticas básicas de una propiedad numérica.

```ts
const resumen = resumenNumerico(registros, 'ventas');
console.log(resumen); // { total, promedio, max, min }
```

---


#### 13. `filtrarPorRangoDeFechas`

Filtra objetos por un rango de fechas.

```ts
const filtrados = filtrarPorRangoDeFechas(registros, 'fecha', new Date('2025-01-01'), new Date('2025-03-31'));
```
#### 13. `detectarOutliers`
---

```ts
const ventas = [
  { producto: 'A', monto: 100 },
  { producto: 'B', monto: 120 },
  { producto: 'C', monto: 95 },
  { producto: 'D', monto: 5000 }, // outlier
  { producto: 'E', monto: 110 }
];
const outliers = detectarOutliers(ventas, 'monto');
console.log(outliers);
```



## 📁 Estructura del archivo Excel

La hoja generada se llama `Países` o `Datos` (según el método) y contiene columnas basadas en los datos proporcionados. Ejemplo:

| ID | País       |
|----|------------|
| 1  | Venezuela  |
| 2  | Colombia   |
| 3  | Argentina  |

---


## ⚙️ Scripts disponibles

```bash
npm run build   # Compila TypeScript a JavaScript
npm start       # Compila y ejecuta test.js
```

---


## 🧩 Tecnologías utilizadas

- TypeScript  
- XLSX (SheetJS)  
- ExcelJS  
- Node.js  

---


## 🧑 Autor

Desarrollado por **Pablo**  
Licencia: ISC

---


## 💡 Ideas futuras

- Soporte para más formatos (CSV, JSON)  
- Personalización de columnas  
- Descarga desde URL o API  
- Interfaz web  
- Gráficos avanzados en Excel  
- Exportación directa a Google Sheets