@hebcal/core 6.0.5 → 6.0.7

package/dist/src/calendar.d.ts

@@ -0,0 +1,111 @@
+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[];