chinese-lunar-date API - v1.0.5
    Preparing search index...

    Interface LunarDateValue

    Lunar date value (immutable data)

    Represents a date in the Chinese lunar calendar system. The year is identified by a 60-year cycle number and a position within that cycle.

    Understanding cycle and year: The Chinese calendar uses a continuous 60-year sexagenary cycle (六十甲子).

    • cycle is the 1-based cycle number — which 60-year block the date falls in. Cycle 1 starts at the epoch year (e.g., 2636 BCE for Chinese calendar). Cycle 78 starts at Gregorian year 1984 (1984 = -2636 + (78-1)*60 + 1).
    • year is the 1-based position within the cycle (1-60). Year 1 = 甲子年, Year 34 = 丁酉年, Year 60 = 癸亥年.

    To convert to a Gregorian year, use:

    gregorianYear = epochYear + (cycle - 1) * 60 + (year - 1)
    // e.g., Chinese epoch = -2636, cycle=78, year=34 → 2024

    Why not just a single year number? The cycle/year system avoids ambiguity at the epoch boundary and naturally maps to the GanZhi (干支) system where year=1 → 甲子.

    // 2024-06-21 in the Chinese calendar
    const value: LunarDateValue = { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
    // cycle=78, year=34 → 甲辰年 (2024 CE)
    // month=5, day=6 → 五月初六
    interface LunarDateValue {
        cycle: number;
        day: number;
        leap: boolean;
        month: number;
        year: number;
    }

    Implemented by

    Index

    Properties

    cycle day leap month year

    Properties

    cycle: number

    60-year cycle number (1-based).

    The Chinese calendar counts years in repeating 60-year blocks. Cycle 1 starts at the epoch year of the calendar variant:

    • Chinese: 2636 BCE (Chalmers epoch)
    • Korean: 2333 BCE (Dangun epoch)

    Example: Cycle 78 corresponds to 1984-2043 CE (Chinese calendar).

    day: number

    Day of month (1-30). Lunar months are 29 or 30 days long.

    Use LunarDate.daysInMonth() to determine the actual length of a given month.

    leap: boolean

    Whether this is a leap month (闰月).

    Leap months are inserted to keep the lunar calendar aligned with solar terms. A leap month has the same number as the preceding month but with leap=true. For example, 2023 has a leap second month: { month: 2, leap: true } = 闰二月.

    month: number

    Lunar month (1-12). Month 1 is 正月 (the first month, starting at Spring Festival).

    Unlike the Gregorian calendar, lunar months are either 29 or 30 days long, determined by astronomical new moon observations.

    year: number

    Year within the 60-year cycle (1-60).

    Year 1 = 甲子年, Year 2 = 乙丑年, ..., Year 60 = 癸亥年. The GanZhi (干支) is derived directly from this value:

    • gan = (year - 1) % 10 (Heavenly Stem index)
    • zhi = (year - 1) % 12 (Earthly Branch index)

    Settings

    Member Visibility

    On This Page

    Properties