jcal-zmanim v1.5.1

jcal-zmanim

A very complete JavaScript library for the Jewish Calendar.

To add jcal-zmanim to your project

npm install jcal-zmanim

OR

yarn add jcal-zmanim

Some basic uses of jcal-zmanim

Print out todays Jewish Date

import {jDate} from "jcal-zmanim";

const today = jDate.now();
console.log(today.toString());

The above code prints out:

Thursday, the 23rd of Kislev 5784

Get the Daf Yomi for today

import {jDate} from "jcal-zmanim";

//Prints out todays daf: "Baba Kamma, Daf 6" console.log(jDate.now().getDafYomi());

##### Print out the sunrise and sunset times for 11/10/23 in Dallas
```javascript
import {jDate, findLocation, Utils} from "jcal-zmanim";

//Get the Jewish Date for November 10th, 2023.
const jd = new jDate("November 10 2023");

//Gets us Dallas Texas... 
const dallas = findLocation('Dallas');

//Acquire the sunrise and sunset times for this date in Dallas
const {sunrise, sunset} = jd.getSunriseSunset(dallas);

//Print it out nicely formatted to the console
console.log(`In ${dallas.Name} on ${jd.toString()}, Sunrise is at ${Utils.getTimeString(sunrise)}, and Sunset is at ${Utils.getTimeString(sunset)}`);

The code above prints out to the console:

In Dallas, TX on Erev Shabbos, the 26th of Cheshvan 5784, Sunrise is at 6:53:36 AM, and Sunset is at 5:28:59 PM

Get your age and the date of your next Jewish Birthday

import {jDate, Utils} from 'jcal-zmanim' 

//We start with the date of birth
const myDateOfBirth = new Date("July 18 1995")  

//Get the Jewish Date for that wonderful day
const jewishDob = new jDate(myDateOfBirth) 

//Get your age today (in the Jewish calendar)
const age = jewishDob.diffFullYears(jDate.now()) 

//Get the next birthday in Jewish
const nextBirthday = jewishDob.addYears(age + 1) 

//Get the next birthday as a Date
const nextBirthdayDate = nextBirthday.getDate(); 

//Print it out
console.log(`Your jewish Birthday is the ${Utils.toSuffixed(jewishDob.Day)} day of ${JewishMonthsEng[jewishDob.Month]}.
On ${Utils.toStringDate(nextBirthdayDate)} you will become ${age + 1} in Jewish.`);

The code above prints out to the console:

Your Jewish Birthday is the 20th day of Tamuz. On Wednesday, the 16th of July 2025 you will become 29 in Jewish.

Get the current Jewish Date in Hong Kong - taking into consideration that it may be after sunset there right now.

import {findLocation, jDate, Utils} from 'jcal-zmanim'

//Get Hong Kong
const hongKong= findLocation('Hong Kong');

//Get the Jewish Date right now in Hong Kong
const nowInHongKong = Utils.nowAtLocation(hongKong);

//Print it out
console.log(nowInHongKong.toString());

Print out the candle lighting time for Dallas Texas on Friday November 10th 2023:

import {jDate, findLocation, Utils} from "jcal-zmanim";

//Get the Jewish Date for Friday, the 10th of November, 2023.
const erevShabbos = new jDate("November 10 2023");

//Get Dallas...
const dallas = findLocation('Dallas');

//Get the candle-lighting time
const candles = erevShabbos.getCandleLighting(dallas); 

//Spit in out formatted nicely...
console.log(`Candle lighting time in ${dallas.Name} on ${erevShabbos.toString()} is at ${Utils.getTimeString(candles)}`);

The code above, prints out to the console:

Candle lighting time in Dallas, TX on Erev Shabbos, the 26th of Cheshvan 5784 is at 5:10:59 PM

The jDate object

A jDate is a single day in the Jewish Calendar. It is used as the basic date unit throughout jcal-zmanim.

import {jDate} from "jcal-zmanim"

//The following will create a Jewish Date object for todays Date.
const jdate = new jDate();

//The following will output the above Jewish Date in the format: Thursday, the 3rd of Kislev 5784.
console.log(jdate.toString());

Creating a jDate instance

A jDate can be created in a number of ways:

Create a jDate using the jDate constructor

• const jdate = new jDate() - Sets the Jewish Date for the current system date
• const jdate = new jDate(javascriptDateObject) - Sets to the Jewish date on the given Gregorian date
• const jdate = new jDate("January 1 2045") - Accepts any valid javascript Date string (uses JavaScript's new Date(string))
• const jdate = new jDate(jewishYear, jewishMonth, jewishDay) - Months start at 1. Nissan is month 1 Adar Sheini is 13.
• const jdate = new jDate(jewishYear, jewishMonth) - Same as above, with Day defaulting to 1
• const jdate = new jDate( { year: 5776, month: 4, day: 5 } ) - same as new jDate(jewishYear, jewishMonth, jewishDay)
• const jdate = new jDate( { year: 5776, month: 4 } ) - same as new jDate(jewishYear, jewishMonth)
• const jdate = new jDate( { year: 5776 } ) - sets to the first day of Rosh Hashana on the given year
• const jdate = new jDate(absoluteDate) - The number of days elapsed since the theoretical date Sunday, December 31, 0001 BCE
• const jdate = new jDate(jewishYear, jewishMonth, jewishDay, absoluteDate) - Most efficient constructor. Needs no calculations at all.
• const jdate = new jDate( { year: 5776, month: 4, day: 5, abs: 122548708 } ) - same as new jDate(jewishYear, jewishMonth, jewishDay, absoluteDate)

Create a jDate using the static toJDate function

• jDate.toJDate() OR jDate.now() - To get the current Jewish Date.

  //To print out the current Jewish Date in English.
  console.log(jDate.toJDate().toString());
  //A shortcut to get the current jDate.
  const currentJDate = jDate.now();
  //To print out the current Jewish Date in Hebrew: 
  console.log(jDate.now().toStringHeb());

• jDate.toJDate(Date) - Sets to the Jewish date on the given Javascript Date object
• jDate.toJDate("January 1 2045") - Accepts any valid Javascript Date string (uses string constructor of Date object)

 //To print out the Jewish Date for January 3rd 2026.
 console.log(jDate.toJDate(new Date(2026, 0, 3)).toString());

 //To print out the Jewish Date for March 23rd 2027: 
 console.log(jDate.toJDate('March 23 2027').toString());

• jDate.toJDate(jewishYear, jewishMonth, jewishDay) - Months start at 1. Nissan is month 1, and Adar Sheini is 13.

 //To print out the Jewish Date for the 6th day of Kislev 5785 in Hebrew: 
 console.log(jDate.toJDate(5785, 11, 6).toStringHeb());
 //Prints out: יום שלישי ו שבט תשפ"ה

• jDate.toJDate(jewishYear, jewishMonth) - Same as above, with Day defaulting to 1
• jDate.toJDate(jewishYear) - sets to the first day of Rosh Hashana on the given year
• jDate.toJDate( { year: 5776, month: 4, day: 5 } ) - Months start at 1. Nissan is month 1 Adara Sheini is 13.
• jDate.toJDate( { year: 5776, month: 4 } ) - Same as above, with Day defaulting to 1
• jDate.toJDate( { year: 5776 } ) - sets to the first day of Rosh Hashana on the given year
• jDate.toJDate(jewishYear, jewishMonth, jewishDay, absoluteDate) - Most efficient. Needs no calculations at all. The absoluteDate is the number of days elapsed since the theoretical date Sunday, December 31, 0001 BCE.
• jDate.toJDate( { year: 5776, month: 4, day: 5, abs: 122548708 } )- same as jDate.toJDate(jewishYear, jewishMonth, jewishDay, absoluteDate)

jDate instance, properties and functions

jDate static properties and functions

The Location Object

The city or location. This is very important for calculating any Zmanim, as sunset and sunrise are different for every city. In addition, there are different Minhagim in different cities.A major example of this would be, in Eretz Yisroel, one day of Yom Tov is observed, while everywhere else, two days are kept.

To acquire the entire list of Locations:

import {Locations} from "jcal-zmanim";

//Prints out the entire list of all 1,288 Location objects
for(let location of Locations) {
  console.log(location);
}

Finding a Location

To search for a Location object for anywhere in the world, import and use the findLocation function.

import {findLocation} from "jcal-zmanim";

//By city name
const myCity = findLocation('Jersusalem');

//Or in Hebrew
const myCityHebrew = findLocation('ירושלים');

//Or by coordinates
const cityByCoords = findLocation({latitude: 31.77, longitude: -35.23});

//The coordinates do not have to be exact. The function will find the closest Location to the given coordinates.
const closeToJerusalem = findLocation({latitude: 31.75, longitude: -35.2});

There are 2 ways to search for a Location:

• const location = findLocation(locationName) - Finds a Location with the given name.If no exact match is found, the location with the name most similar to the supplied locationName will be returned.Note: The algorithm for this is fairly imprecise, so check to make sure that you have acquired the correct location.If the location is in Israel, typing the name in Hebrew may help find the Location.
• const location = findLocation(locationCoordinates) - find a Location by supplying the coordinates in the format: {latitude: 31.5, longitude: -32.54}. The numbers are degree decimals. For latitude, North is a positive number and South is a negative number. For longitude, West is a positive number, and East is a negative number. If no Location is found with those exact coordinates, the Location closest to the supplied coordinates is returned.

Location properties and functions

Creating a new Location

To create a Location for anywhere in the world, use the Location object constructor:

import {Location} from "jcal-zmanim";

const myLocation = new Location(
  'Nowhere', // The location name
  'יהופיץ',     //The name in Hebrew.
  false,     // This place is not in Israel
  35.01      // The latitude.  North is positive.
  -155.23,   // The longitude. East is negative.
  11,        // The Time Zone: The number of hours offset from UTC.
  1106,      // The elevation in Meters. (Feet x 3.2808)
  18        // The number of minutes before sunset candles are lit on Erev Shabbos. 
);

Zmanim

The following functions can be used to get Halachic Zmanim for any date, anywhere.

To get the daily Sunset, Sunrise and Chatzos for any location in the world:

import {findLocation, jDate} from "jcal-zmanim";

//The following code gets Sunset, Sunrise and Chatzos for Lakewood NJ on Purim 5789.

const lakewood = findLocation('Lakewood');
const purim = new jDate(5789,12, 14);
const {sunset, sunrise} = purim.getSunriseSunset(lakewood);
const chatzos = purim.getChatzos(lakewood);

console.log(`Sunset: ${Utils.getTimeString(sunset)}`);
console.log(`Sunrise: ${Utils.getTimeString(sunrise)}`);
console.log(`chatzos: ${Utils.getTimeString(chatzos)}`);

The code above prints out:

Sunset: 5:49:02 PM Sunrise: 6:29:49 AM chatzos: 12:09:25 PM

To get all the Halachic Zmanim for a given day and Location:

import {findLocation, jDate, ZmanimUtils, Utils} from 'jcal-zmanim';

const lakewood = findLocation('Lakewood');
const purim = new jDate(5789,12, 14);

//This will return an array of Zmanim in the format: 
//[{zmanType:{eng, heb}, time: {hour, minute, second}}]
const allZmanim = ZmanimUtils.getAllZmanim(purim, lakewood);

for(let zman of allZmanim) {  
  console.log(`${zman.zmanType.eng}: ${Utils.getTimeString(zman.time)}`)
}

The code above prints out:

Chatzos - Midnight: 12:09:25 AM Alos Hashachar - 90: 4:59:49 AM Alos Hashachar - 72: 5:17:49 AM Taliss and Tefillin: 5:53:49 AM Sunrise at current elevation: 6:29:49 AM Sunrise: 6:29:49 AM Zman Krias Shma - MG"A: 8:33:49 AM Zman Krias Shma - GR"A: 9:18:49 AM Zman Tefilla - MG"A: 9:45:49 AM Zman Tefilla - GR"A: 10:15:49 AM Chatzos - Midday: 12:09:25 PM Mincha Gedola: 12:37:25 PM Mincha Ketana: 3:26:49 PM Plag HaMincha: 4:37:49 PM Sunset at sea level: 5:49:02 PM Sunset: 5:49:02 PM Nightfall - 45: 6:34:02 PM Nightfall - 50: 6:39:02 PM Rabbeinu Tam: 7:01:02 PM Rabbeinu Tam - Zmanios: 6:56:02 PM Rabbeinu Tam - Zmanios MG"A: 7:14:02 PM

To get just the basic daily Halachic Zmanim for a given day and Location:

import {findLocation, jDate, ZmanimUtils, Utils} from 'jcal-zmanim';

const lakewood = findLocation('Lakewood'); const purim = new jDate(5789,12, 14);

//This will return an array of Zmanim in the format: //{zmanType:{eng, heb}, time: {hour, minute, second}} const someZmanim = ZmanimUtils.getBasicShulZmanim(purim, lakewood);

for(let zman of someZmanim) {
console.log(${zman.zmanType.eng}: ${Utils.getTimeString(zman.time)}) }

The code above prints out:
> Chatzos - Midday: 12:09:25 PM<br>
> Alos Hashachar - 90: 4:59:49 AM<br>
> Sunset: 5:49:02 PM<br>
> Candle lighting time: 5:31:02  PM

### Zmanim Types
The ZmanTypes enum can be acquired by importing `ZmanTypeIds` from 'jcal-zmanim'.<br>
If you need to print out the Zman Type description etc., use the `getZmanType` function.

Here is a list of the in-built *Zmanim Types*: 

|ZmanTypeId|Description|English|Hebrew|
| ---: | :--- | :--- | :--- |
| `ZmanTypeIds.ChatzosLayla` |חצות הלילה|Chatzos - Midnight|חצות הלילה|
|  `ZmanTypeIds.Alos90`|עלות השחר - 90 דקות|Alos Hashachar - 90|עלות השחר (90)|
|  `ZmanTypeIds.Alos72`|עלות השחר - 72 דקות|Alos Hashachar - 72|עלות השחר (72)|
|  `ZmanTypeIds.TalisTefillin`|זמן עטיפת טלית ותפילין - 36 דקות|Taliss and Tefillin|טלית ותפילין|
|  `ZmanTypeIds.NetzAtElevation`|הנץ החמה בגובה המיקום|Sunrise at current elevation|הנץ החמה - מגובה|
|  `ZmanTypeIds.NetzMishor`|הנץ החמה בגובה פני הים|Sunrise|הנץ החמה|
|  `ZmanTypeIds.szksMga`|סזק"ש מג"א|Zman Krias Shma - MG"A|סזק"ש מג"א|
|  `ZmanTypeIds.szksGra`|סזק"ש הגר"א|Zman Krias Shma - GR"A|סזק"ש הגר"א|
|  `ZmanTypeIds.sztMga`|סז"ת מג"א|Zman Tefilla - MG"A|סז"ת מג"א|
|  `ZmanTypeIds.sztGra`|סז"ת הגר"א|Zman Tefilla - GR"A|סז"ת הגר"א|
|  `ZmanTypeIds.chatzosDay`|חצות היום|Chatzos - Midday|חצות היום|
|  `ZmanTypeIds.minGed`|מנחה גדולה|Mincha Gedola|מנחה גדולה|
|  `ZmanTypeIds.minKet`|מנחה קטנה|Mincha Ketana|מנחה קטנה|
|  `ZmanTypeIds.plag`|פלג המנחה|Plag HaMincha|פלג המנחה|
|  `ZmanTypeIds.shkiaAtSeaLevel`|שקיעת החמה מגובה פני הים|Sunset at sea level|שקיעת החמה - ממישור|
|  `ZmanTypeIds.shkiaElevation`|שקיעת החמה מגובה המיקום|Sunset|שקיעת החמה|
|  `ZmanTypeIds.tzais45`|45 דקות אחרי שקיעה|Nightfall - 45|צאת הכוכבים (45)|
|  `ZmanTypeIds.tzais50`|50 דקות אחרי שקיעה|Nightfall - 50|צאת הכוכבים (50)|
|  `ZmanTypeIds.tzais72`|72 דקות אחרי שקיעה|Rabbeinu Tam|צה"כ ר"ת - 72 דקות|
|  `ZmanTypeIds.rabbeinuTamZmanios`|72 דקות זמניות אחרי שקיעה|Rabbeinu Tam - Zmanios|צה"כ ר"ת - זמניות|
|  `ZmanTypeIds.rabbeinuTamZmaniosMga`|72 דקות זמניות אחרי שקיעה - מג"א|Rabbeinu Tam - Zmanios MG"A|צה"כ ר"ת - זמניות מג"א|
|  `ZmanTypeIds.candleLighting`|זמן הדלקת נרות|Candle lighting time|זמן הדלקת נרות|
|  `ZmanTypeIds.SofZmanEatingChometz`|סוף זמן אכילת חמץ|Stop eating Chometz|סוף זמן אכילת חמץ|
|  `ZmanTypeIds.SofZmanBurnChometz`|סוף זמן ביעור חמץ|Destroy Chometz|סוף זמן ביעור חמץ|
##### To get a list of particular Zmanim:
```javascript
import {jDate, findLocation, ZmanimUtils, ZmanTypeIds, getZmanType} from 'jcal-zmanim';

//Get Lakewood, NJ
const lakewood = findLocation('Lakewood');

//Get the Jewish Date of Purim 5789
const purim = new jDate(5789,12, 14);

//Here is a list of the Zmanim Types we want
const zmanimTypesWeWant= [                
    getZmanType(ZmanTypeIds.Alos72),
    getZmanType(ZmanTypeIds.chatzosDay),
    getZmanType(ZmanTypeIds.shkiaElevation)
];

//This will return an array of these Zmanim in the format: 
//[{zmanType:{eng, heb}, time: {hour, minute, second}}]
const zmanimForThose = ZmanimUtils.getZmanTimes(
    zmanimTypesWeWant,
    purim.getDate(),
    purim,
    lakewood
);

//Print them out nicely
for(let zman of zmanimForThose) {  
  console.log(`${zman.zmanType.eng}: ${Utils.getTimeString(zman.time)}`)
}

Calculate other Zmanim

To calculate any other Zman, add the number of minutes or Shaas Zmanimios to sunset, sunrise or Chatzos.

For example, to calculate 4 Shaos Zmanios of the Magen Avraham after sunrise in Lakewood NJ on Purim 5789:

import {jDate, findLocation, Utils} from 'jcal-zmanim';

//Get Lakewood, NJ
const lakewood = findLocation('Lakewood');

//Get the Jewish Date of Purim 5789
const purim = new jDate(5789, 12, 14);

//Get Hanetz Hachama
const {sunrise} = purim.getSunriseSunset(lakewood);

//Get the longer Shaos Zmanios length for this day -
//from 72 minutes before sunrise until 72 minutes after sunset
const shaosZmanios = purim.getShaaZmanis(lakewood, 72);

//Add 4 long Shaos Zmanios to Hanetz Hachama (Why not? it's Purim...)
const lateZman = Utils.addMinutes(sunrise, shaosZmanios * 4);

//Print it out nicely
console.log(`Hanetz on Purim 5789 in Lakewood is: ${Utils.getTimeString(sunrise)}\n4 long Sha'os Zmanios after Hanetz is :) ${Utils.getTimeString(lateZman)}`)

The code above prints out:

Hanetz on Purim 5789 in Lakewood is: 6:29:49 AM 4 long Sha'os Zmanios after Hanetz is :) 11:03:49 AM

The Sedra Object

The Sedra object is obtained by calling getSedra on a jDate.

import {jDate} from "jcal-zmanim";

const today = jDate.now();

//Gets the sedra for today out of Israel
const parsha = today.getSedra(false);

//Print that out
console.log(parsha.toString());

The above code printed out:

Chayei Sara

Sedra Property and Functions:

The Molad Functions

Daily Notifications and Shul Notifications

Get a list of Halacha related information about any jDate. This is very useful for creating an application that shows the daily information and Zmanim in a Shul etc. To get these notifications, use the getNotifications function.

There are two lists that are returned from the getNotifications function.

• Daily Notifications - These are information about the given day, such as if it is Shabbos or YomTov, the Daf Yomi, day of Sefirah etc.
• Shul Notifications - These are shul and davening realted information about the given day, such as the Torah reading, skipping Tachnun, saying Hallel, the Shir Shel Yom etc.

Sample use of daily and tefillah notifications:

import {jDate, getNotifications, findLocation} from "jcal-zmanim";

//Get Lakewood NJ
const lakewood = findLocation('Lakewood');

//Get Purim 5784
const purim = new jDate(5784, 13, 14);

//We want to get the notifications that are relevant at 8 o'clock in the morning.
const morningTime = { hour:8, minute:0 };

//Get Purim's notifications
const {dayNotes, tefillahNotes} = getNotifications(purim, morningTime, lakewood, true, true, true);

//Print them out
console.log(`Purim: ${purim.toString()}\nDaily Notes:\n\t${dayNotes.join('\n\t')}\nTefillah Notes:\n\t${tefillahNotes.join('\n\t')}`);

The above code prints out:

Purim: Sunday, the 14th of Adar Sheini 5784 Daily Notes:

• Megilas Esther
• Purim
• Baba Metzia Daf 25

Tefillah Notes:

• No Laminatzeach
• Al Hanissim
• שיר של יום - כ"ב - למנצח על אילת השחר
• No Tachnun

The getNotifications Function - parameters

Parameter	Type	Description
date	Date or jDate	Either a jDate or a javascript Date
time	{hour, minute}	The time of day for which to show notifications for. For example, "Hallel" will not be shown at night etc.
location	Location	Where in the world to show notifications for?
english	boolean	Should the notifications be in English or Hebrew?
showGaonShir	boolean	Should the Shir Shel Yom of the Gr"a be shown?If this paremeter is undefined, it will not be shown, unless the location is in Israel.
showDafYomi	boolean	Should the daily Daf be shown in the daily notifications?Defaults to true.

The Utils Functions

The Utils Class contains many useful jDate and regular Date functions. It also has some extremely useful general functions.