@hebcal/leyning 5.1.0 → 6.0.1

package/README.md

@@ -3,27 +3,10 @@ Javascript Torah Reading API for Parashat HaShavua and holidays
 
 [![Build Status](https://circleci.com/gh/hebcal/hebcal-leyning.svg?style=svg)](https://circleci.com/gh/hebcal/hebcal-leyning)
 
-This package includes both traditional (full kriyah), triennial and weekday
+This package includes both traditional (full kriyah) and weekday
 Torah readings.
 
-“Many congregations pattern their weekly Torah reading cycle after a system
-similar to the one used in ancient Israel during the rabbinic period. In
-this system, the traditional parashiot are each divided into three shorter
-segments, and the whole Torah is completed once every three years. The
-system has both advantages and disadvantages, but its ability to shorten
-the length of Torah reading without sacrificing the complete reading of the
-Torah on a regular basis has made it the choice of some synagogues in the
-Conservative Movement.”
-
-[A Complete Triennial System for Reading the Torah, Committee on Jewish Law and Standards of the Rabbinical Assembly](https://www.rabbinicalassembly.org/sites/default/files/public/halakhah/teshuvot/19861990/eisenberg_triennial.pdf)
-
-Update December 2021: In November 2020, the CJLS modified the triennial
-cycle for some combined parshiyot to change the reading for year 3 to be
-the third section of the parashah.
-
-[Modification of the Triennial Cycle Readings for Combined Parashot in Certain Years](https://www.rabbinicalassembly.org/sites/default/files/2021-09/cohen-triennial.pdf), Rabbi Miles B. Cohen
-
-Update August 2022: Incorporated [An Emendation to Richard Eisenberg’s Complete Triennial System for Reading Torah, to Address a Rare Situation](https://www.rabbinicalassembly.org/sites/default/files/public/halakhah/teshuvot/2011-2020/heller-triennial-emendation.pdf), Rabbi Joshua Heller, 2012
+Triennial Torah Readings have moved to [@hebcal/triennial](https://github.com/hebcal/hebcal-triennial)
 
 ## Installation
 ```bash
@@ -33,8 +16,7 @@ $ npm install @hebcal/leyning
 ## Synopsis
 ```javascript
 import {HebrewCalendar, HDate, Event} from '@hebcal/core';
-import {getLeyningForParshaHaShavua, getTriennialForParshaHaShavua,
- formatAliyahWithBook} from '@hebcal/leyning';
+import {getLeyningForParshaHaShavua, formatAliyahWithBook} from '@hebcal/leyning';
 
 const events = HebrewCalendar.calendar({sedrot: true, noHolidays: true});
 const ev = events.find((ev) => ev.getDesc() == 'Parashat Pinchas');
@@ -50,22 +32,8 @@ for (const [num, aliyah] of Object.entries(reading.fullkriyah)) {
   str += ` (${aliyah.v} verses)`;
   console.log(`${number}: ${str}`);
 }
-const triReading = getTriennialForParshaHaShavua(ev);
-for (const [num, aliyah] of Object.entries(triReading)) {
-  const number = num == 'M' ? 'maftir' : `aliyah ${num}`;
-  const str = formatAliyahWithBook(aliyah);
-  console.log(`Triennial ${number}: ${str}`);
-}
 ```
 
-## Classes
-
-<dl>
-<dt><a href="#Triennial">Triennial</a></dt>
-<dd><p>Triennial Torah readings</p>
-</dd>
-</dl>
-
 ## Constants
 
 <dl>
@@ -77,12 +45,40 @@ for (const [num, aliyah] of Object.entries(triReading)) {
 ## Functions
 
 <dl>
+<dt><a href="#parshaToString">parshaToString(parsha)</a> ⇒ <code>string</code></dt>
+<dd><p>Formats parsha as a string</p>
+</dd>
+<dt><a href="#clone">clone(src)</a> ⇒ <code>any</code></dt>
+<dd><p>Makes a deep copy of the src object using JSON stringify and parse</p>
+</dd>
+<dt><a href="#calculateNumVerses">calculateNumVerses(aliyah)</a> ⇒ <code>number</code></dt>
+<dd><p>Calculates the number of verses in an aliyah or haftara based on
+the <code>b</code> (begin verse), <code>e</code> (end verse) and <code>k</code> (book).
+Modifies <code>aliyah</code> by setting the <code>v</code> field.</p>
+</dd>
 <dt><a href="#formatAliyahWithBook">formatAliyahWithBook(a)</a> ⇒ <code>string</code></dt>
 <dd><p>Formats an aliyah object like &quot;Numbers 28:9-28:15&quot;</p>
 </dd>
 <dt><a href="#formatAliyahShort">formatAliyahShort(aliyah, showBook)</a> ⇒ <code>string</code></dt>
 <dd><p>Formats an aliyah object like &quot;Numbers 28:9-15&quot;</p>
 </dd>
+<dt><a href="#sumVerses">sumVerses(aliyot)</a> ⇒ <code>number</code></dt>
+<dd><p>Returns the total number of verses in an array of Aliyah (or haftarah) objects</p>
+</dd>
+<dt><a href="#makeLeyningParts">makeLeyningParts(aliyot)</a> ⇒ <code><a href="#Aliyah">Array.&lt;Aliyah&gt;</a></code></dt>
+<dd><p>Summarizes an <code>AliyotMap</code> by collapsing all adjacent aliyot.
+Finds any non-overlapping parts (e.g. special 7th aliyah or maftir)</p>
+</dd>
+<dt><a href="#makeSummaryFromParts">makeSummaryFromParts(parts)</a> ⇒ <code>string</code></dt>
+<dd><p>Returns a string representation of the leyning parts.
+Separate verse ranges read from the same book are separated
+by commas, e.g. <code>Isaiah 6:1-7:6, 9:5-6</code>.
+Verse ranges from different books are separated by semicolons,
+e.g. <code>Genesis 21:1-34; Numbers 29:1-6</code>.</p>
+</dd>
+<dt><a href="#makeLeyningSummary">makeLeyningSummary(aliyot)</a> ⇒ <code>string</code></dt>
+<dd><p>Makes a summary of the leyning, like &quot;Genesis 6:9-11:32&quot;</p>
+</dd>
 <dt><a href="#hasFestival">hasFestival(holiday)</a> ⇒ <code>boolean</code></dt>
 <dd><p>Is there a special festival Torah Reading for <code>holiday</code>?</p>
 </dd>
@@ -92,13 +88,19 @@ for (const [num, aliyah] of Object.entries(triReading)) {
 <dt><a href="#getLeyningKeyForEvent">getLeyningKeyForEvent(ev, [il])</a> ⇒ <code>string</code></dt>
 <dd><p>Based on the event date, type and title, finds the relevant leyning key</p>
 </dd>
+<dt><a href="#specialReadings">specialReadings(hd, il, aliyot, reason)</a> ⇒ <code><a href="#Aliyah">Aliyah</a></code> | <code><a href="#Aliyah">Array.&lt;Aliyah&gt;</a></code></dt>
+<dd><p>Determines if the regular parashat haShavua coincides with an event that requires
+a special maftir or Haftara (for example Shabbat HaGadol, Shabbat Chanukah, Rosh
+Chodesh or Machar Chodesh, etc.).</p>
+<p>If a special maftir occurs, modifies <code>aliyot</code> to replace <code>M</code> and sets <code>reason.M</code>
+(and in some cases modifies the 6th and 7th aliyah, setting <code>reason[&#39;7&#39;]</code>).</p>
+<p>If a special Haftarah applies, returns the Haftarah object and sets <code>reason.haftara</code>.
+If no special Haftarah, returns <code>undefined</code></p>
+</dd>
 <dt><a href="#getLeyningForHoliday">getLeyningForHoliday(ev, [il])</a> ⇒ <code><a href="#Leyning">Leyning</a></code></dt>
 <dd><p>Looks up leyning for a given holiday. Returns some
 of full kriyah aliyot, special Maftir, special Haftarah</p>
 </dd>
-<dt><a href="#makeLeyningSummary">makeLeyningSummary(aliyot)</a> ⇒ <code>string</code></dt>
-<dd><p>Makes a summary of the leyning, like &quot;Genesis 6:9-11:32&quot;</p>
-</dd>
 <dt><a href="#getLeyningForHolidayKey">getLeyningForHolidayKey(key, [cholHaMoedDay])</a> ⇒ <code><a href="#Leyning">Leyning</a></code></dt>
 <dd><p>Looks up leyning for a given holiday key. Key should be an
 (untranslated) string used in holiday-readings.json. Returns some
@@ -123,14 +125,8 @@ Parashat haShavua, containing only the <code>weekday</code> aliyot (no <code>ful
 <dt><a href="#lookupParsha">lookupParsha(parsha)</a> ⇒ <code><a href="#ParshaMeta">ParshaMeta</a></code></dt>
 <dd><p>Returns the parsha metadata</p>
 </dd>
-<dt><a href="#getTriennial">getTriennial(year)</a> ⇒ <code><a href="#Triennial">Triennial</a></code></dt>
-<dd><p>Calculates the 3-year readings for a given year</p>
-</dd>
-<dt><a href="#getTriennialForParshaHaShavua">getTriennialForParshaHaShavua(ev)</a> ⇒ <code><a href="#TriennialAliyot">TriennialAliyot</a></code></dt>
-<dd><p>Looks up the triennial leyning for this Parashat HaShavua</p>
-</dd>
-<dt><a href="#getTriennialHaftaraForHoliday">getTriennialHaftaraForHoliday(key, yearNum)</a> ⇒ <code>Object</code></dt>
-<dd><p>Looks up the alternative triennial Haftara for a holiday</p>
+<dt><a href="#writeCsvLines">writeCsvLines(stream, ev, reading, il, isParsha)</a></dt>
+<dd><p>Formats reading for CSV</p>
 </dd>
 </dl>
 
@@ -149,86 +145,50 @@ Parashat haShavua, containing only the <code>weekday</code> aliyot (no <code>ful
 <dt><a href="#ParshaMeta">ParshaMeta</a> : <code>Object</code></dt>
 <dd><p>Parsha metadata</p>
 </dd>
-<dt><a href="#TriennialAliyot">TriennialAliyot</a> : <code>Object</code></dt>
-<dd><p>Represents triennial aliyot for a given date</p>
-</dd>
 </dl>
 
-<a name="Triennial"></a>
-
-## Triennial
-Triennial Torah readings
-
-**Kind**: global class  
-
-* [Triennial](#Triennial)
-    * [new Triennial([hebrewYear])](#new_Triennial_new)
-    * _instance_
-        * [.getReading(parsha, yearNum)](#Triennial+getReading) ⇒ <code>Object.&lt;string, Aliyah&gt;</code>
-        * [.getStartYear()](#Triennial+getStartYear) ⇒ <code>number</code>
-        * [.debug()](#Triennial+debug) ⇒ <code>string</code>
-    * _static_
-        * [.getYearNumber(year)](#Triennial.getYearNumber) ⇒ <code>number</code>
-        * [.getCycleStartYear(year)](#Triennial.getCycleStartYear) ⇒ <code>number</code>
-
-<a name="new_Triennial_new"></a>
-
-### new Triennial([hebrewYear])
-Builds a Triennial object
-
-
-| Param | Type | Description |
-| --- | --- | --- |
-| [hebrewYear] | <code>number</code> | Hebrew Year (default current year) |
-
-<a name="Triennial+getReading"></a>
+<a name="BOOK"></a>
 
-### triennial.getReading(parsha, yearNum) ⇒ <code>Object.&lt;string, Aliyah&gt;</code>
-**Kind**: instance method of [<code>Triennial</code>](#Triennial)  
-**Returns**: <code>Object.&lt;string, Aliyah&gt;</code> - a map of aliyot 1-7 plus "M"  
+## BOOK : <code>Array.&lt;string&gt;</code>
+Names of the books of the Torah. BOOK[1] === 'Genesis'
 
-| Param | Type | Description |
-| --- | --- | --- |
-| parsha | <code>string</code> | parsha name ("Bereshit" or "Achrei Mot-Kedoshim") |
-| yearNum | <code>number</code> | 0 through 2 for which year of Triennial cycle |
+**Kind**: global constant  
+**Read only**: true  
+<a name="parshaToString"></a>
 
-<a name="Triennial+getStartYear"></a>
+## parshaToString(parsha) ⇒ <code>string</code>
+Formats parsha as a string
 
-### triennial.getStartYear() ⇒ <code>number</code>
-**Kind**: instance method of [<code>Triennial</code>](#Triennial)  
-<a name="Triennial+debug"></a>
+**Kind**: global function  
 
-### triennial.debug() ⇒ <code>string</code>
-**Kind**: instance method of [<code>Triennial</code>](#Triennial)  
-<a name="Triennial.getYearNumber"></a>
+| Param | Type |
+| --- | --- |
+| parsha | <code>Array.&lt;string&gt;</code> | 
 
-### Triennial.getYearNumber(year) ⇒ <code>number</code>
-Returns triennial year 1, 2 or 3 based on this Hebrew year
+<a name="clone"></a>
 
-**Kind**: static method of [<code>Triennial</code>](#Triennial)  
+## clone(src) ⇒ <code>any</code>
+Makes a deep copy of the src object using JSON stringify and parse
 
-| Param | Type | Description |
-| --- | --- | --- |
-| year | <code>number</code> | Hebrew year |
+**Kind**: global function  
 
-<a name="Triennial.getCycleStartYear"></a>
+| Param | Type |
+| --- | --- |
+| src | <code>any</code> | 
 
-### Triennial.getCycleStartYear(year) ⇒ <code>number</code>
-Returns Hebrew year that this 3-year triennial cycle began
+<a name="calculateNumVerses"></a>
 
-**Kind**: static method of [<code>Triennial</code>](#Triennial)  
+## calculateNumVerses(aliyah) ⇒ <code>number</code>
+Calculates the number of verses in an aliyah or haftara based on
+the `b` (begin verse), `e` (end verse) and `k` (book).
+Modifies `aliyah` by setting the `v` field.
 
-| Param | Type | Description |
-| --- | --- | --- |
-| year | <code>number</code> | Hebrew year |
-
-<a name="BOOK"></a>
+**Kind**: global function  
 
-## BOOK : <code>Array.&lt;string&gt;</code>
-Names of the books of the Torah. BOOK[1] === 'Genesis'
+| Param | Type |
+| --- | --- |
+| aliyah | [<code>Aliyah</code>](#Aliyah) | 
 
-**Kind**: global constant  
-**Read only**: true  
 <a name="formatAliyahWithBook"></a>
 
 ## formatAliyahWithBook(a) ⇒ <code>string</code>
@@ -252,6 +212,55 @@ Formats an aliyah object like "Numbers 28:9-15"
 | aliyah | [<code>Aliyah</code>](#Aliyah) | 
 | showBook | <code>boolean</code> | 
 
+<a name="sumVerses"></a>
+
+## sumVerses(aliyot) ⇒ <code>number</code>
+Returns the total number of verses in an array of Aliyah (or haftarah) objects
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| aliyot | [<code>Aliyah</code>](#Aliyah) \| [<code>Array.&lt;Aliyah&gt;</code>](#Aliyah) | 
+
+<a name="makeLeyningParts"></a>
+
+## makeLeyningParts(aliyot) ⇒ [<code>Array.&lt;Aliyah&gt;</code>](#Aliyah)
+Summarizes an `AliyotMap` by collapsing all adjacent aliyot.
+Finds any non-overlapping parts (e.g. special 7th aliyah or maftir)
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| aliyot | <code>Object.&lt;string, Aliyah&gt;</code> | 
+
+<a name="makeSummaryFromParts"></a>
+
+## makeSummaryFromParts(parts) ⇒ <code>string</code>
+Returns a string representation of the leyning parts.
+Separate verse ranges read from the same book are separated
+by commas, e.g. `Isaiah 6:1-7:6, 9:5-6`.
+Verse ranges from different books are separated by semicolons,
+e.g. `Genesis 21:1-34; Numbers 29:1-6`.
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| parts | [<code>Aliyah</code>](#Aliyah) \| [<code>Array.&lt;Aliyah&gt;</code>](#Aliyah) | 
+
+<a name="makeLeyningSummary"></a>
+
+## makeLeyningSummary(aliyot) ⇒ <code>string</code>
+Makes a summary of the leyning, like "Genesis 6:9-11:32"
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| aliyot | <code>Object.&lt;string, Aliyah&gt;</code> | 
+
 <a name="hasFestival"></a>
 
 ## hasFestival(holiday) ⇒ <code>boolean</code>
@@ -287,6 +296,28 @@ Based on the event date, type and title, finds the relevant leyning key
 | ev | <code>Event</code> |  | event |
 | [il] | <code>boolean</code> | <code>false</code> | true if Israel holiday scheme |
 
+<a name="specialReadings"></a>
+
+## specialReadings(hd, il, aliyot, reason) ⇒ [<code>Aliyah</code>](#Aliyah) \| [<code>Array.&lt;Aliyah&gt;</code>](#Aliyah)
+Determines if the regular parashat haShavua coincides with an event that requires
+a special maftir or Haftara (for example Shabbat HaGadol, Shabbat Chanukah, Rosh
+Chodesh or Machar Chodesh, etc.).
+
+If a special maftir occurs, modifies `aliyot` to replace `M` and sets `reason.M`
+(and in some cases modifies the 6th and 7th aliyah, setting `reason['7']`).
+
+If a special Haftarah applies, returns the Haftarah object and sets `reason.haftara`.
+If no special Haftarah, returns `undefined`
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| hd | <code>HDate</code> | 
+| il | <code>boolean</code> | 
+| aliyot | <code>Object.&lt;string, Aliyah&gt;</code> | 
+| reason | <code>Object.&lt;string, string&gt;</code> | 
+
 <a name="getLeyningForHoliday"></a>
 
 ## getLeyningForHoliday(ev, [il]) ⇒ [<code>Leyning</code>](#Leyning)
@@ -301,17 +332,6 @@ of full kriyah aliyot, special Maftir, special Haftarah
 | ev | <code>Event</code> |  | the Hebcal event associated with this leyning |
 | [il] | <code>boolean</code> | <code>false</code> | true if Israel holiday scheme |
 
-<a name="makeLeyningSummary"></a>
-
-## makeLeyningSummary(aliyot) ⇒ <code>string</code>
-Makes a summary of the leyning, like "Genesis 6:9-11:32"
-
-**Kind**: global function  
-
-| Param | Type |
-| --- | --- |
-| aliyot | <code>Object.&lt;string, Aliyah&gt;</code> | 
-
 <a name="getLeyningForHolidayKey"></a>
 
 ## getLeyningForHolidayKey(key, [cholHaMoedDay]) ⇒ [<code>Leyning</code>](#Leyning)
@@ -391,40 +411,20 @@ Returns the parsha metadata
 | --- | --- |
 | parsha | <code>string</code> \| <code>Array.&lt;string&gt;</code> | 
 
-<a name="getTriennial"></a>
+<a name="writeCsvLines"></a>
 
-## getTriennial(year) ⇒ [<code>Triennial</code>](#Triennial)
-Calculates the 3-year readings for a given year
+## writeCsvLines(stream, ev, reading, il, isParsha)
+Formats reading for CSV
 
 **Kind**: global function  
 
-| Param | Type | Description |
-| --- | --- | --- |
-| year | <code>number</code> | Hebrew year |
-
-<a name="getTriennialForParshaHaShavua"></a>
-
-## getTriennialForParshaHaShavua(ev) ⇒ [<code>TriennialAliyot</code>](#TriennialAliyot)
-Looks up the triennial leyning for this Parashat HaShavua
-
-**Kind**: global function  
-**Returns**: [<code>TriennialAliyot</code>](#TriennialAliyot) - a map of aliyot 1-7 plus "M"  
-
 | Param | Type |
 | --- | --- |
+| stream | <code>fs.WriteStream</code> | 
 | ev | <code>Event</code> | 
-
-<a name="getTriennialHaftaraForHoliday"></a>
-
-## getTriennialHaftaraForHoliday(key, yearNum) ⇒ <code>Object</code>
-Looks up the alternative triennial Haftara for a holiday
-
-**Kind**: global function  
-
-| Param | Type |
-| --- | --- |
-| key | <code>string</code> | 
-| yearNum | <code>number</code> | 
+| reading | [<code>Leyning</code>](#Leyning) | 
+| il | <code>boolean</code> | 
+| isParsha | <code>boolean</code> | 
 
 <a name="Aliyah"></a>
 
@@ -496,20 +496,3 @@ Parsha metadata
 | [seph] | [<code>Aliyah</code>](#Aliyah) \| [<code>Array.&lt;Aliyah&gt;</code>](#Aliyah) | Haftarah object(s) for Sephardim |
 | fullkriyah | <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code> | Map of aliyot `1` through `7` plus `M` for maftir |
 | weekday | <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code> | Map of weekday Torah Readings    aliyot `1` through `3` for Monday and Thursday |
-
-<a name="TriennialAliyot"></a>
-
-## TriennialAliyot : <code>Object</code>
-Represents triennial aliyot for a given date
-
-**Kind**: global typedef  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| aliyot | <code>Object.&lt;string, Aliyah&gt;</code> | a map of aliyot 1-7 plus "M" |
-| yearNum | <code>number</code> | year number, 0-2 |
-| date | <code>Date</code> | Shabbat date for when this parsha is read in this 3-year cycle |
-| [readSeparately] | <code>boolean</code> | true if a double parsha is read separately in year `yearNum` |
-| [date1] | <code>Date</code> | Shabbat date of the first part of a read-separately aliyah pair |
-| [date2] | <code>Date</code> | Shabbat date of the second part of a read-separately aliyah pair |