Matariki Program (by Team EV)

About

This is an open-source program to determine when the Matariki holiday will occur written in TypeScript using the Node.js runtime. This program was written for the 2022 Hackathon.

Note: After submission we realise the lunar conversion may have not been the best option for years beyond 2100. Looking in getMatariki.ts, we have realised the commented code using the moon phase method (finding the new moon and adding 22 days after) would have been a more accurate and consistent method. Our original method using the JPL Horizons API can be found in the archived branch.

Submission Details

Releases

Installation

Node.js v17 or higher is required. (Note: uses node-fetch v2 due to incompatibility issues with CommonJS and chalk v4.1.2 due to incompatibility issues with ESM)

Install dependencies:

npm install 
# or
yarn install

If you prefer to use yarn, you can install it with npm by running npm i yarn -g to install it globally. If you prefer to use npm, be sure to delete yarn.lock.

Running the program

The script for running the program is defined in the scripts property in package.json

npm start
# or
yarn start

Example:

Testing

This program uses jest for program testing. To run tests, run yarn test or npm test. For coverage, run yarn test:coverage or npm test:coverage. Tetsing files (.test.ts files) are located within the test directory. To view the Icov reports, you can open index.html in a browser (VSC Live Server extension recommended) You should see something like this:

How it works

The program will request you enter a valid year (has to be able to be converted to a number) and will in result output its predictions of when the Matariki holiday for the given year will be.

The program determines its predictions by converting the 23rd day of the 4th month of the provided year in the Chinese lunar calendar to its Gregorian Calendar equivalent (the "pointer" date as referred to throughout the program) by calling the getMatariki() function, and then finding the closest Friday, the date of the Matariki public holiday, by calling the closestFriday() function. The theory behind this is stated in the method section.

TypeScript files will be compiled to the build directory (only generated once npm start or yarn start is executed).

Method

To see the original method, view the archived branch.

It is known that the Tangaroa period occurs 22 days after the new moon in May-June. Moreover, the Chinese Lunar calendar is also determined by the moon’s lunar cycle, where the first of the month is the beginning of the new moon. The Chinese lunar month in the Gregorian May-June-July period is May (五月). Therefore, the Tangaroa period begins on the 23rd of May in the Chinese lunar calendar as it is 22 days after the beginning of May. We can convert the lunar date of May 23rd into the Gregorian date, and we can determine the Matariki holiday using this date, by getting the closest Friday.

If the date we use to determine the Matariki holiday is on a weekend, the holiday will be on the previous Friday. Otherwise, the holiday will occur on the next Friday. Since the Georgian calendar is a solar calendar, we can always predict the Matariki cluster becomes visible at dawn on and after 19 June every year.

Contributing

See the contributing guide.

Todo

Nothing to do.

Contributors

@r1zyn - getMatariki and parseDate functions, commenting
@JiachenHH - Date utility functions
@SILentASSassinE - Method concept, testing (Jest and manual)
@tommy-duan-macleans - index and types files

Note: due to 3 members unfamiliar with git, all members contributed via the Live Share extension for Visual Studio Code, and one member then pushed commits to the repository.

r1zyn/MatarikiProgram