Yarrow Divination

I Ching divination library based on traditional Dayan method (大衍筮法).

Features

✨ Traditional Algorithm - Complete implementation of the classical yarrow stalk divination
- Simulates traditional yarrow stalk division process
- Three changes per line, six lines per hexagram
- Gaussian distribution for human-like errors

📖 Complete Hexagram Database - Built-in data for all 64 hexagrams
- Judgement texts, commentary, and imagery
- Six line texts for each hexagram
- Binary encoding system

🎯 Flexible Usage - Support for various usage modes
- Quiet mode for library integration
- Detailed process display
- Modular design - use only the divination or interpretation parts

Installation

``bash
npm install yarrow-divination
`

Quick Start

`typescript
import { IChing } from 'yarrow-divination';

const iching = new IChing();
const result = await iching.quickDivine();

console.log('Hexagram:', result.interpretation.originalHexagram?.name_cn);
console.log('Binary:', result.result.originalBinary);
console.log('Changing Lines:', result.result.changingLines);
console.log('\nInterpretation:', result.interpretation.originalText);
`

API Reference

$3

Main class that combines divination and interpretation.

#### Constructor

`typescript
new IChing(verbose?: boolean, dataPath?: string)
`

- verbose - Whether to display detailed process (default: false for libraries)
- dataPath - Path to hexagram data JSON file (optional)

#### Methods

##### divine(question?: string)

Perform complete divination with interpretation.

Returns: Promise<{result: HexagramResult, interpretation: InterpretationResult}>

##### quickDivine(question?: string)

Perform quick divination without detailed process.

Returns: Promise<{result: HexagramResult, interpretation: InterpretationResult}>

##### getHexagramByBinary(binary: string)

Get hexagram information by binary string.

##### getHexagramByNumber(number: number)

Get hexagram information by number.

$3

Pure divination engine implementing the traditional method.

#### Constructor

`typescript
new DayanDivination(verbose?: boolean)
`

#### Methods

##### simulate()

Execute calculation without displaying process.

##### getHexagramResult()

Get calculated hexagram result.

$3

Pure hexagram interpreter using the 64 hexagram database.

#### Constructor

`typescript
new HexagramInterpreter(dataPath?: string)
`

#### Methods

##### getHexagramByBinary(binaryStr: string)

##### getHexagramByNumber(number: number)

##### formatHexagramText(hexagram: Hexagram, includeLines?: number[])

##### interpretDivinationResult(divinationResult: HexagramResult)

Data Structures

$3

`typescript
interface HexagramResult {
originalLines: LineValue[]; // Original line values
originalBinary: string; // Original hexagram binary
changedBinary: string; // Changed hexagram binary
changingLines: number[]; // Positions of changing lines
hasChange: boolean; // Whether there are changing lines
}
`

$3

- 6 - 老阴 (Old Yin) - Changes to Yang
- 7 - 少阳 (Young Yang) - Unchanging
- 8 - 少阴 (Young Yin) - Unchanging
- 9 - 老阳 (Old Yang) - Changes to Yin

Examples

$3

`typescript
import { IChing } from 'yarrow-divination';

const iching = new IChing();
const result = await iching.quickDivine("What does the future hold?");

console.log(Original Hexagram: ${result.interpretation.originalHexagram?.name_cn});
console.log(Changing Lines: ${result.result.changingLines.join(', ')});
`

$3

`typescript
import { HexagramInterpreter } from 'yarrow-divination';

const interpreter = new HexagramInterpreter();

// Get hexagram by binary
const hexagram = interpreter.getHexagramByBinary('111111'); // 乾卦
console.log(hexagram.name_cn); // "乾"

// Get hexagram by number
const hexagram2 = interpreter.getHexagramByNumber(1);
console.log(hexagram2?.name_cn); // "乾"
`

$3

`typescript
import { IChing } from 'yarrow-divination';

const iching = new IChing();

// Simulate a custom divination result
const customResult = {
originalBinary: '101010',
changedBinary: '101011',
originalLines: [7, 8, 7, 8, 7, 8],
changingLines: [6],
hasChange: true,
};

const interpretation = (iching as any).interpreter.interpretDivinationResult(customResult);
console.log(interpretation.originalText);
`

Interpretation Rules

| Changing Lines | Interpretation Method |
|---------------|----------------------|
| 0 | Original hexagram judgement |
| 1 | Changing line text |
| 2 | Both changing lines, upper line primary |
| 3 | Both original and changed hexagram |
| 4+ | Changed hexagram as primary |

Project Structure

`
/
├── src/
│ ├── index.ts # Main exports
│ ├── types.ts # TypeScript types
│ ├── iching.ts # Main IChing class
│ ├── dayanDivination.ts # Divination logic
│ ├── hexagramInterpreter.ts # Hexagram interpretation
│ └── examples.ts # Usage examples
├── hexagrams_data.json # 64 hexagram database
├── dist/ # Build output
└── README.md
``

License

MIT

Based on

- Traditional Chinese I Ching (周易) philosophy
- Classical Dayan divination method (大衍筮法)
- Authentic Chinese texts for all 64 hexagrams

Keywords

i-ching, iching, divination, hexagram, chinese-philosophy, dayan, yarrow, 周易, 占卜, 卦象