Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Davidmallega/Gastos-App/llms.txt

Use this file to discover all available pages before exploring further.

El módulo src/utils/format.js concentra toda la lógica de presentación y cálculo numérico de GastosApp. Exporta funciones puras —sin efectos secundarios ni dependencias de estado— que son consumidas por páginas, componentes y la suite de tests. Todas las operaciones con fechas usan tiempo local para evitar desfases UTC en las zonas horarias chilenas (UTC-3 / UTC-4).

​
formatCLP

Convierte un número a su representación en pesos chilenos usando el locale es-CL de la API Intl.NumberFormat.
​
value
number
required
Valor numérico a formatear. Se acepta también un string numérico; null y undefined se tratan como 0.
Retorna: string con formato de moneda CLP (separador de miles con punto, sin decimales). 
import { formatCLP } from './utils/format'

formatCLP(150000)    // '$150.000'
formatCLP(0)         // '$0'
formatCLP('50000')   // '$50.000'
formatCLP(null)      // '$0'

​
parseLocalDate

Parsea una cadena 'YYYY-MM-DD' como fecha local, evitando el desfase de zona horaria que ocurre al usar new Date('YYYY-MM-DD') (que interpreta la cadena como UTC medianoche y puede retroceder un día en Chile).
​
str
string
required
Fecha en formato 'YYYY-MM-DD'. Retorna null si el valor está vacío o mal formado.
Retorna: objeto Date construido con new Date(year, month - 1, day) —sin conversión UTC.
Esta función es la base de todas las demás operaciones con fechas del módulo. Usarla garantiza que formatDate('2025-06-15') siempre muestre el día 15, independientemente de si el sistema corre en UTC-3 o UTC-5.
import { parseLocalDate } from './utils/format'

const d = parseLocalDate('2025-06-15')
d.getDate()    // 15 (correcto en cualquier zona horaria)
d.getMonth()   // 5  (junio, base 0)

​
formatDate

Formatea una fecha 'YYYY-MM-DD' a la representación local larga 'DD/MM/YYYY' según el locale es-CL.
​
dateStr
string
required
Fecha en formato 'YYYY-MM-DD'. Retorna '—' para valores vacíos o inválidos.
Retorna: string con formato 'DD/MM/YYYY' o '—' en caso de error. 
import { formatDate } from './utils/format'

formatDate('2025-06-15')   // '15/06/2025'
formatDate('')             // '—'
formatDate('no-es-fecha')  // '—'

​
formatDateShort

Formatea una fecha 'YYYY-MM-DD' a su representación corta 'DD Mmm' (día + mes abreviado) según el locale es-CL.
​
dateStr
string
required
Fecha en formato 'YYYY-MM-DD'. Retorna '—' para valores vacíos o inválidos.
Retorna: string con formato corto, por ejemplo '15 jun.'. Útil para columnas de tabla con espacio reducido. 
import { formatDateShort } from './utils/format'

formatDateShort('2025-06-15')  // '15 jun.'
formatDateShort(null)          // '—'

​
getMesLabel

Genera la etiqueta textual de un mes y año dados.
​
year
number
required
Año con cuatro dígitos, por ejemplo 2025.
​
month
number
required
Mes en base 0 (enero = 0, diciembre = 11), igual que Date.getMonth().
Retorna: string con el nombre del mes y el año, por ejemplo 'Junio 2025'. 
import { getMesLabel } from './utils/format'

getMesLabel(2025, 5)   // 'Junio 2025'
getMesLabel(2025, 0)   // 'Enero 2025'
getMesLabel(2024, 11)  // 'Diciembre 2024'

​
getMesesOptions

Genera la lista de los últimos 12 meses desde el mes actual, ordenados del más reciente al más antiguo. Se usa para poblar el selector de período en los módulos de facturas, gastos y compromisos. No recibe parámetros. Retorna: Array<{ year: number, month: number, label: string }> con 12 elementos. 
import { getMesesOptions } from './utils/format'

const opciones = getMesesOptions()
// [
//   { year: 2025, month: 5, label: 'Junio 2025' },
//   { year: 2025, month: 4, label: 'Mayo 2025' },
//   ...
//   { year: 2024, month: 6, label: 'Julio 2024' },
// ]

​
getItemsByMonth

Filtra un array de documentos (gastos, facturas, etc.) por año y mes, usando el campo fecha del documento. Si fecha no existe, recurre a createdAt.
​
items
array
required
Array de documentos. Cada elemento debe tener un campo fecha ('YYYY-MM-DD') o createdAt (ISO string).
​
year
number
required
Año con cuatro dígitos.
​
month
number
required
Mes en base 0 (enero = 0).
Retorna: subarray de los items cuya fecha corresponde al año y mes indicados. 
import { getItemsByMonth } from './utils/format'

const junio = getItemsByMonth(todasLasFacturas, 2025, 5)

​
buildNCMap

Construye un mapa de cobertura de Notas de Crédito indexado por facturaRefId. Se usa para calcular el monto efectivo de cada factura una vez descontadas sus NC vinculadas, incluso cuando la NC pertenece a un período diferente al de la factura.
​
allFacturas
Factura[]
required
Array completo de facturas (puede incluir facturas ordinarias y Notas de Crédito). Solo se procesan los elementos cuyo tipoDoc === 'Nota de Crédito' y que tengan facturaRefId definido.
Retorna: object con estructura { [facturaId: string]: number }, donde el valor es la suma total de todas las NC vinculadas a esa factura. La función filtra por tipoDoc === 'Nota de Crédito' y facturaRefId no nulo, luego acumula los totales agrupados por facturaRefId: 
import { buildNCMap } from './utils/format'

const facturas = [
  { id: 'f1', tipoDoc: 'Factura', total: 100000 },
  { id: 'nc1', tipoDoc: 'Nota de Crédito', facturaRefId: 'f1', total: 30000 },
  { id: 'nc2', tipoDoc: 'Nota de Crédito', facturaRefId: 'f1', total: 20000 },
]

const ncMap = buildNCMap(facturas)
// { 'f1': 50000 }

// Ejemplo con múltiples facturas:
const ncMap2 = buildNCMap(todasLasFacturas)
// { 'factura-123': 50000, 'factura-456': 120000 }
Las NC sin facturaRefId (NC no vinculadas) no aparecen en el mapa. Su efecto se aplica directamente en calcTotals.

​
calcTotals

Calcula los totales agregados de un conjunto de ítems (gastos por caja o facturas SII), aplicando correctamente la deducción de Notas de Crédito tanto vinculadas como no vinculadas.
​
items
GastoCaja[] | Factura[]
required
Array de documentos del período a calcular.
​
ncMap
object
Mapa de cobertura NC generado por buildNCMap. Opcional: si se omite, la función construye un mapa interno a partir de los propios items (comportamiento anterior). Se recomienda pasar el mapa externo cuando hay NC de períodos distintos al del período analizado.
Retorna: { neto: number, iva: number, total: number, pagado: number, pendiente: number }.

​
Lógica de deducción de NC

  • NC vinculada (facturaRefId definido): el monto de la NC se descuenta del effectiveAmt de la factura referenciada (Math.max(0, amt - ncCovered)). La NC en sí se omite del acumulador para evitar doble conteo.
  • NC sin vínculo (facturaRefId nulo): su neto, IVA y total se restan directamente del acumulador global.
import { calcTotals, buildNCMap } from './utils/format'

// Con mapa externo (recomendado para informes multi-período):
const ncMap = buildNCMap(todasLasFacturasDelAnio)
const totals = calcTotals(facturasMes, ncMap)
// { neto: 840336, iva: 159664, total: 950000, pagado: 600000, pendiente: 350000 }

// Sin mapa (calcula NC solo desde los items del array):
const totalsSimple = calcTotals(facturasMes)

​
addDays

Suma un número de días a una fecha 'YYYY-MM-DD' y retorna la nueva fecha en el mismo formato. Usa parseLocalDate internamente para evitar desfases UTC.
​
dateStr
string
required
Fecha base en formato 'YYYY-MM-DD'.
​
days
number
required
Número de días a sumar (puede ser negativo para restar días).
Retorna: string en formato 'YYYY-MM-DD' o null si algún parámetro es inválido. 
import { addDays } from './utils/format'

addDays('2025-06-15', 10)   // '2025-06-25'
addDays('2025-06-15', -5)   // '2025-06-10'
addDays('2025-01-28', 5)    // '2025-02-02'

​
getPendienteHealth

Calcula el estado de salud (semáforo) de un documento pendiente de pago según cuántos días han transcurrido desde su fecha de referencia. Si se proporciona fechaVencimiento, esta tiene prioridad sobre fecha.
​
fecha
string
required
Fecha del documento en formato 'YYYY-MM-DD'. Se usa como referencia si no se pasa fechaVencimiento.
​
fechaVencimiento
string
Fecha de vencimiento opcional en formato 'YYYY-MM-DD'. Cuando se pasa, el semáforo se calcula sobre esta fecha en lugar de fecha. Útil para proveedores con plazoPago configurado.
Retorna: { label: string, color: 'blue' | 'green' | 'yellow' | 'red' }.

​
Tabla del semáforo

Días desde la fecha de referencialabelcolor
< 0 (fecha futura)'Programado''blue'
0 – 3'Pendiente''green'
4 – 7'Pendiente''yellow'
> 7'Atrasado''red'
import { getPendienteHealth } from './utils/format'

// Documento con fecha de ayer:
getPendienteHealth('2025-06-14')
// { label: 'Pendiente', color: 'green' }

// Documento de hace 10 días:
getPendienteHealth('2025-06-05')
// { label: 'Atrasado', color: 'red' }

// Documento con vencimiento futuro:
getPendienteHealth('2025-06-01', '2025-06-30')
// { label: 'Programado', color: 'blue' }

​
parseSIIDate

Convierte una fecha en formato DD/MM/YYYY (formato usado por el SII en los CSV del Libro de Compras) al formato interno 'YYYY-MM-DD'. Si la cadena ya está en formato ISO, la retorna sin cambios.
​
str
string
required
Cadena de fecha. Acepta 'DD/MM/YYYY' o 'YYYY-MM-DD'. Retorna '' para valores nulos o vacíos.
Retorna: string en formato 'YYYY-MM-DD' o ''. 
import { parseSIIDate } from './utils/format'

parseSIIDate('01/06/2025')   // '2025-06-01'
parseSIIDate('2025-06-01')   // '2025-06-01'  (ya está en formato correcto)
parseSIIDate(null)           // ''

​
parseNumber

Parsea cadenas numéricas con formato chileno (puntos como separador de miles, coma como separador decimal) y las convierte a number. Elimina cualquier carácter no numérico, incluyendo el símbolo $.
​
str
string | number
required
Cadena numérica a parsear. Retorna 0 para valores vacíos, null o undefined.
Retorna: number (resultado de parseFloat después de normalizar la cadena). 
import { parseNumber } from './utils/format'

parseNumber('1.234.567')    // 1234567
parseNumber('1.234,56')     // 1234.56
parseNumber('$50.000')      // 50000
parseNumber('')             // 0
parseNumber(null)           // 0

Build docs developers (and LLMs) love

Get started for freeTalk to us