### Install lunar-date-vn

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/README.md

Install the lunar-date-vn package using npm.

```bash
npm install lunar-date-vn
```

--------------------------------

### Factory Pattern Example

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

Demonstrates the use of factory methods like fromSolarDate() and fromJd() for creating instances from alternative data sources.

```typescript
// Example usage (conceptual):
// const lunarDate = LunarDate.fromSolarDate(solarDateInstance);
// const lunarDateFromJd = LunarDate.fromJd(julianDate);
```

--------------------------------

### Create SolarDate with ISolarDate Input

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/types.md

Example demonstrating how to create a SolarDate instance using the ISolarDate interface. Ensure the 'lunar-date-vn' library is imported.

```typescript
import { SolarDate, type ISolarDate } from "lunar-date-vn";

const dateInput: ISolarDate = {
  day: 19,
  month: 6,
  year: 2023,
  yearIndex: 2023,
  hour: 14
};

const solar = new SolarDate(dateInput);
```

--------------------------------

### UMD Import for Browsers

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Provides an example of how to include the library in a browser environment using a script tag and access its exports via the `window._calendar` object.

```html
<script src="https://cdn.jsdelivr.net/npm/lunar-date-vn"></script>
<script>
  const { SolarDate, LunarDate } = window._calendar;
</script>
```

--------------------------------

### Create SolarDate Instance from ISolarDate

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Example of creating a SolarDate instance by providing an object that conforms to the ISolarDate interface. Handles invalid dates by returning an error.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

new SolarDate({ day: 1, month: 1, year: 2023 });
```

--------------------------------

### Create LunarDate with ILunarDate Input

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/types.md

Example demonstrating how to create a LunarDate instance using the ILunarDate interface, including the leap_month property. Ensure the 'lunar-date-vn' library is imported.

```typescript
import { LunarDate, type ILunarDate } from "lunar-date-vn";

const lunarInput: ILunarDate = {
  day: 1,
  month: 2,
  year: 2023,
  yearIndex: 2023,
  hour: 0,
  leap_month: true // Month 2 of year 2023 has a leap month
};

const lunar = new LunarDate(lunarInput);
lunar.init();
```

--------------------------------

### Get Lucky Hours for a Lunar Date

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/types.md

Example demonstrating how to retrieve and display lucky hours for a given lunar date using the LunarDate.getLuckyHours() method. Ensure the 'lunar-date-vn' library is imported.

```typescript
import { LunarDate, type ILuckyHour } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();

const luckyHours: ILuckyHour[] | null = lunar.getLuckyHours();
if (luckyHours) {
  luckyHours.forEach(hour => {
    console.log(`${hour.name}: ${hour.time[0]}:00 - ${hour.time[1]}:00`);
  });
  // Output:
  // Tý: 23:00 - 1:00
  // Sửu: 1:00 - 3:00
  // ...
}
```

--------------------------------

### LunarDate.init() Validation Example

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/errors.md

This example shows a scenario where calling LunarDate.init() might result in an error if the day exceeds the actual length of the lunar month, even if the initial construction was within basic bounds.

```typescript
import { LunarDate } from "lunar-date-vn";

// Month that doesn't actually have 30 days in year 2023
const lunar = new LunarDate({ day: 30, month: 3, year: 2023 });
lunar.init(); // Error: day exceeds month length if month 3 has only 29 days
```

--------------------------------

### get()

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Returns an object containing all information about the current LunarDate, including day, month, year, zodiac information, and Julian date.

```APIDOC
## get()

### Description
Returns an object containing all information about the current `LunarDate`.

### Method
```typescript
get(): { name: 'lunar_calendar'; day: number; month: number; year: number; yearIndex: number; hour: number; leap_year?: boolean; julian?: number; year_name: string; leap_month?: boolean }
```

### Returns
Object with properties:

| Property | Type | Description |
|----------|------|-------------|
| name | string | Always 'lunar_calendar' |
| day | number | Day of month (1-30) |
| month | number | Month (1-12) |
| year | number | Year (1200-2199) |
| yearIndex | number | Year index for zodiac calculations |
| hour | number | Hour (0-23) |
| leap_year | boolean | Whether the year has a leap month |
| julian | number | Julian date number |
| year_name | string | Year name in sexagenary cycle (e.g., "Quý Mão") |
| leap_month | boolean | Whether this is a leap month |

### Example
```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.get());
// Output: {
//   name: 'lunar_calendar',
//   day: 2,
//   month: 5,
//   year: 2023,
//   yearIndex: 2023,
//   hour: 0,
//   leap_year: true,
//   julian: 2460115,
//   year_name: 'Quý Mão',
//   leap_month: false
// }
```
```

--------------------------------

### Get LunarDate Information with get()

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

The get() method returns an object containing all information about the current LunarDate, including day, month, year, zodiac information, and Julian date.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.get());
// Output: {
//   name: 'lunar_calendar',
//   day: 2,
//   month: 5,
//   year: 2023,
//   yearIndex: 2023,
//   hour: 0,
//   leap_year: true,
//   julian: 2460115,
//   year_name: 'Quý Mão',
//   leap_month: false
// }
```

--------------------------------

### get()

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/solar-date.md

Returns an object containing all information about the current SolarDate, including day, month, year, hour, leap year status, and Julian date.

```APIDOC
## get()

### Description
Returns an object containing all information about the current `SolarDate`.

### Method
```typescript
get(): { name: 'solar_calendar'; day: number; month: number; year: number; yearIndex: number; hour: number; leap_year?: boolean; julian?: number }
```

### Returns
Object with properties:

| Property | Type | Description |
|----------|------|-------------|
| name | string | Always 'solar_calendar' |
| day | number | Day of month (1-31) |
| month | number | Month (1-12) |
| year | number | Year (1200-2199) |
| yearIndex | number | Year value used for indexing |
| hour | number | Hour (0-23) |
| leap_year | boolean | Whether the year is a leap year |
| julian | number | Julian date number |

### Response Example
```typescript
import { SolarDate } from "lunar-date-vn";

const solar = new SolarDate(new Date());
const info = solar.get();
console.log(info);
// Output: {
//   name: 'solar_calendar',
//   day: 29,
//   month: 5,
//   year: 2026,
//   yearIndex: 2026,
//   hour: 14,
//   leap_year: false,
//   julian: 2460115
// }
```
```

--------------------------------

### Initialize LunarDate with Leap Month and Initialize

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Initialize a LunarDate with a specified leap month and then call init() to populate secondary details. This example also shows conversion to a SolarDate.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

const al = new LunarDate({ day: 1, month: 2, year: 2023, leap_month: true });
al.init();
console.log(al.toSolarDate());
```

--------------------------------

### Valid LunarDate Construction

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/errors.md

Shows examples of constructing valid LunarDate objects, adhering to the day, month, and year range constraints.

```typescript
import { LunarDate } from "lunar-date-vn";

new LunarDate({ day: 14, month: 1, year: 1200 }); // First valid lunar date
new LunarDate({ day: 15, month: 6, year: 2023 }); // Regular lunar date
new LunarDate({ day: 1, month: 1, year: 2199 }); // Year 2199 (different month)
```

--------------------------------

### React Date Conversion Example

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

Demonstrates how to use SolarDate and LunarDate within a React component to manage and display date conversions. Requires React's useState hook.

```typescript
// React example
function DateConverter() {
  const [solar, setSolar] = useState(new SolarDate(new Date()));
  const [lunar, setLunar] = useState(solar.toLunarDate());
  
  const handleDateChange = (newDate: Date) => {
    const newSolar = new SolarDate(newDate);
    setSolar(newSolar);
    setLunar(newSolar.toLunarDate());
  };
  
  return <div>...</div>;
}
```

--------------------------------

### Get current date in both calendars

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Retrieve the current date in both solar and lunar formats and log their details to the console.

```typescript
const today = new SolarDate(new Date());
const todayLunar = today.toLunarDate();

console.log("Solar:", today.get());
console.log("Lunar:", todayLunar?.get());
```

--------------------------------

### Convert date string to Solar and Lunar dates in backend

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/README.md

This backend service example demonstrates converting a date string from a request parameter into SolarDate and LunarDate objects, then returning their data.

```typescript
app.get("/convert/:date", (req, res) => {
  const solar = new SolarDate(new Date(req.params.date));
  const lunar = solar.toLunarDate();
  res.json({ solar: solar.get(), lunar: lunar?.get() });
});
```

--------------------------------

### Get sexagenary cycle names

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Retrieve the Can-Chi names for the year, month, day, and the day of the week for a given lunar date. Initialization is required.

```typescript
const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();

console.log(lunar.getYearName());   // "Quý Mão"
console.log(lunar.getMonthName());  // "Mậu Ngọ"
console.log(lunar.getDayName());    // "Mậu Thân"
console.log(lunar.getDayOfWeek());  // "Thứ hai"
```

--------------------------------

### Get Lunar Year, Month, Day, and Solar Term Names

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Demonstrates how to retrieve various names associated with a lunar date, including year, month, day, first hour, solar term, and day of the week. Ensure the LunarDate object is initialized.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

let lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();

console.log(lunar.getYearName()); // Quý Mão
console.log(lunar.getMonthName()); // Mậu Ngọ
console.log(lunar.getDayName()); // Mậu Thân
console.log(lunar.getFirstHourNameOfTheDay()); // Nhâm Tý
console.log(lunar.getSolarTerm()); // Mang chủng
console.log(lunar.getDayOfWeek()); // Thứ hai
```

--------------------------------

### Retrieve SolarDate Information

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/solar-date.md

The get() method returns an object containing detailed information about the current SolarDate, including day, month, year, hour, leap year status, and Julian date. This is useful for inspecting the current state of the date object.

```typescript
import { SolarDate } from "lunar-date-vn";

const solar = new SolarDate(new Date());
const info = solar.get();
console.log(info);
// Output: {
//   name: 'solar_calendar',
//   day: 29,
//   month: 5,
//   year: 2026,
//   yearIndex: 2026,
//   hour: 14,
//   leap_year: false,
//   julian: 2460115
// }
```

--------------------------------

### Get First Hour Name of the Day

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieves the name of the first hour (Rat/Tý hour) of the day in the sexagenary cycle. Returns a string in the format "{Can} Tý".

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getFirstHourNameOfTheDay()); // "Nhâm Tý"
```

--------------------------------

### Express.js API Endpoint for Date Conversion

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

An example of an Express.js route that accepts solar date parameters, converts them to lunar dates, and returns the results as JSON. Includes basic error handling.

```typescript
// Express example
app.get("/convert/:year/:month/:day", (req, res) => {
  try {
    const solar = new SolarDate({
      day: parseInt(req.params.day),
      month: parseInt(req.params.month),
      year: parseInt(req.params.year),
      yearIndex: parseInt(req.params.year),
      hour: 0
    });
    const lunar = solar.toLunarDate();
    res.json({ solar: solar.get(), lunar: lunar?.get() });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});
```

--------------------------------

### Get Lunar Month Name with CommonJS

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Example of retrieving the month name from a lunar date object when using CommonJS modules. This snippet shows a specific method call.

```javascript
const _calendar = require("lunar-date-vn/dist/index.cjs");

var solar_date = new _calendar.SolarDate(new Date());
var lunar_date = solar_date.toLunarDate();

console.log(lunar_date.getMonthName()); // Mậu Ngọ
```

--------------------------------

### Get Sexagenary Day Name

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieves the name of the day according to the sexagenary cycle (Can-Chi system). Use this to get the day's designation like 'Mậu Thân'.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getDayName()); // "Mậu Thân"
```

--------------------------------

### Directory Structure

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

Shows the project's directory structure, highlighting the main entry point and the organization of modules for lunar date functionality.

```text
src/
├── index.ts                          # Main entry point
└── modules/
    └── lunar-date/
        ├── index.ts                  # Module exports
        ├── calendar.ts               # Base Calendar abstract class
        ├── solar.ts                  # SolarDate class
        ├── lunar.ts                  # LunarDate class
        └── constants.ts              # Lookup tables and constants
```

--------------------------------

### Get SolarDate LAST_DAY constant

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Retrieves the Julian date corresponding to the last day within the calculation range (2199-12-31).

```typescript
public static readonly LAST_DAY: number = SolarDate.jdn(new Date(2199, 11, 31)); //2199-12-31
```

--------------------------------

### Initialize LunarDate with UMD

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Demonstrates initializing a LunarDate instance using the UMD (Universal Module Definition) format, typically loaded via a script tag. The `init()` method is crucial.

```html
<script src="https://cdn.jsdelivr.net/..."></script>
<script>
  var lunar_date = new window._calendar.LunarDate({
    day: 1,
    month: 1,
    year: 2020,
  });
  lunar_date.init();
  console.log(lunar_date);
</script>

<!-- SolarDate {
  day: 1,
  month: 1,
  year: 2020,
  name: 'lunar_calendar',
  jd: 2458874,
  leap_year: false,
  leap_month: false,
} -->
```

--------------------------------

### Get SolarDate FIRST_DAY constant

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Retrieves the Julian date corresponding to the first day within the calculation range (1200-1-31).

```typescript
public static readonly FIRST_DAY: number = SolarDate.jdn(new Date(1200, 0, 31)); //1200-1-31
```

--------------------------------

### Import SolarDate using CommonJS format

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/README.md

Illustrates how to import the SolarDate class using the require function in a CommonJS module system.

```javascript
const { SolarDate } = require("lunar-date-vn")
```

--------------------------------

### SolarDate Constructor (ISolarDate)

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/solar-date.md

Initializes a SolarDate instance using an object containing day, month, and year. It validates the date and throws errors for invalid inputs or dates within the non-existent period of October 1582.

```APIDOC
## SolarDate(date: ISolarDate)

### Description
Creates a `SolarDate` instance from an object containing day, month, and year. The date must be within the valid range of 1200-1-31 to 2199-12-31 and must not fall within the non-existent period of 1582-10-05 to 1582-10-14.

### Parameters
#### Path Parameters
- **date** (ISolarDate) - Required - Object with `day`, `month`, `year` properties

### Throws
- **Invalid date**: Date is outside valid range (1200-1-31 to 2199-12-31) or invalid month/day combination.
- **Invalid date**: Date falls within non-existent period 1582-10-05 to 1582-10-14.

### Example
```typescript
import { SolarDate } from "lunar-date-vn";

const date = new SolarDate({ day: 19, month: 6, year: 2023 });
console.log(date.get());
// Output: { name: 'solar_calendar', day: 19, month: 6, year: 2023, leap_year: false, julian: 2460115 }
```
```

--------------------------------

### Get Lunar Month Name

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieve the sexagenary cycle name for the lunar month. For leap months, it includes '(nhuận)'.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getMonthName()); // "Mậu Ngọ"

const leapLunar = new LunarDate({ day: 1, month: 2, year: 2023, leap_month: true });
leapLunar.init();
console.log(leapLunar.getMonthName()); // "Mậu Ngọ (nhuận)"
```

--------------------------------

### Basic Usage: Solar to Lunar and Lunar to Solar Conversion

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/README.md

Demonstrates basic usage for converting between SolarDate and LunarDate objects, and retrieving calendar information. Ensure LunarDate objects are initialized using `.init()` before accessing their methods.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

// Solar to Lunar
const solar = new SolarDate(new Date());
const lunar = solar.toLunarDate();

// Lunar to Solar
const lunar2 = new LunarDate({ day: 1, month: 1, year: 2023 });
lunar2.init(); // Always initialize
const solar2 = lunar2.toSolarDate();

// Lunar calendar information
console.log(lunar?.getYearName());    // Year in Can-Chi
console.log(lunar?.getDayOfWeek());   // Day of week
console.log(lunar?.getLuckyHours());  // Lucky hours
```

--------------------------------

### Create SolarDate instances

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Instantiate SolarDate objects from various inputs including objects, JavaScript Date objects, and Julian dates.

```typescript
// From object
const solar1 = new SolarDate({ day: 19, month: 6, year: 2023 });

// From Date object
const solar2 = new SolarDate(new Date());

// From Julian date
const solar3 = SolarDate.fromJd(2460115);
```

--------------------------------

### Get Lunar Year Name

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieve the sexagenary cycle name for the lunar year. The format is '{Can} {Chi}', e.g., 'Quý Mão'.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getYearName()); // "Quý Mão"
```

--------------------------------

### Import SolarDate using ES Module format

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/README.md

Shows the standard import statement for using the SolarDate class in an ES Module environment.

```javascript
import { SolarDate } from "lunar-date-vn"
```

--------------------------------

### Initialize LunarDate and convert to SolarDate

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/README.md

Create a LunarDate object with specific day, month, and year, initialize it, and then convert it to a SolarDate. This is useful for date comparisons.

```typescript
const lunar = new LunarDate({ day: 1, month: 1, year: 2000 });
lunar.init();
const solar = lunar.toSolarDate();
// Use for comparing dates
```

--------------------------------

### Get Day of the Week

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieves the name of the day of the week in Vietnamese. Returns a string like "Thứ hai" for Monday.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getDayOfWeek()); // "Thứ hai"
```

--------------------------------

### Import types from lunar-date-vn

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/README.md

Demonstrates how to import specific types like ISolarDate, ILunarDate, and ILuckyHour from the library for use in TypeScript projects.

```typescript
import type { ISolarDate, ILunarDate, ILuckyHour } from "lunar-date-vn";
```

--------------------------------

### Get lucky hours for a lunar date

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Retrieve and display the lucky hours for a specific lunar date. Ensure the LunarDate is initialized first.

```typescript
const lunar = new LunarDate({ day: 15, month: 6, year: 2023 });
lunar.init();

const hours = lunar.getLuckyHours();
if (hours) {
  hours.forEach(({ name, time }) => {
    console.log(`${name}: ${time[0]}:00 - ${time[1]}:00`);
  });
}
```

--------------------------------

### Direct Solar to Lunar Conversion

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

Demonstrates the direct conversion from a SolarDate object to a pre-initialized LunarDate object using the `fromSolarDate` static method.

```text
SolarDate 
  → LunarDate.fromSolarDate() 
    → LunarDate (pre-initialized)
```

--------------------------------

### ILuckyHour Interface

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Defines the structure for Lucky Hour entries, containing the name of the zodiac animal and the time range (start and end hour).

```typescript
{
  name: string;     // Zodiac animal name
  time: number[];   // [start_hour, end_hour]
}
```

--------------------------------

### SolarDate Public Interface

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

Provides details on how to create and use the SolarDate class for Gregorian calendar operations and conversions.

```APIDOC
## SolarDate Public Interface

### Description
Provides details on how to create and use the SolarDate class for Gregorian calendar operations and conversions.

### Constructors
- `constructor(date: ISolarDate)`: Create a SolarDate instance from an ISolarDate object.
- `constructor(date: Date)`: Create a SolarDate instance from a JavaScript Date object.

### Static Methods
- `fromJd(jd: number): SolarDate`: Creates a SolarDate instance from a Julian date number.
- `jdn(date: ICalendarDate | Date): number`: Converts a given date (ICalendarDate object or JavaScript Date) to its Julian date number.

### Static Constants
- `FIRST_DAY: number`: The Julian date number for January 31, 1200.
- `LAST_DAY: number`: The Julian date number for December 31, 2199.

### Instance Methods
- `toDate(): Date`: Converts the SolarDate instance to a JavaScript Date object.
- `toLunarDate(): LunarDate | null`: Converts the SolarDate instance to a LunarDate instance. Returns null if conversion is not possible.
- `setDate(date: ICalendarDate | Date): void`: Updates the date of the SolarDate instance.
- `get(): object`: Retrieves all date information from the SolarDate instance.
```

--------------------------------

### Get Zodiac Year Index

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieves the index (0-11) of the zodiac animal for the given year. This can be used to determine the year's animal sign.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getYearIndex()); // Index representing zodiac animal
```

--------------------------------

### LunarDate Public Interface

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

This section details the public methods available for interacting with the LunarDate library, including constructors, static methods, and instance methods for initialization, conversion, sexagenary cycle information, and calendar details.

```APIDOC
## Constructors

### `constructor(date: ILunarDate)`

Create a LunarDate instance from an ILunarDate object.

## Static Methods

### `fromSolarDate(date: SolarDate): LunarDate | null`

Create a LunarDate instance from a SolarDate object. Returns null if the conversion fails.

## Instance Methods - Initialization

### `init(force_change?: boolean): void`

Initialize the LunarDate instance. Optionally force a change if `force_change` is true.

## Instance Methods - Conversions

### `toSolarDate(): SolarDate | null`

Convert the LunarDate instance to a SolarDate object. Returns null if the conversion fails or Julian date is undefined.

### `setDate(date: ILunarDate): void`

Update the LunarDate instance with new date information from an ILunarDate object. Throws 'Invalid date' error if the provided date is invalid.

### `get(): object`

Get all date information for the LunarDate instance, including calendar details and sexagenary cycle names.

## Instance Methods - Sexagenary Cycle

### `getYearName(): string`

Get the year name in the Sexagenary Cycle (Can-Chi).

### `getMonthName(): string`

Get the month name in the Sexagenary Cycle (Can-Chi).

### `getDayName(): string`

Get the day name in the Sexagenary Cycle (Can-Chi).

### `getFirstHourNameOfTheDay(): string | null`

Get the name of the first hour of the day in the Sexagenary Cycle. Returns null if unavailable.

### `getRealHourName(): string | null`

Get the name of the current hour in the Sexagenary Cycle. Returns null if unavailable.

## Instance Methods - Calendar Information

### `getDayOfWeek(): string | null`

Get the name of the day of the week. Returns null if unavailable.

### `getSolarTerm(): string | null`

Get the current solar term (tiết khí). Returns null if unavailable.

### `getLuckyHours(): ILuckyHour[] | null`

Get the list of lucky hours for the current day. Returns null if unavailable.

### `getYearIndex(): number | null`

Get the zodiac index (0-11) for the year. Returns null if unavailable.
```

--------------------------------

### Error Handling: Null Check for Conversions

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Illustrates how to perform a null check after attempting a date conversion, ensuring that the `init()` method was called.

```typescript
// Null check for conversions
const lunar = new LunarDate({ day: 15, month: 6, year: 2023 });
const solar = lunar.toSolarDate();
if (solar === null) {
  console.error("Conversion failed - ensure lunar.init() was called");
}
```

--------------------------------

### Inspect LunarDate Internal State

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/errors.md

Use the `get()` method to inspect the internal state of a LunarDate object before and after initialization. This is useful for debugging conversion issues.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 15, month: 6, year: 2023 });
console.log(lunar.get()); // Check internal state before init

lunar.init();
console.log(lunar.get()); // Check internal state after init

// Now safe to use
console.log(lunar.getLuckyHours());
```

--------------------------------

### init

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Initializes the LunarDate instance by calculating missing properties. This method must be called before accessing lunar-specific methods.

```APIDOC
## init

### Description
Initializes the `LunarDate` instance by calculating missing properties (`leap_year`, `leap_month`, `jd`). This method must be called after constructing a `LunarDate` before accessing lunar-specific methods.

### Parameters

#### Query Parameters
- **force_change** (boolean) - Optional - If false, only fills undefined properties. If true, recalculates all secondary properties.

### Throws

- **Invalid date**: The provided lunar date is invalid

### Example
```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.get());

lunar.init(true); // Recalculates everything
```
```

--------------------------------

### Valid SolarDate Construction

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/errors.md

Demonstrates the construction of valid SolarDate objects, including the earliest and latest possible dates within the supported range.

```typescript
import { SolarDate } from "lunar-date-vn";

new SolarDate({ day: 31, month: 1, year: 1200 }); // First valid date
new SolarDate({ day: 15, month: 6, year: 2023 }); // Regular date
new SolarDate({ day: 31, month: 12, year: 2199 }); // Last valid date (approximately)
```

--------------------------------

### solar.get()

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Retrieves the current date information from the `SolarDate` instance.

```APIDOC
## solar.get()

### Description
Gets the date information of the `SolarDate` instance.

### Method
`get();`

### Example
```ts
import { SolarDate, LunarDate } from "lunar-date-vn";

const dl = new SolarDate(new Date());
console.log(dl.get());

// {
//   name: 'solar_calendar',
//   day: 19,
//   month: 6,
//   year: 2023,
//   leap_year: false,
//   julian: 2460115
// }
```
```

--------------------------------

### DAY (Days of Week) Constant Array

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/types.md

An array of strings representing the names of the days of the week in Vietnamese, starting with Sunday. Used for displaying day names.

```typescript
['Chủ nhật', 'Thứ hai', 'Thứ ba', 'Thứ tư', 'Thứ năm', 'Thứ sáu', 'Thứ bảy']
```

--------------------------------

### SolarDate Constructor

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Creates an instance of SolarDate from an ISolarDate object. Ensure the date provided is valid.

```APIDOC
## SolarDate Constructor

### Description
Creates an instance of SolarDate from an ISolarDate object. Ensure the date provided is valid.

### Method
`constructor(date: ISolarDate)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **date** (ISolarDate) - Required - An object conforming to the ISolarDate interface, containing day, month, and year.

### Request Example
```typescript
import { SolarDate } from "lunar-date-vn";

new SolarDate({ day: 1, month: 1, year: 2023 });
```

### Response
#### Success Response (200)
An instance of SolarDate.

#### Response Example
```json
{
  "day": 1,
  "month": 1,
  "year": 2023,
  "name": "solar_calendar",
  "jd": 2459951,
  "leap_year": false
}
```
```

--------------------------------

### Get SolarDate details

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Retrieves the current date details from a SolarDate object in a structured format, including day, month, year, leap year status, and Julian date.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

const dl = new SolarDate(new Date());
console.log(dl.get());

// {
//   name: 'solar_calendar',
//   day: 19,
//   month: 6,
//   year: 2023,
//   leap_year: false,
//   julian: 2460115
// }
```

--------------------------------

### Convert Solar to Lunar and Lunar to Solar Dates

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Demonstrates converting between SolarDate and LunarDate objects. Remember to call `init()` on LunarDate instances before using them.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

const solar_date = new SolarDate(new Date());
console.log(solar_date);
console.log(solar_date.toLunarDate());

const lunar_date = new LunarDate({ day: 10, month: 5, year: 2023 });
lunar_date.init(); // initialize lunar_date before using
console.log(lunar_date.toSolarDate());

// SolarDate {
//   day: 19,
//   month: 6,
//   year: 2023,
//   name: 'solar_calendar',
//   jd: 2460115,
//   leap_year: false
// }

// LunarDate {
//   day: 2,
//   month: 5,
//   year: 2023,
//   name: 'lunar_calendar',
//   jd: 2460115,
//   leap_year: true,
//   leap_month: false
// }

// SolarDate {
//   day: 27,
//   month: 6,
//   year: 2023,
//   name: 'solar_calendar',
//   jd: 2460123,
//   leap_year: false
// }
```

--------------------------------

### Include Lunar Date VN via CDN

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Include the library using a CDN link, such as jsDelivr, for direct use in HTML files.

```html
<script src="https://cdn.jsdelivr.net/..."></script>
```

--------------------------------

### Instantiate LunarDate

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Create a LunarDate instance with day, month, and year. Call init() to populate secondary properties like leap_year and jd.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 1, month: 1, year: 2023 });
console.log(lunar);
// Output: LunarDate { day: 1, month: 1, year: 2023, name: 'lunar_calendar', jd: undefined, leap_year: undefined, leap_month: undefined }

lunar.init(); // Initialize to populate secondary values
console.log(lunar.get());
// Output: { day: 1, month: 1, year: 2023, leap_year: true, leap_month: false, ... }
```

--------------------------------

### Get LunarDate Information

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Retrieve all details of a LunarDate entity, including its name, day, month, year, leap status, Julian day, year name, and leap month status.

```typescript
const dl = new SolarDate(new Date());
const al = LunarDate.fromSolarDate(dl);
console.log(al.get());
```

--------------------------------

### Get Current Hour Name

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieves the name of the current hour according to the sexagenary cycle. The heavenly stem adjusts based on the day, and the earthly branch changes every 2 hours.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getRealHourName()); // Returns current hour name (depends on hour property)
```

--------------------------------

### Handle Leap Months in LunarDate

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

When creating a LunarDate, specifying leap_month: true for a month that does not have a leap year will result in auto-correction to false. This example demonstrates correct and auto-corrected leap month handling.

```typescript
import { LunarDate } from "lunar-date-vn";

// Month 2 of year 2023 has a leap month
const leapDate = new LunarDate({ day: 1, month: 2, year: 2023, leap_month: true });
leapDate.init();
console.log(leapDate.leap_month); // true

// Month 3 of year 2023 does not have a leap month
const regularDate = new LunarDate({ day: 1, month: 3, year: 2023, leap_month: true });
regularDate.init();
console.log(regularDate.leap_month); // false (auto-corrected)
```

--------------------------------

### Importing SolarDate and LunarDate from Module Path

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

Import SolarDate and LunarDate from the specific module path for potentially smaller bundle sizes.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn/dist/modules/lunar-date";
```

--------------------------------

### Import SolarDate and LunarDate

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Import the necessary classes from the lunar-date-vn library to begin using its functionalities.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";
```

--------------------------------

### Get Solar Term Name

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieves the name of the solar term (tiết khí) for the given date. Solar terms are 24 points in the solar year based on the sun's ecliptic longitude.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getSolarTerm()); // "Mang chủng"
```

--------------------------------

### Create LunarDate instances

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Create LunarDate objects from object literals or SolarDate objects. Remember to call `init()` after creation.

```typescript
// From object
const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });

// IMPORTANT: Always initialize
lunar.init();

// From SolarDate
const lunar2 = LunarDate.fromSolarDate(solar1);
```

--------------------------------

### getDayName()

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Returns the name of the day according to the sexagenary cycle (Can-Chi system). The format is '{Can} {Chi}'.

```APIDOC
## getDayName()

### Description
Returns the name of the day according to the sexagenary cycle (Can-Chi system).

### Method
```typescript
getDayName(): string
```

### Returns
`string` in format "{Can} {Chi}" (e.g., "Mậu Thân") or empty string if `jd` is undefined.

### Example
```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getDayName()); // "Mậu Thân"
```
```

--------------------------------

### Get Lucky Hours for the Day

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/lunar-date.md

Retrieves an array of lucky hours (giờ hoàng đạo) for the current day. Each lucky hour object includes the zodiac animal name and the time range in 24-hour format.

```typescript
import { LunarDate } from "lunar-date-vn";

const lunar = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar.init();
console.log(lunar.getLuckyHours());
// Output: [
//   { name: 'Tý', time: [ 23, 1 ] },
//   { name: 'Sửu', time: [ 1, 3 ] },
//   { name: 'Thìn', time: [ 7, 9 ] },
//   { name: 'Tỵ', time: [ 9, 11 ] },
//   { name: 'Mùi', time: [ 13, 15 ] },
//   { name: 'Tuất', time: [ 19, 21 ] }
// ]
```

--------------------------------

### Update SolarDate with ICalendarDate or Date

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/solar-date.md

Use setDate to update the SolarDate instance with a new date, accepting either an ICalendarDate object or a standard JavaScript Date object. The example demonstrates updating with both types and logging the result.

```typescript
import { SolarDate } from "lunar-date-vn";

const solar = new SolarDate({ day: 19, month: 6, year: 2023 });
solar.setDate({ day: 1, month: 1, year: 2024 });
console.log(solar.get());
// Output: { day: 1, month: 1, year: 2024, ... }

solar.setDate(new Date(2024, 0, 15));
console.log(solar.get());
// Output: { day: 15, month: 1, year: 2024, ... }
```

--------------------------------

### Get Lucky Hours for a Lunar Date

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Retrieves the lucky hours for a given lunar date. This function returns an array of objects, each specifying the name of the hour (zodiac) and its time range. The LunarDate object is derived from the current solar date.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

const dl = new SolarDate(new Date());
const al = LunarDate.fromSolarDate(dl);
console.log(al.getZodiacHour());

// [
//   { name: 'Tý', time: [ 23, 1 ] },
//   { name: 'Sửu', time: [ 1, 3 ] },
//   { name: 'Thìn', time: [ 7, 9 ] },
//   { name: 'Tỵ', time: [ 9, 11 ] },
//   { name: 'Mùi', time: [ 13, 15 ] },
//   { name: 'Tuất', time: [ 19, 21 ] }
// ]
```

--------------------------------

### Initialize LunarDate

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/README.md

Create a LunarDate entity with basic day, month, and year. Missing secondary information like leap year or Julian day will be undefined until initialized.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

const al = new LunarDate({ day: 1, month: 1, year: 2023 });
console.log(al);
```

--------------------------------

### Create SolarDate from ISolarDate Object

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/solar-date.md

Instantiate SolarDate using an object with day, month, and year properties. Ensure the date is within the valid range (1200-1-31 to 2199-12-31) and avoids the non-existent period of 1582-10-05 to 1582-10-14.

```typescript
import { SolarDate } from "lunar-date-vn";

const date = new SolarDate({ day: 19, month: 6, year: 2023 });
console.log(date.get());
// Output: { name: 'solar_calendar', day: 19, month: 6, year: 2023, leap_year: false, julian: 2460115 }
```

--------------------------------

### ICalendarDate

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/types.md

Base interface for calendar date information, serving as the foundation for both ISolarDate and ILunarDate. It includes properties for day, month, year, yearIndex, and hour.

```APIDOC
## ICalendarDate

### Description
Base interface for calendar date information. Used as the foundation for both `ISolarDate` and `ILunarDate`.

### Type Definition
```typescript
export interface ICalendarDate {
  day: number;
  month: number;
  year: number;
  yearIndex: number;
  hour: number;
}
```

### Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| day | number | Yes | Day of month (1-31 for solar, 1-30 for lunar) |
| month | number | Yes | Month number (1-12) |
| year | number | Yes | Year (1200-2199) |
| yearIndex | number | Yes | Year index used for internal calculations |
| hour | number | Yes | Hour in 24-hour format (0-23) |
```

--------------------------------

### Main API Exports

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

Lists the main classes and types exported by the lunar-date-vn library. These are the primary building blocks for using the library's functionalities.

```typescript
export class SolarDate extends Calendar { ... }
export class LunarDate extends Calendar { ... }
export interface ISolarDate extends ICalendarDate { ... }
export interface ILunarDate extends ICalendarDate { ... }
export interface ILuckyHour { ... }
export type CalendarName = 'solar_calendar' | 'lunar_calendar';
```

--------------------------------

### Handling Lunar to Solar Conversion Errors

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/errors.md

Ensure `LunarDate.init()` is called before converting to `SolarDate` and check for null returns to handle potential conversion failures.

```typescript
import { SolarDate, LunarDate } from "lunar-date-vn";

// Lunar to Solar conversion (requires init)
const lunar2 = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar2.init();
const solar2 = lunar2.toSolarDate();
if (solar2 === null) {
  console.error("Failed to convert lunar to solar");
}
```

--------------------------------

### Class Hierarchy

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/api-overview.md

Depicts the class hierarchy of the lunar-date-vn library, showing the inheritance from the abstract Calendar base class to SolarDate and LunarDate.

```text
Calendar (abstract base class)
├── SolarDate (Gregorian calendar)
└── LunarDate (Vietnamese lunar calendar)
```

--------------------------------

### Convert between Solar and Lunar dates

Source: https://github.com/hieu-buiminh/lunar-date-vn/blob/main/_autodocs/quick-reference.md

Easily convert dates between the solar and lunar calendars using the `toLunarDate()` and `toSolarDate()` methods.

```typescript
// Solar to Lunar
const solar = new SolarDate({ day: 19, month: 6, year: 2023 });
const lunar = solar.toLunarDate();

// Lunar to Solar
const lunar2 = new LunarDate({ day: 2, month: 5, year: 2023 });
lunar2.init();
const solar2 = lunar2.toSolarDate();
```