xiaochengtu 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# xiaochengtu
+
+小成图排盘 TypeScript/JavaScript 库
+
+A TypeScript/JavaScript library for XiaoChengTu (小成图) divination, implementing the traditional Chinese Yi-Jing based prediction method.
+
+## 安装 / Installation
+
+```bash
+# npm
+npm install xiaochengtu
+
+# pnpm
+pnpm add xiaochengtu
+
+# yarn
+yarn add xiaochengtu
+```
+
+## 快速开始 / Quick Start
+
+```typescript
+import { XiaoChengTu, Trigram } from 'xiaochengtu'
+
+// 方式1: 使用卦象直接创建
+const xct = new XiaoChengTu({
+  baseHexagram: { upper: Trigram.Kan, lower: Trigram.Li }, // 水火既济
+  changedHexagram: { upper: Trigram.Dui, lower: Trigram.Gen }, // 泽山咸
+})
+
+// 执行排盘
+const result = xct.divine()
+console.log(result)
+
+// 输出格式化结果
+console.log(xct.toString())
+
+// 方式2: 使用数字起卦
+const xct2 = XiaoChengTu.fromNumbers({
+  baseUpper: 6, // 坎
+  baseLower: 3, // 离
+  changedUpper: 2, // 兑
+  changedLower: 7, // 艮
+})
+
+// 方式3: 随机起卦
+const xct3 = XiaoChengTu.random()
+
+// 方式4: 时间起卦
+const xct4 = XiaoChengTu.fromTime() // 使用当前时间
+const xct5 = XiaoChengTu.fromTime(new Date('2024-01-15T10:30:00')) // 指定时间
+```
+
+## 八卦编号 / Trigram Numbers
+
+使用先天数：
+
+| 数字 | 八卦 | Trigram |
+| ---- | ---- | ------- |
+| 1    | 乾   | Qian    |
+| 2    | 兑   | Dui     |
+| 3    | 离   | Li      |
+| 4    | 震   | Zhen    |
+| 5    | 巽   | Xun     |
+| 6    | 坎   | Kan     |
+| 7    | 艮   | Gen     |
+| 8    | 坤   | Kun     |
+
+## API
+
+### XiaoChengTu 类
+
+主要的排盘类。
+
+#### 构造函数
+
+```typescript
+new XiaoChengTu(input: XiaoChengTuInput)
+```
+
+#### 静态方法
+
+- `XiaoChengTu.fromNumbers(input: NumberDivinationInput)` - 从数字创建
+- `XiaoChengTu.random()` - 随机起卦
+- `XiaoChengTu.fromTime(date?: Date)` - 时间起卦
+
+#### 实例方法
+
+- `divine(): XiaoChengTuResult` - 执行排盘，返回完整结果
+- `getPalaceAnalysis(palace: Palace): PalaceAnalysis | undefined` - 获取指定宫位分析
+- `toString(): string` - 输出格式化的盘面字符串
+
+### 类型定义
+
+#### Trigram (八卦)
+
+```typescript
+enum Trigram {
+  Qian = 'qian', // 乾
+  Dui = 'dui', // 兑
+  Li = 'li', // 离
+  Zhen = 'zhen', // 震
+  Xun = 'xun', // 巽
+  Kan = 'kan', // 坎
+  Gen = 'gen', // 艮
+  Kun = 'kun', // 坤
+}
+```
+
+#### Palace (九宫)
+
+```typescript
+enum Palace {
+  Kan = 1, // 坎宫 - 正北
+  Kun = 2, // 坤宫 - 西南
+  Zhen = 3, // 震宫 - 正东
+  Xun = 4, // 巽宫 - 东南
+  Center = 5, // 中宫 - 中央
+  Qian = 6, // 乾宫 - 西北
+  Dui = 7, // 兑宫 - 正西
+  Gen = 8, // 艮宫 - 东北
+  Li = 9, // 离宫 - 正南
+}
+```
+
+#### FourImages (四象)
+
+```typescript
+enum FourImages {
+  He = 'he', // 阖 - 向心/凝聚
+  Pi = 'pi', // 辟 - 离心/发散
+  Wang = 'wang', // 往 - 外引
+  Lai = 'lai', // 来 - 内引
+}
+```
+
+### 工具函数
+
+```typescript
+// 数字转八卦
+numberToTrigram(num: number): Trigram
+
+// 生成互卦
+generateMutualHexagram(hexagram: Hexagram): Hexagram
+
+// 判断是否为八纯卦
+isPureHexagram(hexagram: Hexagram): boolean
+
+// 判断是否为同位异性卦
+isOppositeHexagram(hexagram: Hexagram): boolean
+
+// 计算中宫
+calculateCenterPalace(baseHexagram: Hexagram, changedHexagram: Hexagram): Trigram
+
+// 计算四象
+calculateFourImages(skyTrigram: Trigram, earthTrigram: Trigram): FourImages
+
+// 计算配对结果
+calculateMatchResult(skyTrigram: Trigram, earthTrigram: Trigram): MatchResult
+
+// 获取八卦中文名
+getTrigramChineseName(trigram: Trigram): string
+
+// 获取宫位中文名
+getPalaceChineseName(palace: Palace): string
+```
+
+## 示例输出
+
+```
+========================================
+小成图排盘结果
+========================================
+本卦: 坎离
+变卦: 兑艮
+本互卦: 离坎
+变互卦: 乾巽
+
+九宫布局:
+----------------------------------------
+| 兑    | 坎    | 坎    |
+| 巽    | 离    | 坤    |
+----------------------------------------
+| 艮    | 乾    | 巽    |
+| 震    | 中    | 兑    |
+----------------------------------------
+| 离    | 离    | 乾    |
+| 艮    | 坎    | 乾    |
+----------------------------------------
+
+各宫分析:
+坎宫（正北）: 天盘离 地盘坎 → 吉 - 内引得配，宜守成
+坤宫（西南）: 天盘坎 地盘坤 → 凶 - 外引失配，奔波徒劳
+...
+```
+
+## 许可证 / License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,412 @@
+/**
+ * 八卦枚举
+ * Bagua (Eight Trigrams) enumeration
+ */
+declare enum Trigram {
+    /** 乾 - Heaven */
+    Qian = "qian",
+    /** 兑 - Lake */
+    Dui = "dui",
+    /** 离 - Fire */
+    Li = "li",
+    /** 震 - Thunder */
+    Zhen = "zhen",
+    /** 巽 - Wind */
+    Xun = "xun",
+    /** 坎 - Water */
+    Kan = "kan",
+    /** 艮 - Mountain */
+    Gen = "gen",
+    /** 坤 - Earth */
+    Kun = "kun"
+}
+/**
+ * 五行枚举
+ * Wu Xing (Five Elements) enumeration
+ */
+declare enum WuXing {
+    /** 金 - Metal */
+    Metal = "metal",
+    /** 木 - Wood */
+    Wood = "wood",
+    /** 水 - Water */
+    Water = "water",
+    /** 火 - Fire */
+    Fire = "fire",
+    /** 土 - Earth */
+    Earth = "earth"
+}
+/**
+ * 阴阳枚举
+ * Yin-Yang enumeration
+ */
+declare enum YinYang {
+    /** 阳 */
+    Yang = "yang",
+    /** 阴 */
+    Yin = "yin"
+}
+/**
+ * 动态属性（升/降）
+ * Dynamic property (Rising/Falling)
+ */
+declare enum DynamicProperty {
+    /** 升 - 外引 (Rising/Outward) */
+    Rising = "rising",
+    /** 降 - 内引 (Falling/Inward) */
+    Falling = "falling"
+}
+/**
+ * 四象类型
+ * Four Images type
+ */
+declare enum FourImages {
+    /** 阖 - 向心/凝聚 */
+    He = "he",
+    /** 辟 - 离心/发散 */
+    Pi = "pi",
+    /** 往 - 外引 */
+    Wang = "wang",
+    /** 来 - 内引 */
+    Lai = "lai"
+}
+/**
+ * 配对结果
+ * Matching result
+ */
+declare enum MatchResult {
+    /** 得配 - 吉 */
+    Match = "match",
+    /** 失配 - 凶 */
+    Mismatch = "mismatch"
+}
+/**
+ * 九宫位置
+ * Nine Palace positions
+ */
+declare enum Palace {
+    /** 坎宫 - 正北 */
+    Kan = 1,
+    /** 坤宫 - 西南 */
+    Kun = 2,
+    /** 震宫 - 正东 */
+    Zhen = 3,
+    /** 巽宫 - 东南 */
+    Xun = 4,
+    /** 中宫 - 中央 */
+    Center = 5,
+    /** 乾宫 - 西北 */
+    Qian = 6,
+    /** 兑宫 - 正西 */
+    Dui = 7,
+    /** 艮宫 - 东北 */
+    Gen = 8,
+    /** 离宫 - 正南 */
+    Li = 9
+}
+/**
+ * 八卦属性
+ * Trigram properties
+ */
+interface TrigramProperties {
+    /** 卦名 */
+    name: string;
+    /** 中文名 */
+    chineseName: string;
+    /** 先天数 */
+    priorHeavenNumber: number;
+    /** 五行 */
+    wuXing: WuXing;
+    /** 阴阳 */
+    yinYang: YinYang;
+    /** 动态属性 */
+    dynamicProperty: DynamicProperty;
+    /** 对应地盘宫位 */
+    palacePosition: Palace;
+}
+/**
+ * 六十四卦（重卦）
+ * Hexagram (64 hexagrams)
+ */
+interface Hexagram {
+    /** 上卦 */
+    upper: Trigram;
+    /** 下卦 */
+    lower: Trigram;
+}
+/**
+ * 九宫盘面
+ * Nine Palace board
+ */
+interface NinePalaceBoard {
+    /** Grid1 - 坎宫 */
+    grid1: Trigram;
+    /** Grid2 - 坤宫 */
+    grid2: Trigram;
+    /** Grid3 - 震宫 */
+    grid3: Trigram;
+    /** Grid4 - 巽宫 */
+    grid4: Trigram;
+    /** Grid5 - 中宫 */
+    grid5: Trigram;
+    /** Grid6 - 乾宫 */
+    grid6: Trigram;
+    /** Grid7 - 兑宫 */
+    grid7: Trigram;
+    /** Grid8 - 艮宫 */
+    grid8: Trigram;
+    /** Grid9 - 离宫 */
+    grid9: Trigram;
+}
+/**
+ * 单宫分析结果
+ * Single palace analysis result
+ */
+interface PalaceAnalysis {
+    /** 宫位 */
+    palace: Palace;
+    /** 天盘卦 */
+    skyTrigram: Trigram;
+    /** 地盘卦 */
+    earthTrigram: Trigram;
+    /** 四象 */
+    fourImage: FourImages;
+    /** 配对结果 */
+    matchResult: MatchResult;
+    /** 综合吉凶描述 */
+    fortune: string;
+}
+/**
+ * 完整排盘结果
+ * Complete divination result
+ */
+interface XiaoChengTuResult {
+    /** 本卦 */
+    baseHexagram: Hexagram;
+    /** 变卦 */
+    changedHexagram: Hexagram;
+    /** 本卦互卦 */
+    baseMutualHexagram: Hexagram;
+    /** 变卦互卦 */
+    changedMutualHexagram: Hexagram;
+    /** 九宫天盘 */
+    board: NinePalaceBoard;
+    /** 各宫分析 */
+    palaceAnalyses: PalaceAnalysis[];
+}
+
+/**
+ * 八卦属性表
+ * Trigram properties lookup table
+ */
+declare const TRIGRAM_PROPERTIES: Record<Trigram, TrigramProperties>;
+/**
+ * 先天数到八卦的映射
+ * Prior Heaven number to Trigram mapping
+ */
+declare const NUMBER_TO_TRIGRAM: Record<number, Trigram>;
+/**
+ * 宫位到地盘八卦的映射
+ * Palace to Earth trigram mapping
+ */
+declare const PALACE_TO_EARTH_TRIGRAM: Record<Palace, Trigram>;
+declare const TRIGRAM_BINARY_CORRECT: Record<Trigram, [number, number, number]>;
+/**
+ * 从二进制转换到八卦
+ * Binary to Trigram conversion
+ */
+declare const BINARY_TO_TRIGRAM: Record<string, Trigram>;
+/**
+ * 同位异性卦列表（用于定中宫判断）
+ * Same position, opposite nature hexagrams
+ */
+declare const OPPOSITE_HEXAGRAMS: Array<{
+    upper: Trigram;
+    lower: Trigram;
+    name: string;
+}>;
+
+/**
+ * 数字取余转换为八卦
+ * Convert number to trigram (with modulo 8)
+ * @param num - 输入数字
+ * @returns 对应的八卦
+ */
+declare function numberToTrigram(num: number): Trigram;
+/**
+ * 生成互卦
+ * Generate mutual hexagram from a hexagram
+ * 互卦：取原卦的 3-5 爻为上卦，2-4 爻为下卦
+ * @param hexagram - 原卦
+ * @returns 互卦
+ */
+declare function generateMutualHexagram(hexagram: Hexagram): Hexagram;
+/**
+ * 判断是否为八纯卦
+ * Check if hexagram is pure (upper = lower)
+ * @param hexagram - 卦象
+ * @returns 是否为八纯卦
+ */
+declare function isPureHexagram(hexagram: Hexagram): boolean;
+/**
+ * 判断是否为同位异性卦
+ * Check if hexagram is an opposite-nature hexagram
+ * @param hexagram - 卦象
+ * @returns 是否为同位异性卦
+ */
+declare function isOppositeHexagram(hexagram: Hexagram): boolean;
+/**
+ * 归藏算法计算中宫
+ * Guicang algorithm for center palace calculation
+ * 同性为阴，异性为阳
+ * @param upper - 上卦
+ * @param lower - 下卦
+ * @returns 归藏结果卦
+ */
+declare function guiCangAlgorithm(upper: Trigram, lower: Trigram): Trigram;
+/**
+ * 计算中宫
+ * Calculate center palace trigram
+ * @param baseHexagram - 本卦
+ * @param changedHexagram - 变卦
+ * @returns 中宫八卦
+ */
+declare function calculateCenterPalace(baseHexagram: Hexagram, changedHexagram: Hexagram): Trigram;
+/**
+ * 装天盘
+ * Build sky palace board
+ * @param baseHexagram - 本卦
+ * @param changedHexagram - 变卦
+ * @param baseMutualHexagram - 本卦互卦
+ * @param changedMutualHexagram - 变卦互卦
+ * @param centerTrigram - 中宫卦
+ * @returns 九宫天盘
+ */
+declare function buildSkyBoard(baseHexagram: Hexagram, changedHexagram: Hexagram, baseMutualHexagram: Hexagram, changedMutualHexagram: Hexagram, centerTrigram: Trigram): NinePalaceBoard;
+/**
+ * 计算四象
+ * Calculate four images
+ * @param skyTrigram - 天盘卦
+ * @param earthTrigram - 地盘卦
+ * @returns 四象类型
+ */
+declare function calculateFourImages(skyTrigram: Trigram, earthTrigram: Trigram): FourImages;
+/**
+ * 计算配对结果
+ * Calculate matching result
+ * @param skyTrigram - 天盘卦
+ * @param earthTrigram - 地盘卦
+ * @returns 配对结果
+ */
+declare function calculateMatchResult(skyTrigram: Trigram, earthTrigram: Trigram): MatchResult;
+/**
+ * 生成吉凶描述
+ * Generate fortune description
+ * @param fourImage - 四象
+ * @param matchResult - 配对结果
+ * @returns 吉凶描述
+ */
+declare function generateFortuneDescription(fourImage: FourImages, matchResult: MatchResult): string;
+/**
+ * 分析单宫
+ * Analyze single palace
+ * @param palace - 宫位
+ * @param skyTrigram - 天盘卦
+ * @returns 宫位分析结果
+ */
+declare function analyzePalace(palace: Palace, skyTrigram: Trigram): PalaceAnalysis;
+/**
+ * 获取八卦的中文名称
+ * Get Chinese name of trigram
+ * @param trigram - 八卦
+ * @returns 中文名称
+ */
+declare function getTrigramChineseName(trigram: Trigram): string;
+/**
+ * 获取宫位的中文名称
+ * Get Chinese name of palace
+ * @param palace - 宫位
+ * @returns 中文名称
+ */
+declare function getPalaceChineseName(palace: Palace): string;
+
+/**
+ * 小成图排盘输入参数
+ */
+interface XiaoChengTuInput {
+    /** 本卦 */
+    baseHexagram: Hexagram;
+    /** 变卦 */
+    changedHexagram: Hexagram;
+}
+/**
+ * 数字起卦输入参数
+ */
+interface NumberDivinationInput {
+    /** 本卦上卦数字 */
+    baseUpper: number;
+    /** 本卦下卦数字 */
+    baseLower: number;
+    /** 变卦上卦数字 */
+    changedUpper: number;
+    /** 变卦下卦数字 */
+    changedLower: number;
+}
+/**
+ * 小成图排盘主类
+ * XiaoChengTu main class
+ */
+declare class XiaoChengTu {
+    private baseHexagram;
+    private changedHexagram;
+    private baseMutualHexagram;
+    private changedMutualHexagram;
+    private centerTrigram;
+    private result;
+    /**
+     * 使用卦象初始化
+     * @param input - 本卦和变卦
+     */
+    constructor(input: XiaoChengTuInput);
+    /**
+     * 从数字创建小成图实例
+     * Create XiaoChengTu instance from numbers
+     * @param input - 数字起卦参数
+     * @returns XiaoChengTu 实例
+     */
+    static fromNumbers(input: NumberDivinationInput): XiaoChengTu;
+    /**
+     * 随机起卦
+     * Generate random divination
+     * @returns XiaoChengTu 实例
+     */
+    static random(): XiaoChengTu;
+    /**
+     * 时间起卦
+     * Generate divination from current time
+     * @param date - 可选，指定时间。默认使用当前时间
+     * @returns XiaoChengTu 实例
+     */
+    static fromTime(date?: Date): XiaoChengTu;
+    /**
+     * 执行排盘
+     * Execute divination and generate result
+     * @returns 排盘结果
+     */
+    divine(): XiaoChengTuResult;
+    /**
+     * 获取指定宫位的分析结果
+     * Get analysis result for specific palace
+     * @param palace - 宫位
+     * @returns 宫位分析结果
+     */
+    getPalaceAnalysis(palace: Palace): PalaceAnalysis | undefined;
+    /**
+     * 输出盘面字符串（用于调试）
+     * Output board as string (for debugging)
+     * @returns 盘面字符串
+     */
+    toString(): string;
+}
+
+export { BINARY_TO_TRIGRAM, DynamicProperty, FourImages, type Hexagram, MatchResult, NUMBER_TO_TRIGRAM, type NinePalaceBoard, type NumberDivinationInput, OPPOSITE_HEXAGRAMS, PALACE_TO_EARTH_TRIGRAM, Palace, type PalaceAnalysis, TRIGRAM_BINARY_CORRECT, TRIGRAM_PROPERTIES, Trigram, type TrigramProperties, WuXing, XiaoChengTu, type XiaoChengTuInput, type XiaoChengTuResult, YinYang, analyzePalace, buildSkyBoard, calculateCenterPalace, calculateFourImages, calculateMatchResult, generateFortuneDescription, generateMutualHexagram, getPalaceChineseName, getTrigramChineseName, guiCangAlgorithm, isOppositeHexagram, isPureHexagram, numberToTrigram };