A HDate represents a Hebrew calendar date.

An instance of this class encapsulates a date in the Hebrew calendar system. It consists of a year, month, and day, without any associated time or location data. The Hebrew calendar is a lunisolar calendar, meaning it is based on both lunar and solar cycles.

A Hebrew date internally stores three numbers:

  • year: The Hebrew year (1-9999). Counted from the traditional Hebrew date of creation (3761 BCE in the Gregorian calendar)
  • month: The Hebrew month (1-13). Month 1 is Nisan, month 7 is Tishrei. There are 12 months in a regular year and 13 months in a leap year.
  • day: The day of the month (1-30)

This class uses Rata Die to convert between the Hebrew and Gregorian calendars.

To calculate times of day, use Zmanim class from @hebcal/core

Constructors

  • Create a Hebrew date. There are 3 basic forms for the HDate() constructor.

    1. No parameters - represents the current Hebrew date at time of instantiation
    2. One parameter
      • Date - represents the Hebrew date corresponding to the Gregorian date using local time. Hours, minutes, seconds and milliseconds are ignored.
      • HDate - clones a copy of the given Hebrew date
      • number - Converts absolute R.D. days to Hebrew date. R.D. 1 == the imaginary date January 1, 1 (Gregorian)
    3. Three parameters: Hebrew day, Hebrew month, Hebrew year. Hebrew day should be a number between 1-30, Hebrew month can be a number or string, and Hebrew year is always a number.

    Parameters

    • Optionalday:
          | number
          | HDate
          | Date
          | SimpleHebrewDate

      Day of month (1-30) if a number. If a Date is specified, represents the Hebrew date corresponding to the Gregorian date using local time. If an HDate is specified, clones a copy of the given Hebrew date.

    • Optionalmonth: string | number

      Hebrew month of year (1=NISAN, 7=TISHREI)

    • Optionalyear: number

      Hebrew year

    Returns HDate

    import {HDate, months} from '@hebcal/hdate';

    const hd1 = new HDate();
    const hd2 = new HDate(new Date(2008, 10, 13));
    const hd3 = new HDate(15, 'Cheshvan', 5769);
    const hd4 = new HDate(15, months.CHESHVAN, 5769);
    const hd5 = new HDate(733359); // ==> 15 Cheshvan 5769
    const monthName = 'אייר';
    const hd6 = new HDate(5, monthName, 5773);

Properties

dd: number

Hebrew day within the month (1-30)

mm: number

Hebrew month of year (1=NISAN, 7=TISHREI)

rd?: number

absolute Rata Die (R.D.) days

yy: number

Hebrew year, 1-9999

Methods

  • Converts from Hebrew date representation to R.D. (Rata Die) fixed days. R.D. 1 is the imaginary date Monday, January 1, 1 (Gregorian). Note also that R.D. = Julian Date − 1,721,424.5

    Returns number

    const hd = new HDate(15, 'Cheshvan', 5769);
    hd.abs(); // 733359
  • Returns a cloned HDate object with a specified amount of time added

    Units are case insensitive, and support plural and short forms. Note, short forms are case sensitive.

    Unit Shorthand Description
    day d days
    week w weeks
    month M months
    year y years

    Parameters

    • amount: string | number
    • Optionalunits: string

    Returns HDate

  • Returns an HDate corresponding to the specified day of week after this Hebrew date

    Parameters

    • dayOfWeek: number

      day of week: Sunday=0, Saturday=6

    Returns HDate

    new HDate(new Date('Wednesday February 19, 2014')).after(6).greg() // Sat Feb 22 2014
    new HDate(new Date('Saturday February 22, 2014')).after(6).greg() // Sat Mar 01 2014
    new HDate(new Date('Sunday February 23, 2014')).after(6).greg() // Sat Mar 01 2014
  • Returns an HDate corresponding to the specified day of week before this Hebrew date

    Parameters

    • dayOfWeek: number

      day of week: Sunday=0, Saturday=6

    Returns HDate

    new HDate(new Date('Wednesday February 19, 2014')).before(6).greg() // Sat Feb 15 2014
    
  • Number of days in the month of this Hebrew date (29 or 30)

    Returns number

    an integer 29-30

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.daysInMonth(); // 29
  • Returns the difference in days between the two given HDates.

    The result is positive if this date is comes chronologically after the other date, and negative if the order of the two dates is reversed.

    The result is zero if the two dates are identical.

    Parameters

    • other: HDate

      Hebrew date to compare

    Returns number

    import {HDate, months} from '@hebcal/hdate';

    const hd1 = new HDate(25, months.KISLEV, 5770);
    const hd2 = new HDate(15, months.CHESHVAN, 5769);
    const days = hd1.deltaDays(hd2); // 394
  • Gets the day within the month (1-30)

    Returns number

    an integer 1-30

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.getDate(); // 15
  • Returns the day of the week for this Hebrew date, where 0 represents Sunday, 1 represents Monday, 6 represents Saturday.

    For the day of the month, see getDate()

    Returns number

    an integer 0-6

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.getDate(); // 4
  • Returns the Hebrew year of this Hebrew date

    Returns number

    an integer >= 1

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.getFullYear(); // 5769
  • Returns the Hebrew month (1=NISAN, 7=TISHREI) of this Hebrew date

    Returns number

    an integer 1-13

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.getMonth(); // 8
  • Returns a transliterated Hebrew month name, e.g. 'Elul' or 'Cheshvan'.

    Returns string

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.getMonthName(); // 'Cheshvan'
  • The Tishrei-based month of this Hebrew date. 1 is Tishrei, 7 is Nisan, 13 is Elul in a leap year

    Returns number

    an integer 1-13

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.getTishreiMonth(); // 2
  • Converts this Hebrew date to the corresponding Gregorian date.

    The returned Date object will be in the local (i.e. host system) time zone. Hours, minutes, seconds and milliseconds will all be zero.

    Note that this function returns the daytime portion of the date. For example, the 15th of Cheshvan 5769 began at sundown on 12 November 2008 and continues through 13 November 2008. This function would return only the date 13 November 2008.

    Returns Date

    const hd = new HDate(15, 'Cheshvan', 5769);
    const date = hd.greg(); // 13 November 2008
    const year = date.getFullYear(); // 2008
    const monthNum = date.getMonth() + 1; // 11
    const day = date.getDate(); // 13
  • Returns true if this Hebrew date occurs during a Hebrew leap year

    Returns boolean

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.isLeapYear(); // false
  • Compares this Hebrew date to another date, returning true if the dates match.

    Parameters

    • other: HDate

      Hebrew date to compare

    Returns boolean

    const hd1 = new HDate(new Date(2008, 10, 13));
    const hd2 = new HDate(15, 'Cheshvan', 5769);
    hd1.isSameDate(hd2); // true
  • Returns an HDate corresponding to the specified day of week nearest to this Hebrew date

    Parameters

    • dayOfWeek: number

      day of week: Sunday=0, Saturday=6

    Returns HDate

    new HDate(new Date('Wednesday February 19, 2014')).nearest(6).greg() // Sat Feb 22 2014
    new HDate(new Date('Tuesday February 18, 2014')).nearest(6).greg() // Sat Feb 15 2014
  • Returns the next Hebrew date

    Returns HDate

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.next(); // '16 Cheshvan 5769'
  • Returns an HDate corresponding to the specified day of week on or after this Hebrew date

    Parameters

    • dayOfWeek: number

      day of week: Sunday=0, Saturday=6

    Returns HDate

    new HDate(new Date('Wednesday February 19, 2014')).onOrAfter(6).greg() // Sat Feb 22 2014
    new HDate(new Date('Saturday February 22, 2014')).onOrAfter(6).greg() // Sat Feb 22 2014
    new HDate(new Date('Sunday February 23, 2014')).onOrAfter(6).greg() // Sat Mar 01 2014
  • Returns an HDate corresponding to the specified day of week on or before this Hebrew date

    Parameters

    • dayOfWeek: number

      day of week: Sunday=0, Saturday=6

    Returns HDate

    new HDate(new Date('Wednesday February 19, 2014')).onOrBefore(6).greg() // Sat Feb 15 2014
    new HDate(new Date('Saturday February 22, 2014')).onOrBefore(6).greg() // Sat Feb 22 2014
    new HDate(new Date('Sunday February 23, 2014')).onOrBefore(6).greg() // Sat Feb 22 2014
  • Returns the previous Hebrew date

    Returns HDate

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.prev(); // '14 Cheshvan 5769'
  • Renders this Hebrew date as a translated or transliterated string, including ordinal e.g. '15th of Cheshvan, 5769'.

    Parameters

    • Optionallocale: string

      Optional locale name (defaults to active locale).

    • OptionalshowYear: boolean

      Display year (defaults to true).

    Returns string

    import {HDate, months} from '@hebcal/hdate';

    const hd = new HDate(15, months.CHESHVAN, 5769);
    console.log(hd.render('en')); // '15th of Cheshvan, 5769'
    console.log(hd.render('he')); // '15 חֶשְׁוָן, 5769'
    console.log(hd.render('en', false)); // '15th of Cheshvan'
    console.log(hd.render('he', false)); // '15 חֶשְׁוָן'

    Locale

  • Renders this Hebrew date in Hebrew gematriya, regardless of locale.

    Parameters

    • OptionalsuppressNikud: boolean

    Returns string

    import {HDate, months} from '@hebcal/hdate';
    const hd = new HDate(15, months.CHESHVAN, 5769);
    hd.renderGematriya(); // 'ט״ו חֶשְׁוָן תשס״ט'
    hd.renderGematriya(true); // 'ט״ו חשון תשס״ט'
  • Returns a cloned HDate object with a specified amount of time subracted

    Units are case insensitive, and support plural and short forms. Note, short forms are case sensitive.

    Unit Shorthand Description
    day d days
    week w weeks
    month M months
    year y years

    Parameters

    • amount: number
    • Optionalunits: string

    Returns HDate

    import {HDate, months} from '@hebcal/hdate';

    const hd1 = new HDate(15, months.CHESHVAN, 5769);
    const hd2 = hd1.add(1, 'weeks'); // 7 Kislev 5769
    const hd3 = hd1.add(-3, 'M'); // 30 Av 5768
  • Returns a string representation of this Hebrew date using English transliterations

    Returns string

    const hd = new HDate(new Date(2008, 10, 13)); // 15 Cheshvan 5769
    hd.toString(); // '15 Cheshvan 5769'
  • Convenience function for determining the R.D. date near a specified R.D. date, corresponding to the specified day of week.

    Note: Applying this function to d+6 gives us the dayOfWeek on or after an absolute day d. Similarly, applying it to d+3 gives the dayOfWeek nearest to absolute date d, applying it to d-1 gives the dayOfWeek previous to absolute date d, and applying it to d+7 gives the dayOfWeek following absolute date d.

    Parameters

    • dayOfWeek: number

      day of week: Sunday=0, Saturday=6

    • absdate: number

    Returns number

  • Number of days in Hebrew month in a given year (29 or 30)

    Parameters

    • month: number

      Hebrew month (e.g. months.TISHREI)

    • year: number

      Hebrew year

    Returns number

    import {HDate, months} from '@hebcal/hdate';
    HDate.daysInMonth(months.CHESHVAN, 5769); // 29
  • Number of days in the Hebrew year. Regular years can have 353, 354, or 355 days. Leap years can have 383, 384, or 385 days.

    Parameters

    • year: number

      Hebrew year

    Returns number

    HDate.daysInYear(5783); // 355
    HDate.daysInYear(5784); // 383
  • Construct a new instance of HDate from a Gematriya-formatted string

    Parameters

    • str: string
    • OptionalcurrentThousands: number

    Returns HDate

    HDate.fromGematriyaString('כ״ז בְּתַמּוּז תשפ״ג') // 27 Tamuz 5783
    HDate.fromGematriyaString('כ׳ סיון תש״ד') // 20 Sivan 5704
    HDate.fromGematriyaString('ה׳ אִיָיר תש״ח') // 5 Iyyar 5708
  • Returns a transliterated string name of Hebrew month in year, for example 'Elul' or 'Cheshvan'.

    Parameters

    • month: number

      Hebrew month (e.g. months.TISHREI)

    • year: number

      Hebrew year

    Returns string

    import {HDate, months} from '@hebcal/hdate';
    HDate.getMonthName(months.CHESHVAN, 5769); // 'Cheshvan'
  • Converts Hebrew date to R.D. (Rata Die) fixed days. R.D. 1 is the imaginary date Monday, January 1, 1 on the Gregorian Calendar.

    Parameters

    • year: number

      Hebrew year

    • month: number

      Hebrew month (1=NISAN, 7=TISHREI)

    • day: number

      Hebrew date (1-30)

    Returns number

    import {HDate, months} from '@hebcal/hdate';
    HDate.hebrew2abs(5769, months.CHESHVAN, 15); // 733359
  • Tests if the object is an instance of HDate

    Parameters

    • obj: any

    Returns boolean

    HDate.isHDate(new HDate()); // true
    HDate.isHDate(new Date()); // false
    HDate.isHDate(null); // false
    HDate.isHDate(12345); // false
    HDate.isHDate('15 Cheshvan 5769'); // false
  • Returns true if Hebrew year is a leap year

    Parameters

    • year: number

      Hebrew year

    Returns boolean

    HDate.isLeapYear(5783); // false
    HDate.isLeapYear(5784); // true
  • true if Cheshvan is long in Hebrew year

    Parameters

    • year: number

      Hebrew year

    Returns boolean

    HDate.longCheshvan(5783); // true
    HDate.longCheshvan(5784); // false
  • Converts Hebrew month string name to numeric

    Parameters

    • monthName: string | number

    Returns number

    import {HDate, months} from '@hebcal/hdate';
    HDate.monthFromName(months.CHESHVAN); // 8
    HDate.monthFromName('Cheshvan'); // 8
    HDate.monthFromName('חשון'); // 8
  • Returns the Hebrew month number (NISAN=1, TISHREI=7)

    Parameters

    • month: string | number

      A number, or Hebrew month name string

    Returns number

    import {HDate, months} from '@hebcal/hdate';
    HDate.monthNum(months.CHESHVAN); // 8
    HDate.monthNum('Cheshvan'); // 8
    HDate.monthNum('חשון'); // 8
  • Number of months in this Hebrew year (either 12 or 13 depending on leap year)

    Parameters

    • year: number

      Hebrew year

    Returns number

    HDate.monthsInYear(5783); // 12
    HDate.monthsInYear(5784); // 13
  • true if Kislev is short in Hebrew year

    Parameters

    • year: number

      Hebrew year

    Returns boolean

    HDate.shortKislev(5783); // false
    HDate.shortKislev(5784); // true