@hebcal/core 6.5.1 → 6.5.3

package/dist/src/ashkenazi.po.js

@@ -1 +1 @@
-export default { "headers": { "plural-forms": "nplurals=2; plural=(n > 1);", "language": "en_CA@ashkenazi" }, "contexts": { "": { "Shabbat": ["Shabbos"], "Achrei Mot": ["Achrei Mos"], "Bechukotai": ["Bechukosai"], "Beha'alotcha": ["Beha’aloscha"], "Bereshit": ["Bereshis"], "Chukat": ["Chukas"], "Erev Shavuot": ["Erev Shavuos"], "Erev Sukkot": ["Erev Sukkos"], "Ki Tavo": ["Ki Savo"], "Ki Teitzei": ["Ki Seitzei"], "Ki Tisa": ["Ki Sisa"], "Matot": ["Matos"], "Pesach Shabbat Chol ha-Moed": ["Pesach Shabbos Chol ha-Moed"], "Purim Katan": ["Purim Koton"], "Shabbat Chazon": ["Shabbos Chazon"], "Shabbat HaChodesh": ["Shabbos HaChodesh"], "Shabbat HaGadol": ["Shabbos HaGadol"], "Shabbat Nachamu": ["Shabbos Nachamu"], "Shabbat Parah": ["Shabbos Parah"], "Shabbat Shekalim": ["Shabbos Shekalim"], "Shabbat Shuva": ["Shabbos Shuvah"], "Shabbat Zachor": ["Shabbos Zachor"], "Shavuot": ["Shavuos"], "Shavuot I": ["Shavuos I"], "Shavuot II": ["Shavuos II"], "Shemot": ["Shemos"], "Shmini Atzeret": ["Shmini Atzeres"], "Simchat Torah": ["Simchas Torah"], "Sukkot": ["Sukkos"], "Sukkot I": ["Sukkos I"], "Sukkot II": ["Sukkos II"], "Sukkot II (CH''M)": ["Sukkos II (CH’’M)"], "Sukkot III (CH''M)": ["Sukkos III (CH’’M)"], "Sukkot IV (CH''M)": ["Sukkos IV (CH’’M)"], "Sukkot V (CH''M)": ["Sukkos V (CH’’M)"], "Sukkot VI (CH''M)": ["Sukkos VI (CH’’M)"], "Sukkot VII (Hoshana Raba)": ["Sukkos VII (Hoshana Raba)"], "Sukkot Shabbat Chol ha-Moed": ["Sukkos Shabbos Chol ha-Moed"], "Ta'anit Bechorot": ["Ta’anis Bechoros"], "Ta'anit BeHaB": ["Ta’anis BeHaB"], "Ta'anit Esther": ["Ta’anis Esther"], "Toldot": ["Toldos"], "Vaetchanan": ["Vaeschanan"], "Yitro": ["Yisro"], "Vezot Haberakhah": ["Vezos Haberakhah"], "Parashat": ["Parshas"], "Leil Selichot": ["Leil Selichos"], "Shabbat Mevarchim Chodesh": ["Shabbos Mevorchim Chodesh"], "Shabbat Shirah": ["Shabbos Shirah"], "Asara B'Tevet": ["Asara B’Teves"], "Birkat Hachamah": ["Birkas HaChamah"], "Birkat HaChamah": ["Birkas HaChamah"], "Shushan Purim Katan": ["Shushan Purim Koton"], "Alot HaShachar": ["Alos HaShachar"], "Misheyakir": ["Misheyakir"], "Misheyakir Machmir": ["Misheyakir Machmir"], "Sunrise": ["Sunrise"], "Kriat Shema, sof zeman": ["Krias Shema, sof zman"], "Tefilah, sof zeman": ["Tefilah, sof zman"], "Kriat Shema, sof zeman (MGA)": ["Krias Shema, sof zman (MGA)"], "Kriat Shema, sof zeman (GRA)": ["Krias Shema, sof zman (GRA)"], "Tefilah, sof zeman (MGA)": ["Tefilah, sof zman (MGA)"], "Tefilah, sof zeman (GRA)": ["Tefilah, sof zman (GRA)"], "Chatzot HaLailah": ["Chatzos HaLailah"], "Chatzot HaYom": ["Chatzos"], "Chatzot hayom": ["Chatzos"], "Mincha Gedolah": ["Mincha Gedolah"], "Mincha Ketanah": ["Mincha Ketanah"], "Plag HaMincha": ["Plag HaMincha"], "Sunset": ["Sunset"], "Bein HaShemashot": ["Bein HaShemashos"], "Tzeit HaKochavim": ["Tzeis HaKochavim"] } } };
+export default { "headers": { "plural-forms": "nplurals=2; plural=(n > 1);", "language": "en_CA@ashkenazi" }, "contexts": { "": { "Shabbat": ["Shabbos"], "Achrei Mot": ["Achrei Mos"], "Bechukotai": ["Bechukosai"], "Beha'alotcha": ["Beha’aloscha"], "Bereshit": ["Bereshis"], "Chukat": ["Chukas"], "Erev Shavuot": ["Erev Shavuos"], "Erev Sukkot": ["Erev Sukkos"], "Ki Tavo": ["Ki Savo"], "Ki Teitzei": ["Ki Seitzei"], "Ki Tisa": ["Ki Sisa"], "Matot": ["Matos"], "Pesach Shabbat Chol ha-Moed": ["Pesach Shabbos Chol ha-Moed"], "Purim Katan": ["Purim Koton"], "Rosh Hashana LaBehemot": ["Rosh Hashana LaBeheimos"], "Shabbat Chazon": ["Shabbos Chazon"], "Shabbat HaChodesh": ["Shabbos HaChodesh"], "Shabbat HaGadol": ["Shabbos HaGadol"], "Shabbat Nachamu": ["Shabbos Nachamu"], "Shabbat Parah": ["Shabbos Parah"], "Shabbat Shekalim": ["Shabbos Shekalim"], "Shabbat Shuva": ["Shabbos Shuvah"], "Shabbat Zachor": ["Shabbos Zachor"], "Shavuot": ["Shavuos"], "Shavuot I": ["Shavuos I"], "Shavuot II": ["Shavuos II"], "Shemot": ["Shemos"], "Shmini Atzeret": ["Shmini Atzeres"], "Simchat Torah": ["Simchas Torah"], "Sukkot": ["Sukkos"], "Sukkot I": ["Sukkos I"], "Sukkot II": ["Sukkos II"], "Sukkot II (CH''M)": ["Sukkos II (CH’’M)"], "Sukkot III (CH''M)": ["Sukkos III (CH’’M)"], "Sukkot IV (CH''M)": ["Sukkos IV (CH’’M)"], "Sukkot V (CH''M)": ["Sukkos V (CH’’M)"], "Sukkot VI (CH''M)": ["Sukkos VI (CH’’M)"], "Sukkot VII (Hoshana Raba)": ["Sukkos VII (Hoshana Raba)"], "Sukkot Shabbat Chol ha-Moed": ["Sukkos Shabbos Chol ha-Moed"], "Ta'anit Bechorot": ["Ta’anis Bechoros"], "Ta'anit BeHaB": ["Ta’anis BeHaB"], "Ta'anit Esther": ["Ta’anis Esther"], "Toldot": ["Toldos"], "Vaetchanan": ["Vaeschanan"], "Yitro": ["Yisro"], "Vezot Haberakhah": ["Vezos Haberakhah"], "Parashat": ["Parshas"], "Leil Selichot": ["Leil Selichos"], "Shabbat Mevarchim Chodesh": ["Shabbos Mevorchim Chodesh"], "Shabbat Shirah": ["Shabbos Shirah"], "Asara B'Tevet": ["Asara B’Teves"], "Birkat Hachamah": ["Birkas HaChamah"], "Birkat HaChamah": ["Birkas HaChamah"], "Shushan Purim Katan": ["Shushan Purim Koton"], "Alot HaShachar": ["Alos HaShachar"], "Misheyakir": ["Misheyakir"], "Misheyakir Machmir": ["Misheyakir Machmir"], "Sunrise": ["Sunrise"], "Kriat Shema, sof zeman": ["Krias Shema, sof zman"], "Tefilah, sof zeman": ["Tefilah, sof zman"], "Kriat Shema, sof zeman (MGA)": ["Krias Shema, sof zman (MGA)"], "Kriat Shema, sof zeman (GRA)": ["Krias Shema, sof zman (GRA)"], "Tefilah, sof zeman (MGA)": ["Tefilah, sof zman (MGA)"], "Tefilah, sof zeman (GRA)": ["Tefilah, sof zman (GRA)"], "Chatzot HaLailah": ["Chatzos HaLailah"], "Chatzot HaYom": ["Chatzos"], "Chatzot hayom": ["Chatzos"], "Mincha Gedolah": ["Mincha Gedolah"], "Mincha Ketanah": ["Mincha Ketanah"], "Plag HaMincha": ["Plag HaMincha"], "Sunset": ["Sunset"], "Bein HaShemashot": ["Bein HaShemashos"], "Tzeit HaKochavim": ["Tzeis HaKochavim"] } } };

package/dist/src/candles.d.ts

@@ -8,7 +8,20 @@ import { TimedEvent } from './TimedEvent';
  * @private
  */
 export declare function makeCandleEvent(ev: Event | undefined, hd: HDate, options: CalOptions, isFriday: boolean, isSaturday: boolean): TimedEvent | undefined;
-/** A fast day also contains a start and end time */
+/**
+ * A fast day holiday with attached start and end time events.
+ *
+ * Wraps an underlying fast-day {@link HolidayEvent} and (when computable
+ * for the given location) exposes a "Fast begins" and "Fast ends"
+ * {@link TimedEvent}. Generated by {@link HebrewCalendar.calendar} when
+ * `options.candlelighting` is `true` and `options.location` is provided.
+ *
+ * - Minor fasts begin at *Alot HaShachar* (16.1° below horizon in the morning)
+ *   and end at tzeit (7.083° by default — overridable via `options.fastEndDeg`).
+ * - Tish'a B'Av begins at sunset on the previous day and ends at tzeit.
+ * - When a minor fast falls on a Friday, the end time is suppressed
+ *   (Shabbat begins before nightfall).
+ */
 export declare class FastDayEvent extends HolidayEvent {
     /** original event */
     readonly linkedEvent: HolidayEvent;

package/dist/src/candles.js

@@ -52,7 +52,20 @@ export function makeCandleEvent(ev, hd, options, isFriday, isSaturday) {
 }
 const FAST_BEGINS = hdesc.FAST_BEGINS;
 const FAST_ENDS = hdesc.FAST_ENDS;
-/** A fast day also contains a start and end time */
+/**
+ * A fast day holiday with attached start and end time events.
+ *
+ * Wraps an underlying fast-day {@link HolidayEvent} and (when computable
+ * for the given location) exposes a "Fast begins" and "Fast ends"
+ * {@link TimedEvent}. Generated by {@link HebrewCalendar.calendar} when
+ * `options.candlelighting` is `true` and `options.location` is provided.
+ *
+ * - Minor fasts begin at *Alot HaShachar* (16.1° below horizon in the morning)
+ *   and end at tzeit (7.083° by default — overridable via `options.fastEndDeg`).
+ * - Tish'a B'Av begins at sunset on the previous day and ends at tzeit.
+ * - When a minor fast falls on a Friday, the end time is suppressed
+ *   (Shabbat begins before nightfall).
+ */
 export class FastDayEvent extends HolidayEvent {
     /** original event */
     linkedEvent;

package/dist/src/event.d.ts

@@ -70,10 +70,20 @@ export declare const flags: {
  * 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 */
@@ -132,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;
     /**
@@ -184,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

@@ -86,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 */
@@ -171,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;
@@ -237,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/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;
 }