@jkumonpm/dayjs-roc

Day.js plugin for Taiwan ROC (Republic of China) calendar year. Supports RRR/RR format output and ROC date parsing.

Install

npm install @jkumonpm/dayjs-roc

Requires dayjs as a peer dependency.

Two Usage Modes

1️⃣ Plugin Mode (Day.js Extension)

import dayjs from 'dayjs'
import roc from '@jkumonpm/dayjs-roc'

dayjs.extend(roc)

// Format with ROC year
dayjs('2026-04-04').format('RRR/MM/DD')  // → '115/04/04'
dayjs('2026-04-04').format('RR/MM/DD')   // → '15/04/04'
dayjs('1912-01-01').format('RRR年MM月DD日') // → '001年01月01日'

// Get ROC year directly
dayjs('2026-04-04').rocYear()  // → 115

2️⃣ Direct Function Mode (No Day.js Required)

import { rocToAD, adToROC, isROCDate, parseROC, formatRRR, formatRR, isROC, parseROCDate } from '@jkumonpm/dayjs-roc'

// Convert ROC year to AD year
rocToAD(115)   // → 2026
rocToAD(1)     // → 1912
rocToAD(0)     // → null

// Convert AD year to ROC year
adToROC(2026)  // → 115
adToROC(1912)  // → 1
adToROC(1911)  // → null

// Validate ROC date string
isROCDate('115/04/04')  // → true
isROCDate('115/13/01')  // → false
isROC('115/04/04')      // → true (alias)

// Parse ROC date string to native Date
parseROC('115/04/04')   // → Date(2026, 3, 4)
parseROC('invalid')     // → null

// Parse ROC date string to Dayjs
parseROCDate('115/04/04')?.format('YYYY-MM-DD')  // → '2026-04-04'
parseROCDate('invalid')  // → null

// Format ROC year
formatRRR(115)  // → '115'
formatRRR(1)    // → '001'
formatRR(15)    // → '15'
formatRR(1)     // → '01'

Format Tokens

| Token | Output | Description | |-------|--------|-------------| | RRR | 115 | 3-digit ROC year (zero-padded) | | RR | 15 | 2-digit ROC year (zero-padded) |

Examples

const today = dayjs()

// Combine with standard Day.js tokens
today.format('RRR/MM/DD')        // → '115/04/04'
today.format('RRR 年 M 月 D 日')   // → '115 年 4 月 4 日'
today.format('dddd, RRR/MM/DD')  // → 'Saturday, 115/04/04'
today.format('RR/MM/DD HH:mm')   // → '15/04/04 14:30'

Utility Functions

isROC(str)

Check if a string is a valid ROC date format.

import { isROC } from '@jkumonpm/dayjs-roc'

isROC('115/04/04')    // → true
isROC('1/1/1')        // → true
isROC('115-04-04')    // → true
isROC('2024/01/01')   // → true (AD year also valid as ROC)
isROC('115/13/01')    // → false (invalid month)
isROC('abc')          // → false

parseROCDate(str)

Parse a ROC date string into a Dayjs instance.

import { parseROCDate } from '@jkumonpm/dayjs-roc'

const date = parseROCDate('115/04/04')
date?.year()   // → 2026
date?.month()  // → 3 (April, 0-indexed)
date?.date()   // → 4
date?.format('YYYY-MM-DD')  // → '2026-04-04'

parseROCDate('invalid')  // → null

Core Functions (no Day.js required)

import { rocToAD, adToROC, isROCDate, parseROC, formatRRR, formatRR } from '@jkumonpm/dayjs-roc'

// Convert ROC year to AD year
rocToAD(115)   // → 2026
rocToAD(1)     // → 1912
rocToAD(0)     // → null

// Convert AD year to ROC year
adToROC(2026)  // → 115
adToROC(1912)  // → 1
adToROC(1911)  // → null

// Validate ROC date string
isROCDate('115/04/04')  // → true
isROCDate('115/13/01')  // → false

// Parse ROC date string to native Date
parseROC('115/04/04')   // → Date(2026, 3, 4)
parseROC('invalid')     // → null

// Format ROC year
formatRRR(115)  // → '115'
formatRRR(1)    // → '001'
formatRR(15)    // → '15'
formatRR(1)     // → '01'

Supported Formats

| Input Format | Example | Supported | |-------------|---------|-----------| | RRR/MM/DD | 115/04/04 | ✅ | | RR/MM/DD | 15/04/04 | ✅ | | RRR-MM-DD | 115-04-04 | ✅ | | RR-MM-DD | 15-04-04 | ✅ | | R/M/D | 1/1/1 | ✅ |

Limitations

• ROC year 1 (AD 1912) onwards only — dates before 1912 return null
• No support for pre-ROC calendar — historical dates before the Republic of China are not supported
• RR token truncates — years >= 100 will return null for RR format

Conversion Rule

ROC year = AD year - 1911
AD year  = ROC year + 1911

The Republic of China calendar starts from 1912 (ROC year 1).

API Reference

Plugin

| Method | Returns | Description | |--------|---------|-------------| | dayjs().format('RRR/...') | string | Format with 3-digit ROC year | | dayjs().format('RR/...') | string | Format with 2-digit ROC year | | dayjs().rocYear() | number \| null | Get ROC year number |

Exports

| Function | Input | Output | Description | |----------|-------|--------|-------------| | isROC(str) | string | boolean | Validate ROC date format | | parseROCDate(str) | string | Dayjs \| null | Parse ROC date to Dayjs | | rocToAD(year) | number | number \| null | Convert ROC to AD year | | adToROC(year) | number | number \| null | Convert AD to ROC year | | isROCDate(str) | string | boolean | Validate ROC date (alias) | | parseROC(str) | string | Date \| null | Parse ROC date to native Date | | formatRRR(year) | number | string \| null | Format as 3-digit ROC year | | formatRR(year) | number | string \| null | Format as 2-digit ROC year |

License

MIT