Every few months somebody on a team I'm helping says "it's just business days, how hard can it be?" and then we spend an afternoon arguing about whether a Friday counts. Here are the three bugs I run into most often, with the sources I check before I trust any calendar logic.
1. "Weekend" is not a constant
The most common shortcut is day === 0 || day === 6. In JavaScript, Date.prototype.getDay() returns 0 for Sunday through 6 for Saturday (MDN), so that line hard-codes a Saturday/Sunday weekend.
That assumption breaks fast once you leave the US. The UAE's official government portal says federal entities moved to a four-and-a-half-day week effective January 1, 2022: Monday to Thursday plus a half day Friday, with Saturday and Sunday as the official weekend. Same page, one emirate over: the Government of Sharjah works Monday to Thursday, and its official weekend is three days, Friday through Sunday (u.ae, working hours in the public sector).
So "the UAE weekend" isn't even one value, and it changed within the last few years. If your data model stores a country code and derives the weekend from it, you will be wrong for someone. Store the weekend as data, per calendar, and expect it to change.
Bonus trap: languages disagree on numbering. JS getDay() is Sunday = 0. Python's date.isoweekday() follows ISO 8601, Monday = 1 through Sunday = 7, while date.weekday() is Monday = 0 (Python docs). I've seen a backend and frontend disagree by a whole day because one side sent 5 and meant Friday, the other read Saturday.
2. Substitute holidays have their own rules
A holiday list that only contains fixed dates misses substitute (observed) days, and the rules for those are country-specific and sometimes holiday-specific.
South Korea is a good example. Under the Regulations on Public Holidays of Government Offices, substitute holidays have existed for most national holidays since 2021, and a May 2023 revision added Buddha's Birthday and Christmas. Yonhap reported that Buddha's Birthday 2023 fell on a Saturday, so the following Monday became the day off (Yonhap, May 2, 2023).
The detail that bites people: the regulation treats holidays differently. Most get a substitute when they land on a Saturday or Sunday, but the three-day Lunar New Year and Chuseok blocks only trigger one when a day overlaps a Sunday or another holiday. And if the computed substitute itself lands on a Saturday, it rolls to the next non-holiday (Korean Law Information Center, Article 3). A generic "if weekend, move to Monday" function gets this wrong.
My rule now: don't compute substitute days yourself unless you've read the actual regulation. Pull observed dates from an official published calendar and store them as explicit rows.
3. Inclusive vs. exclusive end dates
"How many business days from March 2 to March 6?" Is that 4 or 5? Both answers are defensible, and that's the problem. Contracts, payroll, and shipping SLAs pick differently, and the UI rarely says which one it used.
I now treat ranges as half-open [start, end) internally, the same convention most date libraries use for intervals, and make inclusivity an explicit flag at the edge:
// weekend: Set of getDay() values, e.g. new Set([6, 0]) or new Set([5, 6, 0]) for Sharjah // holidays: Set of "YYYY-MM-DD" strings, including substitute days function businessDays(start, end, { weekend, holidays, inclusiveEnd = false }) { const d = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate())); const stop = new Date(Date.UTC(end.getUTCFullYear(), end.getUTCMonth(), end.getUTCDate())); if (inclusiveEnd) stop.setUTCDate(stop.getUTCDate() + 1); let count = 0; for (; d < stop; d.setUTCDate(d.getUTCDate() + 1)) { const key = d.toISOString().slice(0, 10); if (!weekend.has(d.getUTCDay()) && !holidays.has(key)) count++; } return count; } Two choices in there are deliberate. Everything runs in UTC on date-only values, so a DST shift can't produce a 23-hour "day" that the loop double-counts or skips. And the weekend is a parameter, not a constant.
How I sanity-check
Unit tests catch regressions, but they only check what I already believed. When I change calendar logic I compare a handful of ranges against an independent tool. Lately I've used WorkdayMap for that because it lets me set a custom workweek and holidays, which is exactly the part I'm usually unsure about. If my number and the tool's disagree, the bug is almost always one of the three above.
What's the weirdest calendar rule you've had to encode? I'm collecting them.

