https://github.com/rodmarzavala/gt-utils-js
https://github.com/rodmarzavala/gt-utils-js
cui departamentos departamentos-guatemala dpi finance geo guatemala municipios municipios-guatemala municipios-guatemaltecos nit sat
Last synced: 11 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/rodmarzavala/gt-utils-js
- Owner: rodmarzavala
- Created: 2026-05-01T10:05:10.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-01T10:56:55.000Z (3 months ago)
- Last Synced: 2026-05-01T12:22:18.551Z (3 months ago)
- Topics: cui, departamentos, departamentos-guatemala, dpi, finance, geo, guatemala, municipios, municipios-guatemala, municipios-guatemaltecos, nit, sat
- Language: TypeScript
- Homepage: https://rodmarzavala.github.io/gt-utils-js/
- Size: 144 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# gt-utils-js
Biblioteca estándar sin dependencias (Zero-Dependency) y con tipado estricto (TypeScript) para validaciones y utilidades específicas de Guatemala.
Optimizada para entornos Edge (Cloudflare Workers, Vercel Edge), Deno, Bun y Node.js. El código, nombres de variables y API se mantienen en inglés bajo principios de Clean Code, pero la lógica responde a la legislación y cultura de Guatemala.
## Instalación
```bash
npm install @rodmarzavala/gt-utils-js
# o usando yarn
yarn add @rodmarzavala/gt-utils-js
# o usando pnpm
pnpm add @rodmarzavala/gt-utils-js
```
## Características Principales
Esta biblioteca provee 7 submódulos especializados:
- **Identidad:** Validación rigurosa de NIT y CUI/DPI (Módulo 11 oficial de SAT y RENAP). Incluye la nueva disposición SAT 2025 donde los CUI válidos operan como NIT. Retorna el departamento y código de municipio emisor.
- **Finanzas:** Conversión de números a letras para Facturación Electrónica (FEL) y detección de bancos por número de cuenta (G&T, Banrural, BI, BAM, Promerica, etc).
- **Vehículos:** Analizador y validador de Placas Vehiculares (comerciales, particulares, motos, y reglas estrictas del reglamento de tránsito, como exclusiones de vocales O, I, Q, Ñ).
- **Geografía:** Resolución Inversa Nacional: pasa coordenadas (Lat, Lng) y te dice en qué municipio y departamento de Guatemala caen (Ray-Casting algorithm ligero).
- **Impuestos:** Retenciones de IVA y escalonadas de ISR (Régimen General > Q2,500) redondeadas al centavo contable exacto.
- **Feriados y Calendario:** Algoritmo astronómico para cálculo de Semana Santa, listado de asuetos, y traslados de feriados largos de acuerdo a la Ley de Promoción de Turismo Interno (Decreto 19-2018 y CC).
- **Laboral:** Calculadora de Liquidaciones al centavo. Determina fechas de corte y pagos proporcionales de Aguinaldo, Bono 14, Vacaciones y cálculo de indemnización por despido injustificado (regla de 14 salarios / 12 meses).
## Uso Rápido
La librería expone todas sus utilidades desde el punto de entrada principal.
```typescript
import {
isValidNit,
isValidCui,
getCuiInformation,
calculateTaxes,
calculateSeverance,
getLicensePlateInfo,
getHolidays,
findMunicipalityByLatLng,
amountToWords
} from 'gt-utils-js';
// 1. Identidad
console.log(isValidNit('123456-0')); // true
console.log(isValidCui('1234567890101')); // true
console.log(getCuiInformation('1234567890101'));
// { isValid: true, department: 'Guatemala', municipalityId: 1 }
// 2. Impuestos y Facturación
console.log(amountToWords(150.50)); // "CIENTO CINCUENTA QUETZALES CON 50/100 CENTAVOS"
console.log(calculateTaxes({
amount: 3000,
regime: 'GENERAL',
isRetentionAgent: true,
currency: 'GTQ'
}));
// { subtotal: 2678.57, iva: 321.43, retentionIsr: 133.93, retentionIva: 48.21, totalToReceive: 2817.86 }
// 3. Vehículos
console.log(parseLicensePlate('P-123BCD'));
// { isValid: true, type: 'P', number: '123', letters: 'BCD' }
// 4. Laboral
console.log(calculateSeverance({
startDate: new Date('2022-01-01'),
endDate: new Date('2023-12-31'),
monthlySalary: 6000,
reason: 'UNJUSTIFIED_FIRING'
}));
// { aguinaldo, bono14, vacations, indemnizacion: 14000, totalToReceive: 20501.37, ... }
// 5. Geografía (Coordenadas -> Municipio)
// Palacio Nacional
console.log(findMunicipalityByLatLng(14.643445, -90.513222));
// { name: 'Guatemala', department: 'Guatemala' }
// 6. Feriados
const holidays2024 = getHolidays(2024);
// Retorna todos los asuetos incluyendo fechas móviles (ej. 30 de junio movido a lunes)
```
## Documentación Detallada
- [Docs Oficiales](https://rodmarzavala.github.io/gt-utils-js) (Próximamente vía GitHub Pages)
## Tests
El paquete tiene una cobertura de pruebas exhaustiva. Para ejecutar las pruebas tú mismo:
```bash
pnpm install
pnpm test
```
También incluimos un archivo `playground.ts` que demuestra cada funcionalidad. Para correrlo:
```bash
npx tsx src/playground.ts
```
## Licencia
MIT