⛔️ DEPRECATED

This package has been deprecated in favor of @hebcal/core.

Hebcal JavaScript

Original C written by Danny Sadinoff, with portions by Michael J. Radwin. 2014 JavaScript port by Eyal Schachter (age 15).

Description

Hebcal JS is a JavaScript API to aid working with the Hebrew calendar. It is available for both browser and Node.JS.

It can convert between Hebrew and Gregorian dates, get weekly sedra, holidays, and halachik times (zemanim).

You can include it in a client-side (browser) script with the hebcal.min.js script in the client subfolder (17KB gzipped). It exposes a global variable, Hebcal. For Node, install hebcal from NPM...

$ npm install hebcal

...and include Hebcal with var Hebcal = require('hebcal');

Hebcal JS is currently at version 2.3.2. It is approximately equivalent to Hebcal C 3.15. I (Eyal) did not write Hebcal JS 1.0. 2.x is a nearly-complete rewrite of it.

The version documented here is 2.3.2.

Releases

• 2.0.0 - 2014-02-18 (19 Adar 1 5774)
• 2.1.0 - 2014-03-16 (14 Adar 2 5774 [Purim])
• 2.1.1 - 2014-04-04 (5 Nisan 5774)
• 2.1.2 - 2014-04-04 (5 Nisan 5774)
• 2.2.0 - 2014-06-29 (1 Tamuz 5774)
• 2.2.1 - 2016-04-17 (9 Nisan 5776)
• 2.2.2 - 2016-04-18 (10 Nisan 5776)
• 2.2.3 - 2017-02-14 (18 Shvat 5777)
• 2.2.4 - 2017-05-17 (21 Iyyar 5777)
• 2.2.5 - 2017-07-02 (8 Tamuz 5777)
• 2.2.6 - 2017-10-29 (10 Cheshvan 5778)
• 2.3.0 - 2019-02-11 (6 Adar 1 5779)
• 2.3.1 - 2019-02-11 (6 Adar 1 5779)
• 2.3.2 - 2019-09-25 (25 Elul 5779)
• 2.3.3 - 2021-11-03 (28 Cheshvan 5782)

Contributors

Hebcal JS was ported from C by Eyal Schachter (Scimonster).

The original C and JavaScript code was written by Danny Sadinoff, with contributions by Michael J. Radwin.

Various other people have made contributions on GitHub.

License / Distribution

Copyright (C) 1994-2011 Danny Sadinoff Portions Copyright (c) 2011 Michael J. Radwin. All Rights Reserved.

Hebcal JavaScript is distributed under the GNU Public License version 3. The original Hebcal C is under the GPLv2. The program and its source code may be freely distributed. For details, see the file COPYING in the distribution.

Remember, the GPL means you can't use this in a closed-source program! (But see #72)

If you are using this program, I'd like to hear about -- know who you are, what version you're using, and how you're using Hebcal, and anything else you'd like to tell me, so that i can adjust the program to meet users' needs.

The original Hebcal is at hebcal/hebcal.

API

This is where every property and method is listed.

• CLI
• Hebcal
• Hebcal.HDate
• Hebcal.Month
• Hebcal.GregYear
• Hebcal.GregMonth
• Hebcal.cities
• Hebcal.holidays
• Hebcal.events
• Utilities:
• • gematriya
• • range

Information on certain standards

Descriptions

Sometimes a "description array" will be mentioned. This is an array with between 1 and 3 properties: [Sfardit pronunciation[, Ashkenazis pronunciation[, Hebrew spelling]]].

Methods that fetch a value from this array expect one of the following strings: "a" for Ashkenazis, "h", for Hebrew, and anything else for Sfardit.

Month names

Hebcal is not too particular about month names, and only checks up to the second letter. That means that, despite being totally incorrect, "cheese" will return the same value as "cheshvan". Month names work in both Hebrew and English.

Nisan, Iyyar, Sivan, Tamuz, Av, Elul, Tishrei, Cheshvan, Kislev, Tevet, Shvat, Adar (1, 2). ניסן, אייר, סיון, תמוז, אב, אלול, תשרי, חשון, כסלו, טבת, שבט, אדר (1, 2).

Sun times

Hebcal JS uses the SunCalc JavaScript library to calculate sun times. They do not provide an accuracy claim, but i have found their times to be up to 3 minutes off from the accepted times. Do not rely on Zemanim until the last moment!

Finding location in browser

Both scripts run on the exact same code, except for one thing. In the browser, Hebcal will attempt to set Hebcal.defaultLocation to the user's location using the geolocation API. The ready event (see Hebcal.events) is fired once the location has been obtained, or failed to be obtained.

This will cause any webpages with the Hebcal script to request the user's permission to view their location. If they deny it, the default location will be [0, 0].

To turn off this feature, use the hebcal.noloc.min.js script instead of the usual hebcal.min.js script. The unminified version is hebcal.noloc.js. All of these files are in the client folder.

Source maps

When using Hebcal JS in the browser, it may be helpful for debugging to include a sourcemap file for browsers that support it. Both minified and unminified, regular and noloc, have a sourcemap file. This is <js filename>.map.

Ordering in this documentation

Be forewarned: the ordering of properties/methods in this documentation is almost completely arbitrary. It mostly follows the order of the code, which is itself written in pretty much whatever order i decided i needed those methods. If you're looking for a specific thing, i highly recommend using your browser's find tool (ctrl+f, or cmd+f for you Mac types). If you just want to know everything about Hebcal JS, just start at the top and work your way down.

Command line interface

Hebcal JS (as of v2.1) also provides a simple CLI. It's mainly for just testing output. If you really need an advanced CLI, use the main Hebcal code.

You can access this CLI by installing Hebcal JS globally from NPM:

npm install -g hebcal

This exposes the hebcaljs command. This is to differentiate it from the ordinary hebcal command.

For usage information, run hebcaljs -h.

Hebcal

The global variable (if running in the browser) Hebcal is the entrypoint to Hebcal. It is a constructor returning an object represtenting a Hebrew year, and also has many other properties.

new Hebcal([year[, month]]);

year, if provided, should be an int representing a Hebrew year, for example, 5774. If it is falsey (includes null, undefined, 0, false, etc), it defaults to the current year. If it is not falsy, and not a number, Hebcal will throw an error.

month, if provided, supports multiple types:

• String -- The name of a single month.
• Number -- The number of a single month (Nisan is 1, Tishrei 7).
• Array -- An array of either of the above two, or mixed. Basically, anything that can be passed to Hebcal.Month (see below).

If not provided, it defaults to all of the months in the given year. If it is a different type, Hebcal will throw an error.

To get the full current year:

var year = new Hebcal();

Properties on Hebcal instances

Hebcal.prototype.year

Number. The year represented in the Hebcal. (Not actually a prototype value.)

Hebcal.prototype.months

Array of Hebcal.Months. Is not intended to be used directly, but rather with the getMonth() and map() methods. (Not actually a prototype value.)

Hebcal.prototype.holidays

v2.2 and later: An object, with keys as HDate strings, and values are arrays of Hebcal.holidays.Events. It is not recommended to use this object directly. Instead, use HDate().holidays() for fetching and Hebcal().addHoliday() for adding.

BEFORE v2.2: Array of holidays, as Hebcal.holidays.Events, for the represented year.

Not actually a prototype value.

Hebcal.prototype.length

Number of days in the year. (Not actually a prototype value.)

Hebcal.prototype.il

Boolean get/set. Whether the current location is in Israel or not. This is relevant with regards to holidays. This gets set by Hebcal.defaultCity, and year.setCity(). It's possible that you may have to set it yourself in certain circumstances. (Not actually a prototype value.)

Hebcal.prototype.lat and long

Number get/sets. The latitude and longitude of the current location. This is relevant with regards to getting times for dates. (Not actually prototype values.) Default: 0.

Hebcal.prototype.setCity(city)

year.setCity('Jerusalem');

Sets the lat/long to the given city's location. Returns the Hebcal it was called upon. This allows for easy method chaining.

For more information regarding cities, see Hebcal.cities below.

Hebcal.prototype.setLocation(latitude, longitude)

year.setLocation(40.716, -74.016); // coords of New York

Sets the lat/long to the given location. Returns the Hebcal it was called upon.

Hebcal.prototype.isLeapYear()

var isleap = year.isLeapYear();

Takes 0 arguments, returns a boolean.

Hebcal.prototype.next()

var nextYear = year.next();

Takes 0 arguments, returns Hebcal representing the following year.

Hebcal.prototype.prev()

var prevYear = year.prev();

Takes 0 arguments, returns Hebcal representing the preceding year.

Hebcal.prototype.getMonth(month)

var tishrei = year.getMonth(7);
var adar2 = year.getMonth(-1);
var shvat = year.getMonth('shvat');
var elul = year.getMon