Skip to content

Commit

Permalink
Document more clearly which Zmanim functions use elevation
Browse files Browse the repository at this point in the history
  • Loading branch information
@mjradwin
mjradwin committed May 20, 2024
1 parent 97504c8 commit d768dad
Show file tree
Hide file tree
Showing 2 changed files with 98 additions and 33 deletions.
62 changes: 46 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1998,6 +1998,7 @@ Enables or disables elevation adjustment for zmanim support elevation adjustment
### zmanim.timeAtAngle(angle, rising) ⇒ <code>Date</code>
Convenience function to get the time when sun is above or below the horizon
for a certain angle (in degrees).
This function does not support elevation adjustment.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)

Expand All @@ -2010,41 +2011,52 @@ for a certain angle (in degrees).

### zmanim.sunrise() ⇒ <code>Date</code>
Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+seaLevelSunrise"></a>

### zmanim.seaLevelSunrise() ⇒ <code>Date</code>
Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)
Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon).
This function does not support elevation adjustment.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+sunset"></a>

### zmanim.sunset() ⇒ <code>Date</code>
When the upper edge of the Sun disappears below the horizon (0.833° below horizon)
When the upper edge of the Sun disappears below the horizon (0.833° below horizon).
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+seaLevelSunset"></a>

### zmanim.seaLevelSunset() ⇒ <code>Date</code>
When the upper edge of the Sun disappears below the horizon (0.833° below horizon)
When the upper edge of the Sun disappears below the horizon (0.833° below horizon).
This function does not support elevation adjustment.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+dawn"></a>

### zmanim.dawn() ⇒ <code>Date</code>
Civil dawn; Sun is 6° below the horizon in the morning
Civil dawn; Sun is 6° below the horizon in the morning.
Because degree-based functions estimate the amount of light in the sky,
the result is not impacted by elevation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+dusk"></a>

### zmanim.dusk() ⇒ <code>Date</code>
Civil dusk; Sun is 6° below the horizon in the evening
Civil dusk; Sun is 6° below the horizon in the evening.
Because degree-based functions estimate the amount of light in the sky,
the result is not impacted by elevation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+gregEve"></a>

### zmanim.gregEve() ⇒ <code>Date</code>
Returns sunset for the previous day.
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+chatzot"></a>

Expand All @@ -2055,37 +2067,46 @@ Midday – Chatzot; Sunrise plus 6 halachic hours
<a name="Zmanim+chatzotNight"></a>

### zmanim.chatzotNight() ⇒ <code>Date</code>
Midnight – Chatzot; Sunset plus 6 halachic hours
Midnight – Chatzot; Sunset plus 6 halachic hours.
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+alotHaShachar"></a>

### zmanim.alotHaShachar() ⇒ <code>Date</code>
Dawn – Alot haShachar; Sun is 16.1° below the horizon in the morning
Dawn – Alot haShachar; Sun is 16.1° below the horizon in the morning.
Because degree-based functions estimate the amount of light in the sky,
the result is not impacted by elevation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+misheyakir"></a>

### zmanim.misheyakir() ⇒ <code>Date</code>
Earliest talis & tefillin – Misheyakir; Sun is 11.5° below the horizon in the morning
Earliest talis & tefillin – Misheyakir; Sun is 11.5° below the horizon in the morning.
Because degree-based functions estimate the amount of light in the sky,
the result is not impacted by elevation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+misheyakirMachmir"></a>

### zmanim.misheyakirMachmir() ⇒ <code>Date</code>
Earliest talis & tefillin – Misheyakir Machmir; Sun is 10.2° below the horizon in the morning
Earliest talis & tefillin – Misheyakir Machmir; Sun is 10.2° below the horizon in the morning.
Because degree-based functions estimate the amount of light in the sky,
the result is not impacted by elevation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+sofZmanShma"></a>

### zmanim.sofZmanShma() ⇒ <code>Date</code>
Latest Shema (Gra); Sunrise plus 3 halachic hours, according to the Gra
Latest Shema (Gra); Sunrise plus 3 halachic hours, according to the Gra.
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+sofZmanTfilla"></a>

### zmanim.sofZmanTfilla() ⇒ <code>Date</code>
Latest Shacharit (Gra); Sunrise plus 4 halachic hours, according to the Gra
Latest Shacharit (Gra); Sunrise plus 4 halachic hours, according to the Gra.
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+sofZmanShmaMGA"></a>
Expand Down Expand Up @@ -2146,19 +2167,22 @@ https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/
<a name="Zmanim+minchaGedola"></a>

### zmanim.minchaGedola() ⇒ <code>Date</code>
Earliest Mincha – Mincha Gedola; Sunrise plus 6.5 halachic hours
Earliest Mincha – Mincha Gedola; Sunrise plus 6.5 halachic hours.
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+minchaKetana"></a>

### zmanim.minchaKetana() ⇒ <code>Date</code>
Preferable earliest time to recite Minchah – Mincha Ketana; Sunrise plus 9.5 halachic hours
Preferable earliest time to recite Minchah – Mincha Ketana; Sunrise plus 9.5 halachic hours.
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+plagHaMincha"></a>

### zmanim.plagHaMincha() ⇒ <code>Date</code>
Plag haMincha; Sunrise plus 10.75 halachic hours
Plag haMincha; Sunrise plus 10.75 halachic hours.
If elevation is enabled, this function will include elevation in the calculation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+tzeit"></a>
Expand All @@ -2168,7 +2192,7 @@ Plag haMincha; Sunrise plus 10.75 halachic hours

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [angle] | <code>number</code> | <code>8.5</code> | optional time for solar depression. Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars. |
| [angle] | <code>number</code> | <code>8.5</code> | optional time for solar depression. Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars. Because degree-based functions estimate the amount of light in the sky, the result is not impacted by elevation. |

<a name="Zmanim+neitzHaChama"></a>

Expand All @@ -2188,13 +2212,17 @@ Alias for 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
it is 13.5 minutes before tzies 7.083.
Because degree-based functions estimate the amount of light in the sky,
the result is not impacted by elevation.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)
<a name="Zmanim+sunriseOffset"></a>

### zmanim.sunriseOffset(offset, roundMinute, forceSeaLevel) ⇒ <code>Date</code>
Returns sunrise + `offset` minutes (either positive or negative).
If elevation is enabled, this function will include elevation in the calculation
unless `forceSeaLevel` is `true`.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)

Expand All @@ -2208,6 +2236,8 @@ Returns sunrise + `offset` minutes (either positive or negative).

### zmanim.sunsetOffset(offset, roundMinute, forceSeaLevel) ⇒ <code>Date</code>
Returns sunset + `offset` minutes (either positive or negative).
If elevation is enabled, this function will include elevation in the calculation
unless `forceSeaLevel` is `true`.

**Kind**: instance method of [<code>Zmanim</code>](#Zmanim)

Expand Down
69 changes: 52 additions & 17 deletions src/zmanim.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ export class Zmanim {
/**
* Convenience function to get the time when sun is above or below the horizon
* for a certain angle (in degrees).
* This function does not support elevation adjustment.
* @param {number} angle
* @param {boolean} rising
* @return {Date}
Expand All @@ -100,53 +101,65 @@ export class Zmanim {
}
/**
* Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
sunrise() {
const zdt = this.useElevation ? this.noaa.getSunrise() : this.noaa.getSeaLevelSunrise();
return zdtToDate(zdt);
}
/**
* Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)
* Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon).
* This function does not support elevation adjustment.
* @return {Date}
*/
seaLevelSunrise() {
const zdt = this.noaa.getSeaLevelSunrise();
return zdtToDate(zdt);
}
/**
* When the upper edge of the Sun disappears below the horizon (0.833° below horizon)
* When the upper edge of the Sun disappears below the horizon (0.833° below horizon).
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
sunset() {
const zdt = this.useElevation ? this.noaa.getSunset() : this.noaa.getSeaLevelSunset();
return zdtToDate(zdt);
}
/**
* When the upper edge of the Sun disappears below the horizon (0.833° below horizon)
* When the upper edge of the Sun disappears below the horizon (0.833° below horizon).
* This function does not support elevation adjustment.
* @return {Date}
*/
seaLevelSunset() {
const zdt = this.noaa.getSeaLevelSunset();
return zdtToDate(zdt);
}
/**
* Civil dawn; Sun is 6° below the horizon in the morning
* Civil dawn; Sun is 6° below the horizon in the morning.
* Because degree-based functions estimate the amount of light in the sky,
* the result is not impacted by elevation.
* @return {Date}
*/
dawn() {
const zdt = this.noaa.getBeginCivilTwilight();
return zdtToDate(zdt);
}
/**
* Civil dusk; Sun is 6° below the horizon in the evening
* Civil dusk; Sun is 6° below the horizon in the evening.
* Because degree-based functions estimate the amount of light in the sky,
* the result is not impacted by elevation.
* @return {Date}
*/
dusk() {
const zdt = this.noaa.getEndCivilTwilight();
return zdtToDate(zdt);
}
/** @return {Date} */
/**
* Returns sunset for the previous day.
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
gregEve() {
const prev = new Date(this.date);
prev.setDate(prev.getDate() - 1);
Expand All @@ -165,32 +178,41 @@ export class Zmanim {
* @return {Date}
*/
chatzot() {
const zdt = this.noaa.getSunTransit();
const startOfDay = this.noaa.getSeaLevelSunrise();
const endOfDay = this.noaa.getSeaLevelSunset();
const zdt = this.noaa.getSunTransit(startOfDay, endOfDay);
return zdtToDate(zdt);
}
/**
* Midnight – Chatzot; Sunset plus 6 halachic hours
* Midnight – Chatzot; Sunset plus 6 halachic hours.
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
chatzotNight() {
return new Date(this.sunrise().getTime() - (this.nightHour() * 6));
}
/**
* Dawn – Alot haShachar; Sun is 16.1° below the horizon in the morning
* Dawn – Alot haShachar; Sun is 16.1° below the horizon in the morning.
* Because degree-based functions estimate the amount of light in the sky,
* the result is not impacted by elevation.
* @return {Date}
*/
alotHaShachar() {
return this.timeAtAngle(16.1, true);
}
/**
* Earliest talis & tefillin – Misheyakir; Sun is 11.5° below the horizon in the morning
* Earliest talis & tefillin – Misheyakir; Sun is 11.5° below the horizon in the morning.
* Because degree-based functions estimate the amount of light in the sky,
* the result is not impacted by elevation.
* @return {Date}
*/
misheyakir() {
return this.timeAtAngle(11.5, true);
}
/**
* Earliest talis & tefillin – Misheyakir Machmir; Sun is 10.2° below the horizon in the morning
* Earliest talis & tefillin – Misheyakir Machmir; Sun is 10.2° below the horizon in the morning.
* Because degree-based functions estimate the amount of light in the sky,
* the result is not impacted by elevation.
* @return {Date}
*/
misheyakirMachmir() {
Expand All @@ -211,14 +233,16 @@ export class Zmanim {
return zdtToDate(zdt);
}
/**
* Latest Shema (Gra); Sunrise plus 3 halachic hours, according to the Gra
* Latest Shema (Gra); Sunrise plus 3 halachic hours, according to the Gra.
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
sofZmanShma() { // Gra
return this.getShaahZmanisBasedZman(3);
}
/**
* Latest Shacharit (Gra); Sunrise plus 4 halachic hours, according to the Gra
* Latest Shacharit (Gra); Sunrise plus 4 halachic hours, according to the Gra.
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
sofZmanTfilla() { // Gra
Expand Down Expand Up @@ -315,21 +339,24 @@ export class Zmanim {
return new Date(alot.getTime() + (4 * temporalHour));
}
/**
* Earliest Mincha – Mincha Gedola; Sunrise plus 6.5 halachic hours
* Earliest Mincha – Mincha Gedola; Sunrise plus 6.5 halachic hours.
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
minchaGedola() {
return this.getShaahZmanisBasedZman(6.5);
}
/**
* Preferable earliest time to recite Minchah – Mincha Ketana; Sunrise plus 9.5 halachic hours
* Preferable earliest time to recite Minchah – Mincha Ketana; Sunrise plus 9.5 halachic hours.
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
minchaKetana() {
return this.getShaahZmanisBasedZman(9.5);
}
/**
* Plag haMincha; Sunrise plus 10.75 halachic hours
* Plag haMincha; Sunrise plus 10.75 halachic hours.
* If elevation is enabled, this function will include elevation in the calculation.
* @return {Date}
*/
plagHaMincha() {
Expand All @@ -338,6 +365,8 @@ export class Zmanim {
/**
* @param {number} [angle=8.5] optional time for solar depression.
* Default is 8.5 degrees for 3 small stars, use 7.083 degrees for 3 medium-sized stars.
* Because degree-based functions estimate the amount of light in the sky,
* the result is not impacted by elevation.
* @return {Date}
*/
tzeit(angle=8.5) {
Expand All @@ -361,7 +390,9 @@ export class Zmanim {
* 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
* it is 13.5 minutes before tzies 7.083.
* Because degree-based functions estimate the amount of light in the sky,
* the result is not impacted by elevation.
* @return {Date}
*/
beinHaShmashos() {
Expand Down Expand Up @@ -437,6 +468,8 @@ export class Zmanim {

/**
* Returns sunrise + `offset` minutes (either positive or negative).
* If elevation is enabled, this function will include elevation in the calculation
* unless `forceSeaLevel` is `true`.
* @param {number} offset minutes
* @param {boolean} roundMinute round time to nearest minute (default true)
* @param {boolean} forceSeaLevel use sea-level sunrise (default false)
Expand All @@ -459,6 +492,8 @@ export class Zmanim {

/**
* Returns sunset + `offset` minutes (either positive or negative).
* If elevation is enabled, this function will include elevation in the calculation
* unless `forceSeaLevel` is `true`.
* @param {number} offset minutes
* @param {boolean} roundMinute round time to nearest minute (default true)
* @param {boolean} forceSeaLevel use sea-level sunset (default false)
Expand Down

0 comments on commit d768dad

Please sign in to comment.