behindthemath/kosherzmanim

Port of the KosherJava zmanim library to TypeScript

This project is at an alpha stage.

Things will break, and APIs might change. Be cautious using this in production. Additionally, not all methods have been tested for accuracy.

Introduction

Kosher Zmanim is a TS/JS port of the KosherJava library.

Installation

NPM:

npm install kosher-zmanim

UMD (browser):

<script src="https://unpkg.com/kosher-zmanim/dist/kosher-zmanim.min.js"></script>

It is highly recommended that you pin the version (e.g. https://unpkg.com/[email protected]/dist/kosher-zmanim.min.js), so updates don't break your app.

Usage and Documentation

Importing

ES6 modules / Typescript:

import * as KosherZmanim from "kosher-zmanim";

Or:

import { ComplexZmanimCalendar, getZmanimJson } from "kosher-zmanim";

CommonJS modules:

const KosherZmanim = require("kosher-zmanim");

Or:

const { ComplexZmanimCalendar, getZmanimJson } = require("kosher-zmanim");

UMD (browser):

For UMD, a global KosherZmanim object is exposed.

Library Usage:

The KosherJava library has been ported to JS, following the original API as close as possible. The classes are exposed as named exports. You can instantiate or extend those classes as necessary, the same way you would in Java.

const zmanimCalendar = new KosherZmanim.ZmanimCalendar();

See the KosherJava API documentation for more details.

Simple usage

Alternatively, there is a getZmanimJson() utility method.

const zmanim = KosherZmanim.getZmanimJson(options);

Check out the demo, and look at the code to see an example of how it's used.

options object

The options object has the following structure and defaults:

{
    date: Date | string | number = new Date(),
    timeZoneId: string
    locationName?: string,
    latitude: number,
    longitude: number,
    elevation?: number = 0,
    complexZmanim?: boolean = false,
}

Note about how zmanim are calculated

This library uses Luxon as a date/time library, since Javascript's Date object does not support setting timezones other than the system timezone. All class methods that return a DateTime object will be in UTC.

Breaking changes from KosherJava

• AstronomicalCalendar.getTemporalHour() returns null instead of Long.MIN_VALUE if the calculations cannot be completed.
• JS/TS does not have a parallel to Java's Long.MIN_VALUE, so Long_MIN_VALUE is set to NaN.
• The following methods are not supported:
  • AstronomicalCalendar.toString()
  • AstronomicalCalendar.toJSON() (Use ZmanimFormatter.toJSON(astronomicalCalendar) instead).
  • AstronomicalCalculator.getDefault() (Use new NOAACalculator() instead).
  • JewishCalendar.getDafYomiBavli() (Use YomiCalculator.getDafYomiBavli(jewishCalendar) instead).
  • JewishCalendar.getDafYomiYerushalmi() (Use YerushalmiYomiCalculator.getDafYomiYerushalmi(jewishCalendar) instead).
  • Time.toString() (Use new ZmanimFormatter(TimeZone.getTimeZone("UTC")).format(time) instead).
  • ZmanimFormatter.toXML()
• Some method signatures are different, due to the differences between Java and JS.
• The Zman class uses public members instead of getters and setters.

kosherzmanim's Issues

Bug in getMoladAsDate - JewishCalendar - Jerusalem Time Zone

The time zone need to be "Etc/GMT+2" now is "Etc/GMT-2".
The line is:
var yerushalayimStandardTZ = "Etc/GMT-2";
Thank you ver much.

Add tefilla rules

Are you able to add the tefilla rules to this library?
if you start it off ill be able to help out if you need.
thanks

Add ESM bundle

[opening issue as requested]

Included ESM entry point dist/lib-es6/kosher-zmanim.ts is not bundled.
Would be useful for use from browser, playgrounds, Deno, Bun, etc.

(Although in many use cases unbundled ESM is actually fine, I seemed to get an error about the export Big not being found. esm.sh's bundle worked fine, though)

Is this project still maintained?

I would love to use it in my app, but I'm not sure if the owner is still around. I see a number of PR requests and unhandled issues and it worries me a bit.

why Timezone ID & Location Name are mandatory ?

Latitude and Longitude are not enough?

problem in demo code

Hi,

In the demo code you use parseInt for latitude, longitude & elevation, so for locations not on exact degrees it's impossible to get right zmanim!

Zvika

Can we please have an actual example of using this project not through JSON?!

It may just be me, but I am a beginner to Javascripts quirks. I have to research everything I do before I can implement it. The beauty of this project is that it is exactly like the KosherJava version with a few differences because of the language. However, as a newcomer, this project NEEDS better documentation. I just have a big problem with the fact that the documentation doesn't even show how to display the luxon DateTime objects returned by the API.

For example look at this piece of code:

var zmanimCalendar = new ComplexZmanimCalendar(new GeoLocation( "Jerusalem", 31.76904, 35.21633, 792, "Asia/Jerusalem" )); console.log(zmanimCalendar.getAlos72Zmanis().toJSDate().toLocaleTimeString());
This is originally what I used to display the zmanim. However, now I realize that this only works in my timezone/locality. If I change the location to New York, the time shown gets skewed 7 hours. Now I need to figure out how to use luxon to display the time in THAT timezone.

Again, I have no complaints against the work you put into the project, but it is not beginner friendly AT ALL. This is not the first time I had to reimplement a feature using this project because I was not informed of some quirks of javascript.

So can you please post some more examples in the readme using this project? Show an example like my where you want to display the time in any DateTime object around the world. Show how to use convert the time to show seconds and to not show seconds.

I know this is research we as beginners can do ourservles, but javascript is EVIL with timezones! I would love it if you could show how to properly use your package with luxon by adding examples and ideas.

Thank you and kol tuv!

JS doesn't produce the same results as Java

I'd like to start off by saying that I am a huge fan of this port. In my opinion it's miles ahead of anything else out there for JS. Even though the README states this project is in alpha stage, I've found it to be quite complete and reliable.
With that out of the way, something I just realized is that the results of lib seem to be a few seconds off from what the Java library produces. To illustrate this:

I used the Zmanim Calendar Generator to generate zmanim for my location (Hashmonaim) and used this as a reference for the Java results.

Taking a look at candle lighting for 2020-04-10:

This matches up exactly with MyZmanim.com. I even compared several zmanim and different days. The largest discrepancy I found was 1 second (!). I'm pretty convinced MyZmanim uses the Java zmanim project.

However, when I try to produce the results in JS using this lib, I get results that are on average 5 seconds off:

const moment = require('moment');
const { ComplexZmanimCalendar, GeoLocation } = require('kosher-zmanim');

const cal = new ComplexZmanimCalendar(
	new GeoLocation('Hashmonaim', 31.93263, 35.02327, 255.18, 'Asia/Jerusalem')
);

cal.setMoment(moment('2020-04-10'));

console.log(cal.getCandleLighting()); // Fri Apr 10 2020 18:47:44 GMT+0300 (Israel Daylight Time)

Its just a couple seconds but they're crucial when minutes are rounded. I hope I'm missing something simple. Struck me as really strange especially because the source of this project is so similar to the Java. Makes me think that this might have to do with a loss of precision when handling big numbers in JS. Although, from a few quick greps I couldn't find any huge number literals.

getZmanimJson does not return plagHamincha

KosherZmanim.getZmanimJson(options) does not return the standard plagHamincha. This is true even when complexZmanim = true.

Wrong Times For Asia/Jerusalem Timezone

I got wrong times using the JS example with the following input:
Date: 2018-08-11T21:34:45.830Z
Timezone ID: Asia/Jerusalem
Location Name: Haifa
Latitude: 32.80124
Longitude: 35.00327
Elevation: 0

You can see at the following output for example that the candle lighting time is wrong "2018-08-13T13:09:32+03:00"

"metadata":{
"date":"2018-08-12",
"type":"net.sourceforge.zmanim.ZmanimCalendar",
"algorithm":"US Naval Almanac Algorithm",
"location":"Haifa",
"latitude":"32",
"longitude":"35",
"elevation":"0.0",
"timeZoneName":"Israel Standard Time",
"timeZoneID":"Asia/Jerusalem",
"timeZoneOffset":"3.0"},
"BasicZmanim":{
"BeginAstronomicalTwilight":"2018-08-12T22:32:44+03:00",
"AlosHashachar":"2018-08-12T22:43:10+03:00",
"Alos72":"2018-08-12T22:50:08+03:00",
"BeginNauticalTwilight":"2018-08-12T23:05:08+03:00",
"BeginCivilTwilight":"2018-08-12T23:36:10+03:00",
"Sunrise":"2018-08-13T00:02:08+03:00",
"SeaLevelSunrise":"2018-08-13T00:02:08+03:00",
"SofZmanShmaMGA":"2018-08-13T02:47:29+03:00",
"SofZmanShmaGRA":"2018-08-13T03:23:29+03:00",
"SofZmanTfilaMGA":"2018-08-13T04:06:36+03:00",
"SofZmanTfilaGRA":"2018-08-13T04:30:36+03:00",
"Chatzos":"2018-08-13T06:44:50+03:00",
"CandleLighting":"2018-08-13T13:09:32+03:00",
"SeaLevelSunset":"2018-08-13T13:27:32+03:00",
"Sunset":"2018-08-13T13:27:32+03:00",
"EndCivilTwilight":"2018-08-13T13:53:28+03:00",
"Tzais":"2018-08-13T14:06:15+03:00",
"EndNauticalTwilight":"2018-08-13T14:24:28+03:00",
"Tzais72":"2018-08-13T14:39:32+03:00",
"EndAstronomicalTwilight":"2018-08-13T14:56:48+03:00",
"ShaahZmanisGra":"PT1H7M6.931S",
"ShaahZmanisMGA":"PT1H19M6.931S"}}

none json example and jerusalem timezone issue

hello... have a suggestion for those who don't have great js or alot of coding skill's ...

1. putting a working example that dost use json. with simple functions just for example...
2. i have a problem with incorrect time returned .. i think it's because on the problem with Jerusalem timezone,
   as described here:
   https://kosherjava.com/tag/software-bugs/

this is probebly very Noobish but i have no idea how to fix it in the current javascript,
btw do i have to set a date? it seems to be work on "Default".
help please :)
thank you.

my example: values taken from input...

`<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <script src="https://unpkg.com/[email protected]/dist/kosher-zmanim.min.js"></script>
  </head>
  <body>
    <table>
      <tr>
        <td><label for="date">Date (ISO 8601)</label></td>
        <td><input id="date"/></td>
      </tr>
      <tr>
        <td><label for="timeZoneId">Timezone ID</label></td>
        <td><input id="timeZoneId" value="Asia/Jerusalem"/></td>
      </tr>
      <tr>
        <td><label for="locationName">Location Name</label></td>
        <td><input id="locationName" value="nahariya"/></td>
      </tr>
      <tr>
        <td><label for="latitude">Latitude</label></td>
        <td><input id="latitude" value="33.01135"/></td>
      </tr>
      <tr>
        <td><label for="longitude">Longitude</label></td>
        <td><input id="longitude" value="35.09467"/></td>
      </tr>
      <tr>
        <td><label for="elevation">Elevation</label></td>
        <td><input id="elevation" value="0"/></td>
      </tr>
    </table>

    <br/>
    <button id="calculate">Calculate</button>

    <pre id="output"></pre>
    <pre id="sunrise"></pre>
    <pre id="ddate"></pre>

    <script>
	var name = document.querySelector("input#locationName").value;
	var lat = Number.parseInt(document.querySelector("input#latitude").value);
	var lon = Number.parseInt(document.querySelector("input#longitude").value);
	var ele = Number.parseInt(document.querySelector("input#elevation").value);
	var zone = document.querySelector("input#timeZoneId").value;
	
	const GeoLocation = new KosherZmanim.GeoLocation(name,lat,lon,ele,zone);  
	const zmanimCalendar = new KosherZmanim.ZmanimCalendar(GeoLocation);
		
      (function() {
        
    document.querySelector("button#calculate").addEventListener("click", function() {
	
	var alot = zmanimCalendar.getAlosHashachar();
 	var sunrise = zmanimCalendar.getSunrise();
	 
	

          // Output the results example ,
		  
                 var d = new Date(); 
	         var n = d.toISOString();
		 document.querySelector("#ddate").innerText = n; // return incorect date... , just to show you.....
 
          document.querySelector("#output").innerText = "alot  " + alot.hour + ":" + alot.minute; // return incorect time...
	  document.querySelector("#sunrise").innerText = "sunrise  " + sunrise.hour + ":" + sunrise.minute;  // return incorect time...
		  
             
		  
        });
      })();
    </script>

  </body>
</html>.

`

Very Nice!

Hey, congratulations on shipping this!