@hebcal/core 6.5.0 → 6.5.2

package/dist/src/event.d.ts

@@ -63,15 +63,27 @@ export declare const flags: {
     readonly DAILY_LEARNING: 67108864;
     /** Yizkor */
     readonly YIZKOR: 134217728;
+    /** BeHaB fast days on Monday, Thursday and Monday after Pesach and Sukkot */
+    readonly BEHAB: 268435456;
 };
 /**
  * Represents an Event with a title, date, and flags.
  *
  * Events are used to represent holidays, candle-lighting times,
- * Torah readings, and more.
+ * Torah readings, Omer days, Hebrew dates, and more. Most concrete event
+ * types are subclasses (e.g. {@link HolidayEvent}, {@link TimedEvent},
+ * {@link ParshaEvent}, {@link OmerEvent}) and are produced by
+ * {@link HebrewCalendar.calendar}.
  *
- * To get the title of the event a language other than English
- * with Sephardic transliterations, use the `render()` method.
+ * To get the title of the event in a language other than English with
+ * Sephardic transliterations, use the {@link Event.render} method.
+ *
+ * @example
+ * import {Event, HDate, flags} from '@hebcal/core';
+ * const ev = new Event(new HDate(6, 'Sivan', 5749), 'Shavuot', flags.CHAG);
+ * ev.getDate().toString(); // '6 Sivan 5749'
+ * ev.getDesc();             // 'Shavuot'
+ * ev.render('he');          // 'שָׁבוּעוֹת'
  */
 export declare class Event {
     /** Hebrew date of this event */
@@ -130,25 +142,47 @@ export declare class Event {
     render(locale?: string): string;
     /**
      * Returns a brief (translated) description of this event.
-     * For most events, this is the same as render(). For some events, it procudes
-     * a shorter text (e.g. without a time or added description).
+     *
+     * For most events this is the same as {@link render}. Some subclasses
+     * (e.g. {@link CandleLightingEvent}, {@link HavdalahEvent},
+     * {@link OmerEvent}) produce shorter text without an attached time or
+     * extra qualifier — useful for compact UI display.
+     * @example
+     * import {CandleLightingEvent} from '@hebcal/core';
+     * // For a regular Event, renderBrief() == render():
+     * const ev = new Event(new HDate(6, 'Sivan', 5749), 'Shavuot', flags.CHAG);
+     * ev.renderBrief('en'); // 'Shavuot'
      * @param [locale] Optional locale name (defaults to empty locale)
      */
     renderBrief(locale?: string): string;
     /**
-     * Optional holiday-specific Emoji or `null`.
+     * Returns the event's emoji character (e.g. `🕯️`, `🕎`, `🇮🇱`, `🍏🍯`),
+     * or `null` if no emoji is associated with this event.
+     * Subclasses override this to provide holiday-specific emoji.
      */
     getEmoji(): string | null;
     /**
-     * Returns a simplified (untranslated) description for this event. For example,
-     * the `HolidayEvent` class supports
-     * "Erev Pesach" => "Pesach", and "Sukkot III (CH''M)" => "Sukkot".
-     * For many holidays the basename and the event description are the same.
+     * Returns a simplified (untranslated) description for this event, suitable
+     * for grouping related events under a single name.
+     *
+     * For example, {@link HolidayEvent} strips qualifiers so that
+     * `"Erev Pesach"` → `"Pesach"` and `"Sukkot III (CH''M)"` → `"Sukkot"`.
+     * For many events the basename and the event description are identical.
+     * @example
+     * import {HolidayEvent, HDate, months, flags} from '@hebcal/core';
+     * const ev = new HolidayEvent(
+     *   new HDate(14, months.NISAN, 5784), 'Erev Pesach', flags.EREV);
+     * ev.getDesc();    // 'Erev Pesach'
+     * ev.basename();   // 'Pesach'
      */
     basename(): string;
     /**
-     * Returns a URL to hebcal.com or sefaria.org for more detail on the event.
-     * Returns `undefined` for events with no detail page.
+     * Returns a URL to hebcal.com or sefaria.org for more detail on the event,
+     * or `undefined` for events with no detail page.
+     *
+     * Subclasses such as {@link HolidayEvent}, {@link ChanukahEvent},
+     * {@link AsaraBTevetEvent}, {@link ParshaEvent}, and {@link OmerEvent}
+     * override this with their own URL patterns.
      */
     url(): string | undefined;
     /**
@@ -182,7 +216,18 @@ export declare class Event {
      */
     observedIn(il: boolean): boolean;
     /**
-     * Returns a list of event categories
+     * Returns an array of category strings classifying this event, derived
+     * from its {@link flags} bitmask. The first element is the broad category
+     * (e.g. `'holiday'`, `'roshchodesh'`, `'parashat'`, `'omer'`), followed
+     * by zero or more refinements (e.g. `'major'`, `'minor'`, `'fast'`).
+     *
+     * Returns `['unknown']` if no flag maps to a known category.
+     * @example
+     * import {Event, HDate, flags} from '@hebcal/core';
+     * new Event(new HDate(10, 'Tishrei', 5784), 'Yom Kippur', flags.MAJOR_FAST)
+     *   .getCategories(); // ['holiday', 'major', 'fast']
+     * new Event(new HDate(1, 'Shvat', 5784), 'Rosh Chodesh Sh\'vat', flags.ROSH_CHODESH)
+     *   .getCategories(); // ['roshchodesh']
      */
     getCategories(): string[];
 }

package/dist/src/event.js

@@ -63,6 +63,8 @@ export const flags = {
     DAILY_LEARNING: 0x4000000,
     /** Yizkor */
     YIZKOR: 0x8000000,
+    /** BeHaB fast days on Monday, Thursday and Monday after Pesach and Sukkot */
+    BEHAB: 0x10000000,
 };
 const flagToCategory = [
     [flags.MAJOR_FAST, 'holiday', 'major', 'fast'],
@@ -84,10 +86,20 @@ const flagToCategory = [
  * Represents an Event with a title, date, and flags.
  *
  * Events are used to represent holidays, candle-lighting times,
- * Torah readings, and more.
+ * Torah readings, Omer days, Hebrew dates, and more. Most concrete event
+ * types are subclasses (e.g. {@link HolidayEvent}, {@link TimedEvent},
+ * {@link ParshaEvent}, {@link OmerEvent}) and are produced by
+ * {@link HebrewCalendar.calendar}.
  *
- * To get the title of the event a language other than English
- * with Sephardic transliterations, use the `render()` method.
+ * To get the title of the event in a language other than English with
+ * Sephardic transliterations, use the {@link Event.render} method.
+ *
+ * @example
+ * import {Event, HDate, flags} from '@hebcal/core';
+ * const ev = new Event(new HDate(6, 'Sivan', 5749), 'Shavuot', flags.CHAG);
+ * ev.getDate().toString(); // '6 Sivan 5749'
+ * ev.getDesc();             // 'Shavuot'
+ * ev.render('he');          // 'שָׁבוּעוֹת'
  */
 export class Event {
     /** Hebrew date of this event */
@@ -169,31 +181,53 @@ export class Event {
     }
     /**
      * Returns a brief (translated) description of this event.
-     * For most events, this is the same as render(). For some events, it procudes
-     * a shorter text (e.g. without a time or added description).
+     *
+     * For most events this is the same as {@link render}. Some subclasses
+     * (e.g. {@link CandleLightingEvent}, {@link HavdalahEvent},
+     * {@link OmerEvent}) produce shorter text without an attached time or
+     * extra qualifier — useful for compact UI display.
+     * @example
+     * import {CandleLightingEvent} from '@hebcal/core';
+     * // For a regular Event, renderBrief() == render():
+     * const ev = new Event(new HDate(6, 'Sivan', 5749), 'Shavuot', flags.CHAG);
+     * ev.renderBrief('en'); // 'Shavuot'
      * @param [locale] Optional locale name (defaults to empty locale)
      */
     renderBrief(locale) {
         return this.render(locale);
     }
     /**
-     * Optional holiday-specific Emoji or `null`.
+     * Returns the event's emoji character (e.g. `🕯️`, `🕎`, `🇮🇱`, `🍏🍯`),
+     * or `null` if no emoji is associated with this event.
+     * Subclasses override this to provide holiday-specific emoji.
      */
     getEmoji() {
         return this.emoji || null;
     }
     /**
-     * Returns a simplified (untranslated) description for this event. For example,
-     * the `HolidayEvent` class supports
-     * "Erev Pesach" => "Pesach", and "Sukkot III (CH''M)" => "Sukkot".
-     * For many holidays the basename and the event description are the same.
+     * Returns a simplified (untranslated) description for this event, suitable
+     * for grouping related events under a single name.
+     *
+     * For example, {@link HolidayEvent} strips qualifiers so that
+     * `"Erev Pesach"` → `"Pesach"` and `"Sukkot III (CH''M)"` → `"Sukkot"`.
+     * For many events the basename and the event description are identical.
+     * @example
+     * import {HolidayEvent, HDate, months, flags} from '@hebcal/core';
+     * const ev = new HolidayEvent(
+     *   new HDate(14, months.NISAN, 5784), 'Erev Pesach', flags.EREV);
+     * ev.getDesc();    // 'Erev Pesach'
+     * ev.basename();   // 'Pesach'
      */
     basename() {
         return this.getDesc();
     }
     /**
-     * Returns a URL to hebcal.com or sefaria.org for more detail on the event.
-     * Returns `undefined` for events with no detail page.
+     * Returns a URL to hebcal.com or sefaria.org for more detail on the event,
+     * or `undefined` for events with no detail page.
+     *
+     * Subclasses such as {@link HolidayEvent}, {@link ChanukahEvent},
+     * {@link AsaraBTevetEvent}, {@link ParshaEvent}, and {@link OmerEvent}
+     * override this with their own URL patterns.
      */
     url() {
         return undefined;
@@ -235,7 +269,18 @@ export class Event {
         return il ? this.observedInIsrael() : this.observedInDiaspora();
     }
     /**
-     * Returns a list of event categories
+     * Returns an array of category strings classifying this event, derived
+     * from its {@link flags} bitmask. The first element is the broad category
+     * (e.g. `'holiday'`, `'roshchodesh'`, `'parashat'`, `'omer'`), followed
+     * by zero or more refinements (e.g. `'major'`, `'minor'`, `'fast'`).
+     *
+     * Returns `['unknown']` if no flag maps to a known category.
+     * @example
+     * import {Event, HDate, flags} from '@hebcal/core';
+     * new Event(new HDate(10, 'Tishrei', 5784), 'Yom Kippur', flags.MAJOR_FAST)
+     *   .getCategories(); // ['holiday', 'major', 'fast']
+     * new Event(new HDate(1, 'Shvat', 5784), 'Rosh Chodesh Sh\'vat', flags.ROSH_CHODESH)
+     *   .getCategories(); // ['roshchodesh']
      */
     getCategories() {
         const mask = this.getFlags();

package/dist/src/getStartAndEnd.js

@@ -21,6 +21,7 @@ function getYear(options) {
         ? new HDate().getFullYear()
         : new Date().getFullYear();
 }
+const MAX_NUM_YEARS = 2000;
 /**
  * Parse options object to determine start & end days
  * @private
@@ -30,7 +31,11 @@ export function getStartAndEnd(options) {
         throw new TypeError('Both options.start and options.end are required');
     }
     else if (options.start && options.end) {
-        return [getAbs(options.start), getAbs(options.end)];
+        const start = getAbs(options.start), end = getAbs(options.end);
+        if (end - start > 365 * MAX_NUM_YEARS) {
+            throw new RangeError(`Date range exceeds ${MAX_NUM_YEARS} years`);
+        }
+        return [start, end];
     }
     const isHebrewYear = Boolean(options.isHebrewYear);
     const theYear = getYear(options);
@@ -42,6 +47,9 @@ export function getStartAndEnd(options) {
     }
     const theMonth = getMonth(options);
     const numYears = Number(options.numYears) || 1;
+    if (numYears > MAX_NUM_YEARS) {
+        throw new RangeError(`options.numYears exceeds ${MAX_NUM_YEARS}`);
+    }
     if (isHebrewYear) {
         return startEndHebrew(theMonth, theYear, numYears);
     }

package/dist/src/hallel.js

@@ -1,5 +1,6 @@
 import { months } from '@hebcal/hdate';
 import { flags } from './event';
+import { holidayDesc as hdesc } from './staticHolidays';
 const NONE = 0;
 const HALF = 1;
 const WHOLE = 2;
@@ -7,41 +8,32 @@ const WHOLE = 2;
  * @private
  */
 export function hallel_(events, hdate) {
-    const whole = events
-        .filter(ev => {
-        const desc = ev.getDesc();
+    const abs = hdate.abs();
+    for (const ev of events) {
         const hd = ev.getDate();
+        if (hd.abs() !== abs) {
+            continue;
+        }
+        const desc = ev.getDesc();
         const month = hd.getMonth();
         const mday = hd.getDate();
-        return (desc.startsWith('Chanukah') ||
+        const mask = ev.getFlags();
+        if (desc.startsWith('Chanukah') ||
             desc.startsWith('Shavuot') ||
             desc.startsWith('Sukkot') ||
             (month === months.NISAN &&
                 (mday === 15 || mday === 16) &&
-                ev.getFlags() & flags.CHAG) || // Pesach
-            desc === "Yom HaAtzma'ut" ||
-            desc === 'Yom Yerushalayim');
-    })
-        .map(ev => {
-        return ev.getDate().abs();
-    });
-    const abs = hdate.abs();
-    if (whole.includes(abs)) {
-        return WHOLE;
-    }
-    const half = events
-        .filter(ev => {
-        const desc = ev.getDesc();
-        return (ev.getFlags() & flags.ROSH_CHODESH ||
+                mask & flags.CHAG) || // Pesach
+            desc === hdesc.YOM_HAATZMA_UT ||
+            desc === hdesc.YOM_YERUSHALAYIM) {
+            return WHOLE;
+        }
+        if (mask & flags.ROSH_CHODESH ||
             (desc.startsWith('Pesach') &&
-                desc !== 'Pesach I' &&
-                desc !== 'Pesach II'));
-    })
-        .map(ev => {
-        return ev.getDate().abs();
-    });
-    if (half.includes(abs)) {
-        return HALF;
+                desc !== hdesc.PESACH_I &&
+                desc !== hdesc.PESACH_II)) {
+            return HALF;
+        }
     }
     return NONE;
 }

package/dist/src/he.po.d.ts

@@ -132,6 +132,7 @@ declare const _default: {
             "Sukkot VII (Hoshana Raba)": string[];
             "Sukkot Shabbat Chol ha-Moed": string[];
             "Ta'anit Bechorot": string[];
+            "Ta'anit BeHaB": string[];
             "Ta'anit Esther": string[];
             "Tish'a B'Av": string[];
             "Tu B'Av": string[];

package/dist/src/he.po.js

@@ -1 +1 @@
-export default { "headers": { "plural-forms": "nplurals=2; plural=(n > 1);", "language": "he_IL" }, "contexts": { "": { "Shabbat": ["שַׁבָּת"], "Parashat": ["פָּרָשַׁת"], "Achrei Mot": ["אַחֲרֵי מוֹת"], "Balak": ["בָּלָק"], "Bamidbar": ["בְּמִדְבַּר"], "Bechukotai": ["בְּחֻקֹּתַי"], "Beha'alotcha": ["בְּהַעֲלֹתְךָ"], "Behar": ["בְּהַר"], "Bereshit": ["בְּרֵאשִׁית"], "Beshalach": ["בְּשַׁלַּח"], "Bo": ["בֹּא"], "Chayei Sara": ["חַיֵּי שָֹרָה"], "Chukat": ["חֻקַּת"], "Devarim": ["דְּבָרִים"], "Eikev": ["עֵקֶב"], "Emor": ["אֱמוֹר"], "Ha'azinu": ["הַאֲזִינוּ"], "Kedoshim": ["קְדֹשִׁים"], "Ki Tavo": ["כִּי־תָבוֹא"], "Ki Teitzei": ["כִּי־תֵצֵא"], "Ki Tisa": ["כִּי תִשָּׂא"], "Korach": ["קֹרַח"], "Lech-Lecha": ["לֶךְ־לְךָ"], "Masei": ["מַסְעֵי"], "Matot": ["מַטּוֹת"], "Metzora": ["מְצֹרָע"], "Miketz": ["מִקֵּץ"], "Mishpatim": ["מִשְׁפָּטִים"], "Nasso": ["נָשׂא"], "Nitzavim": ["נִצָּבִים"], "Noach": ["נֹחַ"], "Pekudei": ["פְקוּדֵי"], "Pinchas": ["פִּינְחָס"], "Re'eh": ["רְאֵה"], "Sh'lach": ["שְׁלַח־לְךָ"], "Shemot": ["שְׁמוֹת"], "Shmini": ["שְּׁמִינִי"], "Shoftim": ["שׁוֹפְטִים"], "Tazria": ["תַזְרִיעַ"], "Terumah": ["תְּרוּמָה"], "Tetzaveh": ["תְּצַוֶּה"], "Toldot": ["תּוֹלְדוֹת"], "Tzav": ["צַו"], "Vaera": ["וָאֵרָא"], "Vaetchanan": ["וָאֶתְחַנַּן"], "Vayakhel": ["וַיַּקְהֵל"], "Vayechi": ["וַיְחִי"], "Vayeilech": ["וַיֵּלֶךְ"], "Vayera": ["וַיֵּרָא"], "Vayeshev": ["וַיֵּשֶׁב"], "Vayetzei": ["וַיֵּצֵא"], "Vayigash": ["וַיִּגַּשׁ"], "Vayikra": ["וַיִּקְרָא"], "Vayishlach": ["וַיִּשְׁלַח"], "Vezot Haberakhah": ["וְזֹאת הַבְּרָכָה"], "Yitro": ["יִתְרוֹ"], "Asara B'Tevet": ["עֲשָׂרָה בְּטֵבֵת"], "Candle lighting": ["הַדְלָקַת נֵרוֹת"], "Chanukah": ["חֲנוּכָּה"], "Chanukah: 1 Candle": ["חֲנוּכָּה: א׳ נֵר"], "Chanukah: 2 Candles": ["חֲנוּכָּה: ב׳ נֵרוֹת"], "Chanukah: 3 Candles": ["חֲנוּכָּה: ג׳ נֵרוֹת"], "Chanukah: 4 Candles": ["חֲנוּכָּה: ד׳ נֵרוֹת"], "Chanukah: 5 Candles": ["חֲנוּכָּה: ה׳ נֵרוֹת"], "Chanukah: 6 Candles": ["חֲנוּכָּה: ו׳ נֵרוֹת"], "Chanukah: 7 Candles": ["חֲנוּכָּה: ז׳ נֵרוֹת"], "Chanukah: 8 Candles": ["חֲנוּכָּה: ח׳ נֵרוֹת"], "Chanukah: 8th Day": ["חֲנוּכָּה: יוֹם ח׳"], "Days of the Omer": ["סְפִירַת הָעוֹמֶר"], "Omer": ["עוֹמֶר"], "day of the Omer": ["בָּעוֹמֶר"], "Erev Pesach": ["עֶרֶב פֶּסַח"], "Erev Purim": ["עֶרֶב פּוּרִים"], "Erev Rosh Hashana": ["עֶרֶב רֹאשׁ הַשָּׁנָה"], "Erev Shavuot": ["עֶרֶב שָׁבוּעוֹת"], "Erev Simchat Torah": ["עֶרֶב שִׂמְחַת תּוֹרָה"], "Erev Sukkot": ["עֶרֶב סֻכּוֹת"], "Erev Tish'a B'Av": ["עֶרֶב תִּשְׁעָה בְּאָב"], "Erev Yom Kippur": ["עֶרֶב יוֹם כִּפּוּר"], "Havdalah": ["הַבְדָּלָה"], "Lag BaOmer": ["ל״ג בָּעוֹמֶר"], "Leil Selichot": ["סְלִיחוֹת"], "Pesach": ["פֶּסַח"], "Pesach I": ["פֶּסַח א׳"], "Pesach II": ["פֶּסַח ב׳"], "Pesach II (CH''M)": ["פֶּסַח ב׳ (חוה״מ)"], "Pesach III (CH''M)": ["פֶּסַח ג׳ (חוה״מ)"], "Pesach IV (CH''M)": ["פֶּסַח ד׳ (חוה״מ)"], "Pesach Sheni": ["פֶּסַח שֵׁנִי"], "Pesach V (CH''M)": ["פֶּסַח ה׳ (חוה״מ)"], "Pesach VI (CH''M)": ["פֶּסַח ו׳ (חוה״מ)"], "Pesach VII": ["פֶּסַח ז׳"], "Pesach VIII": ["פֶּסַח ח׳"], "Pesach Shabbat Chol ha-Moed": ["פֶּסַח שַׁבָּת חֹל הַמּוֹעֵד"], "Purim": ["פּוּרִים"], "Purim Katan": ["פּוּרִים קָטָן"], "Rosh Chodesh %s": ["רֹאשׁ חוֹדֶשׁ %s"], "Rosh Chodesh": ["רֹאשׁ חוֹדֶשׁ"], "Rosh Hashana": ["רֹאשׁ הַשָּׁנָה"], "Rosh Hashana I": ["רֹאשׁ הַשָּׁנָה א׳"], "Rosh Hashana II": ["רֹאשׁ הַשָּׁנָה ב׳"], "Shabbat Chazon": ["שַׁבַּת חֲזוֹן"], "Shabbat HaChodesh": ["שַׁבַּת הַחֹדֶשׁ"], "Shabbat HaGadol": ["שַׁבַּת הַגָּדוֹל"], "Shabbat Nachamu": ["שַׁבַּת נַחֲמוּ"], "Shabbat Parah": ["שַׁבַּת פָּרָה"], "Shabbat Shekalim": ["שַׁבַּת שְׁקָלִים"], "Shabbat Shuva": ["שַׁבַּת שׁוּבָה"], "Shabbat Zachor": ["שַׁבַּת זָכוֹר"], "Shavuot": ["שָׁבוּעוֹת"], "Shavuot I": ["שָׁבוּעוֹת א׳"], "Shavuot II": ["שָׁבוּעוֹת ב׳"], "Shmini Atzeret": ["שְׁמִינִי עֲצֶרֶת"], "Shushan Purim": ["שׁוּשָׁן פּוּרִים"], "Sigd": ["חַג הַסִּיגְד"], "Simchat Torah": ["שִׂמְחַת תּוֹרָה"], "Sukkot": ["סֻכּוֹת"], "Sukkot I": ["סֻכּוֹת א׳"], "Sukkot II": ["סֻכּוֹת ב׳"], "Sukkot II (CH''M)": ["סֻכּוֹת ב׳ (חוה״מ)"], "Sukkot III (CH''M)": ["סֻכּוֹת ג׳ (חוה״מ)"], "Sukkot IV (CH''M)": ["סֻכּוֹת ד׳ (חוה״מ)"], "Sukkot V (CH''M)": ["סֻכּוֹת ה׳ (חוה״מ)"], "Sukkot VI (CH''M)": ["סֻכּוֹת ו׳ (חוה״מ)"], "Sukkot VII (Hoshana Raba)": ["סֻכּוֹת ז׳ (הוֹשַׁעְנָא רַבָּה)"], "Sukkot Shabbat Chol ha-Moed": ["סֻכּוֹת שַׁבָּת חֹל הַמּוֹעֵד"], "Ta'anit Bechorot": ["תַּעֲנִית בְּכוֹרוֹת"], "Ta'anit Esther": ["תַּעֲנִית אֶסְתֵּר"], "Tish'a B'Av": ["תִּשְׁעָה בְּאָב"], "Tu B'Av": ["ט״וּ בְּאָב"], "Tu BiShvat": ["ט״וּ בִּשְׁבָט"], "Tu B'Shvat": ["ט״וּ בִּשְׁבָט"], "Tzom Gedaliah": ["צוֹם גְּדַלְיָה"], "Tzom Tammuz": ["צוֹם י״ז בְּתַמּוּז"], "Yom HaAtzma'ut": ["יוֹם הָעַצְמָאוּת"], "Yom HaShoah": ["יוֹם הַשּׁוֹאָה"], "Yom HaZikaron": ["יוֹם הַזִּכָּרוֹן"], "Yom Kippur": ["יוֹם כִּפּוּר"], "Yom Yerushalayim": ["יוֹם יְרוּשָׁלַיִם"], "Yom HaAliyah": ["יוֹם הַעֲלִיָּה"], "Yom HaAliyah School Observance": ["שְׁמִירָת בֵּית הַסֵפֶר לְיוֹם הַעֲלִיָּה"], "Rosh Chodesh Adar": ["רֹאשׁ חוֹדֶשׁ אֲדָר"], "Rosh Chodesh Adar I": ["רֹאשׁ חוֹדֶשׁ אֲדָר א׳"], "Rosh Chodesh Adar II": ["רֹאשׁ חוֹדֶשׁ אֲדָר ב׳"], "Rosh Chodesh Av": ["רֹאשׁ חוֹדֶשׁ אָב"], "Rosh Chodesh Cheshvan": ["רֹאשׁ חוֹדֶשׁ חֶשְׁוָן"], "Rosh Chodesh Elul": ["רֹאשׁ חוֹדֶשׁ אֱלוּל"], "Rosh Chodesh Iyyar": ["רֹאשׁ חוֹדֶשׁ אִיָּיר"], "Rosh Chodesh Kislev": ["רֹאשׁ חוֹדֶשׁ כִּסְלֵו"], "Rosh Chodesh Nisan": ["רֹאשׁ חוֹדֶשׁ נִיסָן"], "Rosh Chodesh Sh'vat": ["רֹאשׁ חוֹדֶשׁ שְׁבָט"], "Rosh Chodesh Sivan": ["רֹאשׁ חוֹדֶשׁ סִיוָן"], "Rosh Chodesh Tamuz": ["רֹאשׁ חוֹדֶשׁ תַּמּוּז"], "Rosh Chodesh Tammuz": ["רֹאשׁ חוֹדֶשׁ תַּמּוּז"], "Rosh Chodesh Tevet": ["רֹאשׁ חוֹדֶשׁ טֵבֵת"], "min": ["דַּקּוֹת"], "Fast begins": ["תְּחִילַּת הַצוֹם"], "Fast ends": ["סִיּוּם הַצוֹם"], "Rosh Hashana LaBehemot": ["רֹאשׁ הַשָּׁנָה לְמַעְשַׂר בְּהֵמָה"], "Tish'a B'Av (observed)": ["(תִּשְׁעָה בְּאָב (נִדְחָה"], "Shabbat Mevarchim Chodesh": ["שַׁבַּת מְבָרְכִים חוֹדֶשׁ"], "Shabbat Shirah": ["שַׁבַּת שִׁירָה"], "Lovingkindness": ["חֶסֶד"], "Might": ["גְּבוּרָה"], "Beauty": ["תִּפְאֶרֶת"], "Eternity": ["נֶּצַח"], "Splendor": ["הוֹד"], "Foundation": ["יְּסוֹד"], "Majesty": ["מַּלְכוּת"], "day": ["יוֹם"], "Yom Kippur Katan": ["יוֹם כִּפּוּר קָטָן"], "Yizkor": ["יִזְכּוֹר"], "Family Day": ["יוֹם הַמִּשׁפָּחָה"], "Yitzhak Rabin Memorial Day": ["יוֹם הַזִּכָּרוֹן לְיִצְחָק רַבִּין"], "Jabotinsky Day": ["יוֹם זַ׳בּוֹטִינְסְקִי"], "Herzl Day": ["יוֹם הֶרְצְל"], "Ben-Gurion Day": ["יוֹם בֶּן־גּוּרִיּוֹן"], "Hebrew Language Day": ["יוֹם הַשָׂפָה הַעִברִית"], "Birkat Hachamah": ["בִּרְכַּת הַחַמָּה"], "Birkat HaChamah": ["בִּרְכַּת הַחַמָּה"], "Shushan Purim Katan": ["שׁוּשָׁן פּוּרִים קָטָן"], "Purim Meshulash": ["פּוּרִים מְשׁוּלָּשׁ"], "Chag HaBanot": ["חַג הַבָּנוֹת"], "Molad": ["מוֹלָד הָלְּבָנָה"], "chalakim": ["חֲלָקִים"], "Alot HaShachar": ["עֲלוֹת הַשַּׁחַר"], "Misheyakir": ["מִשֶּׁיַּכִּיר"], "Misheyakir Machmir": ["מִשֶּׁיַּכִּיר מַחְמִיר"], "Sunrise": ["נֵץ הַחַמָּה"], "Kriat Shema, sof zeman": ["סוֹף זְמַן קְרִיאַת שְׁמַע"], "Tefilah, sof zeman": ["סוֹף זְמַן תְּפִלָּה"], "Kriat Shema, sof zeman (MGA)": ["סוֹף זְמַן קְרִיאַת שְׁמַע (מג״א)"], "Kriat Shema, sof zeman (GRA)": ["סוֹף זְמַן קְרִיאַת שְׁמַע (גְּרָ״א)"], "Tefilah, sof zeman (MGA)": ["סוֹף זְמַן תְּפִלָּה (מג״א)"], "Tefilah, sof zeman (GRA)": ["סוֹף זְמַן תְּפִלָּה (גְּרָ״א)"], "Chatzot HaLailah": ["חֲצוֹת הַלַּיְלָה"], "Chatzot HaYom": ["חֲצוֹת הַיּוֹם"], "Chatzot hayom": ["חֲצוֹת הַיּוֹם"], "Mincha Gedolah": ["מִנְחָה גְּדוֹלָה"], "Mincha Ketanah": ["מִנְחָה קְטַנָּה"], "Plag HaMincha": ["פְּלַג הַמִּנְחָה"], "Sunset": ["שְׁקִיעַת הַחַמָּה"], "Bein HaShemashot": ["בֵּין הַשְּׁמָשׁוֹת"], "Tzeit HaKochavim": ["צֵאת הַכּוֹכָבִים"], "Biur Chametz": ["בִּעוּר חָמֵץ"], "Finish eating chametz": ["סוֹף זְמַן אֲכִילַת חָמֵץ"] } } };
+export default { "headers": { "plural-forms": "nplurals=2; plural=(n > 1);", "language": "he_IL" }, "contexts": { "": { "Shabbat": ["שַׁבָּת"], "Parashat": ["פָּרָשַׁת"], "Achrei Mot": ["אַחֲרֵי מוֹת"], "Balak": ["בָּלָק"], "Bamidbar": ["בְּמִדְבַּר"], "Bechukotai": ["בְּחֻקֹּתַי"], "Beha'alotcha": ["בְּהַעֲלֹתְךָ"], "Behar": ["בְּהַר"], "Bereshit": ["בְּרֵאשִׁית"], "Beshalach": ["בְּשַׁלַּח"], "Bo": ["בֹּא"], "Chayei Sara": ["חַיֵּי שָֹרָה"], "Chukat": ["חֻקַּת"], "Devarim": ["דְּבָרִים"], "Eikev": ["עֵקֶב"], "Emor": ["אֱמוֹר"], "Ha'azinu": ["הַאֲזִינוּ"], "Kedoshim": ["קְדֹשִׁים"], "Ki Tavo": ["כִּי־תָבוֹא"], "Ki Teitzei": ["כִּי־תֵצֵא"], "Ki Tisa": ["כִּי תִשָּׂא"], "Korach": ["קֹרַח"], "Lech-Lecha": ["לֶךְ־לְךָ"], "Masei": ["מַסְעֵי"], "Matot": ["מַטּוֹת"], "Metzora": ["מְצֹרָע"], "Miketz": ["מִקֵּץ"], "Mishpatim": ["מִשְׁפָּטִים"], "Nasso": ["נָשׂא"], "Nitzavim": ["נִצָּבִים"], "Noach": ["נֹחַ"], "Pekudei": ["פְקוּדֵי"], "Pinchas": ["פִּינְחָס"], "Re'eh": ["רְאֵה"], "Sh'lach": ["שְׁלַח־לְךָ"], "Shemot": ["שְׁמוֹת"], "Shmini": ["שְּׁמִינִי"], "Shoftim": ["שׁוֹפְטִים"], "Tazria": ["תַזְרִיעַ"], "Terumah": ["תְּרוּמָה"], "Tetzaveh": ["תְּצַוֶּה"], "Toldot": ["תּוֹלְדוֹת"], "Tzav": ["צַו"], "Vaera": ["וָאֵרָא"], "Vaetchanan": ["וָאֶתְחַנַּן"], "Vayakhel": ["וַיַּקְהֵל"], "Vayechi": ["וַיְחִי"], "Vayeilech": ["וַיֵּלֶךְ"], "Vayera": ["וַיֵּרָא"], "Vayeshev": ["וַיֵּשֶׁב"], "Vayetzei": ["וַיֵּצֵא"], "Vayigash": ["וַיִּגַּשׁ"], "Vayikra": ["וַיִּקְרָא"], "Vayishlach": ["וַיִּשְׁלַח"], "Vezot Haberakhah": ["וְזֹאת הַבְּרָכָה"], "Yitro": ["יִתְרוֹ"], "Asara B'Tevet": ["עֲשָׂרָה בְּטֵבֵת"], "Candle lighting": ["הַדְלָקַת נֵרוֹת"], "Chanukah": ["חֲנוּכָּה"], "Chanukah: 1 Candle": ["חֲנוּכָּה: א׳ נֵר"], "Chanukah: 2 Candles": ["חֲנוּכָּה: ב׳ נֵרוֹת"], "Chanukah: 3 Candles": ["חֲנוּכָּה: ג׳ נֵרוֹת"], "Chanukah: 4 Candles": ["חֲנוּכָּה: ד׳ נֵרוֹת"], "Chanukah: 5 Candles": ["חֲנוּכָּה: ה׳ נֵרוֹת"], "Chanukah: 6 Candles": ["חֲנוּכָּה: ו׳ נֵרוֹת"], "Chanukah: 7 Candles": ["חֲנוּכָּה: ז׳ נֵרוֹת"], "Chanukah: 8 Candles": ["חֲנוּכָּה: ח׳ נֵרוֹת"], "Chanukah: 8th Day": ["חֲנוּכָּה: יוֹם ח׳"], "Days of the Omer": ["סְפִירַת הָעוֹמֶר"], "Omer": ["עוֹמֶר"], "day of the Omer": ["בָּעוֹמֶר"], "Erev Pesach": ["עֶרֶב פֶּסַח"], "Erev Purim": ["עֶרֶב פּוּרִים"], "Erev Rosh Hashana": ["עֶרֶב רֹאשׁ הַשָּׁנָה"], "Erev Shavuot": ["עֶרֶב שָׁבוּעוֹת"], "Erev Simchat Torah": ["עֶרֶב שִׂמְחַת תּוֹרָה"], "Erev Sukkot": ["עֶרֶב סֻכּוֹת"], "Erev Tish'a B'Av": ["עֶרֶב תִּשְׁעָה בְּאָב"], "Erev Yom Kippur": ["עֶרֶב יוֹם כִּפּוּר"], "Havdalah": ["הַבְדָּלָה"], "Lag BaOmer": ["ל״ג בָּעוֹמֶר"], "Leil Selichot": ["סְלִיחוֹת"], "Pesach": ["פֶּסַח"], "Pesach I": ["פֶּסַח א׳"], "Pesach II": ["פֶּסַח ב׳"], "Pesach II (CH''M)": ["פֶּסַח ב׳ (חוה״מ)"], "Pesach III (CH''M)": ["פֶּסַח ג׳ (חוה״מ)"], "Pesach IV (CH''M)": ["פֶּסַח ד׳ (חוה״מ)"], "Pesach Sheni": ["פֶּסַח שֵׁנִי"], "Pesach V (CH''M)": ["פֶּסַח ה׳ (חוה״מ)"], "Pesach VI (CH''M)": ["פֶּסַח ו׳ (חוה״מ)"], "Pesach VII": ["פֶּסַח ז׳"], "Pesach VIII": ["פֶּסַח ח׳"], "Pesach Shabbat Chol ha-Moed": ["פֶּסַח שַׁבָּת חֹל הַמּוֹעֵד"], "Purim": ["פּוּרִים"], "Purim Katan": ["פּוּרִים קָטָן"], "Rosh Chodesh %s": ["רֹאשׁ חוֹדֶשׁ %s"], "Rosh Chodesh": ["רֹאשׁ חוֹדֶשׁ"], "Rosh Hashana": ["רֹאשׁ הַשָּׁנָה"], "Rosh Hashana I": ["רֹאשׁ הַשָּׁנָה א׳"], "Rosh Hashana II": ["רֹאשׁ הַשָּׁנָה ב׳"], "Shabbat Chazon": ["שַׁבַּת חֲזוֹן"], "Shabbat HaChodesh": ["שַׁבַּת הַחֹדֶשׁ"], "Shabbat HaGadol": ["שַׁבַּת הַגָּדוֹל"], "Shabbat Nachamu": ["שַׁבַּת נַחֲמוּ"], "Shabbat Parah": ["שַׁבַּת פָּרָה"], "Shabbat Shekalim": ["שַׁבַּת שְׁקָלִים"], "Shabbat Shuva": ["שַׁבַּת שׁוּבָה"], "Shabbat Zachor": ["שַׁבַּת זָכוֹר"], "Shavuot": ["שָׁבוּעוֹת"], "Shavuot I": ["שָׁבוּעוֹת א׳"], "Shavuot II": ["שָׁבוּעוֹת ב׳"], "Shmini Atzeret": ["שְׁמִינִי עֲצֶרֶת"], "Shushan Purim": ["שׁוּשָׁן פּוּרִים"], "Sigd": ["חַג הַסִּיגְד"], "Simchat Torah": ["שִׂמְחַת תּוֹרָה"], "Sukkot": ["סֻכּוֹת"], "Sukkot I": ["סֻכּוֹת א׳"], "Sukkot II": ["סֻכּוֹת ב׳"], "Sukkot II (CH''M)": ["סֻכּוֹת ב׳ (חוה״מ)"], "Sukkot III (CH''M)": ["סֻכּוֹת ג׳ (חוה״מ)"], "Sukkot IV (CH''M)": ["סֻכּוֹת ד׳ (חוה״מ)"], "Sukkot V (CH''M)": ["סֻכּוֹת ה׳ (חוה״מ)"], "Sukkot VI (CH''M)": ["סֻכּוֹת ו׳ (חוה״מ)"], "Sukkot VII (Hoshana Raba)": ["סֻכּוֹת ז׳ (הוֹשַׁעְנָא רַבָּה)"], "Sukkot Shabbat Chol ha-Moed": ["סֻכּוֹת שַׁבָּת חֹל הַמּוֹעֵד"], "Ta'anit Bechorot": ["תַּעֲנִית בְּכוֹרוֹת"], "Ta'anit BeHaB": ["תַּעֲנִית בה״ב"], "Ta'anit Esther": ["תַּעֲנִית אֶסְתֵּר"], "Tish'a B'Av": ["תִּשְׁעָה בְּאָב"], "Tu B'Av": ["ט״וּ בְּאָב"], "Tu BiShvat": ["ט״וּ בִּשְׁבָט"], "Tu B'Shvat": ["ט״וּ בִּשְׁבָט"], "Tzom Gedaliah": ["צוֹם גְּדַלְיָה"], "Tzom Tammuz": ["צוֹם י״ז בְּתַמּוּז"], "Yom HaAtzma'ut": ["יוֹם הָעַצְמָאוּת"], "Yom HaShoah": ["יוֹם הַשּׁוֹאָה"], "Yom HaZikaron": ["יוֹם הַזִּכָּרוֹן"], "Yom Kippur": ["יוֹם כִּפּוּר"], "Yom Yerushalayim": ["יוֹם יְרוּשָׁלַיִם"], "Yom HaAliyah": ["יוֹם הַעֲלִיָּה"], "Yom HaAliyah School Observance": ["שְׁמִירָת בֵּית הַסֵפֶר לְיוֹם הַעֲלִיָּה"], "Rosh Chodesh Adar": ["רֹאשׁ חוֹדֶשׁ אֲדָר"], "Rosh Chodesh Adar I": ["רֹאשׁ חוֹדֶשׁ אֲדָר א׳"], "Rosh Chodesh Adar II": ["רֹאשׁ חוֹדֶשׁ אֲדָר ב׳"], "Rosh Chodesh Av": ["רֹאשׁ חוֹדֶשׁ אָב"], "Rosh Chodesh Cheshvan": ["רֹאשׁ חוֹדֶשׁ חֶשְׁוָן"], "Rosh Chodesh Elul": ["רֹאשׁ חוֹדֶשׁ אֱלוּל"], "Rosh Chodesh Iyyar": ["רֹאשׁ חוֹדֶשׁ אִיָּיר"], "Rosh Chodesh Kislev": ["רֹאשׁ חוֹדֶשׁ כִּסְלֵו"], "Rosh Chodesh Nisan": ["רֹאשׁ חוֹדֶשׁ נִיסָן"], "Rosh Chodesh Sh'vat": ["רֹאשׁ חוֹדֶשׁ שְׁבָט"], "Rosh Chodesh Sivan": ["רֹאשׁ חוֹדֶשׁ סִיוָן"], "Rosh Chodesh Tamuz": ["רֹאשׁ חוֹדֶשׁ תַּמּוּז"], "Rosh Chodesh Tammuz": ["רֹאשׁ חוֹדֶשׁ תַּמּוּז"], "Rosh Chodesh Tevet": ["רֹאשׁ חוֹדֶשׁ טֵבֵת"], "min": ["דַּקּוֹת"], "Fast begins": ["תְּחִילַּת הַצוֹם"], "Fast ends": ["סִיּוּם הַצוֹם"], "Rosh Hashana LaBehemot": ["רֹאשׁ הַשָּׁנָה לְמַעְשַׂר בְּהֵמָה"], "Tish'a B'Av (observed)": ["(תִּשְׁעָה בְּאָב (נִדְחָה"], "Shabbat Mevarchim Chodesh": ["שַׁבַּת מְבָרְכִים חוֹדֶשׁ"], "Shabbat Shirah": ["שַׁבַּת שִׁירָה"], "Lovingkindness": ["חֶסֶד"], "Might": ["גְּבוּרָה"], "Beauty": ["תִּפְאֶרֶת"], "Eternity": ["נֶּצַח"], "Splendor": ["הוֹד"], "Foundation": ["יְּסוֹד"], "Majesty": ["מַּלְכוּת"], "day": ["יוֹם"], "Yom Kippur Katan": ["יוֹם כִּפּוּר קָטָן"], "Yizkor": ["יִזְכּוֹר"], "Family Day": ["יוֹם הַמִּשׁפָּחָה"], "Yitzhak Rabin Memorial Day": ["יוֹם הַזִּכָּרוֹן לְיִצְחָק רַבִּין"], "Jabotinsky Day": ["יוֹם זַ׳בּוֹטִינְסְקִי"], "Herzl Day": ["יוֹם הֶרְצְל"], "Ben-Gurion Day": ["יוֹם בֶּן־גּוּרִיּוֹן"], "Hebrew Language Day": ["יוֹם הַשָׂפָה הַעִברִית"], "Birkat Hachamah": ["בִּרְכַּת הַחַמָּה"], "Birkat HaChamah": ["בִּרְכַּת הַחַמָּה"], "Shushan Purim Katan": ["שׁוּשָׁן פּוּרִים קָטָן"], "Purim Meshulash": ["פּוּרִים מְשׁוּלָּשׁ"], "Chag HaBanot": ["חַג הַבָּנוֹת"], "Molad": ["מוֹלָד הָלְּבָנָה"], "chalakim": ["חֲלָקִים"], "Alot HaShachar": ["עֲלוֹת הַשַּׁחַר"], "Misheyakir": ["מִשֶּׁיַּכִּיר"], "Misheyakir Machmir": ["מִשֶּׁיַּכִּיר מַחְמִיר"], "Sunrise": ["נֵץ הַחַמָּה"], "Kriat Shema, sof zeman": ["סוֹף זְמַן קְרִיאַת שְׁמַע"], "Tefilah, sof zeman": ["סוֹף זְמַן תְּפִלָּה"], "Kriat Shema, sof zeman (MGA)": ["סוֹף זְמַן קְרִיאַת שְׁמַע (מג״א)"], "Kriat Shema, sof zeman (GRA)": ["סוֹף זְמַן קְרִיאַת שְׁמַע (גְּרָ״א)"], "Tefilah, sof zeman (MGA)": ["סוֹף זְמַן תְּפִלָּה (מג״א)"], "Tefilah, sof zeman (GRA)": ["סוֹף זְמַן תְּפִלָּה (גְּרָ״א)"], "Chatzot HaLailah": ["חֲצוֹת הַלַּיְלָה"], "Chatzot HaYom": ["חֲצוֹת הַיּוֹם"], "Chatzot hayom": ["חֲצוֹת הַיּוֹם"], "Mincha Gedolah": ["מִנְחָה גְּדוֹלָה"], "Mincha Ketanah": ["מִנְחָה קְטַנָּה"], "Plag HaMincha": ["פְּלַג הַמִּנְחָה"], "Sunset": ["שְׁקִיעַת הַחַמָּה"], "Bein HaShemashot": ["בֵּין הַשְּׁמָשׁוֹת"], "Tzeit HaKochavim": ["צֵאת הַכּוֹכָבִים"], "Biur Chametz": ["בִּעוּר חָמֵץ"], "Finish eating chametz": ["סוֹף זְמַן אֲכִילַת חָמֵץ"] } } };

package/dist/src/hebcal.d.ts

@@ -24,7 +24,7 @@ export declare class HebrewCalendar {
      * The date range returned by this function can be controlled by:
      * * `options.year` - Gregorian (e.g. 1993) or Hebrew year (e.g. 5749)
      * * `options.isHebrewYear` - to interpret `year` as Hebrew year
-     * * `options.numYears` - generate calendar for multiple years (default 1)
+     * * `options.numYears` - generate calendar for multiple years (default 1, maximum 2000)
      * * `options.month` - Gregorian or Hebrew month (to filter results to a single month)
      *
      * Alternatively, specify start and end days with `Date` or {@link HDate} instances:
@@ -187,57 +187,126 @@ export declare class HebrewCalendar {
     static getYahrzeit(hyear: number, gdate: Date | HDate): HDate | undefined;
     /**
      * Lower-level holidays interface, which returns a `Map` of `Event`s indexed by
-     * `HDate.toString()`. These events must filtered especially for `flags.IL_ONLY`
+     * `HDate.toString()`. These events must be filtered for `flags.IL_ONLY`
      * or `flags.CHUL_ONLY` depending on Israel vs. Diaspora holiday scheme.
+     *
+     * Includes Rosh Chodesh, fasts, Yom Kippur Katan, Special Shabbatot, etc.,
+     * but does not generate candle-lighting times, Torah readings, or Omer days.
+     * The result is cached in an internal LRU.
+     * @example
+     * import {HebrewCalendar} from '@hebcal/core';
+     * const map = HebrewCalendar.getHolidaysForYear(5784);
+     * for (const [hdStr, events] of map.entries()) {
+     *   for (const ev of events) {
+     *     console.log(hdStr, ev.getDesc());
+     *   }
+     * }
      * @param year Hebrew year
      */
     static getHolidaysForYear(year: number): HolidayYearMap;
     /**
-     * Returns an array of holidays for the year
+     * Returns a sorted array of holidays observed during the given Hebrew year.
+     *
+     * Events are pre-filtered by Israel vs. Diaspora schedule, so callers do not
+     * need to inspect `flags.IL_ONLY` / `flags.CHUL_ONLY` themselves.
+     * Includes Rosh Chodesh, fasts, modern holidays, special Shabbatot, etc.,
+     * but does not generate candle-lighting times, Torah readings, or Omer days.
+     * @example
+     * import {HebrewCalendar} from '@hebcal/core';
+     * const events = HebrewCalendar.getHolidaysForYearArray(5784, false);
+     * console.log(events[0].getDesc()); // 'Rosh Hashana 5784'
      * @param year Hebrew year
      * @param il use the Israeli schedule for holidays
      */
     static getHolidaysForYearArray(year: number, il: boolean): HolidayEvent[];
     /**
-     * Returns an array of Events on this date (or `undefined` if no events)
+     * Returns an array of holiday Events that occur on the given date,
+     * or `undefined` if no holidays occur that day.
+     *
+     * When `il` is omitted, both Diaspora-only and Israel-only events are
+     * returned; pass `true` or `false` to filter to a single schedule.
+     * @example
+     * import {HebrewCalendar, HDate, months} from '@hebcal/core';
+     * const hd = new HDate(15, months.NISAN, 5784);
+     * const events = HebrewCalendar.getHolidaysOnDate(hd, false);
+     * console.log(events?.map(ev => ev.getDesc())); // ['Pesach I']
      * @param date Hebrew Date, Gregorian date, or absolute R.D. day number
      * @param [il] use the Israeli schedule for holidays
      */
     static getHolidaysOnDate(date: HDate | Date | number, il?: boolean): HolidayEvent[] | undefined;
     /**
-     * Eruv Tavshilin
+     * Returns `true` if Eruv Tavshilin should be prepared on the given date.
+     *
+     * Eruv Tavshilin is prepared when a Yom Tov falls on Friday (so cooking
+     * for Shabbat that begins Friday night may continue from Yom Tov into
+     * Shabbat). This requires the day before to be a weekday (Wednesday or
+     * Thursday), the following Friday to be Yom Tov, and the day after Friday
+     * (Shabbat) to also be a sacred day.
+     * @example
+     * import {HebrewCalendar} from '@hebcal/core';
+     * // Thursday April 25, 2024 — first day of Pesach 5784, with Shabbat
+     * // chol ha-moed the next day, so Eruv Tavshilin is required:
+     * HebrewCalendar.eruvTavshilin(new Date(2024, 3, 25), false); // true
+     * @param date Gregorian or Hebrew date to test
+     * @param il use the Israeli holiday schedule
      */
     static eruvTavshilin(date: Date | HDate, il: boolean): boolean;
     /**
-     * Helper function to format a 23-hour (00:00-23:59) time in US format ("8:13pm") or
-     * keep as "20:13" for any other locale/country. Uses {@link CalOptions} to determine
-     * locale.
-     * If `options.hour12` is `false`, locale is ignored and always returns 24-hour time.
-     * If `options.hour12` is `true`, locale is ignored and always returns 12-hour time.
+     * Helper function to format a 24-hour (00:00-23:59) time string in either
+     * 12-hour US format (e.g. `"8:13pm"`) or keep it in 24-hour format (e.g.
+     * `"20:13"`) for any other locale or country.
+     *
+     * The locale (and therefore default behavior) is derived from
+     * `options.location` / `options.locale`. The `options.hour12` override
+     * takes precedence: if `false`, locale is ignored and the result is always
+     * 24-hour; if `true`, locale is ignored and the result is always 12-hour.
+     * @example
+     * import {HebrewCalendar, Location} from '@hebcal/core';
+     * const opts = {location: Location.lookup('Chicago')};
+     * HebrewCalendar.reformatTimeStr('20:30', 'pm', opts);          // '8:30pm'
+     * HebrewCalendar.reformatTimeStr('20:30', 'pm', {hour12: false}); // '20:30'
      * @param timeStr - original time like "20:30"
      * @param suffix - "p" or "pm" or " P.M.". Add leading space if you want it
      * @param options
      */
     static reformatTimeStr(timeStr: string, suffix: string, options: CalOptions): string;
+    /**
+     * Returns the semantic version string of the `@hebcal/core` package
+     * (e.g. `"5.10.0"`). Useful for logging or feature detection.
+     */
     static version(): string;
     /**
-     * Convenience function to create an instance of `Sedra` or reuse a previously
-     * created and cached instance.
+     * Convenience function to create an instance of {@link Sedra} or reuse a
+     * previously created and cached instance for the same year + schedule.
+     *
+     * Use this in preference to `new Sedra(...)` when calling repeatedly,
+     * since an internal LRU cache (~120 entries) avoids recomputing the
+     * keviyah-specific reading pattern.
+     * @example
+     * import {HebrewCalendar} from '@hebcal/core';
+     * const sedra = HebrewCalendar.getSedra(5784, false);
+     * const result = sedra.lookup(new HDate(15, 'Cheshvan', 5784));
+     * console.log(result.parsha); // ['Lech-Lecha']
+     * @param hyear Hebrew year
+     * @param il Use Israel sedra schedule (`false` for Diaspora)
      */
     static getSedra(hyear: number, il: boolean): Sedra;
     /**
-     * Return a number containing information on what Hallel is said on that day.
+     * Determines which form of Hallel (if any) is recited
+     * on a given Hebrew date.
+     *
+     * Returns 0 (none), 1 (half Hallel), or 2 (whole Hallel).
      *
      * Whole Hallel is said on Chanukah, the first Yom Tov of Pesach, Shavuot, Sukkot,
      * Yom Ha'atzmaut, and Yom Yerushalayim.
      *
      * Half Hallel is said on Rosh Chodesh (not Rosh Hashanah), and the last 6 days of Pesach.
-     *
-     * The number is one of the following values:
-     *
-     * 0 - No Hallel
-     * 1 - Half Hallel
-     * 2 - Whole Hallel
+     * @returns 0 for no Hallel, 1 for half Hallel, 2 for whole Hallel
+     * @example
+     * import {HebrewCalendar, HDate, months} from '@hebcal/core';
+     * HebrewCalendar.hallel(new HDate(25, months.KISLEV, 5784), false); // 2 (Chanukah)
+     * HebrewCalendar.hallel(new HDate(1, months.SHVAT, 5784), false);   // 1 (Rosh Chodesh)
+     * HebrewCalendar.hallel(new HDate(2, months.SHVAT, 5784), false);   // 0
      */
     static hallel(hdate: HDate, il: boolean): number;
     /**
@@ -255,6 +324,15 @@ export declare class HebrewCalendar {
      * Tachanun is not said at Mincha on days before it is not said at Shacharit.
      *
      * Tachanun is not said at Shacharit on Shabbat, but is at Mincha, usually.
+     * @example
+     * import {HebrewCalendar, HDate, months} from '@hebcal/core';
+     * // Regular weekday — Tachanun is said at both services
+     * HebrewCalendar.tachanun(new HDate(2, months.SHVAT, 5784), false);
+     * // => { shacharit: true, mincha: true, allCongs: true }
+     *
+     * // Rosh Chodesh — no Tachanun
+     * HebrewCalendar.tachanun(new HDate(1, months.SHVAT, 5784), false);
+     * // => { shacharit: false, mincha: false, allCongs: false }
      */
     static tachanun(hdate: HDate, il: boolean): TachanunResult;
 }