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

    Class JapaneseDate

    Japanese calendar date (UTC+9, epoch 2636 BCE)

    Uses the same epoch as the Chinese calendar but with UTC+9 timezone. The timezone difference can cause different leap month assignments in rare cases where a new moon falls near midnight.

    Japanese month names use traditional names (睦月, 如月, 弥生, etc.) when formatted with 'ja-JP' locale.

    const date = JapaneseDate.fromGregorian(2024, 6, 15)
    date.formatFull('ja-JP')  // "甲辰年 皐月初十"
    date.getZodiac('ja-JP')   // "辰"

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    _config calendarType cycle day leap month year

    Accessors

    dayGanZhi dayGanZhiPair festivals ganZhiInfo gregorianYear gregorianYearCn gregorianYearCnLower monthGanZhi monthGanZhiPair weekday weekdayName weekdayShort yearGanZhi yearGanZhiPair zodiac zodiacEmoji zodiacIndex

    Methods

    _value addDays addMonths addYears daysInMonth diffDays equals format formatCompact formatFull formatGanZhi formatISO getFestivals getSolarTermName getWeekdayName getWeekdayShort getZodiac isAfter isBefore toDate toGregorian toJDE toJSON toString with fromDate fromGregorian fromISO fromJDE fromTimestamp fromValue newYear parse today

    Constructors

    Properties

    Protected Readonly_config

    _config: CalendarConfig
    calendarType: CalendarType
    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)

    Accessors

    • get dayGanZhi(): string

      Day GanZhi string, e.g. "甲子"

      Returns string

    • get dayGanZhiPair(): GanZhiPair

      Day GanZhi pair

      Returns GanZhiPair

    • get festivals(): FestivalInfo[]

      Get festivals on this date in simplified Chinese

      Returns FestivalInfo[]

    • get ganZhiInfo(): GanZhiInfo

      Full GanZhi info

      Returns GanZhiInfo

    • get gregorianYear(): number

      Get the corresponding Gregorian year

      This is the most common way to get a human-readable year number. Computed from cycle and year using the calendar's epoch.

      Returns number

      ChineseDate.fromGregorian(2024, 6, 21).gregorianYear  // 2024
    • get gregorianYearCn(): string

      Gregorian year in Chinese numerals (〇 style), e.g. "二〇二五"

      Returns string

    • get gregorianYearCnLower(): string

      Gregorian year in Chinese numerals (零 style), e.g. "二零二五"

      Returns string

    • get monthGanZhi(): string

      Month GanZhi string, e.g. "丙寅"

      Returns string

    • get monthGanZhiPair(): GanZhiPair

      Month GanZhi pair

      Returns GanZhiPair

    • get weekday(): number

      Weekday number (0=Sunday, 1=Monday, ..., 6=Saturday)

      Returns number

    • get weekdayName(): string

      Weekday full name in simplified Chinese, e.g. "星期六"

      Returns string

    • get weekdayShort(): string

      Weekday short name in simplified Chinese, e.g. "六"

      Returns string

    • get yearGanZhi(): string

      Year GanZhi string, e.g. "甲辰"

      Returns string

    • get yearGanZhiPair(): GanZhiPair

      Year GanZhi pair

      Returns GanZhiPair

    • get zodiac(): string

      Zodiac animal in simplified Chinese

      Returns string

    • get zodiacEmoji(): string

      Zodiac emoji

      Returns string

    • get zodiacIndex(): number

      Zodiac index (0-11)

      Returns number

    Methods

    Protected_value

    • Add days to this date, returning a new instance

      Works by converting to Gregorian, adding days, then converting back. This ensures correct handling of month/year boundaries.

      Parameters

      • days: number

        Number of days to add (negative to subtract)

      Returns this

      New LunarDate instance

      const date = ChineseDate.fromGregorian(2024, 6, 21)
      const tomorrow = date.addDays(1)
      const yesterday = date.addDays(-1)

    • Add Gregorian months to this date, returning a new instance

      Works on the Gregorian calendar: adds months and adjusts the year if necessary. If the resulting day exceeds the month's length, it is clamped to the last day of the month.

      Parameters

      • months: number

        Number of months to add (negative to subtract)

      Returns this

      New LunarDate instance

      const date = ChineseDate.fromGregorian(2024, 1, 31)
      const next = date.addMonths(1) // 2024-02-29 (leap year, clamped)

    • Add Gregorian years to this date, returning a new instance

      If the resulting date is invalid (e.g., Feb 29 on a non-leap year), the day is clamped to the last day of the month.

      Parameters

      • years: number

        Number of years to add (negative to subtract)

      Returns this

      New LunarDate instance

    • Get the number of days in this lunar month

      A lunar month is either 29 days (small month / 小月) or 30 days (big month / 大月). Calculated by converting to Gregorian and comparing the day 1 of this month and the day 1 of the next month.

      Returns number

      29 or 30

      const date = ChineseDate.fromGregorian(2024, 6, 21)
      date.daysInMonth()  // 29 or 30

    • Get the number of days between this date and another

      Returns a positive number if this date is after the other, negative if before, and zero if they are the same day.

      Parameters

      • other: LunarDate

        The other date to compare with

      Returns number

      Number of days difference (this - other)

      const a = ChineseDate.fromGregorian(2024, 6, 21)
      const b = ChineseDate.fromGregorian(2024, 6, 18)
      a.diffDays(b)  // 3
      b.diffDays(a)  // -3

    • Check equality with another LunarDate

      Parameters

      Returns boolean

    • Format with a custom pattern (supports all tokens including Gregorian and weekday)

      Parameters

      Returns string

      Formatted string

      const date = ChineseDate.fromGregorian(2024, 6, 21)
      date.format('{Ygz}{Z}年 {Mname}{Dname}', 'zh-CN')  // "甲辰龙年 五月初六"
      date.format('{Ygz}{Z}年 {Mname}{Dname}', 'zh-TW')  // "甲辰龍年 五月初六"
      date.format(PATTERNS.GREGORIAN_ISO)                  // "2024-06-21"
      date.format(PATTERNS.GREGORIAN_CN_FULL)              // "二〇二四年六月二十一日"

    • Compact format: cycle/year/month/leap/day

      leap is encoded as 0 (false) or 1 (true).

      Returns string

      String like "78/34/7/0/28"

      ChineseDate.fromGregorian(2024, 6, 21).formatCompact()  // "78/34/5/0/6"

    • Full format with locale support

      Parameters

      • locale: LocaleCode = 'zh-CN'

        Locale code (default: 'zh-CN')

      Returns string

      Formatted string like "甲辰龙年 五月初六" (zh-CN) or "甲辰龍年 五月初六" (zh-TW)

      ChineseDate.fromGregorian(2024, 6, 21).formatFull()         // "甲辰龙年 五月初六"
      ChineseDate.fromGregorian(2024, 6, 21).formatFull('zh-TW')  // "甲辰龍年 五月初六"
      ChineseDate.fromGregorian(2024, 6, 21).formatFull('zh-HK')  // "甲辰龍年 五月初六"

    • GanZhi (干支) format: year month day pillars

      Parameters

      • locale: LocaleCode = 'zh-CN'

        Locale code (default: 'zh-CN')

      Returns string

      Formatted string like "甲辰年 庚午月 甲寅日" (zh-CN), "甲辰년 경오월 갑인일" (ko-KR), or "Năm 甲辰 Tháng 庚午 Ngày 甲寅" (vi-VN)

      ChineseDate.fromGregorian(2024, 6, 21).formatGanZhi()         // "甲辰年 庚午月 甲寅日"
      ChineseDate.fromGregorian(2024, 6, 21).formatGanZhi('ko-KR')  // "甲辰년 경오월 갑인일"

    • ISO format: CY-Y-M-L-D

      leap is encoded as 0 (false) or 1 (true).

      Returns string

      String like "78-34-7-0-28"

      ChineseDate.fromGregorian(2024, 6, 21).formatISO()  // "78-34-5-0-6"

    • Check if this date is a solar term day, returns the name or null

      Parameters

      Returns string | null

    • Check if this date is after another

      Parameters

      Returns boolean

    • Convert to JavaScript Date

      Returns Date

    • Convert to Gregorian date

      Returns GregorianDate

      Gregorian date object

      ChineseDate.fromGregorian(2024, 6, 21).toGregorian()
      // { year: 2024, month: 6, day: 21 }

    • Convert to JDE

      Returns number

    • Default string representation (full format)

      Returns string

    • Create from a JavaScript Date object. Uses local timezone for date components.

      Parameters

      • date: Date

      Returns JapaneseDate

    • Create from a Gregorian date

      Parameters

      • year: number

        Gregorian year (e.g., 2024)

      • month: number

        Month (1-12)

      • day: number

        Day of month

      Returns JapaneseDate

      LunarDate instance

      LunarDate.fromGregorian(2024, 6, 21)
      // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }

    • Create from a Gregorian date string

      Supports formats:

      • ISO: "2025-10-11"
      • Slash: "2025/10/11"
      • Chinese: "2025年10月11日"

      Parameters

      • isoStr: string

        Gregorian date string

      Returns JapaneseDate | null

      LunarDate instance, or null if the string cannot be parsed

    • Create from a Unix timestamp (milliseconds since 1970-01-01T00:00:00Z)

      Parameters

      • ms: number

        Unix timestamp in milliseconds

      Returns JapaneseDate

      LunarDate instance

    • Create from a LunarDateValue object

      Useful for reconstructing a date from serialized data.

      Parameters

      Returns JapaneseDate

      LunarDate.fromValue({ cycle: 78, year: 34, month: 5, leap: false, day: 6 })

    • Get Japanese New Year for a Gregorian year

      Parameters

      • gyear: number

      Returns GregorianDate

    • Parse a date string and create a LunarDate instance

      Auto-detects the format:

      • Gregorian ISO: "2025-10-11"
      • Gregorian slash: "2025/10/11"
      • Gregorian Chinese: "2025年10月11日"

      Parameters

      • str: string

        Date string

      Returns JapaneseDate | null

      LunarDate instance, or null if the string cannot be parsed

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods