Jewish Holidays

An easy-to-use npm package for checking Jewish holidays and Shabbat.

To install the package, run one of the following commands:

npm i jewish-holidays

or with yarn

yarn add jewish-holidays

Usage

You can use the package in your JavaScript projects as shown below:

import { isYomTov, isShabbat } from 'jewish-holidays';

// Check if a date is Yom Tov
const date = new Date();
const isInChutzLaaretz = true; // Adjust as needed
console.log(isYomTov(date, isInChutzLaaretz)); // true or false

// Check if a date is Shabbat
console.log(isShabbat(date)); // true or false

Functions

getDateInfo

getDateInfo(date: Date | BasicJewishDate, isChutzLaaretz?: boolean, language?: Language) => DateInfo

Returns a full summary of the given date, aggregating every holiday/observance check in a single object.

• date: A JavaScript Date object or a BasicJewishDate object.
• isChutzLaaretz: (optional) A boolean indicating if the calculation should consider diaspora holidays.
• language: (optional) 'en' or 'he' — the language to report names in. Defaults to 'en'. See Languages.

The returned DateInfo object contains the normalized jewishDate, the boolean flags isYomTov, isErevYomTov, isCholHaMoed, isShabbat, isErevShabbat, isRoshChodesh, isChanukah, isPurim, isTzom, and holidays — the name(s) of any matched observance (the specific Yom Tov name(s), the specific Purim name (Purim or Shushan Purim), the specific fast name (e.g. Tisha BeAv), plus a label for each of Chol HaMoed, Rosh Chodesh and Chanukah), or an empty array. Each observance is named only once, so 10 Tishri is ["Yom Kippur"] rather than a Yom Tov entry and a separate fast entry.

On a fast day it also carries tzom, a TzomInfo object naming the fast and saying how it was shifted off Shabbat, if at all — see getTzomInfo. The field is absent on every other day.

import { getDateInfo } from 'jewish-holidays';

const info = getDateInfo(new Date(2024, 9, 3)); // Rosh Hashanah
console.log(info.isYomTov); // true
console.log(info.holidays); // ["Rosh Hashanah", "Rosh Chodesh"]

const fast = getDateInfo(new Date(2029, 6, 22)); // 10 Av 5789
console.log(fast.tzom); // { name: "Tisha BeAv", shift: "postponed" }
console.log(fast.holidays); // ["Tisha BeAv"]

const hebrew = getDateInfo(new Date(2029, 6, 22), false, 'he');
console.log(hebrew.tzom); // { name: "תשעה באב", shift: "postponed" }
console.log(hebrew.holidays); // ["תשעה באב"]

getTodayInfo

getTodayInfo(isChutzLaaretz?: boolean, language?: Language) => DateInfo

A convenience wrapper that returns getDateInfo for today's date (new Date()).

• isChutzLaaretz: (optional) A boolean indicating if the calculation should consider diaspora holidays.
• language: (optional) 'en' or 'he'. Defaults to 'en'.

isYomTov

isYomTov(date: Date | BasicJewishDate, isChutzLaaretz: boolean) => boolean

Determines if the given date is a Yom Tov (Jewish holiday).

• date: A JavaScript Date object or a BasicJewishDate object.
• isChutzLaaretz: A boolean indicating if the calculation should consider diaspora holidays.

isShabbat

isShabbat(date: Date | BasicJewishDate) => boolean

Determines if the given date is Shabbat.

• date: A JavaScript Date object or a BasicJewishDate object.

isErevShabbat

isErevShabbat(date: Date | BasicJewishDate) => boolean

Determines if the given date is Erev Shabbat (Friday).

• date: A JavaScript Date object or a BasicJewishDate object.

isErevYomTov

isErevYomTov(date: Date | BasicJewishDate) => boolean

Determines if the given date is Erev Yom Tov (the day before a Jewish holiday).

• date: A JavaScript Date object or a BasicJewishDate object.

isCholHaMoed

isCholHaMoed(date: Date | BasicJewishDate, isChutzLaaretz?: boolean) => boolean

Determines if the given date is Chol HaMoed (the intermediate days of Passover or Sukkot).

• date: A JavaScript Date object or a BasicJewishDate object.
• isChutzLaaretz: (optional) A boolean indicating if the calculation should consider diaspora holidays.

isRoshChodesh

isRoshChodesh(date: Date | BasicJewishDate) => boolean

Determines if the given date is Rosh Chodesh (the beginning of a new Jewish month).

• date: A JavaScript Date object or a BasicJewishDate object.

isChanukah

isChanukah(date: Date | BasicJewishDate) => boolean

Determines if the given date is during Chanukah.

• date: A JavaScript Date object or a BasicJewishDate object.

isPurim

isPurim(date: Date | BasicJewishDate) => boolean

Determines if the given date is Purim.

• date: A JavaScript Date object or a BasicJewishDate object.

isTzom

isTzom(date: Date | BasicJewishDate) => boolean

Determines if the given date is a Jewish fast day (Tzom).

• date: A JavaScript Date object or a BasicJewishDate object.

A fast whose calendar date falls on Shabbat is observed on another day, so this returns false for the Shabbat and true for the day the fast moved to.

getTzomInfo

getTzomInfo(date: Date | BasicJewishDate, language?: Language) => TzomInfo | undefined

Returns the fast day observed on the given date, or undefined when it is not a fast day.

• date: A JavaScript Date object or a BasicJewishDate object.
• language: (optional) 'en' or 'he'. Defaults to 'en'.

TzomInfo is { name: string; shift: "postponed" | "advanced" | null }. A fast observed on its own calendar date has shift: null. When the calendar date falls on Shabbat the fast is either postponed to the Sunday (Tzom Gdalia, Shiva Asar BeTamuz, Tisha BeAv) or advanced to the preceding Thursday (Taanit Esther, whose Sunday is Purim itself, and Taanit Bechorot, whose Sunday is Erev Pesach). Yom Kippur is fasted on Shabbat itself, and Asara BeTevet can fall on Friday but never on Shabbat.

import { getTzomInfo } from 'jewish-holidays';

getTzomInfo(new Date(2029, 6, 22)); // { name: "Tisha BeAv", shift: "postponed" }
getTzomInfo(new Date(2024, 2, 21)); // { name: "Taanit Esther", shift: "advanced" }
getTzomInfo(new Date(2025, 2, 13)); // { name: "Taanit Esther", shift: null }
getTzomInfo(new Date(2024, 2, 23)); // undefined — 13 AdarII fell on Shabbat
getTzomInfo(new Date(2029, 6, 22), 'he'); // { name: "תשעה באב", shift: "postponed" }

shift is a stable discriminator, not display text, so it stays in English in both languages — render it yourself, e.g. נדחה for "postponed" and מוקדם for "advanced".

getTzomotList

getTzomotList() => Tzom[]

Returns the list of fast days, each a Holiday plus shiftOnShabbat, the rule that applies when its calendar date falls on Shabbat ("postponed", "advanced", or null for the fasts that are never shifted).

import { getTzomotList } from 'jewish-holidays';

console.log(getTzomotList()[0]);
// { day: 3, monthName: "Tishri", name: "Tzom Gdalia",
//   hebrewName: "צום גדליה", shiftOnShabbat: "postponed" }

Languages

Names are available in transliterated English and in Hebrew. Language is 'en' | 'he', and 'en' is the default everywhere, so existing code keeps returning exactly what it did before.

Every entry a holiday list returns carries both names — name and hebrewName — so getTzomotList, getYomTovList and getPurimList take no argument and a bilingual consumer needs only one call:

import { getTzomotList, getHolidayName } from 'jewish-holidays';

const tishaBeAv = getTzomotList().find((t) => t.name === 'Tisha BeAv');
console.log(tishaBeAv.name);       // "Tisha BeAv"
console.log(tishaBeAv.hebrewName); // "תשעה באב"

getHolidayName(tishaBeAv, 'he'); // "תשעה באב"

The functions that report a single resolved name — getDateInfo, getTodayInfo and getTzomInfo — take a language argument that decides which one lands in holidays and tzom.name:

getDateInfo(new Date(2024, 9, 3)).holidays;              // ["Rosh Hashanah", "Rosh Chodesh"]
getDateInfo(new Date(2024, 9, 3), false, 'he').holidays; // ["ראש השנה", "ראש חודש"]

getHolidayName

getHolidayName(holiday: Holiday, language?: Language) => string

Returns a holiday's name in the requested language.

• holiday: Any Holiday (or Tzom) entry.
• language: (optional) 'en' or 'he'. Defaults to 'en'.

License

MIT