npm package: @jysperu/helper-commons
Description: Funciones generales
Latest version: 1.2.1

# @jysperu/helper-commons

[![npm version](https://badge.fury.io/js/@jysperu%2Fhelper-commons.svg)](https://badge.fury.io/js/@jysperu%2Fhelper-commons)
[![npm downloads](https://img.shields.io/npm/dm/@jysperu/helper-commons)](https://www.npmjs.com/package/@jysperu/helper-commons)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@jysperu/helper-commons)](https://bundlephobia.com/package/@jysperu/helper-commons)

Librería de **utilidades comunes** para proyectos TypeScript/JavaScript con funciones de logging, manipulación de fechas y utilidades generales.

## 🚀 Características

- 🔧 **TypeScript** completamente tipado
- ⚡ **Funciones optimizadas** para manipulación de fechas Unix
- 🚩 **Logging** con timestamps y niveles
- 📊 **Utilidades de tiempo** (hora anterior/siguiente, día, mes, año)
- 📅 **Formateo de fechas** personalizable
- 🔄 **Funciones asíncronas** de utilidad (sleep, noop)
- 🌍 **Re-exporta** librerías de navegador (alert, cookie, api)

## 📦 Instalación

```bash
npm install @jysperu/helper-commons
```

## ⚡ Inicio Rápido

```typescript
import { log, log$info, log$warn, log$error, unixtime, today, momento, sleep, prevday, nextday, prevhour, nexthour } from "@jysperu/helper-commons";

// Logging con diferentes niveles
log("Mensaje simple");
log$info("Información con timestamp");
log$warn("Advertencia con timestamp");
log$error("Error con timestamp");

// Utilidades de fecha y tiempo
const ahora = unixtime(); // Timestamp Unix actual
const ayer = prevday(); // Ayer en timestamp Unix
const mañana = nextday(); // Mañana en timestamp Unix

// Formateo de fechas
console.log(today()); // "2025-11-17"
console.log(today("/")); // "2025/11/17"
console.log(momento()); // "DOM 17NOV2025 2:30:45 PM"

// Utilidades asíncronas
await sleep(2); // Pausa 2 segundos
```

## 📚 API Reference

### 🔤 Funciones de Logging

#### log(...messages)

Logging básico sin timestamp.

```typescript
log("Mensaje", "otro mensaje", { objeto: true });
```

#### log$info(...messages)

Log de información con timestamp.

```typescript
log$info("Información importante");
```

#### log$warn(...messages)

Log de advertencia con timestamp.

```typescript
log$warn("Advertencia del sistema");
```

#### log$error(...messages)

Log de error con timestamp.

```typescript
log$error("Error crítico", error);
```

### ⏰ Funciones de Tiempo

#### unixtime()

Obtiene el timestamp Unix actual.

```typescript
const ahora = unixtime(); // 1700227845
```

#### time()

Obtiene el timestamp en milisegundos.

```typescript
const ms = time(); // 1700227845123
```

#### unixtime2date(timestamp?)

Convierte timestamp Unix a objeto Date.

```typescript
const fecha = unixtime2date(1700227845);
const ahoraComoDate = unixtime2date(); // usa timestamp actual
```

### 📅 Manipulación de Fechas

#### Funciones de navegación temporal:

```typescript
// Horas
prevhour(timestamp?, setminute0?) // Hora anterior
nexthour(timestamp?, setminute0?) // Hora siguiente

// Días
prevday(timestamp?) // Día anterior
nextday(timestamp?) // Día siguiente

// Meses
prevmonth(timestamp?) // Mes anterior
nextmonth(timestamp?) // Mes siguiente

// Años
prevyear(timestamp?) // Año anterior
nextyear(timestamp?) // Año siguiente
```

#### nearlyday(timestamp, day, afterToday?)

Encuentra la fecha más cercana con el día especificado.

```typescript
const proximoDia15 = nearlyday(unixtime(), 15); // Próximo día 15 del mes
```

### 📊 Extracción de Fecha

```typescript
unixtime2day(timestamp); // Extrae día (1-31)
unixtime2month(timestamp); // Extrae mes (1-12)
unixtime2year(timestamp); // Extrae año (ej: 2025)
```

### 🔄 Formateo

#### today(separator?)

Fecha actual formateada.

```typescript
today(); // "2025-11-17"
today("/"); // "2025/11/17"
today("."); // "2025.11.17"
```

#### momento()

Timestamp formateado en timezone de Lima.

```typescript
momento(); // "DOM 17NOV2025 2:30:45.123 PM"
```

### 🛠️ Utilidades

#### sleep(seconds)

Pausa asíncrona.

```typescript
await sleep(1.5); // Pausa 1.5 segundos
```

#### noop()

Función vacía asíncrona.

```typescript
await noop(); // No hace nada, útil como placeholder
```

#### isodate2unixtime(isoDate)

Convierte fecha ISO a timestamp Unix.

```typescript
const unix = isodate2unixtime("2025-11-17T14:30:00Z");
const unix2 = isodate2unixtime(new Date());
```

## 🌍 Re-exports

Esta librería también re-exporta las siguientes utilidades de browser:

### Alertas (desde @jysperu/browser-alert)

```typescript
import {
  alert_loading,
  alert_confirm,
  alert_message,
  alert_success,
  alert_error,
  alert_info,
  alert_warning,
  alert_close,
} from "@jysperu/helper-commons";
```

### Cookies (desde @jysperu/browser-cookie)

```typescript
import { getCookie, setCookie, delCookie, getCookies, delCookies, cookieExists } from "@jysperu/helper-commons";
```

### API (desde @jysperu/helper-fetcher)

```typescript
import { api, api_get, api_post, api_request } from "@jysperu/helper-commons";
```

## 🌍 Compatibilidad

- ✅ Todos los navegadores modernos
- ✅ Compatible con frameworks (React, Vue, Angular, Svelte)
- ✅ Node.js y entornos SSR
- ✅ TypeScript nativo
- ✅ ES Modules y CommonJS

## 🔗 Enlaces y Recursos

- 📘 **Repositorio**: [GitLab - helper-commons](https://gitlab.com/tiny.node/helper/commons)
- 🐛 **Issues**: [Reportar problemas](https://gitlab.com/tiny.node/helper/commons/issues)
- 📦 **npm**: [@jysperu/helper-commons](https://www.npmjs.com/package/@jysperu/helper-commons)
- 🏢 **JYS Perú**: [www.jys.pe](https://www.jys.pe)

## 📄 Licencia

**MIT License** - Consulta el archivo [LICENSE](./LICENSE) para detalles completos.

```text
MIT License - Copyright (c) 2025 JYS Perú
```

---

Desarrollado con ❤️ por [**JYS Perú**](https://www.jys.pe)