bchurchill / badi-cal Goto Github PK

View Code? Open in Web Editor NEW

11.0 4.0 4.0 1.47 MB

A javascript library for Badi calendar conversions.

Home Page: https://bchurchill.github.io/badi-cal/

License: MIT License

JavaScript 100.00%

bahai bahai-calendar javascript badi-claendar

badi-cal's Introduction

badi-cal

Purpose

This project is a reusable javascript library for converting dates between the Badi calendar and the Gregorian calendar.

There's also a demo application which shows Holy days and the Badi months in a tabular listing. It's hosted at https://bchurchill.github.io/badi-cal.

What day to host Feast on
What days the Holy Days fall on, taking into account the 10 July 2014 UHJ letter

Using the Code

If you would like to use the code in this project, the "browser-build-v1" and "browser-build-v2" directories contain v1 and v2 of badi-cal that out-of-the-box box in browsers. If you would like to use this project in a browser environment, go ahead and import the javascript file from one of these directories into your html. The v1 code has slightly more functionality than the v2 version, but this functionality is deprecated. The v2 API is cleaner.
If you have a more sophisticated javascript environment (node, webpack, etc...) then the "build-v2" directory can be used in your project. This will work with environments that support javascript modules (es6 imports, CommonJS, etc...)

Setup Environment

Make sure to have the following installed in your dev environment
NodeJS
Yarn (optional, but you should really really do it)

Getting a Clean Build

Builds are created in the "browser-build-v1", "browser-build-v2", and "build-v2" directories, so you shouldn't have to build any code if you want to just use an existing build.
If you are making changes to the code, then please do the following:
- You can clean the builds with npm run clean-build
- You can generate a new build with npm run create-build
- It is not necessary to clean the build before creating one, but there may be stale files left over from the previous build, especially if you are adding / removing / deleting files between builds

Running the Examples

If you would like to build and run the examples, run the following from the command line:

cd path/to/repo
yarn # or "npm install" if you are not using yarn
npm run start-example1

Go to localhost:8080 in your browser

NOTE: When loading pages in your browser, chrome tends to cache results, so if refreshing some change, it may show you old content. Follow instruction (here)[http://stackoverflow.com/questions/5690269/disabling-chrome-cache-for-website-development] to disable browser caching.

About the Code

src/index.js

The root of the project that exports the modules. If you are using a browser build, then the project is exported using a different mechanism. Please see the section src/v1 and src/v2

src/BadiDate.js

This contains the core API for the BadiDate class.

examples

This contains all the example apps that you can run. These show you how to use the badi-cal API and helps confirm that it is working as expected.

src/extern

This contains dependencies that could not be managed by npm. The dependencies in this directory are mostly astronomical calculations. In the future, this folder should be deprecated and all the dependencies of this project should be tracked by a package manager.

src/v1 and src/v2

These directories contain some setup code for generating the browser builds. This is mostly responsible for exposing state to the window object. These directories are ignored for builds that are not browser-dependent and use a module system.
From updating the project from V1 to V2, we have removed a lot of the functionality previously implemented in V1.
V2 only contains the BadiDate class, and the API for this class is slightly different
If there is some functionality that you would like to see in V2, please create a task.

src/HolyDays.js and src/LocationMap.js

These contain any data that the BadiCalendar needs for doing calculations. The location map contains longitude and latitude of important cities and HolyDays contains metadata about all the holy days.

src/Astronomy.js

Contains calculations for Astronomical events, for example, sunset times.

Before Committing Code

Make sure that all the Unit Tests are Working

npm run test

Ensure the first example still works.
If making breaking changes, increment the version number in package.json.
Re-Bundle the downloadable javascript file

npm run clean-build
npm run create-build

Status

This code is probably stable enough to be used in a project. It has been used in small projects over the last two years or so, and we've yet to find any significant bugs (e.g. incorrect dates). However, using the API correctly can take some effort and it can be confusing (see, for example, #5). Thus, it's important to make sure you carefully test any projects that use this library to ensure that everything works right.

The underlying algorithms used for the astronomical computations, which are taken from a famous text by Meeus, are typically accurate to within a few minutes. However, it is inaccurate for very high and very low lattitudes (those close to the poles). It also looses accuracy going into the future. As a result of these issues, we verify the dates of Naw-Ruz and the Twin Holy Days with those distributed from the Baha'i World Centre, and ensure that whatever we generate matches that.

Specs

In a world ravaged by thousand-page technical manuals, we're happy to use the following letters from the Universal House of Justice as a specification:

The 10 July 2014 letter, http://universalhouseofjustice.bahai.org/activities-bahai-community/20140710_001
The 11 Dec 2014 letter, included in this repository

badi-cal's People

Contributors

Stargazers

Watchers

Forkers

wayferer brettz9 brenmcnamara bahai-era

badi-cal's Issues

documentation updates

A few more documentation updates:

Create a style guide corresponding to what's in the repository now
Create a guide that simply documents what the functions of the public API do

create string output with custom format

Many date/time libraries will have a format() method that takes a string containing escape sequences, and then format the date according to that string. We might want, for example, escapes like this for this library:

%d  day of the month
%m  month
%y  year
%w  name of weekday
%H  hour
%M  minute
%S  second

Find Days

Maybe I'm using this wrong but the results here don't look right as Bahá is missing. Thoughts?

Sunset time based on current location

On reddit you mentioned that you're planning on doing this at some point but I was just wondering is it similar to the tehran_sunset function but just needs to be passed the lat/long of the location and then converted to local timezone?

setup continuous integration for deploying gh-pages branch

(self-explanatory)

migrate test suite from example2 (harness) to unit test infrastructure

(should be self-explanatory)

.jshintignore, .jshintrc

After running npm run clean-build and npm run create-build there were two new files created, .jshintignore and .jshintrc. I don't know the best practice for handling these files in version control (or what they do, frankly), so perhaps we can decide if they should be added to the .gitignore or committed into the repository?

Variable names

As far as I can tell, we only store two kinds of values in a javascript Date object:

The time of a fixed astronomical event (in UTC). This might be a moment of sunset, the moment of a new moon, the spring equinox, or so on.
A gregorian day at a fixed time (e.g. midnight).
In some cases we store both kinds of values in one variable at different times (e.g. when computing the new moons)

I think we should use different names for the first two kinds of variables (e.g. utcFoobar or dateFoobar), and introduce new variables to account for the third kind. This would certainly be an improvement over the original variable names, which admittedly aren't that informative. We can do something similar for function names.

As an example, this was partially done in find_naw_ruz in the old code, where some variables ended with _day and others ended with _utc. But that wasn't systematic. What would actually be really ideal is to rewrite the code with a different type for a gregorian day (e.g. month/day/year) and only use Date objects for UTC. I don't know if doing that refactor is worth it though.

As far as I can tell there are no other "types" of variables where we store time, but if for some reason we ever stored something with localtime we might name that variable differently.

Retire v1 API

The V1 API is (probably) only used for the example code, so we could reasonably refactor it into the example itself and not need to worry about maintaining it.

Create a Gregorian Date Component Class

There are semantic issues with the provided Date class in js
It would be more clear and better suited to have an alternative Gregorian Date Component, which can be used to represent a gregorian date

printable calendar view

It would be nice to make a utility like the UNIX cal utility that prints out the current month in a calendar format and highlights the current day. I could imagine running such a utility on a machine via NodeJS. Or maybe it's time to switch languages...

Converting 'Date' to 'BadiDate'

Hey. So I'm not sure if I have run into an issue or it's just my lack of understanding but I think there is something wrong. When I run the following:

var todayDate = new Date();
var todayDateBadi = new BadiCal.gregorian_to_badi(todayDate);
console.log(todayDate, todayDateBadi.toString(), BadiCal.find_naw_ruz(todayDate.getUTCFullYear()))

on my machine I get:

Thu Jun 25 2015 05:36:33 GMT-0600 (CST) "2 Raḥmat 172" Fri Mar 20 2015 18:00:00 GMT-0600 (CST)

but when I run it on a device with its location settings set to NZ timezone I get:

Thu Jun 25 2015 23:37:09 GMT+1200 (NZST) "2 Raḥmat 172" Sat Mar 21 2015 13:00:00 GMT+1300 (NZDT)

The sunset time for today in NZ was 5:12pm so shouldn't it be returning "3 Rahmat 172"?

Internationalization

There is some request to be more consistent in showing the Gregorian dates across other languages. See http://www.reddit.com/r/bahai/comments/34ly9c/badi_calendar_app_feedback_appreciated/crr5mex. This might combine with #1 since I think the locale affects if weekdays are shown.

Day of the week

I might have overlooked it but is there a way to get the day of the week at the moment? i.e. Istiqlál

Leap year

Does badi.js take leap years into account? i.e. if looking for when Naw Ruz is next year is badi.js taking into account that next year is a leap year?

Caching

Right now, every date is computed from scratch. One nicety is that we can compute provisional dates for future years based on the 10 July 2014 letter, but there are some downsides:

Client-side performance might suffer.
Subtle bugs in the browser's javascript interpreter could cause erroneous dates. This isn't very likely, but it could happen after an urgent security update, for example. Javascript isn't very good at being reliable across platforms.

So, a totally reasonable thing to do would be to cache the computed values for all the years corresponding to the official dates provided by the Baha'i World Center. This offers two obvious advantages:

The client will be much faster
We can be 100% assured that the dates will match the official ones, even if there are subtle bugs in the client-side javascript interpreter (e.g. floating point arithmetic mistakes).