@m8t-jacob/pln-utils

Fully typed TypeScript utilities for Polish finance: NBP exchange rates, public holidays / working days, VAT calculations, and PLN formatting.

• Strict TypeScript, ships dual ESM + CJS builds with .d.ts
• Zero runtime dependencies — the NBP client uses the global fetch (Node.js 20+), everything else is pure logic
• Tree-shakeable; import the whole package or a single subpath
• Moving Polish holidays computed from Easter Sunday (Meeus/Jones/Butcher algorithm), not a hardcoded table

Install

npm install @m8t-jacob/pln-utils

Quickstart

import { addVat, formatPln, getExchangeRate, isWorkingDay } from '@m8t-jacob/pln-utils';

await getExchangeRate('USD'); // { code: 'USD', rate: 4.05, date: '2025-01-15', table: 'A' }
addVat(100, 23); // 123
formatPln(1234.56); // '1 234,56 zł'
isWorkingDay('2025-05-01'); // false (Święto Pracy)

You can also import from a subpath if you only need one module, which keeps bundlers from pulling in the others:

import { getExchangeRate } from '@m8t-jacob/pln-utils/nbp';
import { getHolidays, isWorkingDay } from '@m8t-jacob/pln-utils/holidays';
import { addVat, removeVat } from '@m8t-jacob/pln-utils/vat';
import { formatPln, parsePln } from '@m8t-jacob/pln-utils/format';

API

NBP exchange rates (nbp)

| Function | Description | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | getExchangeRate(code, options?): Promise<ExchangeRate> | Table A mid rate for one currency, for today or options.date | | getExchangeRates(options?): Promise<ExchangeRate[]> | Full table (A, B, or C) for today or options.date | | getGoldPrice(options?): Promise<{ price: number; date: string }> | NBP gold price (PLN per gram) | | convert(amount, from, to, options?): Promise<number> | Converts an amount between two currencies via PLN (table A mid rates) | | NbpError | Thrown for invalid input, network failures, or non-OK API responses |

All NBP functions throw NbpError for an invalid 3-letter currency code, a malformed date (must be YYYY-MM-DD), a 404 (e.g. no table published for that date), or a network failure. None of them are tested against the live API — the test suite mocks fetch so CI runs deterministically offline.

Holidays and working days (holidays)

| Function | Description | | ----------------------------------------------- | --------------------------------------------------------------------- | | getHolidays(year): Holiday[] | All Polish statutory public holidays for a year, sorted chronologically | | isHoliday(date): boolean | Whether a Date or YYYY-MM-DD string is a public holiday | | isWorkingDay(date): boolean | true unless the date is a weekend or a public holiday | | addWorkingDays(date, n): Date | Adds (or subtracts, for negative n) n working days | | workingDaysBetween(start, end): number | Counts working days strictly between two dates (order-independent) | | getEaster(year): Date | Easter Sunday for a year (Meeus/Jones/Butcher algorithm) |

Moving holidays (Easter Sunday and Monday, Pentecost +49 days, Corpus Christi +60 days) are derived from getEaster, not hardcoded per year.

VAT (vat)

| Function | Description | | ---------------------------------------- | ------------------------------------------------------- | | VAT_RATES | { STANDARD: 23, REDUCED_8: 8, REDUCED_5: 5, ZERO: 0 } | | addVat(net, rate): number | Adds VAT to a net amount, returning the gross amount | | removeVat(gross, rate): number | Removes VAT from a gross amount, returning the net amount | | vatAmount(net, rate): number | The VAT amount itself | | netToGross(net, rate): number | Alias for addVat | | grossToNet(gross, rate): number | Alias for removeVat | | roundToGrosze(value): number | Float-safe rounding to two decimal places (grosze) |

All amounts are rounded to grosze (two decimal places) using a float-safe rounding helper, avoiding classic IEEE-754 issues like 1.005 * 100 not rounding as expected.

Formatting (format)

| Function | Description | | ------------------------------------------------------------------ | ------------------------------------------------------------------- | | formatPln(amount, options?): string | Formats a number as 1 234,56 zł (Polish locale, Intl.NumberFormat) | | parsePln(str): number | Parses a formatted PLN string back into a number |

formatPln accepts { decimals?: number; symbol?: boolean }. Note that the thousands separator is a non-breaking space (U+00A0), matching Intl.NumberFormat('pl-PL') output — parsePln accepts both regular and non-breaking spaces.

🇵🇱 Po polsku

@m8t-jacob/pln-utils to biblioteka narzędzi finansowych dla Polski: klient kursów walut NBP, polskie dni ustawowo wolne od pracy i dni robocze, kalkulacje VAT oraz formatowanie kwot w PLN. Moduł nbp korzysta z globalnego fetch (Node.js 20+) i wymaga dostępu do sieci; pozostałe moduły (holidays, vat, format) to czysta logika bez zależności i bez operacji I/O. Święta ruchome (Wielkanoc, Zielone Świątki, Boże Ciało) są wyliczane algorytmem Gaussa/Meeusa, a nie zapisane na sztywno dla każdego roku.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the development workflow and GOOD_FIRST_ISSUES.md for ideas if you're looking for a place to start. This project follows the Contributor Covenant.

License

MIT © 2026 Jakub Jagiełło