date-japanese

Convert Japanese calendar dates to Western calendar dates and vice versa. Full support for Kanji numerals in Wareki dates.

Installation

npm install --save date-japanese

Quick Start

Node.js

const {toWesternCalendar, toJapaneseCalendar} = require('date-japanese');

toWesternCalendar('令和4年2月21日', 'YYYY-MM-DD'); // -> 2022-02-21
toWesternCalendar('令和七年一月三十一日', 'YYYY-MM-DD'); // -> 2025-01-31
toWesternCalendar('令和4年2月', 'YYYY-MM'); // -> 2022-02
toWesternCalendar('昭和64年', 'YYYY'); // -> 1989

toJapaneseCalendar('2022-02-21'); // -> 令和4年2月21日
toJapaneseCalendar('1989-01'); // -> 昭和64年1月
toJapaneseCalendar('1990'); // -> 平成2年

Or in ES6 syntax:

import {toWesternCalendar, toJapaneseCalendar} from 'date-japanese';

toWesternCalendar('令和4年2月21日', 'YYYY-MM-DD'); // -> 2022-02-21
toWesternCalendar('令和七年一月三十一日', 'YYYY-MM-DD'); // -> 2025-01-31
toWesternCalendar('令和4年2月', 'YYYY-MM'); // -> 2022-02
toWesternCalendar('昭和64年', 'YYYY'); // -> 1989

toJapaneseCalendar('2022-02-21'); // -> 令和4年2月21日
toJapaneseCalendar('1989-01'); // -> 昭和64年1月
toJapaneseCalendar('1990'); // -> 平成2年

Browser

<script src="node_modules/date-japanese/dist/build.js"></script>
<script>
  dateJapanese.toWesternCalendar('令和4年2月21日', 'YYYY-MM-DD'); // -> 2022-02-21
  dateJapanese.toJapaneseCalendar('2022-02-21'); // -> 令和4年2月21日
</script>

Or in ES6 syntax:

<script type="module">
  import {toWesternCalendar, toJapaneseCalendar} from 'node_modules/date-japanese/dist/build.mjs';

  toWesternCalendar('令和4年2月21日', 'YYYY-MM-DD'); // -> 2022-02-21
  toJapaneseCalendar('2022-02-21'); // -> 令和4年2月21日
</script>

API

toWesternCalendar(japaneseDate, format, throwOnInvalid)

Converts a Japanese calendar date to a Western calendar date in the specified format.
Supported eras: Meiji (明治), Taisho (大正), Showa (昭和), Heisei (平成), Reiwa (令和).
This function can also handle Japanese dates written with Kanji numerals.

Parameters:

• japaneseDate: Japanese calendar date (e.g., '令和4年2月20日', '令和4年2月', '令和4年').
• format: Output date format. Available tokens: YYYY, YY, M, MM, MMM, MMMM, D, DD (default: 'YYYY-MM-DD').
• throwOnInvalid: If true, throws an error if the input date is invalid. If false, returns an empty string (default: false).

Return value:

The Western calendar date in the specified format, or an empty string if the input is invalid and throwOnInvalid is false.

Examples:

toWesternCalendar('令和元年5月1日'); // -> 2019-05-01
toWesternCalendar('令和4年2月21日', 'YYYY/MM/DD'); // -> 2022/02/21
toWesternCalendar('平成元年1月', 'YYYY-MM'); // -> 1989-01

toJapaneseCalendar(westernDate)

Converts a Western calendar date to a Japanese calendar date. This function only supports dates from 1868-01-25 onwards (Meiji era and later).

Parameters:

• westernDate: Western calendar date in one of the following formats: 'YYYY-MM-DD', 'YYYY-M-D', 'YYYY/MM/DD', 'YYYY/M/D', 'MM-DD-YYYY', 'M-D-YYYY', 'MM/DD/YYYY', 'M/D/YYYY', 'YYYY-MM', 'YYYY-M', 'YYYY/MM', 'YYYY/M', 'MM-YYYY', 'M-YYYY', 'MM/YYYY', 'M/YYYY', 'YYYY'.
• throwOnInvalid: If true, throws an error if the input date is invalid. If false, returns an empty string (default: false).

Return value: The Japanese calendar date, or an empty string if the input date is before the Meiji era or invalid (and throwOnInvalid is false).

Examples:

toJapaneseCalendar('2019-05-01'); // -> 令和元年5月1日
toJapaneseCalendar('2022-02-21'); // -> 令和4年2月21日
toJapaneseCalendar('1989-02'); // -> 平成元年2月

isValidJapaneseCalendar(value)

Checks if the given value is a valid Japanese calendar date.

Parameters:

• value: The value to be validated.

Return value:

true if the value is a valid Japanese calendar date, false otherwise.

Examples:

isValidJapaneseCalendar('令和元年5月1日'); // -> true
isValidJapaneseCalendar('令和4年2月21日'); // -> true
isValidJapaneseCalendar('2022-02-21'); // -> false

Demos

This package includes demos for various environments:

• Browser Demo: demo/browser/index.html
  • See the screenshot below for a preview.
• Node.js (CommonJS): cjs/index.cjs
• Node.js (ES Modules): esm/index.js

Browser Demo Screenshot

Prototypes

prototypes/run_japanese_calendar.mjs

node prototypes/run_japanese_calendar.mjs -d 2025-01-30 # -> Western Calendar: 2025-01-30, Japanese Calendar: 令和7年1月30日
node prototypes/run_japanese_calendar.mjs -d 2025/1/30 # -> Western Calendar: 2025/1/30, Japanese Calendar: 令和7年1月30日
node prototypes/run_japanese_calendar.mjs -d 2025-01 # -> Western Calendar: 2025-01, Japanese Calendar: 令和7年1月
node prototypes/run_japanese_calendar.mjs -d 2025/1 # -> Western Calendar: 2025/1, Japanese Calendar: 令和7年1月
node prototypes/run_japanese_calendar.mjs -d 2025 # -> Western Calendar: 2025, Japanese Calendar: 令和7年

prototypes/run_wester_calendar.mjs

node prototypes/run_wester_calendar.mjs -d 令和七年一月二日 # -> Japanese Calendar: 令和七年一月二日, Western Calendar: 2025-01-02
node prototypes/run_wester_calendar.mjs -d 大正元年7月30日 # -> Japanese Calendar: 大正元年7月30日, Western Calendar: 1912-07-30

Testing

npm test

Release Notes

All changes can be found here.

Author

Takuya Motoshima

• github/takuya-motoshima
• twitter/TakuyaMotoshima
• facebook/takuya.motoshima.7

License

MIT