DEV Community: UpcomingDays

Your holiday library is probably right. Here are the days it got wrong for us, and the correction layer we built

UpcomingDays — Thu, 08 Oct 2026 22:14:46 +0000

If you calculate business days, delivery dates or payroll in more than one country, you probably use the excellent open-source holidays package for Python. We do too. It covers more than 200 countries and territories and is right almost all of the time.

"Almost" matters when you publish holiday lists that people plan around. So before we list a country, we compare the library's dates with the government's own announcements. Thirteen countries needed at least one correction. None of these are really bugs. Governments publish decisions the library can't know in advance. But the patterns are worth knowing if holiday data feeds anything important.

The five kinds of mismatch we found

1. Holidays moved by decree to make a long weekend. Kuwait and Oman often move a holiday to a Thursday or Sunday. The library computes the "natural" date:

Country	Holiday (2026)	`holidays` 0.105	Official
Kuwait	Prophet's Birthday	Aug 25 (estimated)	Aug 27
Oman	Sultan's Accession Day	Jan 11	Jan 15
Oman	National Day	Nov 20–21	Nov 25–26

2. Lunar dates confirmed differently from the estimate. Islamic holidays depend on a moon sighting or an official calendar. Tanzania announced Eid al-Adha 2026 for May 27, where the library has May 28. India's central government list puts Holi 2027 on March 23, a day after the library's date.

3. A fixed date that's just off by one. Morocco's Amazigh New Year is January 14 by royal decree. The library has January 13.

4. Missing days. Morocco added Unity Day (October 31) as a national holiday from 2026. Ethiopia's statutory list includes Downfall of the Derg (May 28). Costa Rica has three days that are paid only if worked: August 2, August 31 and December 1. Whether those count as "holidays" depends on your use case, which is exactly why you want to decide that explicitly.

5. Regional days listed as national. Guatemala's Assumption Day (August 15) is a holiday in Guatemala City only, not nationwide.

The correction layer

We didn't want to fork the library. Instead, a thin layer sits on top with three tables: date overrides, additions and removals. In our production version, each entry has a comment naming the official source.

import warnings
import holidays

# (country, name, date the library gives) -> official date
OVERRIDES = {
    ("MA", "Amazigh New Year", "2026-01-13"): "2026-01-14",
    ("KW", "Prophet's Birthday (estimated)", "2026-08-25"): "2026-08-27",
}
# Nationwide days the library is missing: (country, year) -> [(date, name)]
ADDITIONS = {
    ("MA", 2026): [("2026-10-31", "Unity Day")],
    ("CR", 2026): [("2026-08-02", "Our Lady of the Angels Day")],
}
# Listed as nationwide, but regional only: (country, name)
REMOVALS = {("GT", "Assumption Day")}

def corrected(code, year):
    used = set()
    rows = []
    for d, name in sorted(holidays.country_holidays(code, years=year, language="en_US").items()):
        if (code, name) in REMOVALS:
            continue
        key = (code, name, d.isoformat())
        if key in OVERRIDES:
            used.add(key)
            rows.append((OVERRIDES[key], name.replace(" (estimated)", "")))
        else:
            rows.append((d.isoformat(), name))
    rows += ADDITIONS.get((code, year), [])
    # An override that matched nothing means the library changed: re-check it.
    for key in OVERRIDES:
        if key[0] == code and key[2].startswith(str(year)) and key not in used:
            warnings.warn(f"stale override {key}")
    return sorted(rows)

for code in ("MA", "KW", "GT"):
    for row in corrected(code, 2026):
        if any(k in row[1] for k in ("Amazigh", "Unity", "Prophet", "Assumption")):
            print(code, *row)

With holidays==0.105:

MA 2026-01-14 Amazigh New Year
MA 2026-08-25 Prophet's Birthday (estimated)
MA 2026-08-26 Prophet's Birthday (estimated)
MA 2026-10-31 Unity Day
KW 2026-08-27 Prophet's Birthday

Guatemala's Assumption Day is gone, Kuwait's date is moved, and Morocco gains Unity Day.

Three details made this hold up over time:

Key overrides on the library's own value, not just the holiday name. ("MA", "Amazigh New Year", "2026-01-13") only applies while the library still says January 13. If a new release fixes it upstream, the key stops matching.
Warn on stale overrides. That unmatched key then raises a warning instead of silently doing nothing. Our first run of this snippet showed why: without language="en_US", Morocco's names come back in Arabic, nothing matched, and the warnings fired straight away.
Clear the "estimated" flag when you apply an official date. The library marks some lunar dates as (estimated). Once you've replaced one with a government-announced date, it isn't an estimate any more, and your UI shouldn't say it is.

Where the official dates come from

Each correction has a primary source: a government circular (Kuwait, Bahrain, Jordan), a labour ministry calendar (Oman, Costa Rica), a royal decree (Morocco), India's DoPT holiday order for central government offices, or national news coverage of the announcement (Tanzania). Record the source next to the override, because you'll need it again next year when the dates change.

Please report what you find upstream as well. A fix in the library is better than a fix in everyone's correction layer.

We use this layer for the country holiday pages on UpcomingDays, where I work. The snippet above is standalone and needs only pip install holidays.

This article was written with the help of AI. The code was run against holidays 0.105, and each correction was checked against the official source named in our data before publishing.

Computing Eid, Rosh Hashanah and Lunar New Year dates in JavaScript with Intl calendars, and where it goes wrong

UpcomingDays — Thu, 08 Oct 2026 22:03:43 +0000

Most "how many days until…" code is easy until someone asks about Eid al-Fitr, Hanukkah or Lunar New Year. These holidays follow lunar or lunisolar calendars, so they move against the Gregorian calendar every year.

You don't need a library for most of them. Modern JavaScript engines ship ICU, and Intl.DateTimeFormat can render any date in the Hebrew, Islamic (Umm al-Qura) or Chinese calendar. With a little scanning, that gives you the Gregorian date of a holiday. It also has a few traps. Below is the approach we use, plus the three places it went wrong for us.

The idea: scan the year and ask Intl what day it is

Intl converts from Gregorian to another calendar, but there's no built-in conversion back. So for a target year, walk through every day and keep the ones whose calendar month and day match what you want. That's 365 formatter calls, which is fast enough, and easy to cache per year.

const DAY_MS = 86_400_000;

// ICU spells some month names with special characters ("Dhuʻl-Hijjah"),
// so compare normalised strings.
function normalize(s) {
  return s.toLowerCase().normalize("NFD")
    .replace(/[\u0300-\u036f]/g, "")   // strip accents
    .replace(/[ʻʼ'’`-]/g, "")          // "Dhuʻl-Hijjah" -> "dhulhijjah"
    .trim();
}

// Every Gregorian date in `year` that falls on `day` of `month` in `calendar`.
function findDates(calendar, year, month, day) {
  const fmt = new Intl.DateTimeFormat(`en-u-ca-${calendar}`, {
    timeZone: "UTC", month: "long", day: "numeric",
  });
  const hits = [];
  for (let t = Date.UTC(year, 0, 1); t < Date.UTC(year + 1, 0, 1); t += DAY_MS) {
    const parts = fmt.formatToParts(new Date(t));
    const m = parts.find((p) => p.type === "month").value;
    const d = Number(parts.find((p) => p.type === "day").value);
    if (normalize(m) === normalize(month) && d === day) {
      hits.push(new Date(t).toISOString().slice(0, 10));
    }
  }
  return hits;
}

console.log(findDates("hebrew", 2026, "Tishri", 1));                // Rosh Hashanah
console.log(findDates("hebrew", 2026, "Kislev", 25));               // Hanukkah, first day
console.log(findDates("islamic-umalqura", 2026, "Shawwal", 1));      // Eid al-Fitr
console.log(findDates("islamic-umalqura", 2026, "Dhul-Hijjah", 10)); // Eid al-Adha

Output on Node 24 (ICU 78):

[ '2026-09-12' ]
[ '2026-12-05' ]
[ '2026-03-20' ]
[ '2026-05-27' ]

Two details matter:

Use timeZone: "UTC" and UTC midnights. Otherwise the formatter applies your machine's offset, and dates near midnight drift by a day depending on where the code runs.
Return an array, not a single date. That's the first trap.

Trap 1: one Gregorian year can contain the same Islamic date twice

The Islamic year is about 354 days, about 11 days shorter than the Gregorian year. Every 33 years or so, a date comes round twice in one Gregorian year:

console.log(findDates("islamic-umalqura", 2030, "Ramadan", 1));
// [ '2030-01-05', '2030-12-26' ]

Ramadan starts twice in 2030. If your function returns only the first match, a countdown in mid-2030 will look backwards and say "Ramadan already started". For "next occurrence" logic, search this year and next year, then pick the first date on or after today.

Trap 2: Umm al-Qura is a prediction, not what every country observes

islamic-umalqura is Saudi Arabia's calculated calendar. Many countries and communities start Ramadan and the Eids based on a local sighting of the crescent moon. Their dates can differ by a day, and they aren't known for certain until the night before.

Treat the computed date as an estimate, and say so in the UI. For public-holiday purposes, governments often publish their own dates. Those should win over anything you calculate.

Hebrew calendar dates don't have this problem: that calendar is arithmetic, so ICU's results are exact. Do remember that Jewish holidays begin at sundown on the previous evening. Rosh Hashanah 2026 is Saturday, September 12, but it begins on the evening of the 11th.

Trap 3: ICU's Chinese calendar can be off by a day

You can also pull the start of the Chinese calendar's first month out of Intl:

const cfmt = new Intl.DateTimeFormat("en-u-ca-chinese", {
  timeZone: "UTC", month: "numeric", day: "numeric",
});

for (const y of [2026, 2027, 2028]) {
  for (let t = Date.UTC(y, 0, 15); t < Date.UTC(y, 2, 1); t += DAY_MS) {
    const p = cfmt.formatToParts(new Date(t));
    if (p.find((x) => x.type === "month").value === "1" &&
        p.find((x) => x.type === "day").value === "1") {
      console.log(y, new Date(t).toISOString().slice(0, 10));
      break;
    }
  }
}
// 2026 2026-02-17
// 2027 2027-02-07   <- wrong
// 2028 2028-01-26

2026 and 2028 are right, but the Hong Kong Observatory's 2027 conversion table puts the first day of the first lunar month on February 6, 2027, and Hong Kong's gazetted public holiday is also February 6. ICU says the 7th.

So for Lunar New Year we stopped computing and use a small table checked against an official source instead. It's 20 lines of data, and it can't drift. We do the same for Diwali, which follows regional Hindu almanacs (panchang) that no Intl calendar implements.

What we ended up with

Hebrew holidays: computed with Intl, exact. Remember the sundown start.
Islamic holidays: computed with islamic-umalqura, always shown as an estimate, and overridden by official government dates where they exist. Return all matches in a year.
Lunar New Year and Diwali: curated tables with sources and an explicit coverage range. Outside that range we say "not listed for this year" rather than guess.

The tests matter more than the code. Our test suite pins known dates, for example Eid al-Fitr on March 20, 2026, Eid al-Adha on May 27, 2026, and Rosh Hashanah starting on the evening of September 11, 2026. That way an ICU update can't silently move a holiday.

This is the approach behind the holiday countdowns on UpcomingDays, where I work. The snippets above are standalone and run as they are in Node 18+ or any modern browser.

This article was written with the help of AI. The code was run and the dates were checked against the sources named above before publishing.