Chinese Kinship Calculator: Instantly Decode Family Relationship Terms

Imagine walking into a room full of relatives you only see once a year. You freeze. Is that man your paternal grandmother's brother? Or is she your maternal grandfather's sister? The specific title escapes you. This is a common struggle for children and adults alike. The "Chinese Kinship Calculator" is designed to solve this. Simply type in a description of the relationship and get the correct title instantly.

Live demo: passer-by.com/relationship/
Mobile version: passer-by.com/relationship/vue/

Installation

The library is compatible with both web browsers and Node.js environments.

Browser
Include the library using a script tag:
<script src="https://passer-by.com/relationship/dist/relationship.min.js">
This provides access to a global relationship function.

Node.js
Install the package via npm:
npm install relationship.js

CommonJS:
const relationship = require("relationship.js");

ES Module:
import relationship from 'relationship.js';

How to Use

The primary function is relationship. It supports two input formats: an options object or a natural-language string.

Options Mode

relationship(options)

The options object includes the following properties:

var options = {
    text: '',      // The target description, with links separated by '的' (e.g., '妈妈的妈妈的哥哥')
    target: '',     // The person from whose perspective the relationship is calculated (default is self)
    sex: -1,        // Your gender: 0 for female, 1 for male
    type: 'default', // 'default' for the term, 'chain' for the relationship path, 'pair' for mutual terms
    reverse: false, // Set to true to find what they should call you
    mode: 'default',// Regional mode, which can be customized via setMode
    optimal: false  // Finds the shortest possible path between two people
};

Examples:

• What do I call my mother's mother's brother?
  relationship({text: '妈妈的妈妈的哥哥'})
  Returns: ['舅外公']

• How should my "七舅姥爷" address me?
  relationship({text: '七舅姥爷', reverse: true, sex: 1})
  Returns: ['甥外孙']

• What are the possible definitions of "舅公"?
  relationship({text: '舅公', type: 'chain'})
  Returns: ['爸爸的妈妈的兄弟', '妈妈的妈妈的兄弟', '老公的妈妈的兄弟']

• How does a "舅妈" address an "外婆"?
  relationship({text: '外婆', target: '舅妈', sex: 1})
  Returns: ['婆婆']

• What is the relationship between an "外婆" and a "奶奶"?
  relationship({text: '外婆', target: '奶奶', type: 'pair'})
  Returns: ['儿女亲家']

String Mode

relationship(expression)

You can also use natural phrasing such as "xxx是xxx的什么人" (Who is X to Y?) or "xxx叫xxx什么" (What does X call Y?).

Examples:

• relationship('舅妈如何称呼外婆？') → ['婆婆']
• relationship('外婆和奶奶之间是什么关系？') → ['儿女亲家']

Internal Properties and Methods

• Access the current data table: relationship.data
• View the total record count: relationship.dataCount
• Define a custom regional mode: relationship.setMode(mode_name, mode_data)

Example:

relationship.setMode('northern', {
    'm,f': ['姥爷'],
    'm,m': ['姥姥'],
    'm,xb,s&o': ['表哥'],
    'm,xb,s&l': ['表弟'],
});

Development and Contributing

To install development dependencies:
npm install

To build the minified production bundle:
npm run build

To run tests (ensure you add new cases to tests/test.js):
npm test

A Note on Regional Differences

Chinese kinship terms vary significantly between northern and southern regions. This calculator aims for broad accuracy, but it may not reflect every local dialect or custom.

Some terms are inherently ambiguous and may span different generations or contexts:

• 大爷: Can refer to a grandfather's older brother or a father's older brother (common in northern China).
• 舅公: Can refer to a parent's maternal uncle or a husband's maternal uncle.
• 伯公: Can refer to a parent's paternal uncle or a husband's paternal uncle.
• 叔公: Refers to a parent's younger paternal uncle or a husband's paternal uncle.
• 姨公: Refers to a parent's uncle by marriage or a husband's uncle by marriage.
• 姨夫: Can mean an aunt's husband or a wife's sister's husband.
• 姑夫: Can mean a father's sister's husband or a husband's sister's husband.
• 婶子: Usually an uncle's wife, but can also refer to a husband's younger brother's wife.
• 妗子: Refers to a maternal uncle's wife or a wife's brother's wife.

Modern defaults are applied where necessary:

• 媳妇: In this tool, it defaults to "wife." (Note: In some northern dialects or historical contexts, it means "daughter-in-law.")
• 太太: In this tool, it defaults to "wife." (Note: In other contexts, it can refer to an elderly woman or a great-grandparent.)