@hebcal/core 6.5.1 → 6.5.2

package/dist/src/location.js

@@ -20,6 +20,7 @@
  */
 import { GeoLocation } from '@hebcal/noaa';
 import citiesJson from './cities.json';
+import QuickLRU from 'quick-lru';
 const classicCities = new Map();
 // Zip-Codes.com TimeZone IDs
 const ZIPCODES_TZ_MAP = {
@@ -38,7 +39,9 @@ const ZIPCODES_TZ_MAP = {
     '16': 'Pacific/Chuuk', //      Micronesia (GMT +11:00)
 };
 /** @private */
-const timeFormatCache = new Map();
+const timeFormatCache = new QuickLRU({
+    maxSize: 120,
+});
 /**
  * Gets a 24-hour time formatter (e.g. 07:41 or 20:03) from cache
  * or makes a new one if needed
@@ -64,7 +67,31 @@ function initClassicCities() {
         Location.addLocation(cityName, location);
     }
 }
-/** Class representing Location */
+/**
+ * Class representing a geographic location for use with candle-lighting,
+ * havdalah, and zmanim calculations.
+ *
+ * Extends {@link GeoLocation} from `@hebcal/noaa` with Jewish-calendar
+ * specific data: an Israel/Diaspora flag, ISO country code, and an optional
+ * geographic identifier. Also provides {@link Location.lookup} for ~60
+ * built-in "classic" Hebcal cities.
+ *
+ * @example
+ * import {Location} from '@hebcal/core';
+ *
+ * // Create a location for a custom address
+ * const loc = new Location(
+ *   41.85003,    // latitude
+ *   -87.65005,   // longitude
+ *   false,       // not in Israel
+ *   'America/Chicago',
+ *   'Chicago, Illinois, USA',
+ *   'US'
+ * );
+ *
+ * // Or look up a built-in classic city
+ * const tlv = Location.lookup('Tel Aviv');
+ */
 export class Location extends GeoLocation {
     il;
     cc;
@@ -107,14 +134,31 @@ export class Location extends GeoLocation {
         this.cc = countryCode;
         this.geoid = geoid;
     }
+    /**
+     * Returns `true` if this location is in Israel (uses the Israeli holiday
+     * and Torah-reading schedule), `false` for the Diaspora.
+     */
     getIsrael() {
         return this.il;
     }
+    /**
+     * Returns the full descriptive location name passed to the constructor,
+     * or `null` if no name was provided.
+     * @example
+     * Location.lookup('San Francisco')?.getName(); // 'San Francisco, California, USA'
+     */
     getName() {
         return this.getLocationName();
     }
     /**
-     * Returns the location name, up to the first comma
+     * Returns the location name truncated at the first comma. Useful for
+     * compact display where only the city name is desired.
+     *
+     * Special-cased so that US locations of the form `"Washington, DC"` or
+     * `"Washington, D.C., ..."` keep the `DC` / `D.C.` suffix attached.
+     * @example
+     * Location.lookup('San Francisco')?.getShortName(); // 'San Francisco'
+     * Location.lookup('Washington DC')?.getShortName(); // 'Washington, DC'
      */
     getShortName() {
         const name = this.getLocationName();
@@ -133,18 +177,37 @@ export class Location extends GeoLocation {
         }
         return name.substring(0, comma);
     }
+    /**
+     * Returns the ISO 3166 alpha-2 country code (e.g. `"US"`, `"IL"`, `"FR"`)
+     * passed to the constructor, or `undefined` if none was provided.
+     */
     getCountryCode() {
         return this.cc;
     }
+    /**
+     * Returns the Olson timezone identifier (e.g. `"America/Chicago"`).
+     * Alias for `getTimeZone()` from the parent `GeoLocation` class.
+     */
     getTzid() {
         return this.getTimeZone();
     }
     /**
-     * Gets a 24-hour time formatter (e.g. 07:41 or 20:03) for this location
+     * Returns a cached 24-hour `Intl.DateTimeFormat` (e.g. `07:41` or `20:03`)
+     * configured for this location's timezone. Formatters are memoized by
+     * timezone so repeated calls do not allocate.
+     * @example
+     * const loc = Location.lookup('Tel Aviv')!;
+     * const fmt = loc.getTimeFormatter();
+     * fmt.format(new Date()); // e.g. '18:42'
      */
     getTimeFormatter() {
         return getFormatter(this.getTimeZone());
     }
+    /**
+     * Returns the optional geographic identifier passed to the constructor
+     * (typically a GeoNames numeric ID or a US Zip Code string), or
+     * `undefined` if none was provided.
+     */
     getGeoId() {
         return this.geoid;
     }
@@ -164,7 +227,13 @@ export class Location extends GeoLocation {
      * 'San Diego', 'San Francisco', 'Sao Paulo', 'Seattle', 'Sydney',
      * 'Tel Aviv', 'Tiberias', 'Toronto', 'Vancouver', 'White Plains',
      * 'Washington DC', 'Worcester'
-     * @param name
+     *
+     * Lookups are case-insensitive. Returns `undefined` if the name is not
+     * recognized. The list can be extended with {@link Location.addLocation}.
+     * @example
+     * const loc = Location.lookup('San Francisco');
+     * console.log(loc?.getTzid()); // 'America/Los_Angeles'
+     * @param name case-insensitive classic city name
      */
     static lookup(name) {
         if (classicCities.size === 0) {
@@ -172,11 +241,24 @@ export class Location extends GeoLocation {
         }
         return classicCities.get(name.toLowerCase());
     }
+    /**
+     * Returns a JSON-serialized representation of this Location.
+     * Useful for debugging and structured logging.
+     */
     toString() {
         return JSON.stringify(this);
     }
     /**
-     * Converts legacy Hebcal timezone to a standard Olson tzid.
+     * Converts a legacy Hebcal-style timezone (a numeric GMT offset plus a
+     * coarse DST region) to a standard IANA/Olson timezone ID.
+     *
+     * This exists to migrate data from older Hebcal versions that stored
+     * timezones as GMT offset + DST scheme rather than as a full tzid.
+     * @example
+     * Location.legacyTzToTzid(2, 'israel'); // 'Asia/Jerusalem'
+     * Location.legacyTzToTzid(0, 'eu');     // 'Europe/London'
+     * Location.legacyTzToTzid(0, 'none');   // 'UTC'
+     * Location.legacyTzToTzid(-5, 'none');  // 'Etc/GMT-5'
      * @param tz integer, GMT offset in hours
      * @param dst 'none', 'eu', 'usa', or 'israel'
      */
@@ -236,9 +318,18 @@ export class Location extends GeoLocation {
         }
     }
     /**
-     * Adds a location name for `Location.lookup()` only if the name isn't
-     * already being used. Returns `false` if the name is already taken
-     * and `true` if successfully added.
+     * Registers a new named location with the built-in `Location.lookup()`
+     * registry. Names are stored case-insensitively. Returns `false` if a
+     * location with the same (lower-cased) name is already registered, and
+     * `true` if successfully added.
+     *
+     * Use this to extend the built-in set of ~60 classic Hebcal cities with
+     * your own custom locations.
+     * @example
+     * const tlv = new Location(32.0853, 34.7818, true,
+     *   'Asia/Tel_Aviv', 'My Office, Tel Aviv', 'IL');
+     * Location.addLocation('My Office', tlv);   // true
+     * Location.lookup('my office')?.getTzid();  // 'Asia/Tel_Aviv'
      */
     static addLocation(cityName, location) {
         const name = cityName.toLowerCase();

package/dist/src/molad.d.ts

@@ -4,7 +4,20 @@ import { CalOptions } from './CalOptions';
 import { HDate } from '@hebcal/hdate';
 import './locale';
 /**
- * Represents a molad, the moment when the new moon is "born"
+ * Represents a *molad* — the calculated moment when the new moon is "born"
+ * for a given Hebrew month.
+ *
+ * The molad is announced in synagogue on Shabbat Mevarchim (the Shabbat
+ * before Rosh Chodesh) and is the anchor point for Kiddush Levana zmanim.
+ * Calculations use the traditional chalakim arithmetic
+ * (1 hour = 1080 chalakim) anchored to *Molad Tohu BaHaRaD*.
+ *
+ * @example
+ * import {Molad, months} from '@hebcal/core';
+ * const m = new Molad(5784, months.NISAN);
+ * console.log(m.getMonthName()); // 'Nisan'
+ * console.log(m.getHour(), m.getMinutes(), m.getChalakim()); // e.g. 1 31 12
+ * console.log(m.render('en')); // 'Molad Nisan: Mon, 1:31am and 12 chalakim'
  */
 export declare class Molad {
     private readonly m;
@@ -12,9 +25,9 @@ export declare class Molad {
     private readonly month;
     private instant?;
     /**
-     * Calculates the molad for a Hebrew month
-     * @param year
-     * @param month 1=NISSAN, 7=TISHREI
+     * Calculates the molad for a given Hebrew year and month.
+     * @param year Hebrew year
+     * @param month 1=NISAN, 7=TISHREI (uses Nisan-based numbering)
      */
     constructor(year: number, month: number);
     /**
@@ -56,12 +69,18 @@ export declare class Molad {
      */
     getChalakim(): number;
     /**
-     * Returns the molad in Standard Time in Yerushalayim as a Temporal.ZonedDateTime.
+     * Returns the molad in Standard Time in Yerushalayim as a `Temporal.ZonedDateTime`.
      * This method subtracts 20.94 minutes (20 minutes and 56.496 seconds) from the computed time (Har Habayis with a longitude
      * of 35.2354° is 5.2354° away from the %15 timezone longitude) to get to standard time. This method
      * intentionally uses standard time and not daylight savings time.
      *
-     * @return the Temporal.ZonedDateTime representing the moment of the molad in Yerushalayim standard time (GMT + 2)
+     * The returned value is cached after the first call.
+     * @example
+     * import {Molad, months} from '@hebcal/core';
+     * const m = new Molad(5784, months.NISAN);
+     * const zdt = m.getInstant();
+     * console.log(zdt.toString()); // e.g. '2024-04-08T17:21:13.333+00:00[UTC]'
+     * @return the `Temporal.ZonedDateTime` representing the moment of the molad
      */
     getInstant(): Temporal.ZonedDateTime;
     /**
@@ -109,8 +128,21 @@ export declare class Molad {
      */
     getSofZmanKidushLevana15Days(): Temporal.ZonedDateTime;
     /**
+     * Returns a human-readable, localized string announcing the molad —
+     * suitable for use on Shabbat Mevarchim. The format includes the Hebrew
+     * month name, day of week, hour : minute, and chalakim if non-zero.
+     *
+     * Time format honors `options.hour12` and `options.location` (12-hour vs.
+     * 24-hour); see {@link HebrewCalendar.reformatTimeStr}.
+     * @example
+     * import {Molad, months} from '@hebcal/core';
+     * const m = new Molad(5784, months.NISAN);
+     * m.render('en', {hour12: true});
+     * // => 'Molad Nisan: Mon, 7:21pm and 6 chalakim'
+     * m.render('he');
+     * // => 'מוֹלָד נִיסָן יִהְיֶה בַּיּוֹם שֵׁנִי בשָׁבוּעַ, …'
      * @param [locale] Optional locale name (defaults to empty locale)
-     * @param options
+     * @param options used for time formatting (12-hour vs 24-hour)
      */
     render(locale?: string, options?: CalOptions): string;
 }

package/dist/src/molad.js

@@ -54,7 +54,20 @@ function getHebrewTimeOfDay(hour) {
     return night;
 }
 /**
- * Represents a molad, the moment when the new moon is "born"
+ * Represents a *molad* — the calculated moment when the new moon is "born"
+ * for a given Hebrew month.
+ *
+ * The molad is announced in synagogue on Shabbat Mevarchim (the Shabbat
+ * before Rosh Chodesh) and is the anchor point for Kiddush Levana zmanim.
+ * Calculations use the traditional chalakim arithmetic
+ * (1 hour = 1080 chalakim) anchored to *Molad Tohu BaHaRaD*.
+ *
+ * @example
+ * import {Molad, months} from '@hebcal/core';
+ * const m = new Molad(5784, months.NISAN);
+ * console.log(m.getMonthName()); // 'Nisan'
+ * console.log(m.getHour(), m.getMinutes(), m.getChalakim()); // e.g. 1 31 12
+ * console.log(m.render('en')); // 'Molad Nisan: Mon, 1:31am and 12 chalakim'
  */
 export class Molad {
     m;
@@ -62,9 +75,9 @@ export class Molad {
     month;
     instant;
     /**
-     * Calculates the molad for a Hebrew month
-     * @param year
-     * @param month 1=NISSAN, 7=TISHREI
+     * Calculates the molad for a given Hebrew year and month.
+     * @param year Hebrew year
+     * @param month 1=NISAN, 7=TISHREI (uses Nisan-based numbering)
      */
     constructor(year, month) {
         this.m = calculateMolad(year, month);
@@ -126,12 +139,18 @@ export class Molad {
         return this.m.chalakim;
     }
     /**
-     * Returns the molad in Standard Time in Yerushalayim as a Temporal.ZonedDateTime.
+     * Returns the molad in Standard Time in Yerushalayim as a `Temporal.ZonedDateTime`.
      * This method subtracts 20.94 minutes (20 minutes and 56.496 seconds) from the computed time (Har Habayis with a longitude
      * of 35.2354° is 5.2354° away from the %15 timezone longitude) to get to standard time. This method
      * intentionally uses standard time and not daylight savings time.
      *
-     * @return the Temporal.ZonedDateTime representing the moment of the molad in Yerushalayim standard time (GMT + 2)
+     * The returned value is cached after the first call.
+     * @example
+     * import {Molad, months} from '@hebcal/core';
+     * const m = new Molad(5784, months.NISAN);
+     * const zdt = m.getInstant();
+     * console.log(zdt.toString()); // e.g. '2024-04-08T17:21:13.333+00:00[UTC]'
+     * @return the `Temporal.ZonedDateTime` representing the moment of the molad
      */
     getInstant() {
         this.instant ??= getMoladAsDate(this.m);
@@ -203,8 +222,21 @@ export class Molad {
         return zdt.add({ hours: 24 * 15 });
     }
     /**
+     * Returns a human-readable, localized string announcing the molad —
+     * suitable for use on Shabbat Mevarchim. The format includes the Hebrew
+     * month name, day of week, hour : minute, and chalakim if non-zero.
+     *
+     * Time format honors `options.hour12` and `options.location` (12-hour vs.
+     * 24-hour); see {@link HebrewCalendar.reformatTimeStr}.
+     * @example
+     * import {Molad, months} from '@hebcal/core';
+     * const m = new Molad(5784, months.NISAN);
+     * m.render('en', {hour12: true});
+     * // => 'Molad Nisan: Mon, 7:21pm and 6 chalakim'
+     * m.render('he');
+     * // => 'מוֹלָד נִיסָן יִהְיֶה בַּיּוֹם שֵׁנִי בשָׁבוּעַ, …'
      * @param [locale] Optional locale name (defaults to empty locale)
-     * @param options
+     * @param options used for time formatting (12-hour vs 24-hour)
      */
     render(locale, options) {
         const monthName = Locale.gettext(this.getMonthName(), locale);

package/dist/src/omer.d.ts

@@ -6,21 +6,49 @@ import './locale';
  * Lang for the Sefira can be English, Hebrew, or Hebrew in Sephardic transliteration.
  */
 export type OmerLang = 'en' | 'he' | 'translit';
-/** Represents a day 1-49 of counting the Omer from Pesach to Shavuot */
+/**
+ * Represents one of the 49 days of counting the Omer between Pesach and
+ * Shavuot (16 Nisan through 5 Sivan).
+ *
+ * Each day has an associated Sefirah pairing (e.g. *Chesed shebiGevurah*),
+ * a word from Psalm 67 (Lamnatzeach), a letter from verse 5 of Psalm 67,
+ * and a word/acrostic from the Ana BeKoach prayer — all accessible via
+ * the methods on this class.
+ *
+ * @example
+ * import {OmerEvent, HDate, months} from '@hebcal/core';
+ * const ev = new OmerEvent(new HDate(16, months.NISAN, 5784), 1);
+ * ev.render('en');        // '1st day of the Omer'
+ * ev.render('he');        // 'א׳ בָּעוֹמֶר'
+ * ev.sefira('translit');  // 'Chesed shebChesed'
+ * ev.getTodayIs('en');    // 'Today is 1 day of the Omer'
+ */
 export declare class OmerEvent extends Event {
     private readonly weekNumber;
     private readonly daysWithinWeeks;
     readonly omer: number;
     /**
-     * @param date
-     * @param omerDay
+     * Constructs an Omer event for a given day (1–49).
+     *
+     * Throws `RangeError` if `omerDay` is outside 1–49.
+     * @param date Hebrew date this Omer day is counted on (the evening of)
+     * @param omerDay day of the Omer, 1 through 49
      */
     constructor(date: HDate, omerDay: number);
     /**
-     * Returns the sefira. For example, on day 8:
+     * Returns the Sefirah pairing associated with this Omer day —
+     * one of the seven lower Sefirot within another, calculated as
+     * `day-within-week` of `week-within-cycle`. For example, on day 8
+     * (week 2, day 1):
      *  * חֶֽסֶד שֶׁבִּגְבוּרָה
      *  * Chesed shebiGevurah
      *  * Lovingkindness within Might
+     * @example
+     * import {OmerEvent, HDate, months} from '@hebcal/core';
+     * const day8 = new OmerEvent(new HDate(23, months.NISAN, 5784), 8);
+     * day8.sefira('en');        // 'Lovingkindness within Might'
+     * day8.sefira('he');        // 'חֶֽסֶד שֶׁבִּגְבוּרָה'
+     * day8.sefira('translit');  // 'Chesed shebiGevurah'
      * @param lang `en` (English), `he` (Hebrew with nikud), or `translit` (Hebrew in Sephardic transliteration)
      * @returns a string such as `Lovingkindness within Might` or `חֶֽסֶד שֶׁבִּגְבוּרָה`
      */

package/dist/src/omer.js

@@ -188,14 +188,33 @@ const anaBekoach = sefira.anaBekoach;
 const ps67lines = sefira.ps67lines;
 const lamnatzeach = ps67lines.flatMap((x) => x.split(/[ ־]/));
 const lamnatzeachLetters = sefira.lamnatzeachLetters.split('');
-/** Represents a day 1-49 of counting the Omer from Pesach to Shavuot */
+/**
+ * Represents one of the 49 days of counting the Omer between Pesach and
+ * Shavuot (16 Nisan through 5 Sivan).
+ *
+ * Each day has an associated Sefirah pairing (e.g. *Chesed shebiGevurah*),
+ * a word from Psalm 67 (Lamnatzeach), a letter from verse 5 of Psalm 67,
+ * and a word/acrostic from the Ana BeKoach prayer — all accessible via
+ * the methods on this class.
+ *
+ * @example
+ * import {OmerEvent, HDate, months} from '@hebcal/core';
+ * const ev = new OmerEvent(new HDate(16, months.NISAN, 5784), 1);
+ * ev.render('en');        // '1st day of the Omer'
+ * ev.render('he');        // 'א׳ בָּעוֹמֶר'
+ * ev.sefira('translit');  // 'Chesed shebChesed'
+ * ev.getTodayIs('en');    // 'Today is 1 day of the Omer'
+ */
 export class OmerEvent extends Event {
     weekNumber;
     daysWithinWeeks;
     omer;
     /**
-     * @param date
-     * @param omerDay
+     * Constructs an Omer event for a given day (1–49).
+     *
+     * Throws `RangeError` if `omerDay` is outside 1–49.
+     * @param date Hebrew date this Omer day is counted on (the evening of)
+     * @param omerDay day of the Omer, 1 through 49
      */
     constructor(date, omerDay) {
         super(date, `Omer ${omerDay}`, flags.OMER_COUNT);
@@ -205,10 +224,19 @@ export class OmerEvent extends Event {
         this.omer = omerDay;
     }
     /**
-     * Returns the sefira. For example, on day 8:
+     * Returns the Sefirah pairing associated with this Omer day —
+     * one of the seven lower Sefirot within another, calculated as
+     * `day-within-week` of `week-within-cycle`. For example, on day 8
+     * (week 2, day 1):
      *  * חֶֽסֶד שֶׁבִּגְבוּרָה
      *  * Chesed shebiGevurah
      *  * Lovingkindness within Might
+     * @example
+     * import {OmerEvent, HDate, months} from '@hebcal/core';
+     * const day8 = new OmerEvent(new HDate(23, months.NISAN, 5784), 8);
+     * day8.sefira('en');        // 'Lovingkindness within Might'
+     * day8.sefira('he');        // 'חֶֽסֶד שֶׁבִּגְבוּרָה'
+     * day8.sefira('translit');  // 'Chesed shebiGevurah'
      * @param lang `en` (English), `he` (Hebrew with nikud), or `translit` (Hebrew in Sephardic transliteration)
      * @returns a string such as `Lovingkindness within Might` or `חֶֽסֶד שֶׁבִּגְבוּרָה`
      */

package/dist/src/parshaYear.d.ts

@@ -1,6 +1,17 @@
 import { ParshaEvent } from './ParshaEvent';
 /**
- * Calculates weekly Torah Reading on Saturdays for entire year
+ * Calculates the weekly Torah Reading (Parashat HaShavua) on Saturdays for
+ * an entire Hebrew year.
+ *
+ * Saturdays on which a Yom Tov reading displaces the regular parsha
+ * (e.g. Shabbat Chol ha-Moed Pesach/Sukkot, Yom Kippur on Shabbat) are
+ * skipped — for those use {@link getHolidaysOnDate} or
+ * {@link Sedra.lookup}.
+ * @example
+ * import {parshaYear} from '@hebcal/core';
+ * const events = parshaYear(5784, false);
+ * events[0].render('en'); // 'Parashat Vayeilech'
+ * events[0].getDate().toString(); // '4 Tishrei 5784'
  * @param year Hebrew year
  * @param il Israel (false for Diaspora)
  * @returns an array of `ParshaEvent` occurring on Saturdays that contain a regular

package/dist/src/parshaYear.js

@@ -2,7 +2,18 @@ import { HDate, months } from '@hebcal/hdate';
 import { ParshaEvent } from './ParshaEvent';
 import { getSedra } from './sedra';
 /**
- * Calculates weekly Torah Reading on Saturdays for entire year
+ * Calculates the weekly Torah Reading (Parashat HaShavua) on Saturdays for
+ * an entire Hebrew year.
+ *
+ * Saturdays on which a Yom Tov reading displaces the regular parsha
+ * (e.g. Shabbat Chol ha-Moed Pesach/Sukkot, Yom Kippur on Shabbat) are
+ * skipped — for those use {@link getHolidaysOnDate} or
+ * {@link Sedra.lookup}.
+ * @example
+ * import {parshaYear} from '@hebcal/core';
+ * const events = parshaYear(5784, false);
+ * events[0].render('en'); // 'Parashat Vayeilech'
+ * events[0].getDate().toString(); // '4 Tishrei 5784'
  * @param year Hebrew year
  * @param il Israel (false for Diaspora)
  * @returns an array of `ParshaEvent` occurring on Saturdays that contain a regular

package/dist/src/pkgVersion.d.ts

@@ -1,2 +1,2 @@
 /** DO NOT EDIT THIS AUTO-GENERATED FILE! */
-export declare const version = "6.5.1";
+export declare const version = "6.5.2";

package/dist/src/pkgVersion.js

@@ -1,2 +1,2 @@
 /** DO NOT EDIT THIS AUTO-GENERATED FILE! */
-export const version = '6.5.1';
+export const version = '6.5.2';

package/dist/src/sedra.d.ts

@@ -27,7 +27,23 @@ export type SedraResult = {
     il: boolean;
 };
 /**
- * Represents Parashah HaShavua for an entire Hebrew year
+ * Represents the weekly Torah-reading (Parashat HaShavua) schedule for an
+ * entire Hebrew year.
+ *
+ * The schedule depends on the year's *keviyah* — the day of week of Rosh
+ * Hashana, whether the year is leap, whether Cheshvan/Kislev are long or
+ * short, and whether the schedule is for Israel or the Diaspora (since
+ * Israel and the Diaspora diverge in some years when the 8th day of Pesach
+ * or the 2nd day of Shavuot fall on Shabbat).
+ *
+ * Prefer {@link getSedra} (or {@link HebrewCalendar.getSedra}) over
+ * calling this constructor directly, since both cache their results.
+ *
+ * @example
+ * import {Sedra, HDate, months} from '@hebcal/core';
+ * const sedra = new Sedra(5784, false);
+ * const result = sedra.lookup(new HDate(15, months.CHESHVAN, 5784));
+ * console.log(result.parsha); // ['Lech-Lecha']
  */
 export declare class Sedra {
     private readonly year;
@@ -37,14 +53,29 @@ export declare class Sedra {
     private readonly theSedraArray;
     private readonly yearKey;
     /**
-     * Caculates the Parashah HaShavua for an entire Hebrew year
+     * Calculates the Parashat HaShavua schedule for an entire Hebrew year.
      * @param hyear - Hebrew year (e.g. 5749)
      * @param il - Use Israel sedra schedule (false for Diaspora)
      */
     constructor(hyear: number, il: boolean);
     /**
-     * Returns the date that a parsha occurs
-     * or `null` if the parsha doesn't occur this year
+     * Returns the date a parsha is read this year, or `null` if it does not
+     * occur in this year's schedule.
+     *
+     * A doubled parsha (e.g. `'Matot-Masei'`) will only return a date in years
+     * where that pair is actually read together; in years where they are read
+     * separately, this returns `null`. Use {@link findContaining} to find the
+     * date a parsha is read regardless of whether it is doubled.
+     *
+     * Throws `RangeError` for an out-of-range numeric input or an invalid
+     * doubled-parsha pair, and `TypeError` for a malformed array argument.
+     * @example
+     * import {Sedra} from '@hebcal/core';
+     * const sedra = new Sedra(5784, false);
+     * sedra.find('Noach')?.toString();         // '15 Cheshvan 5784'
+     * sedra.find(1)?.toString();                // same, by 0-based index
+     * sedra.find('Matot-Masei')?.toString();   // null in 5784 — read separately
+     * sedra.find(['Matot', 'Masei']);          // also null in 5784
      * @param parsha if a `string`, specified with Sephardic transliterations
      *  like `'Noach'` or `'Matot-Masei'`. If an array, must be a 1- or 2-element
      *  array such as `['Noach']` or `['Matot', 'Masei']`. If a `number`, should
@@ -54,22 +85,63 @@ export declare class Sedra {
     find(parsha: number | string | string[]): HDate | null;
     private findInternal;
     /**
-     * Returns the date that a parsha (or its doubled or undoubled counterpart)
-     * occurs, or `null` if the parsha doesn't occur this year
+     * Returns the date a parsha is read this year, looking through both
+     * single and doubled forms.
+     *
+     * For example, if `'Matot'` is read individually this year, this returns
+     * its date; if it is read as part of `'Matot-Masei'` this year, this
+     * returns the date of `'Matot-Masei'` (and similarly for `'Masei'`).
+     * Conversely, asking for `'Matot-Masei'` in a year where they are split
+     * will return the date of `'Matot'` alone.
+     * @example
+     * import {Sedra} from '@hebcal/core';
+     * const sedra = new Sedra(5784, false);
+     * // Matot-Masei is split in 5784; both individual halves resolve:
+     * sedra.findContaining('Matot')?.toString();        // '22 Tamuz 5784'
+     * sedra.findContaining('Masei')?.toString();        // '29 Tamuz 5784'
+     * // Asking for the doubled name returns the date of the first half:
+     * sedra.findContaining('Matot-Masei')?.toString();  // '22 Tamuz 5784'
      */
     findContaining(parsha: number | string): HDate | null;
     /**
-     * Returns the underlying annual sedra schedule.
-     * Used by `@hebcal/triennial`
+     * Returns the underlying annual reading schedule as an array, where each
+     * entry corresponds to one Saturday (starting from the first Shabbat on
+     * or after Rosh Hashana). Entries are either:
+     * - a non-negative `number`: a 0-based parsha index (e.g. `0` for
+     *   *Bereshit*)
+     * - a negative `number`: the negated first index of a doubled parsha
+     *   (e.g. `-21` for *Vayakhel-Pekudei*)
+     * - a `string`: a holiday name when a Yom Tov displaces the weekly reading
+     *   (e.g. `'Pesach Shabbat Chol ha-Moed'`, `'Yom Kippur'`)
+     *
+     * Used by `@hebcal/triennial`.
      */
     getSedraArray(): readonly NumberOrString[];
     /**
-     * R.D. date of the first Saturday on or after Rosh Hashana
+     * Returns the R.D. (Rata Die / Fixed Date) absolute day number of the
+     * first Saturday on or after Rosh Hashana of this year. This is the
+     * anchor point for {@link getSedraArray} — index `0` of that array
+     * corresponds to this date.
      */
     getFirstSaturday(): number;
+    /** Returns the Hebrew year this `Sedra` instance covers. */
     getYear(): number;
     /**
-     * Returns an object describing the parsha on the first Saturday on or after `hd`
+     * Returns details about the parsha read on the first Saturday on or after
+     * `hd`. If `hd` is itself a Saturday, the reading for that date is
+     * returned; otherwise the reading for the upcoming Saturday is returned.
+     *
+     * If the given date falls in the final days of the Hebrew year (after
+     * the last reading of this year's schedule), this method transparently
+     * delegates to the next year's `Sedra`.
+     * @example
+     * import {Sedra, HDate, months} from '@hebcal/core';
+     * const sedra = new Sedra(5784, false);
+     * // A weekday — returns the upcoming Shabbat's reading
+     * const result = sedra.lookup(new HDate(13, months.CHESHVAN, 5784));
+     * console.log(result.parsha); // ['Lech-Lecha']
+     * console.log(result.chag);   // false
+     * console.log(result.hdate.toString()); // '15 Cheshvan 5784' (Saturday)
      * @param hd Hebrew date or R.D. days
      */
     lookup(hd: HDate | number): SedraResult;
@@ -86,10 +158,18 @@ export declare class Sedra {
 export declare const parshiot: readonly string[];
 type NumberOrString = number | string;
 /**
- * Convenience function to create an instance of `Sedra` or reuse a previously
- * created and cached instance.
- * @param hyear
- * @param il
+ * Convenience function to create an instance of {@link Sedra} or reuse a
+ * previously created and cached instance for the same year and schedule.
+ *
+ * Prefer this over `new Sedra(...)` when calling repeatedly — an internal
+ * LRU cache (~120 entries) avoids recomputing the keviyah-specific schedule.
+ * @example
+ * import {getSedra, HDate, months} from '@hebcal/core';
+ * const sedra = getSedra(5784, false);
+ * const {parsha} = sedra.lookup(new HDate(15, months.CHESHVAN, 5784));
+ * console.log(parsha); // ['Lech-Lecha']
+ * @param hyear Hebrew year
+ * @param il Use Israel sedra schedule (`false` for Diaspora)
  */
 export declare function getSedra(hyear: number, il: boolean): Sedra;
 export {};