Logo

TEA Calendar

Pragmatically convert Gregorian calendar date of the period 1583-2100 to Chinese Calendar date

Demo

Table Of Contents

About the Project

This pure JavaScript program converts any Gregorian calendar date of the period 1583-2100 to its corresponding Chinese calendar date. It is designed to be an alternative to the conversion via the JavaScript's Standard built-in objects, which is not always reliable for the real-world usage (cf. the code example below or this codepen) and rather difficult to be adjusted to the existing Chinese calendar without loss of efficiency. 

//conversion wiht the JavaScript's Standard built-in objects
const date = new Date('2018-11-08T12:00:00.000');
const options = {year: 'numeric', month: 'numeric', day: 'numeric' };
const dateFormat = new Intl.DateTimeFormat('fr-CA-u-ca-chinese', options);
let output = dateFormat.format(date);
//output in Chrome as well as in Firefox: "2/10/35".
//In reality, the corresponding date is "1/10/35".

Note About the correct conversion of the date above, cf., for example, the conversion table 2011-2020 published by the Taipei Astronomical Museum or the Gregorian-Lunar Calendar Conversion Table 2018 of Hong Kong Observatory.

Usage

Installation

# npm
npm i tea-calendar

Basic conversion

  • import the core module:
import {Teac} from '/PATH/TO/teac.js'

  • input a Gregorian Calendar date string in "YYYY-MM-DD" format to get an array of four elements:

    • number of the year in the sexagenary cycle,

    • lunar month number,

    • day number,

    • Boolean value for leap month (true: leap month)

const date = new Teac('2025-07-28').num();
// Expected output: [42, 6, 4, true]

Note In order to avoid the impact of time zone setting of the device (or the network), this program uses the UTC and the 12:00:00 GMT+00:00 for each input date. For example, the string '2023-04-04' is converted to "2023-04-04T12:00:00.000Z" before the construction of the corresponding JavaScript Date object.

i18n

Firstly, import the linguistic module Lang with the core module:

import {Teac, Lang} from './Teac.js'
Output the sexagenary years in string format
  • in Chinese:
const d = new Teac('2025-07-28').yearIn('zh');
// Expected output: ['乙巳', 6, 4, true]
  • in Korean:
const d = new Teac('2025-07-28').yearIn('ko');
// Expected output: ['을사', 6, 4, true]
  • in Pinyin:
const d = new Teac('2025-07-28').yearIn('en');
// Expected output: ['yi-si', 6, 4, true]
Output entirely in text format
  • in Traditional Chinese:
const d = new Teac('2025-07-28').sino(0)
// Expected output: ['乙巳年', '閏六月', '初四']
  • in simplified Chinese:
const d = new Teac('2025-07-28').sino(1)
// Expected output: ['乙巳年', "闰六月', '初四']
  • without literal characters:
const d = new Teac('2025-07-28').sino(0, false);
// Expected output: ['乙巳', "閏六', '初四']

License

Distributed under the MIT License. See LICENSE for more information. Distributed under the MIT License. See LICENSE for more information.

Author

Acknowledgements