Chanukah candle-lighting is at Bein HaShmashos (13.5 minutes before t…

…he sun is 7.083° below the horizon in the evening)

README.md

@@ -1925,6 +1925,7 @@ https://gml.noaa.gov/grad/solcalc/calcdetails.html
         * [.tzeit([angle])](#Zmanim+tzeit) ⇒ <code>Date</code>
         * [.neitzHaChama()](#Zmanim+neitzHaChama) ⇒ <code>Date</code>
         * [.shkiah()](#Zmanim+shkiah) ⇒ <code>Date</code>
+        * [.beinHaShmashos()](#Zmanim+beinHaShmashos) ⇒ <code>Date</code>
         * [.sunriseOffset(offset, roundMinute, forceSeaLevel)](#Zmanim+sunriseOffset) ⇒ <code>Date</code>
         * [.sunsetOffset(offset, roundMinute, forceSeaLevel)](#Zmanim+sunsetOffset) ⇒ <code>Date</code>
     * _static_
@@ -2121,6 +2122,15 @@ Alias for sunrise
 ### zmanim.shkiah() ⇒ <code>Date</code>
 Alias for sunset
 
+**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)  
+<a name="Zmanim+beinHaShmashos"></a>
+
+### zmanim.beinHaShmashos() ⇒ <code>Date</code>
+Rabbeinu Tam holds that bein hashmashos is a specific time
+between sunset and tzeis hakochavim.
+One opinion on how to calculate this time is that
+it is 13.5 minutes before tzies 7.083
+
 **Kind**: instance method of [<code>Zmanim</code>](#Zmanim)  
 <a name="Zmanim+sunriseOffset"></a>
 
@@ -2671,6 +2681,8 @@ Represents a built-in holiday like Pesach, Purim or Tu BiShvat
     * [.urlDateSuffix()](#HolidayEvent+urlDateSuffix) ⇒ <code>string</code>
     * [.getEmoji()](#HolidayEvent+getEmoji) ⇒ <code>string</code>
     * [.getCategories()](#HolidayEvent+getCategories) ⇒ <code>Array.&lt;string&gt;</code>
+    * [.render([locale])](#HolidayEvent+render) ⇒ <code>string</code>
+    * [.renderBrief([locale])](#HolidayEvent+renderBrief) ⇒ <code>string</code>
 
 <a name="HolidayEvent+basename"></a>
 
@@ -2692,6 +2704,30 @@ Represents a built-in holiday like Pesach, Purim or Tu BiShvat
 
 ### holidayEvent.getCategories() ⇒ <code>Array.&lt;string&gt;</code>
 **Kind**: instance method of [<code>HolidayEvent</code>](#HolidayEvent)  
+<a name="HolidayEvent+render"></a>
+
+### holidayEvent.render([locale]) ⇒ <code>string</code>
+Returns (translated) description of this event
+
+**Kind**: instance method of [<code>HolidayEvent</code>](#HolidayEvent)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [locale] | <code>string</code> | Optional locale name (defaults to active locale). |
+
+<a name="HolidayEvent+renderBrief"></a>
+
+### holidayEvent.renderBrief([locale]) ⇒ <code>string</code>
+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).
+
+**Kind**: instance method of [<code>HolidayEvent</code>](#HolidayEvent)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [locale] | <code>string</code> | Optional locale name (defaults to active locale). |
+
 <a name="RoshChodeshEvent"></a>
 
 ## RoshChodeshEvent
@@ -2754,20 +2790,22 @@ Represents Mevarchim haChodesh, the announcement of the new month
 **Kind**: global class  
 
 * [MevarchimChodeshEvent](#MevarchimChodeshEvent)
-    * [new MevarchimChodeshEvent(date, monthName)](#new_MevarchimChodeshEvent_new)
+    * [new MevarchimChodeshEvent(date, monthName, [memo])](#new_MevarchimChodeshEvent_new)
     * [.basename()](#MevarchimChodeshEvent+basename) ⇒ <code>string</code>
     * [.render([locale])](#MevarchimChodeshEvent+render) ⇒ <code>string</code>
+    * [.renderBrief([locale])](#MevarchimChodeshEvent+renderBrief) ⇒ <code>string</code>
 
 <a name="new_MevarchimChodeshEvent_new"></a>
 
-### new MevarchimChodeshEvent(date, monthName)
+### new MevarchimChodeshEvent(date, monthName, [memo])
 Constructs Mevarchim haChodesh event
 
 
 | Param | Type | Description |
 | --- | --- | --- |
 | date | [<code>HDate</code>](#HDate) | Hebrew date event occurs |
 | monthName | <code>string</code> | Hebrew month name (not translated) |
+| [memo] | <code>string</code> |  |
 
 <a name="MevarchimChodeshEvent+basename"></a>
 
@@ -2784,6 +2822,17 @@ Returns (translated) description of this event
 | --- | --- | --- |
 | [locale] | <code>string</code> | Optional locale name (defaults to active locale). |
 
+<a name="MevarchimChodeshEvent+renderBrief"></a>
+
+### mevarchimChodeshEvent.renderBrief([locale]) ⇒ <code>string</code>
+Returns (translated) description of this event
+
+**Kind**: instance method of [<code>MevarchimChodeshEvent</code>](#MevarchimChodeshEvent)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [locale] | <code>string</code> | Optional locale name (defaults to active locale). |
+
 <a name="DailyLearning"></a>
 
 ## DailyLearning
@@ -2914,7 +2963,8 @@ These defaults can be changed using these options:
 
 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 dusk (when the sun is 6.0° below the horizon in the evening)
+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).
 

hebcal.d.ts

@@ -455,6 +455,13 @@ declare module '@hebcal/core' {
         neitzHaChama(): Date;
         /** Alias for sunset */
         shkiah(): Date;
+        /**
+         * Rabbeinu Tam holds that bein hashmashos is a specific time
+         * between sunset and tzeis hakochavim.
+         * One opinion on how to calculate this time is that
+         * it is 13.5 minutes before tzies 7.083
+         */
+        beinHaShmashos(): Date;
         /**
          * Returns sunrise + `offset` minutes (either positive or negative).
          * @param offset minutes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hebcal/core",
-  "version": "5.1.1",
+  "version": "5.2.0",
   "author": "Michael J. Radwin (https://github.com/mjradwin)",
   "contributors": [
     "Eyal Schachter (https://github.com/Scimonster)",
@@ -51,7 +51,7 @@
     "prepublish": "npm run build",
     "po2json": "node ./po2json.cjs po/*.po",
     "version": "node ./version.cjs package.json src/pkgVersion.js",
-    "readme": "npx -p jsdoc-to-markdown jsdoc2md dist/index.js",
+    "readme": "cp dist/index.mjs tmp.js && npx -p jsdoc-to-markdown jsdoc2md tmp.js && rm -f tmp.js",
     "pretest": "npm run build",
     "lint": "eslint src",
     "coverage": "nyc --concurrency 2 ava",

src/candles.js

@@ -217,7 +217,9 @@ function makeTimedEvent(hd, time, desc, ev, options) {
 
 
 /**
- * Makes a candle-lighting event for Chankah (not on Friday/Saturday)
+ * Makes a candle-lighting event for Chankah (not on Friday/Saturday).
+ * At one point this used civil dusk (6 degrees below horizon).
+ * Another source suggests 4.6667 degrees below horizon.
  * @private
  * @param {Event} ev
  * @param {HDate} hd
@@ -227,7 +229,6 @@ function makeTimedEvent(hd, time, desc, ev, options) {
 export function makeWeekdayChanukahCandleLighting(ev, hd, options) {
   const location = options.location;
   const zmanim = new Zmanim(location, hd.greg(), options.useElevation);
-  const candleLightingTime = zmanim.dusk();
-  // const candleLightingTime = zmanim.tzeit(4.6667);
+  const candleLightingTime = zmanim.beinHaShmashos();
   return makeTimedEvent(hd, candleLightingTime, ev.getDesc(), ev, options);
 }

src/candles.spec.js

@@ -349,18 +349,18 @@ test('chanukah-candles', (t) => {
   const events = HebrewCalendar.calendar(options);
   const actual = events.map(eventTitleDateTime);
   const expected = [
-    {dt: '2020-12-10T16:46:00-05:00', desc: 'Chanukah: 1 Candle'},
+    {dt: '2020-12-10T16:39:00-05:00', desc: 'Chanukah: 1 Candle'},
     {dt: '2020-12-11T15:56:00-05:00', desc: 'Chanukah: 2 Candles'},
     {dt: '2020-12-11T15:56:00-05:00', desc: 'Candle lighting'},
     {dt: '2020-12-12T17:01:00-05:00', desc: 'Chanukah: 3 Candles'},
     {dt: '2020-12-12T17:01:00-05:00', desc: 'Havdalah'},
-    {dt: '2020-12-13T16:47:00-05:00', desc: 'Chanukah: 4 Candles'},
-    {dt: '2020-12-14T16:47:00-05:00', desc: 'Chanukah: 5 Candles'},
-    {dt: '2020-12-15T16:47:00-05:00', desc: 'Chanukah: 6 Candles'},
+    {dt: '2020-12-13T16:40:00-05:00', desc: 'Chanukah: 4 Candles'},
+    {dt: '2020-12-14T16:40:00-05:00', desc: 'Chanukah: 5 Candles'},
+    {dt: '2020-12-15T16:40:00-05:00', desc: 'Chanukah: 6 Candles'},
     {dt: '2020-12-16', desc: 'Chag HaBanot'},
-    {dt: '2020-12-16T16:48:00-05:00', desc: 'Chanukah: 7 Candles'},
+    {dt: '2020-12-16T16:41:00-05:00', desc: 'Chanukah: 7 Candles'},
     {dt: '2020-12-16', desc: 'Rosh Chodesh Tevet'},
-    {dt: '2020-12-17T16:48:00-05:00', desc: 'Chanukah: 8 Candles'},
+    {dt: '2020-12-17T16:41:00-05:00', desc: 'Chanukah: 8 Candles'},
     {dt: '2020-12-18', desc: 'Chanukah: 8th Day'},
     {dt: '2020-12-18T15:58:00-05:00', desc: 'Candle lighting'},
     {dt: '2020-12-19T17:04:00-05:00', desc: 'Havdalah'},

src/hebcal.js

@@ -556,7 +556,8 @@ export class HebrewCalendar {
    *
    * 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 dusk (when the sun is 6.0° below the horizon in the evening)
+   * 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).
    *

src/zmanim.js

@@ -325,7 +325,21 @@ export class Zmanim {
   shkiah() {
     return this.sunset();
   }
-
+  /**
+   * Rabbeinu Tam holds that bein hashmashos is a specific time
+   * between sunset and tzeis hakochavim.
+   * One opinion on how to calculate this time is that
+   * it is 13.5 minutes before tzies 7.083
+   * @return {Date}
+   */
+  beinHaShmashos() {
+    const tzeit = this.tzeit(7.083);
+    const millis = tzeit.getTime();
+    if (isNaN(millis)) {
+      return tzeit;
+    }
+    return new Date(millis - (13.5 * 60 * 1000));
+  }
   /**
    * Uses timeFormat to return a date like '20:34'
    * @param {Date} dt

src/zmanim.spec.js

@@ -52,6 +52,7 @@ test('zmanim', (t) => {
     plagHaMincha: '18:48',
     sunset: '20:22',
     shkiah: '20:22',
+    beinHaShmashos: '20:50',
     dusk: '20:56',
     tzeit: '21:13',
   };
@@ -97,6 +98,7 @@ test('zmanim-tlv', (t) => {
     plagHaMincha: '03/06/2021, 16:29:26',
     sunset: '03/06/2021, 17:42:22',
     shkiah: '03/06/2021, 17:42:22',
+    beinHaShmashos: '03/06/2021, 17:58:27',
     dusk: '03/06/2021, 18:06:50',
     tzeit: '03/06/2021, 18:18:39',
   };
@@ -490,6 +492,7 @@ test('zmanim-UTC', (t) => {
     plagHaMincha: '16:47:00',
     seaLevelSunset: '18:02:15',
     sunset: '18:02:53',
+    beinHaShmashos: '18:15:51',
     dusk: '18:24:39',
     tzeit: '18:35:31',
   };