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

npm install yarrow-divination

Quick Start

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

IChing Class

Main class that combines divination and interpretation.

Constructor

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.

DayanDivination Class

Pure divination engine implementing the traditional method.

Constructor

new DayanDivination(verbose?: boolean)

Methods

simulate()

Execute calculation without displaying process.

getHexagramResult()

Get calculated hexagram result.

HexagramInterpreter Class

Pure hexagram interpreter using the 64 hexagram database.

Constructor

new HexagramInterpreter(dataPath?: string)

Methods

getHexagramByBinary(binaryStr: string)

getHexagramByNumber(number: number)

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

interpretDivinationResult(divinationResult: HexagramResult)

Data Structures

HexagramResult

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
}

LineValue

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

Examples

Basic Usage

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(', ')}`);

Direct Hexagram Lookup

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); // "乾"

Custom Hexagram Interpretation

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, 周易, 占卜, 卦象