jaspi-core

Utilitarios leves da Jaspi para padronizar regras de negocio de:

• datas
• competencias
• numeros decimais
• texto

A ideia da lib e simples: centralizar operacoes repetidas e deixar o codigo de regra de negocio mais previsivel, com uma API pequena e direta.

Instalacao

npm install @jaspisistemas/jaspi-core

Importacao

import jaspi, { date, num, text } from "@jaspisistemas/jaspi-core";

Voce pode usar tanto o default export jaspi quanto os namespaces nomeados date, num e text.

No dia a dia, o padrao costuma ficar assim:

var data = date.newDateTime("26/03/2026 17:08:00.000");

console.log(date.format(data)); // "26/03/2026"
console.log(date.formatDateTime(data)); // "26/03/2026 17:08:00.000"

Exemplo rapido

import { jaspi } from "@jaspisistemas/jaspi-core";

jaspi.date.configure({ competenciaStart: "01/2023" });

const competencia = jaspi.date.parse("03/2026");
const competenciaTexto = jaspi.date.formatCompetencia(competencia);
const saldo = jaspi.num.round("4.243,339", 2);
const opcoesCombo = jaspi.date.competenciaOptionsDefault();

console.log(competenciaTexto); // "03/2026"
console.log(saldo); // 4243.34
console.log(opcoesCombo.length); // depende da data atual, mas sempre vem com itens de competencia

O que a biblioteca resolve

• competencia como data de calendario
• geracao de listas de competencias para combos
• arredondamento e formatacao numerica
• helpers simples de texto

Uso pratico

jaspi.date

from(value)

Converte uma string em Date aceitando apenas estes formatos:

• dd/mm/yyyy
• dd-mm-yyyy
• dd/mm/yyyy HH:mm
• dd/mm/yyyy HH:mm:ss
• dd/mm/yyyy HH:mm:ss.SSS
• yyyy/mm/dd
• yyyy-mm-dd
• yyyy/mm/dd HH:mm
• yyyy/mm/dd HH:mm:ss
• yyyy/mm/dd HH:mm:ss.SSS

O separador entre data e hora pode ser espaco ou T.

console.log(date.format(date.from("01/02/2000"))); // "01/02/2000"
console.log(date.format(date.from("2000/04/12"))); // "12/04/2000"
console.log(date.format(date.from("2000-04-12"))); // "12/04/2000"
console.log(date.formatDateTime(date.from("01/02/2000T17:08"))); // "01/02/2000 17:08:00.000"
console.log(date.formatDateTime(date.from("2000/04/12 17:08:15.250"))); // "12/04/2000 17:08:15.250"

Configuracao

import { date } from "@jaspisistemas/jaspi-core";

date.configure({ competenciaStart: "01/2023" });
console.log(date.format(date.getCompetenciaStart())); // "01/01/2023"

date.setCompetenciaStart("03/2024");
console.log(date.format(date.getCompetenciaStart())); // "01/03/2024"

nullDate()

Retorna a data tecnica 01/01/0001.

const value = date.nullDate();
console.log(date.format(value)); // "01/01/0001"

today() e now()

today() retorna somente a data atual do ambiente. now() retorna data e hora atuais.

const hoje = date.today();
const agora = date.now();

console.log(date.format(hoje)); // exemplo: "26/03/2026"
console.log(date.formatDateTime(agora)); // exemplo: "26/03/2026 17:08:00.000"

newDate(day, month, year)

Cria uma data no horario zero.

const value = date.newDate(26, 3, 2026);
console.log(date.format(value)); // "26/03/2026"

newDateTime(value)

Aceita string de data/hora no formato dd/mm/yyyy hh:mm:ss.sss ou yyyy-mm-dd hh:mm:ss.sss.

const value = date.newDateTime("26/03/2026 17:08:00.000");
console.log(date.formatDateTime(value)); // "26/03/2026 17:08:00.000"

const fromIso = date.newDateTime("2026-03-26 17:08");
console.log(date.formatDateTime(fromIso)); // "26/03/2026 17:08:00.000"

newCompetency(month, year)

Cria a competencia como o primeiro dia do mes.

const competencia = date.newCompetency(3, 2026);
console.log(date.formatCompetencia(competencia)); // "03/2026"

startOfMonth(value) e endOfMonth(value)

const base = date.newDate(26, 3, 2026);

console.log(date.format(date.startOfMonth(base))); // "01/03/2026"
console.log(date.format(date.endOfMonth(base))); // "31/03/2026"

addDays(value, days)

const base = date.newDate(26, 3, 2026);
const proximaSemana = date.addDays(base, 7);

console.log(date.format(proximaSemana)); // "02/04/2026"

addMonths(value, months)

const base = date.newDate(31, 1, 2026);
const proximoMes = date.addMonths(base, 1);

console.log(date.format(proximoMes)); // "28/02/2026"

addYear(value, years)

const base = date.newDate(29, 2, 2024);
const proximoAno = date.addYear(base, 1);

console.log(date.format(proximoAno)); // "28/02/2025"

diferenca(inicio, fim)

Retorna a diferenca em segundos.

const inicio = date.newDateTime("26/03/2026 17:08:00.000");
const fim = date.newDateTime("26/03/2026 17:08:15.250");

console.log(date.diferenca(inicio, fim)); // 15.25

compare(left, right) e isSameDate(left, right)

const a = date.newDate(26, 3, 2026);
const b = date.newDate(27, 3, 2026);

console.log(date.compare(a, b)); // -1
console.log(date.compare(b, a)); // 1
console.log(date.isSameDate(a, date.newDate(26, 3, 2026))); // true

toFormat(value, pattern?)

const value = date.newDate(26, 3, 2026);

console.log(date.toFormat(value)); // "26/03/2026"
console.log(date.toFormat(value, "dd MM yyyy")); // "26 03 2026"

format(value, separator?)

Atalho para toFormat, com separador customizavel.

const value = date.newDate(26, 3, 2026);

console.log(date.format(value)); // "26/03/2026"
console.log(date.format(value, "-")); // "26-03-2026"

formatDateTime(value, dateSeparator?, timeSeparator?)

const value = date.newDateTime("26/03/2026 17:08:00.123");

console.log(date.formatDateTime(value)); // "26/03/2026 17:08:00.123"
console.log(date.formatDateTime(value, "-", ".")); // "26-03-2026 17.08.00.123"

parse(value)

Aceita competencia (MM/YYYY), YYYY/MM e datas completas.

console.log(date.format(date.parse("03/2026"))); // "01/03/2026"
console.log(date.format(date.parse("2026/03"))); // "01/03/2026"
console.log(date.format(date.parse("26/03/2026"))); // "26/03/2026"

formatCompetencia(value)

const value = date.newDate(26, 3, 2026);

console.log(date.formatCompetencia(value)); // "03/2026"

competenciaOptions(from, to)

Gera uma lista de competencias entre duas datas.

const opcoes = date.competenciaOptions("01/2026", "03/2026");

console.log(opcoes.map((item) => item.label));
// ["01/2026", "02/2026", "03/2026"]

competenciaOptionsFrom(from)

Gera as competencias de uma data inicial ate o mes atual.

date.setCompetenciaStart("01/2026");

const opcoes = date.competenciaOptionsFrom("01/2026");

console.log(opcoes[0]?.label); // "01/2026"

competenciaOptionsDefault()

Usa o competenciaStart configurado na lib como inicio e vai ate a competencia atual.

date.setCompetenciaStart("01/2023");

const opcoes = date.competenciaOptionsDefault();

console.log(opcoes[0]?.label); // "01/2023"

jaspi.num

parse(value)

console.log(num.parse("4243.339")); // 4243.339
console.log(num.parse("4.243,339")); // 4243.339
console.log(num.parse("10,5")); // 10.5

format(value, decimals?)

console.log(num.format(10.5)); // "10.50"
console.log(num.format(10.5, 3)); // "10.500"

add(left, right)

console.log(num.add("10,5", "2,25")); // 12.75

subtract(left, right)

console.log(num.subtract("10,5", "2,25")); // 8.25

multiply(left, right)

console.log(num.multiply("10,5", "2")); // 21

divide(left, right)

console.log(num.divide("10,5", "2")); // 5.25

Se o divisor for zero, a lib dispara erro.

// num.divide(10, 0); // Error: Division by zero

round(value, decimals?)

console.log(num.round("4243.339", 2)); // 4243.34
console.log(num.round("4.243,339", 2)); // 4243.34

sum(values)

console.log(num.sum(["10,5", "2,25", 7])); // 19.75

compare(left, right)

console.log(num.compare("10.1", "10.2")); // -1
console.log(num.compare("10.2", "10.1")); // 1
console.log(num.compare("10.2", "10.2")); // 0

jaspi.text

trim(value)

console.log(text.trim("  jaspi  ")); // "jaspi"

padLeft(value, size, fill?)

console.log(text.padLeft("7", 3)); // "007"
console.log(text.padLeft("A", 4, "*")); // "***A"

padRight(value, size, fill?)

console.log(text.padRight("Jaspi", 8)); // "Jaspi   "
console.log(text.padRight("A", 4, "-")); // "A---"

contains(value, search)

console.log(text.contains("controle de competencia", "competencia")); // true

startsWith(value, prefix)

console.log(text.startsWith("Jaspi Core", "Jaspi")); // true

endsWith(value, suffix)

console.log(text.endsWith("arquivo.txt", ".txt")); // true

Principios

• sem dependencias externas
• API pequena e direta
• compativel com backend e frontend
• pronta para evoluir por versao

Resumo da API

date

• configure({ competenciaStart })
• getCompetenciaStart()
• setCompetenciaStart(value)
• nullDate()
• today()
• now()
• newDate(day, month, year)
• newDateTime(value)
• newCompetency(month, year)
• startOfMonth(value)
• endOfMonth(value)
• addDays(value, days)
• addMonths(value, months)
• addYear(value, years)
• diferenca(inicio, fim)
• compare(left, right)
• isSameDate(left, right)
• from(value)
• toFormat(value, pattern?)
• format(value, separator?)
• formatDateTime(value, dateSeparator?, timeSeparator?)
• parse(value)
• formatCompetencia(value)
• competenciaOptions(from, to)
• competenciaOptionsFrom(from)
• competenciaOptionsDefault()

num

• parse(value)
• format(value, decimals?)
• add(left, right)
• subtract(left, right)
• multiply(left, right)
• divide(left, right)
• round(value, decimals?)
• sum(values)
• compare(left, right)

text

• trim(value)
• padLeft(value, size, fill?)
• padRight(value, size, fill?)
• contains(value, search)
• startsWith(value, prefix)
• endsWith(value, suffix)