i-ching-vi

Thư viện tính toán Kinh Dịch (I Ching) tiếng Việt, cung cấp phân tích quẻ tinh vi với cách dùng tên miền Việt Nam chuẩn và hỗ trợ TypeScript đầy đủ.

Phiên bản: 0.0.1
Giấy phép: ISC
Node: >=20

Tính năng

✨ Hệ thống Quẻ hoàn chỉnh

• 64 quẻ với tên tiếng Việt
• Hỗ trợ cả quẻ chính (quẻ gốc) và quẻ biến (quẻ qua động hào)

🔢 Phân tích Lục Hào (6 Hào)

• Xây dựng bảng lục hào hoàn chỉnh với thông tin 6 hào chi tiết
• Tính toán tự động:
  • Địa Chi - 12 vị trí trên thể địa
  • Thiên Can - 10 vị trí trên thể thiên
  • Lục Thần - mối quan hệ giữa các hào
  • Lục Thú - các vị trí động dựa trên thời gian
  • Thế/Ứng - hào thế và hào ứng
  • Tuần Không - các hào không có tác dụng

🎯 Thiết kế hướng miền (Domain-Driven)

• Các hàm tính toán thuần túy, có kết quả xác định
• Các đối tượng miền bất biến
• Giữ nguyên thuật ngữ Kinh Dịch Việt Nam
• Strict TypeScript với type safety đầy đủ

Cài đặt

npm install i-ching-vi

Hoặc dùng yarn:

yarn add i-ching-vi

Bắt đầu nhanh

Tra cứu quẻ cơ bản

import { Que } from "i-ching-vi";

// Lấy quẻ theo tên
const que = Que.fromName("phong lôi ích");
console.log(que.info.name); // "phong lôi ích"

Xây dựng bảng Lục Hào hoàn chỉnh

import { QueLucHao, ThienCan, DiaChi } from "i-ching-vi";

const thoiDiemLapQue = {
  day: {
    thienCan: ThienCan.GIAP, // 甲 - Giáp
    diaChi: DiaChi.THAN, // 申 - Thân
  },
  month: {
    thienCan: ThienCan.CANH, // 庚 - Canh
    diaChi: DiaChi.DAN, // 寅 - Dần
  },
};

// Cách 1: Dùng tên quẻ (khuyến nghị)
const lucHao = QueLucHao.fromQueName(
  thoiDiemLapQue,
  "phong lôi ích",
  [2], // Hào 2 động
);

// Truy cập kết quả
console.log(lucHao.queChinh.info.name); // "phong lôi ích"
console.log(lucHao.queBien.info.name); // "phong trạch trung phu"

// Duyệt qua 6 hào
lucHao.queChinhContext.forEach((hao) => {
  console.log(`Hào ${hao.th}:`);
  console.log(`  Thiên Can: ${hao.mainInfo.thienCan}`);
  console.log(`  Địa Chi: ${hao.mainInfo.diaChi}`);
  console.log(`  Lục Thần: ${hao.mainInfo.lucThan}`);
  console.log(`  Lục Thú: ${hao.lucThu}`);

  if (hao.isThe) console.log("  ▸ Hào thế");
  if (hao.isUng) console.log("  ▸ Hào ứng");
  if (hao.isTK) console.log("  ▸ Tuần không");
  if (hao.isChange) console.log("  ▸ Hào động");
});

Các khái niệm cơ bản

Quẻ (Hexagram - Lục Yao)

Một quẻ Kinh Dịch bao gồm 6 hào, mỗi hào là âm (陰) hoặc dương (陽). Có 64 quẻ khác biệt.

Quẻ Chính vs Quẻ Biến

• Quẻ Chính: Quẻ được rút lên ban đầu
• Quẻ Biến: Kết quả sau khi các hào động qua biến đổi

Bảng Lục Hào

Bảng phân tích hoàn chỉnh hiển thị:

• Địa Chi: Vị trí ánh xạ trong 12 tọa độ trên thể địa
• Thiên Can: Khía cạnh thời gian từ ngày lập quẻ
• Lục Thần: Đặc tính mối quan hệ giữa các hào
• Lục Thú: Ký hiệu động vật dựa trên ngày lập
• Hào Thế: Đại diện cho người hỏi/chủ thể
• Hào Ứng: Đại diện cho sự vật/tương tác
• Tuần Không: Các hào không có tác dụng trong chu kỳ 10 ngày

Hào Động (Hào thay đổi)

Khi một hay nhiều hào được đánh dấu là "động":

• Các hào này qua biến đổi từ âm → dương hoặc dương → âm
• Điều này tạo ra quẻ biến mới
• Mối quan hệ giữa quẻ chính và quẻ biến cung cấp manh mối để diễn dịch

Tham khảo API

QueLucHao

Lớp chính để xây dựng bảng lục hào hoàn chỉnh.

Constructor

// Khuyến nghị: Tạo từ tên quẻ
static fromQueName(
  creationTime: LucHaoDate,
  queChinhName: string,
  dongHao: ChangeLines
): QueLucHao

// Lựa chọn khác: Tạo từ đối tượng Que
static fromCreation(
  creationTime: LucHaoDate,
  queChinh: Que,
  dongHao: ChangeLines
): QueLucHao

Tham số:

• creationTime: Đối tượng với day và month (mỗi cái chứa thienCan và diaChi)
• queChinhName: Tên quẻ tiếng Việt (ví dụ: "phong lôi ích")
• dongHao: Mảng vị trí hào động (1-6, ví dụ: [2] hoặc [2, 5])

Ví dụ:

const lh = QueLucHao.fromQueName(
  {
    day: { thienCan: ThienCan.GIAP, diaChi: DiaChi.THAN },
    month: { thienCan: ThienCan.CANH, diaChi: DiaChi.DAN },
  },
  "phong lôi ích",
  [2],
);

Thuộc tính

readonly queChinh: Que                // Quẻ chính
readonly queBien: Que                 // Quẻ biến
readonly creationTime: LucHaoDate     // Thời gian lập
readonly dongHao: ChangeLines         // Vị trí hào động
readonly queChinhContext: HaoContext[] // Mảng 6 phần tử
readonly queBienContext: HaoContext[]  // Mảng 6 phần tử

HaoContext

Đại diện cho một hào với tất cả thông tin dẫn xuất.

type HaoContext = {
  readonly value: boolean; // true = dương, false = âm
  th: number; // Vị trí 1-6
  mainInfo: {
    thienCan: string; // 10 Thiên Can
    diaChi: string; // 12 Địa Chi
    lucThan: string; // Lục Thần
  };
  lucThu: string; // Lục Thú
  isThe: boolean; // Hào thế?
  isUng: boolean; // Hào ứng?
  isTK: boolean; // Tuần không?
  isChange: boolean; // Hào động?
};

Que (Quẻ)

// Tạo từ tên tiếng Việt
static fromName(name: string): Que

// Truy cập thông tin
que.info.name: string                // "phong lôi ích"
que.lines: Hao[]                     // Mảng 6 phần tử
que.thuongQuai: Quai                 // Quái trên
que.haQuai: Quai                     // Quái dưới
que.originQuai: Quai                 // Họ quái gốc

Trường hợp sử dụng phổ biến

1. Tiên đoán đơn giản

const lucHao = QueLucHao.fromQueName(creationTime, queChinhName, []);

const theHao = lucHao.queChinhContext.find((h) => h.isThe);
const ungHao = lucHao.queChinhContext.find((h) => h.isUng);
console.log(`Hào thế: ${theHao?.th}, Hào ứng: ${ungHao?.th}`);

2. Phân tích hào động

const lucHao = QueLucHao.fromQueName(creationTime, queChinhName, [2, 5]);

const changingLines = lucHao.queChinhContext.filter((h) => h.isChange);
console.log(`Hào động: ${changingLines.map((h) => h.th).join(", ")}`);
console.log(`Quẻ biến: ${lucHao.queBien.info.name}`);

3. Kiểm tra tuần không

const tuanKhong = lucHao.queChinhContext.filter((h) => h.isTK);
console.log(`Vị trí tuần không: ${tuanKhong.map((h) => h.th).join(", ")}`);

4. Xuất dữ liệu bảng

const chartData = {
  queChinh: lucHao.queChinh.info.name,
  queBien: lucHao.queBien.info.name,
  cacHao: lucHao.queChinhContext.map((h) => ({
    viTri: h.th,
    thienCan: h.mainInfo.thienCan,
    diaChi: h.mainInfo.diaChi,
    lucThan: h.mainInfo.lucThan,
    lucThu: h.lucThu,
    laHaoThe: h.isThe,
    laHaoUng: h.isUng,
    laTuanKhong: h.isTK,
    laHaoDong: h.isChange,
  })),
};

Nâng cao

Phân tích quẻ chính vs quẻ biến

lucHao.queChinhContext.forEach((primary, i) => {
  const transformed = lucHao.queBienContext[i];
  const changed = primary.value !== transformed.value;
  console.log(`Hào ${primary.th}: ${changed ? "THAY ĐỔI" : "ổn định"}`);
});

Lọc hào theo đặc tính

// Tất cả hào dương
const yangLines = lucHao.queChinhContext.filter((h) => h.value === true);

// Tất cả hào tuần không
const voidLines = lucHao.queChinhContext.filter((h) => h.isTK);

// Hào thống hiểu
const worldLine = lucHao.queChinhContext.find((h) => h.isThe);

Phát triển

Build

npm run build

Kiểm thử

npm test           # Một lần
npm run test:watch # Theo dõi

Định dạng

npm run lint       # Kiểm tra
npm run format     # Tự động định dạng

Cấu trúc dự án

src/
├── core/
│   ├── base/              # Đối tượng miền
│   └── kinh-dich/
│       ├── base/          # Cấu trúc cơ bản
│       ├── processor/     # Hàm tính toán
│       └── luc-hao/       # Tính năng QueLucHao
└── adapter/
    └── calendar/          # Lịch

Thuật ngữ miền Kinh Dịch

Thư viện này giữ nguyên các thuật ngữ Kinh Dịch Việt Nam xác thực:

| Thuật ngữ | Ý nghĩa | | -------------- | ------------ | | Quẻ Chính | Quẻ ban đầu | | Quẻ Biến | Quẻ biến đổi | | Hào | Đường ngang | | Địa Chi | 12 Địa Chi | | Thiên Can | 10 Thiên Can | | Lục Thần | 6 vị thần | | Lục Thú | 6 con vật | | Hào Thế | Người hỏi | | Hào Ứng | Sự vật | | Tuần Không | Vị trí trống | | Hào Động | Hào thay đổi |

Type Safety

Strict TypeScript với:

• Định nghĩa kiểu đầy đủ
• Xác thực Zod
• Hàm tính thuần
• Đối tượng bất biến

const que: Que = Que.fromName("phong lôi ích");
const chart: QueLucHao = QueLucHao.fromQueName(
  creationTime,
  "phong lôi ích",
  [2],
);

Giấy phép

ISC

Về thư viện

i-ching-vi là thư viện TypeScript hiện đại để phân tích Kinh Dịch với tập trung vào:

• Thuật ngữ Kinh Dịch Việt Nam xác thực
• Độ an toàn kiểu nghiêm ngặt
• Tính toán hàm thuần
• Bộ tính năng quẻ hoàn chỉnh

Để hỏi đáp hoặc đóng góp, vui lòng tham khảo kho dự án.

Xem thêm

• Hướng dẫn Lục Hào
• Tham khảo API