liuyao 0.3.2 → 0.4.0

package/dist/index.d.mts

@@ -0,0 +1,335 @@
+//#region src/core/setup-gram.d.ts
+/**
+ * Kins and their corresponding earthly branches in the Liu Yao divination system, along with the type of relation (世 or 应).
+ * This information is crucial for interpreting the hexagrams and their changing lines in the context of a divination reading.
+ */
+interface SetupGramInfo {
+  /**
+   * There are 5 kins in total.
+   *
+   * - 兄弟 (Brothers): Representing peers, friends, or competitors.
+   * - 妻财 (Wife/Wealth): Representing spouse, wealth, or resources.
+   * - 子孙 (Children/Descendants): Representing offspring, students, or followers.
+   * - 官鬼 (Officials/Ghosts): Representing authority figures, adversaries, or hidden factors.
+   * - 父母 (Parents): Representing parents, mentors, or foundational influences.
+   *
+   * Each kin is associated with one of the twelve earthly branches (地支), which adds another layer of meaning to the hexagram lines.
+   */
+  kin: '兄弟丑土' | '兄弟亥水' | '兄弟午火' | '兄弟卯木' | '兄弟子水' | '兄弟寅木' | '兄弟巳火' | '兄弟戌土' | '兄弟未土' | '兄弟申金' | '兄弟辰土' | '兄弟酉金' | '妻财丑土' | '妻财亥水' | '妻财午火' | '妻财卯木' | '妻财子水' | '妻财寅木' | '妻财巳火' | '妻财戌土' | '妻财未土' | '妻财申金' | '妻财辰土' | '妻财酉金' | '子孙丑土' | '子孙亥水' | '子孙午火' | '子孙卯木' | '子孙子水' | '子孙寅木' | '子孙巳火' | '子孙戌土' | '子孙未土' | '子孙申金' | '子孙辰土' | '子孙酉金' | '官鬼丑土' | '官鬼亥水' | '官鬼午火' | '官鬼卯木' | '官鬼子水' | '官鬼寅木' | '官鬼巳火' | '官鬼戌土' | '官鬼未土' | '官鬼申金' | '官鬼辰土' | '官鬼酉金' | '父母丑土' | '父母亥水' | '父母午火' | '父母卯木' | '父母子水' | '父母寅木' | '父母巳火' | '父母戌土' | '父母未土' | '父母申金' | '父母辰土' | '父母酉金';
+  /**
+   * Host（世）is the augur and Guest（应） is the person or things which to ask about.
+   *
+   * Indexes of Host and Guest satisfies this formula:
+   * ```js
+   * index_guest = (index_host + 3) % 6
+   * ```
+   */
+  hostGuest?: '世' | '应';
+}
+//#endregion
+//#region src/core/common.d.ts
+interface PalaceOrderName {
+  name: string;
+  nameEn: string;
+}
+declare const PalaceOrderTable: PalaceOrderName[];
+interface HexagramInfo {
+  /**
+   * Binary representation of the hexagram, where 0 represents a yin line and 1 represents a yang line. The lines are ordered from the bottom (first line) to the top (sixth line).
+   */
+  binary: `${0 | 1}${0 | 1}${0 | 1}${0 | 1}${0 | 1}${0 | 1}`;
+  /**
+   * Binary to YangCounts.
+   * e.g. `'000000'` 坤为地 -> `[2, 2, 2, 2, 2, 2]`, 2 means Shao Yin.
+   */
+  yangCounts: number[];
+  /**
+   * Name of the hexagram, which includes the names of the upper and lower trigrams.
+   *
+   * For example, "坤为地", "地雷复", "地水师", etc.
+   */
+  id: string;
+  /**
+   * 64 hexagrams correspond to Unicode characters.
+   * For example, "䷁" (U+4DC1) represents the hexagram "坤为地".
+   */
+  sign: string;
+  /**
+   * Five Phases (五行) associated with the hexagram, which can be one of "金" (Metal), "木" (Wood), "水" (Water), "火" (Fire), or "土" (Earth).
+   * It indicates the development and state of things.
+   */
+  phase: '金' | '木' | '水' | '火' | '土';
+  /**
+   * Eight Palaces (八宫) to which the hexagram belongs.
+   * 'Palace' is not a physical palace, but rather a category or family of hexagrams.
+   */
+  palace: '乾' | '兑' | '离' | '震' | '巽' | '坎' | '艮' | '坤';
+  /**
+   * Index of the hexagram within its palace, ranging from 0 to 7. This index helps to identify the specific hexagram within the context of its palace.
+   *
+   * - 本宫卦 Original Palace
+   * - 一世卦 First Generation, 1st yao is changed
+   * - 二世卦 Second Generation, 1st and 2nd yao is changed
+   * - 三世卦 Third Generation, 1st, 2nd and 3rd yao is changed
+   * - 四世卦 Fourth Generation, 1st, 2nd, 3rd and 4th yao is changed
+   * - 五世卦 Fifth Generation, 1st, 2nd, 3rd, 4th and 5th yao is changed
+   * - 游魂卦 Wandering Soul, restores 4th yao of Fifth Generation
+   * - 归魂卦 Returning Soul, restores lower 3 yaos of Fifth Generation
+   */
+  palaceIndex: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+  /**
+   * Setup information of the hexagram. Includes Host-Guest（世应） and Six Kins (六亲) for each of the six lines. This information is crucial for interpreting the hexagrams and their changing lines in the context of a divination reading.
+   *
+   * Host（世）is the augur and Guest（应） is the person or things which to ask about.
+   */
+  setupInfo: [SetupGramInfo, SetupGramInfo, SetupGramInfo, SetupGramInfo, SetupGramInfo, SetupGramInfo];
+}
+declare const HexagramInfoTable: readonly HexagramInfo[];
+interface TrigramInfo {
+  /**
+   * Presents the trigram as a 3-digit binary string. 1 represents a Yang line and 0 represents a Yin line.
+   *
+   * For example, "111" for 乾, "100" for 震, etc.
+   */
+  binary: `${0 | 1}${0 | 1}${0 | 1}`;
+  /**
+   * How many Yang Yaos are in the trigram, such as 0 for 坤, 1 for 震, 2 for 兑, etc.
+   */
+  yangCount: 0 | 1 | 2 | 3;
+  /**
+   * Name of the trigram in Chinese, such as "乾", "坤", "震", etc.
+   */
+  id: string;
+  /**
+   * Name of the trigram in English, such as "Qian", "Kun", "Zhen", etc.
+   */
+  nameEn: string;
+  /**
+   * What the trigram represents in Chinese, such as "天", "地", "水", etc.
+   */
+  represents: string;
+  /**
+   * What the trigram represents in English, such as "heaven", "earth", "water", etc.
+   */
+  representsEn: string;
+  /**
+   * Unicode character representing the trigram, such as "☰" for 乾, "☷" for 坤, etc.
+   */
+  sign: string;
+}
+/**
+ * List of all trigrams in the I Ching, with their binary representation, number of yang lines, name, what they represent, and their corresponding sign.
+ */
+declare const TrigramInfoTable: readonly TrigramInfo[];
+//#endregion
+//#region src/core/six-gods.d.ts
+type SixGod = '玄武' | '白虎' | '螣蛇' | '勾陈' | '朱雀' | '青龙';
+interface SixGodInfo {
+  /**
+   * The Heavenly Stem associated with the Six Gods in this order.
+   * They are '甲乙丙丁戊己庚辛壬癸' in sequence.
+   * Different Heavenly Stems correspond to different orders of Six Gods.
+   */
+  heavenlyStem: string;
+  /**
+   * Six Gods contains '青龙', '朱雀', '勾陈', '螣蛇', '白虎', '玄武'.
+   * Different Heavenly Stems correspond to different orders of Six Gods.
+   *
+   * Six Gods are all auspicious symbols and protectors.
+   * - 青龙: Azure Loong, the God in the East worshipped by the Taoists.
+   * - 朱雀: Vermilion Bird, its body is covered with eternal fire.
+   * - 白虎: White Tiger, as white as snow. If the emperor is not cruel and tyrannical, the White Tiger will appear.
+   * - 玄武：Black Tortoise, a spiritual creature formed by the combination of a tortoise and a snake.
+   * - 螣蛇: Flying Serpent, a limbless divine serpent that can summon clouds and mist and roam within them.
+   * - 勾陈: Gouchen, Also considered as 麒麟 Kylin. It has a body like a musk deer, a tail like that of a dragon, dragon scales, and a single horn.
+   */
+  gods: SixGod[];
+}
+/**
+ * @see 《增删卜易·六神章》
+ */
+declare const SixGodTable: readonly SixGodInfo[];
+//#endregion
+//#region src/classes/yao.d.ts
+declare class Yao {
+  static getName(yangCount: number): "老阴" | "少阳" | "少阴" | "老阳";
+  /**
+   * Support creating a Yao from various types of input:
+   * - A symbol representing the Yao (e.g. '交', '单', '拆', '重')
+   * - A name representing the Yao (e.g. '老阴', '少阳', '少阴', '老阳')
+   * - A digit representing the count of yang (e.g. '0', '1', '2', '3')
+   * - Symbols in ancient books representing a Yao ()
+   * - A field of a TrigramInfo object (e.g. id, binary, nameEn, represents, representsEn, sign)
+   * If the input matches any of these, a corresponding Yao will be created.
+   * Otherwise, null will be returned.
+   */
+  /**
+   * Creating a Yao from symbol.
+   * @param symbol e.g. '×' for 0, '’' for 1, '”' for 2, '○' for 3.
+   */
+  static fromSymbol(symbol: string): Yao | null;
+  /**
+   * Creating a Yao from symbolName.
+   * @param symbolName e.g. '交' for 0, '单' for 1, '拆' for 2, '重' for 3.
+   */
+  static fromSymbolName(symbolName: string): Yao | null;
+  /**
+   * Creating a Yao from name.
+   * @param name e.g. '老阴', '少阳', '少阴', '老阳'.
+   */
+  static fromName(name: string): Yao | null;
+  /**
+   * Create a Yao from a digit string representing the count of yang.
+   */
+  static fromDigitString(digit: string): Yao | null;
+  /**
+   * Create a Yao from any Trigram field value.
+   * @param value `{id: '坤', binary: '000', yangCount: 0}`, so `'坤'`, `'000'` and `0` can all be used.
+   */
+  static fromTrigramField(value: string | number): Yao | null;
+  private _yangCount;
+  /**
+   * How many faces of character of 3 coins in this Yao.
+   * It can only be 0, 1, 2 or 3, which corresponds to 老阴、少阳、少阴、老阳 respectively.
+   * - 0: 老阴 (all three coins are Yin)
+   * - 1: 少阳 (one coin is Yang, two coins are Yin)
+   * - 2: 少阴 (two coins are Yang, one coin is Yin)
+   * - 3: 老阳 (all three coins are Yang)
+   */
+  get yangCount(): 0 | 1 | 2 | 3;
+  /**
+   * Two Polars.
+   * - 0 represents Yin 阴
+   * - 1 represents Yang 阳
+   */
+  get polar(): 0 | 1;
+  /**
+   * If this Yao is dynamic, which means it can change to another Yao. In LiuYao, only 老阴 and 老阳 are dynamic.
+   * - 老阴 (0) can change to 少阳 (1)
+   * - 老阳 (3) can change to 少阴 (2)
+   * - 少阳 (1) and 少阴 (2) cannot change, so they are static.
+   */
+  get isDynamic(): boolean;
+  /**
+   * Whether this Yao has already changed to another Yao. Once a Yao is changed, it cannot change again.
+   */
+  readonly isChanged: boolean;
+  /**
+   * @returns The symbol representing this Yao, which is one of '×', '’', '”', '○'.
+   */
+  get symbol(): string;
+  get symbolName(): string;
+  get name(): "老阴" | "少阳" | "少阴" | "老阳";
+  constructor(yangCount: number, isChanged?: boolean);
+  /**
+   * Change `this.yangCount`
+   */
+  set(yangCount: number): void;
+  clone(): Yao;
+  toChanged(): Yao;
+}
+//#endregion
+//#region src/classes/hexagram.d.ts
+type LiuYao = [Yao, Yao, Yao, Yao, Yao, Yao];
+declare const HexagramYaoOrder: readonly ["初爻", "二爻", "三爻", "四爻", "五爻", "上爻"];
+/**
+ * Hexagram class represents a hexagram, which consists of 6 Yao.
+ * - Each Yao can be either yin or yang, and can be changing or not.
+ * - The hexagram can be constructed from an array of Yao or an array of counts of yang.
+ * - Creates “乾为天” by default.
+ */
+declare class Hexagram {
+  /**
+   * Use tokens like `'012132'` to create a Hexagram, where each digit represents the count of Yang in the corresponding Yao (0 for 老阴, 1 for 少阳, 2 for 少阴, 3 for 老阳). The first digit represents the first Yao (初爻) and the last digit represents the sixth Yao (上爻).
+   */
+  static fromQuaternary(quaternary: string): Hexagram | null;
+  /**
+   * Use tokens like `'单单拆拆重重'` to create a Hexagram.
+   *
+   * Since 交 is 0, 单 is 1, 拆 is 2, and 重 is 3, the above token is equivalent to '112233'.
+   * Which returns '风泽中孚' with its 5th and 6th Yao being dynamic.
+   */
+  static fromSymbolName(symbolNames: string): Hexagram | null;
+  /**
+   * Try to create a Hexagram from an array of counts of Yang. If the input is invalid, null will be returned.
+   */
+  static fromYangCounts(counts: number[]): Hexagram | null;
+  /**
+   * Create a Hexagram from its id, which is the name of the hexagram without the palace name.
+   * @param id "坤为地", "地雷复", "地水师"
+   */
+  static fromId(id: string): Hexagram | null;
+  /**
+   * Find Original Palace Hexagram by the palace name, which is the last character of the hexagram id. For example, '天' for '乾为天', '地' for '坤为地', etc.
+   */
+  static fromPalace(palace: string): Hexagram | null;
+  /**
+   * 6 Yao positions, indexed from bottom to top.
+   * Index from 0 to 5, where 0 is the first Yao (初爻) and 5 is the sixth Yao (上爻).
+   */
+  readonly yaos: LiuYao;
+  /**
+   * HexagramInfo of this hexagram, which can be used to get more information about this hexagram, such as its name, sign, phase, palace, etc.
+   */
+  get info(): HexagramInfo;
+  get palace(): string;
+  /**
+   * Whether the 6 Yaos of this hexagram contain any dynamic Yao.
+   */
+  get isDynamic(): boolean;
+  /**
+   * Whether this hexagram has already changed to another hexagram. Once a hexagram is changed, it cannot change again.
+   */
+  get isChanged(): boolean;
+  /**
+   * Outer trigram of this hexagram, which consists of the last three yao (四爻、五爻、上爻).
+   * @returns A trigram if the outer trigram is dynamic.
+   */
+  get dynamicOuter(): boolean;
+  /**
+   * Inner trigram of this hexagram, which consists of the first three yao (初爻、二爻、三爻).
+   * @returns A trigram if the inner trigram is dynamic.
+   */
+  get dynamicInner(): boolean;
+  /**
+   * Create a Hexagram from an array of Yao with length 6.
+   */
+  constructor(yaos: Yao[]);
+  setYao(index: number, yangCount: number): void;
+  toChanged(): Hexagram | null;
+  /**
+   * Describe this hexagram in a human-readable way, including the original hexagram, the changed hexagram (if any), and the dynamic yao (if any).
+   * - e.g.：“本卦乾为天，变卦坤为地，动爻：初爻、三爻”
+   */
+  toDescription(): string;
+  /**
+   * This output is meant for AI skills.
+   */
+  toAIReadable(): {
+    本卦: HexagramAIReadable;
+    变卦: HexagramAIReadable | '无';
+    世应变化: string;
+  };
+  clone(): Hexagram;
+  toString(): string;
+  [Symbol.toPrimitive](): string;
+}
+interface YaoInfo {
+  爻: string;
+  类型?: '世' | '应';
+  六亲: string;
+}
+interface HexagramAIReadable {
+  初爻: YaoInfo;
+  二爻: YaoInfo;
+  三爻: YaoInfo;
+  四爻: YaoInfo;
+  五爻: YaoInfo;
+  上爻: YaoInfo;
+  卦名: string;
+  宫: string;
+  变爻?: string[];
+}
+//#endregion
+export { Hexagram, type HexagramInfo, HexagramInfoTable, HexagramYaoOrder, PalaceOrderTable as PalaceIndexTable, type SetupGramInfo, type SixGod, type SixGodInfo, SixGodTable, type TrigramInfo, TrigramInfoTable, Yao };
+//# sourceMappingURL=index.d.mts.map