@hebcal/core/dist/esm/calendar.d.ts

A perpetual Jewish Calendar API

import { CalOptions } from './CalOptions';
import { Event } from './event';
/**
 * Calculates holidays and other Hebrew calendar events based on {@link CalOptions}.
 *
 * Each holiday is represented by an {@link Event} object which includes a date,
 * a description, flags and optional attributes.
 * If given no options, returns holidays for the Diaspora for the current Gregorian year.
 *
 * 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.month` - Gregorian or Hebrew month (to filter results to a single month)
 *
 * Alternatively, specify start and end days with `Date` or {@link HDate} instances:
 * * `options.start` - use specific start date (requires `end` date)
 * * `options.end` - use specific end date (requires `start` date)
 *
 * Unless `options.noHolidays == true`, default holidays include:
 * * Major holidays - Rosh Hashana, Yom Kippur, Pesach, Sukkot, etc.
 * * Minor holidays - Purim, Chanukah, Tu BiShvat, Lag BaOmer, etc.
 * * Minor fasts - Ta'anit Esther, Tzom Gedaliah, etc. (unless `options.noMinorFast`)
 * * Special Shabbatot - Shabbat Shekalim, Zachor, etc. (unless `options.noSpecialShabbat`)
 * * Modern Holidays - Yom HaShoah, Yom HaAtzma'ut, etc. (unless `options.noModern`)
 * * Rosh Chodesh (unless `options.noRoshChodesh`)
 *
 * Holiday and Torah reading schedules differ between Israel and the Disapora.
 * Set `options.il=true` to use the Israeli schedule.
 *
 * Additional non-default event types can be specified:
 * * Parashat HaShavua - weekly Torah Reading on Saturdays (`options.sedrot`)
 * * Counting of the Omer (`options.omer`)
 * * Shabbat Mevarchim HaChodesh on Saturday before Rosh Chodesh (`options.shabbatMevarchim`)
 * * Molad announcement on Saturday before Rosh Chodesh (`options.molad`)
 * * Yom Kippur Katan (`options.yomKippurKatan`)
 * * Yizkor (`options.yizkor`)
 *
 * Daily Study of texts are supported by the
 * {@link https://github.com/hebcal/hebcal-learning @hebcal/learning} package,
 * for example:
 * * Babylonian Talmud Daf Yomi (`options.dailyLearning.dafYomi`)
 * * Jerusalem Talmud (Yerushalmi) Yomi (`options.dailyLearning.yerushalmi`)
 * * Mishna Yomi (`options.dailyLearning.mishnaYomi`)
 * * Nach Yomi (`options.dailyLearning.nachYomi`)
 *
 * Candle-lighting and Havdalah times are approximated using latitude and longitude
 * specified by the {@link Location} class. The `Location` class contains a small
 * database of cities with their associated geographic information and time-zone information.
 * If you ever have any doubts about Hebcal's times, consult your local halachic authority.
 * If you enter geographic coordinates above the arctic circle or antarctic circle,
 * the times are guaranteed to be wrong.
 *
 * To add candle-lighting options, set `options.candlelighting=true` and set
 * `options.location` to an instance of `Location`. By default, candle lighting
 * time is 18 minutes before sundown (40 minutes for Jerusalem,
 * 30 minutes for Haifa and Zikhron Ya'akov) and Havdalah is
 * calculated according to Tzeit Hakochavim - Nightfall (the point when 3 small stars
 * are observable in the night time sky with the naked eye). The default Havdalah
 * option (Tzeit Hakochavim) is calculated when the sun is 8.5° below the horizon.
 * These defaults can be changed using these options:
 * * `options.candleLightingMins` - minutes before sundown to light candles
 * * `options.havdalahMins` - minutes after sundown for Havdalah (typical values are 42, 50, or 72).
 *    Havdalah times are suppressed when `options.havdalahMins=0`.
 * * `options.havdalahDeg` - degrees for solar depression for Havdalah.
 *    Default is 8.5 degrees for 3 small stars. Use 7.083 degrees for 3 medium-sized stars.
 *    Havdalah times are suppressed when `options.havdalahDeg=0`.
 *
 * If both `options.candlelighting=true` and `options.location` is specified,
 * Chanukah candle-lighting times and minor fast start/end times will also be generated.
 * Chanukah candle-lighting is at Bein HaShmashos (13.5 minutes before
 * the sun is 7.083° below the horizon in the evening)
 * on weekdays, at regular candle-lighting time on Fridays, and at regular Havdalah time on
 * Saturday night (see above).
 *
 * Minor fasts begin at Alot HaShachar (sun is 16.1° below the horizon in the morning) and
 * end when 3 medium-sized stars are observable in the night sky (sun is 7.083° below the horizon
 * in the evening).
 *
 * Two options also exist for generating an Event with the Hebrew date:
 * * `options.addHebrewDates` - print the Hebrew date for the entire date range
 * * `options.addHebrewDatesForEvents` - print the Hebrew date for dates with some events
 *
 * Lastly, translation and transliteration of event titles is controlled by
 * `options.locale` and the {@link Locale} API.
 * `@hebcal/core` supports three locales by default:
 * * `en` - default, Sephardic transliterations (e.g. "Shabbat")
 * * `ashkenazi` - Ashkenazi transliterations (e.g. "Shabbos")
 * * `he` - Hebrew (e.g. "שַׁבָּת")
 *
 * Additional locales (such as `ru` or `fr`) are supported by the
 * {@link https://github.com/hebcal/hebcal-locales @hebcal/locales} package
 *
 * @example
 * import {HebrewCalendar, HDate, Location, Event} from '@hebcal/core';
 * const options: CalOptions = {
 *   year: 1981,
 *   isHebrewYear: false,
 *   candlelighting: true,
 *   location: Location.lookup('San Francisco'),
 *   sedrot: true,
 *   omer: true,
 * };
 * const events = HebrewCalendar.calendar(options);
 * for (const ev of events) {
 *   const hd = ev.getDate();
 *   const date = hd.greg();
 *   console.log(date.toLocaleDateString(), ev.render('en'), hd.toString());
 * }
 */
export declare function calendar(options?: CalOptions): Event[];