@hebcal/core 6.5.1 → 6.5.3

package/dist/src/hebcal.js

@@ -46,7 +46,7 @@ export 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:
@@ -223,15 +223,36 @@ export class HebrewCalendar {
     }
     /**
      * 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) {
         return getHolidaysForYear_(year);
     }
     /**
-     * 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
      */
@@ -239,7 +260,16 @@ export class HebrewCalendar {
         return getHolidaysForYearArray(year, il);
     }
     /**
-     * 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
      */
@@ -247,7 +277,20 @@ export class HebrewCalendar {
         return getHolidaysOnDate(date, il);
     }
     /**
-     * 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, il) {
         if (date.getDay() < 3 || date.getDay() > 4) {
@@ -262,11 +305,19 @@ export class HebrewCalendar {
         return true;
     }
     /**
-     * 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
@@ -274,32 +325,53 @@ export class HebrewCalendar {
     static reformatTimeStr(timeStr, suffix, options) {
         return reformatTimeStr(timeStr, suffix, options);
     }
+    /**
+     * Returns the semantic version string of the `@hebcal/core` package
+     * (e.g. `"5.10.0"`). Useful for logging or feature detection.
+     */
     static version() {
         return pkgVersion;
     }
     /**
-     * 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, il) {
         return getSedra(hyear, il);
     }
     /**
-     * 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, il) {
-        const events = getHolidaysForYearArray(hdate.getFullYear(), il);
+        const events = getHolidaysOnDate(hdate, il);
+        if (!events) {
+            return 0;
+        }
         return hallel_(events, hdate);
     }
     /**
@@ -317,6 +389,15 @@ export 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, il) {
         return tachanun(hdate, il);

package/dist/src/holidays.d.ts

@@ -1,7 +1,17 @@
 import { HDate } from '@hebcal/hdate';
 import { HolidayEvent } from './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 (e.g. on the second day of a Yom Tov, both `"Pesach II"` for
+ * Diaspora and any Israel-only events). Pass `true` or `false` to filter
+ * to a single schedule.
+ * @example
+ * import {getHolidaysOnDate, HDate, months} from '@hebcal/core';
+ * const events = getHolidaysOnDate(new HDate(15, months.NISAN, 5784), false);
+ * 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
  */
@@ -15,7 +25,16 @@ export type HolidayYearMap = Map<string, HolidayEvent[]>;
  */
 export declare function getHolidaysForYear_(year: number): HolidayYearMap;
 /**
- * Returns an array of holidays for the year
+ * Returns a sorted array of holidays observed during the given Hebrew year,
+ * filtered by Israel vs. Diaspora schedule.
+ *
+ * Includes Rosh Chodesh, fasts, special Shabbatot, modern holidays, etc.,
+ * but does not generate candle-lighting times, Torah readings, or Omer days.
+ * Use {@link HebrewCalendar.calendar} for those.
+ * @example
+ * import {getHolidaysForYearArray} from '@hebcal/core';
+ * const events = getHolidaysForYearArray(5784, false);
+ * console.log(events[0].getDesc()); // 'Rosh Hashana 5784'
  * @param year Hebrew year
  * @param il use the Israeli schedule for holidays
  */

package/dist/src/holidays.js

@@ -27,7 +27,17 @@ import { staticHolidays, staticModernHolidays, holidayDesc as hdesc, } from './s
 import { YomKippurKatanEvent } from './YomKippurKatanEvent';
 import { HolidayEvent, ChanukahEvent, AsaraBTevetEvent, RoshHashanaEvent, RoshChodeshEvent, } from './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 (e.g. on the second day of a Yom Tov, both `"Pesach II"` for
+ * Diaspora and any Israel-only events). Pass `true` or `false` to filter
+ * to a single schedule.
+ * @example
+ * import {getHolidaysOnDate, HDate, months} from '@hebcal/core';
+ * const events = getHolidaysOnDate(new HDate(15, months.NISAN, 5784), false);
+ * 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
  */
@@ -284,7 +294,16 @@ function getBirkatHaChama(year) {
     return 0;
 }
 /**
- * Returns an array of holidays for the year
+ * Returns a sorted array of holidays observed during the given Hebrew year,
+ * filtered by Israel vs. Diaspora schedule.
+ *
+ * Includes Rosh Chodesh, fasts, special Shabbatot, modern holidays, etc.,
+ * but does not generate candle-lighting times, Torah readings, or Omer days.
+ * Use {@link HebrewCalendar.calendar} for those.
+ * @example
+ * import {getHolidaysForYearArray} from '@hebcal/core';
+ * const events = getHolidaysForYearArray(5784, false);
+ * console.log(events[0].getDesc()); // 'Rosh Hashana 5784'
  * @param year Hebrew year
  * @param il use the Israeli schedule for holidays
  */

package/dist/src/index.d.ts

@@ -17,7 +17,7 @@ export { MoladBase, calculateMolad } from './moladBase';
 export { getMoladAsDate } from './moladDate';
 export { Molad, MoladEvent } from './molad';
 export { OmerEvent, OmerLang } from './omer';
-export { TachanunResult } from './tachanun';
+export { TachanunResult, tachanun } from './tachanun';
 export { Sedra, SedraResult, parshiot, getSedra } from './sedra';
 export { ParshaEvent } from './ParshaEvent';
 export { parshaYear } from './parshaYear';

package/dist/src/index.js

@@ -16,6 +16,7 @@ export { calculateMolad } from './moladBase';
 export { getMoladAsDate } from './moladDate';
 export { Molad, MoladEvent } from './molad';
 export { OmerEvent } from './omer';
+export { tachanun } from './tachanun';
 export { Sedra, parshiot, getSedra } from './sedra';
 export { ParshaEvent } from './ParshaEvent';
 export { parshaYear } from './parshaYear';

package/dist/src/isAssurBemlacha.d.ts

@@ -1,9 +1,29 @@
 import { Location } from './location';
 /**
- * Utility method to determine if the date and time has a <em>melacha</em> (work) prohibition.
- * Although there are many opinions on the time of <em>tzais</em>, for simplicity
- * this function uses solar depression of 8.5 degrees.
+ * Returns `true` if the given moment (date + time) falls within a period
+ * when *melacha* (work) is prohibited — i.e. Shabbat or a Yom Tov.
  *
- * @return `true` if <em>melacha</em> is prohibited or `false` if it is not.
+ * The Shabbat/Yom Tov window is taken to begin at sunset (shkiah) on the
+ * preceding day (Erev Shabbat / Erev Yom Tov / Yom Tov sheni) and to end
+ * at *tzais* (nightfall) on the day itself. *Tzais* is calculated using a
+ * solar depression of 8.5° for simplicity; consult a halachic authority
+ * for more stringent opinions.
+ *
+ * `useElevation` controls whether the location's elevation is taken into
+ * account when computing sunset (it has no effect on the degree-based
+ * tzais calculation). The Israel/Diaspora schedule comes from
+ * `location.getIsrael()`.
+ *
+ * Throws if sunset cannot be calculated for the given location
+ * (e.g. polar regions).
+ * @example
+ * import {isAssurBemlacha, Location} from '@hebcal/core';
+ * const loc = Location.lookup('Jerusalem')!;
+ * // Friday after sunset:
+ * isAssurBemlacha(new Date('2024-04-26T18:00:00Z'), loc, false); // true
+ * @param currentTime the moment to test (with hour/minute)
+ * @param location geographic location (also supplies Israel/Diaspora flag and tzid)
+ * @param useElevation include elevation when computing sunset
+ * @return `true` if *melacha* is prohibited, `false` if it is not
  */
 export declare function isAssurBemlacha(currentTime: Date, location: Location, useElevation: boolean): boolean;

package/dist/src/isAssurBemlacha.js

@@ -29,11 +29,31 @@ function isTodayAssurBemelacha(dow, events) {
     return false;
 }
 /**
- * Utility method to determine if the date and time has a <em>melacha</em> (work) prohibition.
- * Although there are many opinions on the time of <em>tzais</em>, for simplicity
- * this function uses solar depression of 8.5 degrees.
+ * Returns `true` if the given moment (date + time) falls within a period
+ * when *melacha* (work) is prohibited — i.e. Shabbat or a Yom Tov.
  *
- * @return `true` if <em>melacha</em> is prohibited or `false` if it is not.
+ * The Shabbat/Yom Tov window is taken to begin at sunset (shkiah) on the
+ * preceding day (Erev Shabbat / Erev Yom Tov / Yom Tov sheni) and to end
+ * at *tzais* (nightfall) on the day itself. *Tzais* is calculated using a
+ * solar depression of 8.5° for simplicity; consult a halachic authority
+ * for more stringent opinions.
+ *
+ * `useElevation` controls whether the location's elevation is taken into
+ * account when computing sunset (it has no effect on the degree-based
+ * tzais calculation). The Israel/Diaspora schedule comes from
+ * `location.getIsrael()`.
+ *
+ * Throws if sunset cannot be calculated for the given location
+ * (e.g. polar regions).
+ * @example
+ * import {isAssurBemlacha, Location} from '@hebcal/core';
+ * const loc = Location.lookup('Jerusalem')!;
+ * // Friday after sunset:
+ * isAssurBemlacha(new Date('2024-04-26T18:00:00Z'), loc, false); // true
+ * @param currentTime the moment to test (with hour/minute)
+ * @param location geographic location (also supplies Israel/Diaspora flag and tzid)
+ * @param useElevation include elevation when computing sunset
+ * @return `true` if *melacha* is prohibited, `false` if it is not
  */
 export function isAssurBemlacha(currentTime, location, useElevation) {
     const zmanim = new Zmanim(location, currentTime, useElevation);

package/dist/src/isAveilut.d.ts

@@ -1,10 +1,21 @@
 import { HDate } from '@hebcal/hdate';
 /**
- * Utility method to determine if the given date is during a mourning period.
+ * Returns `true` if the given date falls within a public period of communal
+ * mourning — specifically:
  *
- * This broad helper returns `true` during Sefirat HaOmer and Bein HaMetzarim.
- * It does not attempt to model minhag-specific exceptions within those periods.
+ * - **Sefirat HaOmer**: 16 Nisan through 5 Sivan (the 49 days of the Omer).
+ * - **Bein HaMetzarim** ("between the straits"): 17 Tammuz through 9 Av
+ *   (10 Av when 9 Av is postponed because it falls on Shabbat).
  *
+ * This is a broad helper — it does not attempt to model minhag-specific
+ * exceptions within those periods (e.g. Lag BaOmer, Rosh Chodesh Iyar,
+ * the distinction between Sephardic and Ashkenazic customs on which
+ * portion of the Omer is observed as mourning, etc.).
+ * @example
+ * import {isAveilut, HDate, months} from '@hebcal/core';
+ * isAveilut(new HDate(20, months.NISAN, 5784)); // true (Omer)
+ * isAveilut(new HDate(25, months.TAMUZ, 5784)); // true (Three Weeks)
+ * isAveilut(new HDate(15, months.AV, 5784));    // false
  * @param date Hebrew Date, Gregorian date, or absolute R.D. day number
  * @return `true` if the date is during a mourning period
  */

package/dist/src/isAveilut.js

@@ -23,11 +23,22 @@ function isBeinHaMetzarim(hd) {
     return abs >= begin && abs <= end;
 }
 /**
- * Utility method to determine if the given date is during a mourning period.
+ * Returns `true` if the given date falls within a public period of communal
+ * mourning — specifically:
  *
- * This broad helper returns `true` during Sefirat HaOmer and Bein HaMetzarim.
- * It does not attempt to model minhag-specific exceptions within those periods.
+ * - **Sefirat HaOmer**: 16 Nisan through 5 Sivan (the 49 days of the Omer).
+ * - **Bein HaMetzarim** ("between the straits"): 17 Tammuz through 9 Av
+ *   (10 Av when 9 Av is postponed because it falls on Shabbat).
  *
+ * This is a broad helper — it does not attempt to model minhag-specific
+ * exceptions within those periods (e.g. Lag BaOmer, Rosh Chodesh Iyar,
+ * the distinction between Sephardic and Ashkenazic customs on which
+ * portion of the Omer is observed as mourning, etc.).
+ * @example
+ * import {isAveilut, HDate, months} from '@hebcal/core';
+ * isAveilut(new HDate(20, months.NISAN, 5784)); // true (Omer)
+ * isAveilut(new HDate(25, months.TAMUZ, 5784)); // true (Three Weeks)
+ * isAveilut(new HDate(15, months.AV, 5784));    // false
  * @param date Hebrew Date, Gregorian date, or absolute R.D. day number
  * @return `true` if the date is during a mourning period
  */

package/dist/src/isFastDay.d.ts

@@ -1,7 +1,19 @@
 import { HDate } from '@hebcal/hdate';
 /**
- * Utility method to determine if the given date is a fast day.
+ * Returns `true` if the given date is observed as a major or minor fast day.
  *
+ * Major fasts: Yom Kippur, Tish'a B'Av.
+ * Minor fasts: Tzom Gedaliah, Asara B'Tevet, Ta'anit Esther, Ta'anit
+ * Bechorot, Tzom Tammuz (plus BeHaB fasts when enabled).
+ *
+ * Erev Tish'a B'Av — even though the fast begins at sunset — is *not*
+ * counted here: only the actual fast day itself returns `true`.
+ * Postponed fasts return `true` on the actual observed date (e.g. when
+ * 17 Tammuz falls on Shabbat and is observed on the 18th).
+ * @example
+ * import {isFastDay, HDate, months} from '@hebcal/core';
+ * isFastDay(new HDate(10, months.TISHREI, 5784)); // true  (Yom Kippur)
+ * isFastDay(new HDate(11, months.TISHREI, 5784)); // false
  * @param date Hebrew Date, Gregorian date, or absolute R.D. day number
  * @param il use the Israeli schedule for holidays
  * @return `true` if the date is a major or minor fast day

package/dist/src/isFastDay.js

@@ -3,8 +3,20 @@ import { getHolidaysOnDate } from './holidays';
 const FAST_DAY = flags.MAJOR_FAST | flags.MINOR_FAST;
 const EREV = flags.EREV;
 /**
- * Utility method to determine if the given date is a fast day.
+ * Returns `true` if the given date is observed as a major or minor fast day.
  *
+ * Major fasts: Yom Kippur, Tish'a B'Av.
+ * Minor fasts: Tzom Gedaliah, Asara B'Tevet, Ta'anit Esther, Ta'anit
+ * Bechorot, Tzom Tammuz (plus BeHaB fasts when enabled).
+ *
+ * Erev Tish'a B'Av — even though the fast begins at sunset — is *not*
+ * counted here: only the actual fast day itself returns `true`.
+ * Postponed fasts return `true` on the actual observed date (e.g. when
+ * 17 Tammuz falls on Shabbat and is observed on the 18th).
+ * @example
+ * import {isFastDay, HDate, months} from '@hebcal/core';
+ * isFastDay(new HDate(10, months.TISHREI, 5784)); // true  (Yom Kippur)
+ * isFastDay(new HDate(11, months.TISHREI, 5784)); // false
  * @param date Hebrew Date, Gregorian date, or absolute R.D. day number
  * @param il use the Israeli schedule for holidays
  * @return `true` if the date is a major or minor fast day

package/dist/src/location.d.ts

@@ -1,5 +1,29 @@
 import { GeoLocation } from '@hebcal/noaa';
-/** 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 declare class Location extends GeoLocation {
     private readonly il;
     private readonly cc?;
@@ -22,18 +46,54 @@ export declare class Location extends GeoLocation {
      * @param [elevation] - in meters (default `0`)
      */
     constructor(latitude: number, longitude: number, il: boolean, tzid: string, cityName?: string, countryCode?: string, geoid?: string | number, elevation?: number);
+    /**
+     * Returns `true` if this location is in Israel (uses the Israeli holiday
+     * and Torah-reading schedule), `false` for the Diaspora.
+     */
     getIsrael(): boolean;
+    /**
+     * 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(): string | null;
     /**
-     * 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(): string | null;
+    /**
+     * Returns the ISO 3166 alpha-2 country code (e.g. `"US"`, `"IL"`, `"FR"`)
+     * passed to the constructor, or `undefined` if none was provided.
+     */
     getCountryCode(): string | undefined;
+    /**
+     * Returns the Olson timezone identifier (e.g. `"America/Chicago"`).
+     * Alias for `getTimeZone()` from the parent `GeoLocation` class.
+     */
     getTzid(): string;
     /**
-     * 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(): Intl.DateTimeFormat;
+    /**
+     * 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(): string | number | undefined;
     /**
      * Creates a location object from one of 60 "classic" Hebcal city names.
@@ -51,12 +111,31 @@ export declare 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: string): Location | undefined;
+    /**
+     * Returns a JSON-serialized representation of this Location.
+     * Useful for debugging and structured logging.
+     */
     toString(): string;
     /**
-     * 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'
      */
@@ -71,9 +150,18 @@ export declare class Location extends GeoLocation {
      */
     static getUsaTzid(state: string, tz: number, dst: string): string;
     /**
-     * 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: string, location: Location): boolean;
 }