tyme4ts

To use tyme4ts in a TypeScript project, you need to install the package along with typescript and ts-node for execution. Run the following commands in your terminal:

npm init -y
npm i typescript -D
npm i ts-node -D
npm i tyme4ts

Many entities in the library (Animals, Stars, Elements, etc.) are implemented as LoopTyme classes. These represent values that cycle through a fixed set of names.

Common patterns for LoopTyme subclasses:

• Creation: Use fromIndex(index) or fromName(name) to instantiate an object.
• Navigation: Use next(n) to move forward or backward in the cycle.
• Metadata: Most classes provide getName(), getIndex(), and getSize().

The library is built around two primary interfaces:

• Culture: Represents a specific cultural time system. It must implement getName() (returning the culture's name) and toString() (returning a string representation).
• Tyme: Extends Culture and adds the next(n: number) method, which returns the next Tyme instance after n steps, or null if no next value exists.

All time units (Year, Month, Day, etc.) are implementations of these interfaces.

The EightCharProvider interface defines how to derive an EightChar from a LunarHour. You can swap the global provider on LunarHour to change the calculation logic.

Available implementations:

• DefaultEightCharProvider: Uses the standard hour.getSixtyCycleHour().getEightChar() logic.
• LunarSect2EightCharProvider: Uses a specific logic where the month is derived from the lunar year/month components.

To change the provider:

LunarHour.provider = new LunarSect2EightCharProvider();

You can create a SolarDay instance using SolarDay.fromYmd(year, month, day) and then access different calendar systems using the following methods:

• getLunarDay(): Returns the Lunar calendar representation.
• getRabByungDay(): Returns the Rab Byung (Tibetan) calendar representation.
• getHijriDay(): Returns the Hijri calendar representation.

Each method returns a day object that can be converted to a string using .toString().

import {SolarDay} from 'tyme4ts';

const solar: SolarDay = SolarDay.fromYmd(1986, 5, 29);

// 1986年5月29日
console.log(solar.toString());

// 农历丙寅年四月廿一
console.log(solar.getLunarDay().toString());

// 第十七饶迥火虎年四月廿一
console.log(solar.getRabByungDay().toString());

// 1406年赖买丹月20日
console.log(solar.getHijriDay().toString());

The TenStar class represents the ten stars (十神) used in analysis of heavenly stems.

Key methods:

• fromIndex(index: number | string): Creates a TenStar instance.
• fromName(name: string): Creates a TenStar instance.

import { TenStar } from 'tyme4ts';

const star = TenStar.fromName('正财');

The KitchenGodSteed class (extending AbstractCulture) provides traditional cultural strings (often related to '灶马头' or Kitchen God) based on a specific lunar year. It uses Earth Branches and Heaven Stems to return specific phrases for different animals or elements.

Key methods:

• fromLunarYear(lunarYear: number | string): Static factory to create an instance from a lunar year.
• getMouse(), getGrass(), getCattle(), getFlower(), getDragon(), getHorse(), getChicken(), getSilkworm(), getPig(), getField(), getCake(), getGold(), getPeopleCakes(), getPeopleHoes(): Returns specific cultural strings/predictions.
• getName(): Returns the name of the culture ('灶马头').

const steed = KitchenGodSteed.fromLunarYear(2024);
console.log(steed.getMouse()); // e.g., "X鼠偷粮"
console.log(steed.getGold());  // e.g., "X日得金"

The RabByungDay class represents a specific day in the RabByung calendar. It supports leap days and conversion to SolarDay.

Key methods:

• fromYmd(year, month, day): Creates an instance.
• fromSolarDay(solarDay: SolarDay): Converts a solar date to a RabByung date.
• getSolarDay(): Converts the RabByung date to a SolarDay.
• subtract(target: RabByungDay): Returns the difference in days between two dates.
• next(n: number): Returns the date after n days (via solar conversion).

const day = RabByungDay.fromYmd(2024, 1, 1);
const solar = day.getSolarDay();
const diff = day.subtract(someOtherRabByungDay);

The LunarMonth class represents a month in the lunar calendar.

Methods:

• static fromYm(year: number | string, month: number | string): Create a LunarMonth instance. A negative month value indicates a leap month.
• isLeap(): Returns true if this is a leap month.
• getName(): Returns the name (e.g., '正月', '闰二月').
• getDays(): Returns an array of LunarDay objects for this month.
• getFirstDay(): Returns the first LunarDay of the month.
• getWeeks(start: number): Returns an array of LunarWeek objects starting from a specific week index.
• getSixtyCycle(): Returns the SixtyCycle for this month.
• getFetus(): Returns the FetusMonth (if not a leap month).
• getSeason(): Returns the LunarSeason this month belongs to.

const month = LunarMonth.fromYm(2024, 1); // 正月
const days = month.getDays();

Use the EventBuilder to programmatically create Event objects with specific recurrence rules. The builder uses a fluent interface.

Supported event types via builder:

• solarDay(solarMonth, solarDay, delayDays)
• lunarDay(lunarMonth, lunarDay, delayDays)
• solarWeek(solarMonth, weekIndex, week)
• termDay(termIndex, delayDays)
• termHeavenStem(termIndex, heavenStemIndex, delayDays)
• termEarthBranch(termIndex, earthBranchIndex, delayDays)

const myEvent = Event.builder()
  .name('My Custom Event')
  .solarDay(3, 21, 0) // March 21st, 0 days delay
  .build(); // Note: build() is implied by the pattern, though the segment shows the builder methods