@hanology/era

GB/T XXXXX 日曆體系代碼 — parse, generate, and resolve Chinese historical calendar era codes. The GB/T registry is bundled; no separate data install needed.

Parse codes like h-CN.2.24.071.021.01 into structured records, generate canonical code strings, and resolve codes to Gregorian years with bilingual labels.

Install

npm install @hanology/era

The GB/T registry (38 dynasties, 336 rulers, 547 eras, 123 ganzhi entries) is bundled in the package. No data-only install needed.

Quick start

import {
  parseCode, generateCode, isValidCode,
  imperialCode, kinglyCode, rocCode, ganzhiCode,
  EraResolver, loadEraData,
} from '@hanology/era'

// Parse a code string
const parsed = parseCode('h-CN.2.24.071.021.01')
// → { type: 2, dynastyCode: 24, rulerCode: 7, reignCount: 1, eraCode: 2, eraInstance: 1, eraYear: 1, ... }

// Validate
isValidCode('h-CN.2.24.071.021.01')  // true
isValidCode('not-a-code')              // false

// Generate from structured data
const code = imperialCode(24, 7, 1, 2, 1, 1)  // 'h-CN.2.24.071.021.01'

// Resolve to Gregorian year + bilingual label
const resolver = new EraResolver(loadEraData())
const resolved = resolver.resolve(parsed)
// → {
//     code: 'h-CN.2.24.071.021.01',
//     label: '唐玄宗開元元年',
//     labelEn: '1st year of 開元 era, 玄宗 of 唐',
//     gregorianYear: 713
//   }

Four era types

GB/T XXXXX Part 2 defines four calendar-system types:

| Type | Name | Format | Example | |---|---|---|---| | 1 | 王公即位年次紀年 (kingly succession) | h-CN.1.{DD}.{RRR}.{YYY} | h-CN.1.04.011.001 | | 2 | 年號紀年 (imperial era name) | h-CN.2.{DD}.{RRR}.{EER}.{YY} | h-CN.2.24.071.021.01 | | 3 | 中華民國紀年 (ROC) | h-CN.3.{YY} | h-CN.3.01 | | 4 | 天干地支紀年 (ganzhi cycle) | h-CN.4.{CC}.{OO} | h-CN.4.01.50 |

Where:

• DD — 2-digit dynasty code
• RRR — 3-digit ruler segment (2-digit ruler + 1-digit reign)
• YYY — 3-digit year ordinal within reign
• EER — 3-digit era segment (2-digit era + 1-digit instance)
• YY — 2-digit era year
• CC — 2-digit ganzhi code (1–60)
• OO — 2-digit cycle occurrence ordinal

Modules

| Module | What it does | |---|---| | parse.ts | parseCode(code) → ParsedCode \| null; isValidCode(code) | | generate.ts | generateCode(parsed); convenience builders kinglyCode, imperialCode, rocCode, ganzhiCode | | resolve.ts | EraResolver class — code → Gregorian year + labels; reverse lookups; dynasty alias resolution | | data.ts | loadEraData() — reads the bundled GB/T registry | | types.ts | All public types (ParsedCode, ResolvedCode, EraData, entry shapes) |

Full reference: API.md. Architecture rationale: ARCHITECTURE.md. Updating the bundled data: DEVELOPMENT.md.

Source data

The bundled data/era-data.json is a snapshot of the canonical registry at hanologyorg/era-data. That repo holds the source-of-truth data plus the extraction script (scripts/extract-era-data.py) that regenerates it from the GB/T docx.

To pull a fresh snapshot into this package:

npm run sync-data

License

MIT.