@hebcal/leyning 4.20.1 → 5.2.0

package/README.md

@@ -69,7 +69,7 @@ for (const [num, aliyah] of Object.entries(triReading)) {
 ## Constants
 
 <dl>
-<dt><a href="#BOOK">BOOK</a></dt>
+<dt><a href="#BOOK">BOOK</a> : <code>Array.&lt;string&gt;</code></dt>
 <dd><p>Names of the books of the Torah. BOOK[1] === &#39;Genesis&#39;</p>
 </dd>
 </dl>
@@ -77,9 +77,16 @@ for (const [num, aliyah] of Object.entries(triReading)) {
 ## Functions
 
 <dl>
-<dt><del><a href="#addSefariaLinksToLeyning">addSefariaLinksToLeyning(aliyot, showBook)</a></del></dt>
-<dd><p>Makes Sefaria links by adding <code>href</code>, <code>verses</code> and <code>num</code> attributes to each aliyah.
-CAUTION: Modifies the <code>aliyot</code> parameter instead of making a copy.</p>
+<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>
@@ -87,16 +94,36 @@ CAUTION: Modifies the <code>aliyot</code> parameter instead of making a copy.</p
 <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="#getLeyningKeyForEvent">getLeyningKeyForEvent(e, [il])</a> ⇒ <code>string</code></dt>
-<dd><p>Based on the event date, type and title, finds the relevant leyning key</p>
+<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="#getLeyningForHoliday">getLeyningForHoliday(e, [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>
+<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>
+<dt><a href="#lookupFestival">lookupFestival(holiday)</a> ⇒ <code>any</code></dt>
+<dd><p>Returns the raw metadata for festival reading for <code>holiday</code></p>
+</dd>
+<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="#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="#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
@@ -118,10 +145,13 @@ reading for that day (see <a href="#getLeyningForHoliday">getLeyningForHoliday</
 Parashat haShavua, containing only the <code>weekday</code> aliyot (no <code>fullkriyah</code>).</p>
 <p>Otherwise, returns <code>undefined</code>.</p>
 </dd>
+<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, [context])</a> ⇒ <code><a href="#TriennialAliyot">TriennialAliyot</a></code> | <code>Object.&lt;string, Aliyah&gt;</code></dt>
+<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>
@@ -141,6 +171,9 @@ Parashat haShavua, containing only the <code>weekday</code> aliyot (no <code>ful
 <dt><a href="#Leyning">Leyning</a> : <code>Object</code></dt>
 <dd><p>Leyning for a parsha hashavua or holiday</p>
 </dd>
+<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>
@@ -216,24 +249,45 @@ Returns Hebrew year that this 3-year triennial cycle began
 
 <a name="BOOK"></a>
 
-## BOOK
+## BOOK : <code>Array.&lt;string&gt;</code>
 Names of the books of the Torah. BOOK[1] === 'Genesis'
 
 **Kind**: global constant  
-<a name="addSefariaLinksToLeyning"></a>
+**Read only**: true  
+<a name="parshaToString"></a>
 
-## ~~addSefariaLinksToLeyning(aliyot, showBook)~~
-***Deprecated***
+## parshaToString(parsha) ⇒ <code>string</code>
+Formats parsha as a string
 
-Makes Sefaria links by adding `href`, `verses` and `num` attributes to each aliyah.
-CAUTION: Modifies the `aliyot` parameter instead of making a copy.
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| parsha | <code>Array.&lt;string&gt;</code> | 
+
+<a name="clone"></a>
+
+## clone(src) ⇒ <code>any</code>
+Makes a deep copy of the src object using JSON stringify and parse
 
 **Kind**: global function  
 
-| Param | Type | Description |
-| --- | --- | --- |
-| aliyot | <code>Object.&lt;string, Aliyah&gt;</code> | aliyah map to decorate |
-| showBook | <code>boolean</code> | display the book name in the `verses` field (e.g. for special Maftir) |
+| Param | Type |
+| --- | --- |
+| src | <code>any</code> | 
+
+<a name="calculateNumVerses"></a>
+
+## 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.
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| aliyah | [<code>Aliyah</code>](#Aliyah) | 
 
 <a name="formatAliyahWithBook"></a>
 
@@ -258,9 +312,80 @@ 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>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>
+Is there a special festival Torah Reading for `holiday`?
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| holiday | <code>string</code> | 
+
+<a name="lookupFestival"></a>
+
+## lookupFestival(holiday) ⇒ <code>any</code>
+Returns the raw metadata for festival reading for `holiday`
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| holiday | <code>string</code> | 
+
 <a name="getLeyningKeyForEvent"></a>
 
-## getLeyningKeyForEvent(e, [il]) ⇒ <code>string</code>
+## getLeyningKeyForEvent(ev, [il]) ⇒ <code>string</code>
 Based on the event date, type and title, finds the relevant leyning key
 
 **Kind**: global function  
@@ -268,12 +393,12 @@ Based on the event date, type and title, finds the relevant leyning key
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| e | <code>Event</code> |  | event |
+| ev | <code>Event</code> |  | event |
 | [il] | <code>boolean</code> | <code>false</code> | true if Israel holiday scheme |
 
 <a name="getLeyningForHoliday"></a>
 
-## getLeyningForHoliday(e, [il]) ⇒ [<code>Leyning</code>](#Leyning)
+## getLeyningForHoliday(ev, [il]) ⇒ [<code>Leyning</code>](#Leyning)
 Looks up leyning for a given holiday. Returns some
 of full kriyah aliyot, special Maftir, special Haftarah
 
@@ -282,20 +407,9 @@ of full kriyah aliyot, special Maftir, special Haftarah
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| e | <code>Event</code> |  | the Hebcal event associated with this leyning |
+| 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)
@@ -364,6 +478,17 @@ Otherwise, returns `undefined`.
 | hdate | <code>HDate</code> | Hebrew Date |
 | il | <code>boolean</code> | in Israel |
 
+<a name="lookupParsha"></a>
+
+## lookupParsha(parsha) ⇒ [<code>ParshaMeta</code>](#ParshaMeta)
+Returns the parsha metadata
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| parsha | <code>string</code> \| <code>Array.&lt;string&gt;</code> | 
+
 <a name="getTriennial"></a>
 
 ## getTriennial(year) ⇒ [<code>Triennial</code>](#Triennial)
@@ -377,16 +502,15 @@ Calculates the 3-year readings for a given year
 
 <a name="getTriennialForParshaHaShavua"></a>
 
-## getTriennialForParshaHaShavua(ev, [context]) ⇒ [<code>TriennialAliyot</code>](#TriennialAliyot) \| <code>Object.&lt;string, Aliyah&gt;</code>
+## getTriennialForParshaHaShavua(ev) ⇒ [<code>TriennialAliyot</code>](#TriennialAliyot)
 Looks up the triennial leyning for this Parashat HaShavua
 
 **Kind**: global function  
-**Returns**: [<code>TriennialAliyot</code>](#TriennialAliyot) \| <code>Object.&lt;string, Aliyah&gt;</code> - a map of aliyot 1-7 plus "M"  
+**Returns**: [<code>TriennialAliyot</code>](#TriennialAliyot) - a map of aliyot 1-7 plus "M"  
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| ev | <code>Event</code> |  |  |
-| [context] | <code>boolean</code> | <code>false</code> | returns a reading wrapper object which includes `date`, `yearNum` and `aliyot` |
+| Param | Type |
+| --- | --- |
+| ev | <code>Event</code> | 
 
 <a name="getTriennialHaftaraForHoliday"></a>
 
@@ -441,7 +565,7 @@ Leyning for a parsha hashavua or holiday
 | --- | --- | --- |
 | name | [<code>LeyningNames</code>](#LeyningNames) |  |
 | [parsha] | <code>Array.&lt;string&gt;</code> | An array of either 1 (regular) or 2 (doubled parsha).    `undefined` for holiday readings |
-| [parshaNum] | <code>num</code> | 1 for Bereshit, 2 for Noach, etc. `undefined` for holiday readings |
+| [parshaNum] | <code>number</code> | 1 for Bereshit, 2 for Noach, etc. `undefined` for holiday readings |
 | summary | <code>string</code> | Such as `Genesis 1:1 - 6:8` |
 | haft | [<code>Aliyah</code>](#Aliyah) \| [<code>Array.&lt;Aliyah&gt;</code>](#Aliyah) | Haftarah object(s) |
 | haftara | <code>string</code> | Haftarah, such as `Isaiah 42:5 – 43:11` |
@@ -453,6 +577,24 @@ Leyning for a parsha hashavua or holiday
 | [weekday] | <code>Object.&lt;string, Aliyah&gt;</code> | Optional map of weekday Torah Readings    aliyot `1` through `3` for Monday and Thursday |
 | [reason] | <code>Object.&lt;string, string&gt;</code> | Explanations for special readings,    keyed by aliyah number, `M` for maftir or `haftara` for Haftarah |
 
+<a name="ParshaMeta"></a>
+
+## ParshaMeta : <code>Object</code>
+Parsha metadata
+
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| num | <code>number</code> | 1 for Bereshit, 2 for Noach, etc. `undefined` for holiday readings |
+| hebrew | <code>string</code> | parsha name in Hebrew with niqud |
+| book | <code>number</code> | 1 for Genesis, 2 for Exodus, 5 for Deuteronomy |
+| haft | [<code>Aliyah</code>](#Aliyah) \| [<code>Array.&lt;Aliyah&gt;</code>](#Aliyah) | Haftarah object(s) |
+| [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>