@ph-dev-utils/dates

Philippine date utilities for JS + PHP — business-day arithmetic (PH holiday-aware) and Filipino (Tagalog) date formatting. Companion to @ph-dev-utils/core (uses its bundled 2025–2026 PH holiday calendar).

npm install @ph-dev-utils/dates              # JS
composer require phdevutils/dates             # PHP

Why

Every PH HR / leave / cutoff / accounting / SLA app hits the same problem: "what date is N business days from today, skipping weekends and the PH holiday calendar?" — and the late-December gauntlet (Christmas Eve, Christmas, Rizal Day, New Year's Eve all in one stretch) is where naive implementations break. This package gets that right out of the box.

JS usage

import {
  isBusinessDay, addBusinessDays, subBusinessDays, businessDaysBetween,
  nextBusinessDay, previousBusinessDay,
  formatFilipino, filipinoMonth, filipinoDay,
} from '@ph-dev-utils/dates';

isBusinessDay('2026-05-25');                       // true  (Monday)
isBusinessDay('2026-12-25');                       // false (Christmas)
isBusinessDay('2026-05-30', { saturdayIsBusinessDay: true }); // true (6-day workweek)

addBusinessDays('2026-12-23', 1);                  // '2026-12-28' (skips Christmas Eve + Christmas + weekend)
businessDaysBetween('2026-12-21', '2026-12-31');   // 5 (Christmas week + Rizal Day + Last Day all excluded)

formatFilipino('2026-05-25');                      // 'Lunes, 25 ng Mayo 2026'
formatFilipino('2026-05-25', { style: 'short' });  // 'Lun, 25 Mayo 2026'
formatFilipino('2026-05-25', { style: 'date' });   // '25 ng Mayo 2026'
filipinoMonth(5);                                  // 'Mayo'
filipinoDay(1);                                    // 'Lunes'

PHP usage

use PhDevUtils\Dates\{BusinessDays, Format};

BusinessDays::isBusinessDay('2026-05-25');                 // true
BusinessDays::isBusinessDay('2026-12-25');                 // false
BusinessDays::addBusinessDays('2026-12-23', 1);            // '2026-12-28'
BusinessDays::businessDaysBetween('2026-12-21', '2026-12-31'); // 5

Format::filipino('2026-05-25');                            // 'Lunes, 25 ng Mayo 2026'
Format::filipino('2026-05-25', ['style' => 'short']);      // 'Lun, 25 Mayo 2026'
Format::month(5);                                          // 'Mayo'
Format::day(1);                                            // 'Lunes'

Options for business-day functions

interface BusinessDayOptions {
  saturdayIsBusinessDay?: boolean;   // default false (PH standard 5-day week)
  sundayIsBusinessDay?: boolean;     // default false
  extraNonBusinessDates?: string[];  // company shutdown days, e.g. ['2026-12-29', '2026-12-30']
  excludeSpecialWorking?: boolean;   // default false — "special working" days ARE business days
}

About "special working" days: PH proclaims some days as "special working" (work proceeds at 100% pay, no premium) — e.g. Holy Saturday some years, or specific local holidays. They ARE business days by default. Set excludeSpecialWorking: true if your business actually closes on them.

Date type handling

Public APIs accept either ISO YYYY-MM-DD strings or native Date / DateTimeInterface. Internally everything is normalized to ISO strings to avoid timezone foot-guns. Functions return ISO strings, not Date/DateTime objects — wrap them in your call site if you need richer types.

Family

Part of @ph-dev-utils:

• @ph-dev-utils/core — peso, govt IDs, phone, PSGC regions/provinces/cities, holidays (this package's dep)
• @ph-dev-utils/payroll — SSS, PhilHealth, Pag-IBIG, BIR WT on compensation, de minimis caps, ₱90k exemption
• @ph-dev-utils/bir — VAT, percentage tax, BIR form reference
• @ph-dev-utils/psgc-barangays — full 42k PSGC barangay dataset
• @ph-dev-utils/faker — PH-localized fake-data generator including faker.payslip()
• @ph-dev-utils/dates — this one

License

MIT