parse-hebrew-date

Turn the messy Hebrew dates people actually type — "Chof Gimmel Shvat", "ר״ח אדר", "Chof Hey Nissan (Isru Chag Pesach) ~ April 21" — into structured day / month / year components.

npm install parse-hebrew-date

MIT, and no runtime dependencies.

import { parseHebrewDate } from 'parse-hebrew-date';

parseHebrewDate('Chof Gimmel Shvat');
// { day: 23, month: 'Shvat', input: 'Chof Gimmel Shvat', strategy: 'transliterated' }

parseHebrewDate('כ״ג בשבט תשפ״ג');
// { day: 23, month: 'Shvat', year: 5783, input: 'כ״ג בשבט תשפ״ג', strategy: 'gematriya' }

parseHebrewDate('not a date');
// null

Why this exists

Hebrew dates in real datasets — genealogy sheets, shul yahrzeit lists, family calendars — are rarely clean Hebrew script. They are phonetic English typed by whoever kept the list, mixed with abbreviations, parenthetical notes and a Gregorian date stapled on with a tilde.

Libraries like @hebcal/core handle everything downstream of a clean date — conversion, holidays, candle-lighting — and handle it far better than this package ever would. What is missing is the layer underneath: turning what somebody actually typed into a date at all.

| Layer | Handled | | --- | --- | | "כ״ג בשבט תשפ״ג" — clean gematria, nikud, implied thousands digit | ✅ | | "Chof Gimmel Shvat" — transliterated phonetic English | ✅ | | "ר״ח אדר" / "Rosh Chodesh Nissan" — Rosh Chodesh shorthand | ✅ | | "מנחם אב", "Adar Sheini" — compound and qualified month names | ✅ | | "… (Isru Chag Pesach) ~ April 21" — notes, separators, stray years | ✅ | | Gregorian conversion, holidays, zmanim | ❌ — use @hebcal/core |

The output is deliberately plain data, not a date object. Feed it to @hebcal/core or anything else once you know which Hebrew year you are projecting it onto.

What it parses

| Input | Output | | --- | --- | | Chof Gimmel Shvat | 23 Shvat | | Tes Vov Shvat | 15 Shvat | | Chai Elul | 18 Elul | | Yud Beis Menachem Av | 12 Av | | Alef Adar Sheini | 1 Adar II | | 23 Shvat / 15th Shvat | 23 Shvat / 15 Shvat | | כ״ג בשבט תשפ״ג | 23 Shvat 5783 | | כ״ז בְּתַמּוּז תשע״ג | 27 Tamuz 5773 | | כ"ג בשבט תשפ"ג (ASCII quotes) | 23 Shvat 5783 | | ט״ו בשבט | 15 Shvat | | חי אלול | 18 Elul | | ה׳ מנחם אב תשנ״ח | 5 Av 5758 | | ר״ח אדר | 1 Adar | | ר״ח אדר ב | 1 Adar II | | Rosh Chodesh Nissan | 1 Nisan | | Chof Hey Nissan (Isru Chag Pesach) | 25 Nisan, note Isru Chag Pesach | | Chof Gimmel Shvat 5758 | 23 Shvat 5758 | | ח' שבט ~ January 23 | 8 Shvat | | January 23 ~ ח' שבט | 8 Shvat | | garbage | null |

Handled along the way: mixed case, hyphenated numerals, nikud, geresh/gershayim typed as ASCII ' and ", the ב prefix on a month name, the many spellings of one month (Shvat / Shevat / Shevet, Cheshvan / Heshvan / Marcheshvan), extra whitespace, and the backslash-escaped \~ that CSV exports leave behind.

API

parseHebrewDate(input: string): HebrewDateParts | null

Returns null for anything it cannot read. It never throws, including on null, undefined or a non-string — safe to map straight over a spreadsheet column.

parseHebrewDateOrThrow(input: string): HebrewDateParts

The same, but throws HebrewDateParseError (which carries the offending .input) instead of returning null.

HebrewDateParts

interface HebrewDateParts {
  day: number;              // 1–30
  month: HebrewMonthName;   // canonical name
  year?: number;            // Hebrew year, only when the input carried one
  note?: string;            // text found in parentheses
  input: string;            // the original string, untouched
  strategy: ParseStrategy;  // which layer read it
}

strategy is 'gematriya' (delegated to @hebcal/hdate), 'hebrew-script', 'transliterated' or 'rosh-chodesh'. It is useful for triaging an import: a column that comes back entirely 'gematriya' is clean data, one full of 'transliterated' is not.

HEBREW_MONTHS

The fourteen canonical month names, in calendar order from Tishrei:

Tishrei, Cheshvan, Kislev, Tevet, Shvat, Adar, Adar I, Adar II, Nisan, Iyyar, Sivan, Tamuz, Av, Elul.

Notes on behaviour

• Adar. An unqualified Adar stays 'Adar' unless the input also carries a Hebrew year, in which case it becomes 'Adar II' in a leap year — the Adar that Purim falls in — and 'Adar' otherwise. Named outright, 'Adar I' / 'Adar II' are always honoured as written, in either spelling (אדר א / אדר ראשון, Adar Sheini), and in a common year too.
• Years. Only Hebrew years are reported. A plain-digit year is read in the range 5700–5999; a Hebrew-script year in 5400–5999 (1640–2239 CE). A trailing Gregorian year is dropped rather than reported.
• Days are validated. A day outside 1–30 makes the whole parse fail rather than returning an impossible date.
• No calendar maths. This package extracts components. It does not convert to Gregorian, resolve a recurrence, or tell you whether 30 Cheshvan exists in a given year — use @hebcal/core for that. A date that cannot exist comes back exactly as written: ל׳ אלול תשפ״ג parses to 30 Elul 5783 rather than being silently rolled forward to 1 Tishrei 5784. Validating against a real calendar is the caller's job, and needs to stay visible.

Requirements

Node >= 20, and nothing else — zero runtime dependencies. Ships ESM and CommonJS builds with TypeScript declarations for both.

Versions up to and including 0.1.1 depended on @hebcal/hdate for gematria and clean-date parsing. That library is GPL-2.0, which put a copyleft obligation on everyone installing this MIT package, so those few primitives — a gematria table, the Metonic leap-year rule, and a strict clean-date reader — are implemented directly in src/gematria.ts as of 0.2.0. See the changelog; the rewrite also fixed four dating bugs.

Credit

The shape of this package, and the decision to keep it separate from the calendar libraries, both owe a lot to hebcal by Michael J. Radwin and contributors — still the right tool for everything downstream of this one.

License

MIT © 2026 Shmuel Holzman.

Maintained by Holzman AI & Automations. Extracted from Luach, a family Hebrew-calendar app, where it was written to survive a real family spreadsheet.