liuyao 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kasukabe tsumugi
+
+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,118 @@
+# liuyao
+
+Metadata and utility classes for Chinese Liu Yao divination. This package provides typed models for yao lines and hexagrams, along with traditional metadata derived from sources such as Zeng Shan Bu Yi.
+
+For more packages, see [my homepage](https://baendlorel.github.io/?repoType=npm).
+
+## Features
+
+- Create a yao from its yang-count representation.
+- Build a hexagram from six yao lines or from a known hexagram name.
+- Inspect hexagram metadata such as its name, palace, phase, and setup information.
+- Derive the changed hexagram for dynamic lines.
+- Access six-god ordering data for different heavenly stems.
+
+## Installation
+
+```bash
+pnpm add liuyao
+```
+
+## Quick Start
+
+```ts
+import { Hexagram, Yao, SixGodList } from 'liuyao';
+
+const hexagram = Hexagram.fromYaos([
+	new Yao(3),
+	new Yao(1),
+	new Yao(2),
+	new Yao(2),
+	new Yao(1),
+	new Yao(0),
+]);
+
+if (!hexagram) {
+	throw new Error('Invalid hexagram');
+}
+
+console.log(hexagram.info.id);
+console.log(hexagram.toDescriptionEn());
+console.log(hexagram.toChanged()?.info.id);
+console.log(SixGodList[0]);
+```
+
+## Core Concepts
+
+### Yao
+
+A yao is one line in a hexagram. The constructor accepts a yang count from `0` to `3`:
+
+- `0`: old yin, dynamic
+- `1`: young yang, static
+- `2`: young yin, static
+- `3`: old yang, dynamic
+
+Example:
+
+```ts
+import { Yao } from 'liuyao';
+
+const yao = new Yao(3);
+
+console.log(yao.name);
+console.log(yao.symbol);
+console.log(yao.isDynamic);
+```
+
+### Hexagram
+
+A hexagram contains six yao lines ordered from bottom to top.
+
+```ts
+import { Hexagram } from 'liuyao';
+
+const qian = Hexagram.fromId('乾为天');
+
+if (qian) {
+	console.log(qian.info.sign);
+	console.log(qian.info.phase);
+	console.log(qian.dynamicInner);
+}
+```
+
+Useful instance members:
+
+- `info`: metadata for the current hexagram
+- `isDynamic`: whether any line is dynamic
+- `isChanged`: whether the current hexagram is already a changed hexagram
+- `toChanged()`: returns the changed hexagram when dynamic lines exist
+- `toDescription()`: Chinese description
+- `toDescriptionEn()`: English description
+
+Useful factory methods:
+
+- `Hexagram.fromYaos(yaos)`
+- `Hexagram.fromYangCounts(counts)`
+- `Hexagram.fromId(id)`
+- `Hexagram.fromPalace(palace)`
+
+## Exported API
+
+The package currently exports:
+
+- `Hexagram`
+- `Yao`
+- `YaoIndex`
+- `SixGodList`
+- type `SixGod`
+- type `SetupGramInfo`
+
+## Notes
+
+- Traditional names and metadata values are kept in Chinese.
+- The package focuses on data modeling and lookup. It does not implement a full divination workflow by itself.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,302 @@
+/**
+ * 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?: '世' | '应';
+}
+
+interface PalaceIndexName {
+    name: string;
+    nameEn: string;
+}
+declare const PalaceIndexList: PalaceIndexName[];
+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 HexagramList: 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 TrigramList: readonly TrigramInfo[];
+
+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 SixGodList: readonly SixGodInfo[];
+
+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;
+}
+
+type LiuYao = [Yao, Yao, Yao, Yao, Yao, Yao];
+declare const YaoIndex: 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 fromBinary(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;
+    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;
+    /**
+     * 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;
+    toDescriptionEn(): string;
+    clone(): Hexagram;
+    toString(): string;
+    [Symbol.toPrimitive](hint: string): string;
+}
+
+export { Hexagram, HexagramList, PalaceIndexList, SixGodList, TrigramList, Yao, YaoIndex };
+export type { HexagramInfo, SetupGramInfo, SixGod, SixGodInfo, TrigramInfo };