mumuy/relationship: a Chinese kinship calculator that turns '妈妈的妈妈的哥哥' into 舅外公

The problem: a kinship chain that nobody can name out loud

Chinese kinship terms are compositional in a way English ones are not. 妈妈的妈妈的哥哥 is a perfectly clear chain, and the answer is a single word, 舅外公. Most people can follow the chain but cannot produce the word, especially for relatives they see once a year. The README frames this directly: work and life rhythms have changed, distant relatives see less of each other, and during the New Year trip home people do not know what to call whom. It adds that this is not only a children's problem, since younger adults are often just as confused.

The library is for developers who need that lookup inside something else: a family tree UI, a genealogy form, a chatbot, a calculator app. The README lists several sites and products that use it, including 查询网, 在线查询网, 在线工具, 有道语文达人, and the Xiaomi MIUI calculator, both the system app and a web version. That list is the best available signal of the intended audience: consumer-facing Chinese-language tools, not backend data pipelines.

How the calculation works: one method, four types, a modifier grammar

There is exactly one public computation method, relationship. It accepts either an options object or a natural-language sentence. The options object carries text (the target's kinship expression, terms separated by 的), target (the relative's expression, empty meaning yourself), sex (0 female, 1 male), type, reverse, mode, and optimal.

The type field selects the operation. default computes the title, chain computes a relationship chain, and pair computes a joint term. The README's examples make the difference concrete: relationship({text:'妈妈的妈妈的哥哥'}) returns ['舅外公']; the same call with type:'chain' on 舅公 returns ['爸爸的妈妈的兄弟', '妈妈的妈妈的兄弟', '老公的妈妈的兄弟']; and type:'pair' on 外婆 and 奶奶 returns ['儿女亲家']. Setting reverse:true flips the direction, so 七舅姥爷 with reverse:true and sex:1 returns ['甥外孙'].

Underneath, the data table is keyed by a compact grammar. The README documents the relation chain as f:父, m:母, h:夫, w:妻, s:子, d:女, xb:兄弟, ob:兄, lb:弟, xs:姐妹, os:姐, ls:妹. Modifiers are 1 for male, 0 for female, &o for older, &l for younger, # as a separator, and [a|b] for alternatives. That grammar is what makes setMode possible: you can override individual keys with regional vocabulary, and the README's northern example replaces m,f with ['姥爷'] and m,m with ['姥姥'].

The optimal flag is documented in the options table as computing the shortest relationship between the two people. The README does not explain what counts as shortest, and the algorithm write-up is linked from the wiki rather than included in the readme, so treat that flag as one to verify against your own cases.

Installing relationship.js and computing your first title

The package is published as relationship.js and can be loaded in a browser or in Node. The README gives a script tag pointing at the hosted dist file, which exposes a global named relationship. For a project, install from npm:

npm install relationship.js

Then import it. The package.json declares both a CommonJS entry and an ES module entry, so either form works:

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

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

A first real call is the one from the README. You ask what you should call your mother's mother's older brother:

relationship({text:'妈妈的妈妈的哥哥'});
// => ['舅外公']

The return value is an array, not a string, because a chain can have more than one valid title. If you want the reverse direction, pass reverse and your own sex:

relationship({text:'七舅姥爷',reverse:true,sex:1});
// => ['甥外孙']

Sentence mode is the same method with a string instead of an object. The README accepts phrasings like xxx是xxx的什么人, xxx叫xxx什么, and xxx如何称呼xxx, and gives relationship('舅妈如何称呼外婆？') returning ['婆婆']. If you want to inspect what the library knows, relationship.data exposes the current data table and relationship.dataCount exposes how many entries it holds. Both are properties, not methods. The package.json requires Node 20 or newer.

Where the data table stops being right

The README has a section titled 关于分歧, and it is unusually candid. It states that some titles differ between north and south or between regions, that this causes ambiguity, and that the library does not guarantee agreement with your area's conventions. It then lists the collisions. 大爷 is either 爷爷的哥哥 or 父亲的哥哥(北方). 舅公 is 爸妈的舅舅 or 老公的舅舅. The same pattern repeats for 伯公, 叔公, 姨公, 姨夫, 姑夫, 婶子, and 妗子. Each of those is two different relationships sharing one word, and the library returns the set rather than picking for you.

There is a second, deliberate choice the README flags: some titles follow modern common usage rather than older or regional usage. 媳妇 in ancient times or in the north means a son's wife, but here it means one's own wife, with 儿媳妇 written as 息妇. 太太 in some places means an older woman or a great-grandparent, but here it means one's own wife. These are documented decisions, not bugs, and they mean the output will look wrong to a user from a region that uses the older sense.

A third limitation is structural. The library models kinship, not genealogy. It has no notion of a specific family, no IDs, no dates of birth, no adoption, no step-relations, and no half-siblings. It answers questions about the shape of a chain. If you need to render an actual family tree and resolve titles for real people, you supply the tree and use this library only for the naming step.

Custom modes versus building your own lookup

The obvious alternative is a hand-written lookup table: a map from normalized kinship chains to titles, maintained by whichever team owns the product. That approach is smaller and completely predictable, and for a product that only ever needs a dozen relationships it is the right call. The difference in approach is coverage. The README's chain type outputs multiple readings for a single term, and the pair type produces joint terms like 儿女亲家 that a small hand-written table would rarely include. Building that by hand means enumerating the same collisions the README already lists.

The middle path is setMode. The README shows relationship.setMode('northern', {...}) with a data object that overrides individual keys, and the mode option then selects that named mode at call time. This is the design's best feature for regional products: you keep the library's traversal and replace only the vocabulary that differs. The cost is that you must know the data table's key format well enough to write correct overrides, and the README's example is short. It shows four keys and says to refer to the data table format for the rest. There is no documented validation step, so a malformed key is likely to fail silently by simply never matching.

For non-Chinese kinship systems, neither path applies. The grammar, the modifiers, and the data are built around Chinese titles, and the README presents no other language data.

Maintenance, licence, and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-21. The most recent tagged release listed is v1.2.0 from 2022-03-01, while package.json carries version 1.2.9, so the published package has moved ahead of the last release entry. Read that as: the source is being touched, but the release notes are not the place to learn what changed. If you depend on it, pin a version and read the diff yourself.

The licence is MIT, declared in both the LICENSE file and the package.json license field. That permits commercial use and modification with the copyright notice retained. This is not legal advice; if you redistribute the library inside a product, have your own counsel confirm the notice requirements.

The upgrade surface is small. The package ships only dist, so consumers never see src. The public API is one method plus data, dataCount, and setMode. Breaking changes would most likely land in the data table or in the mode override format, which is exactly the part setMode users are coupled to. Node 20 is the declared floor, and the package.json also declares yarn: please-use-npm, so the build tooling expects npm. Development uses npm install, npm run build, and npm test, with test cases in tests/test.js according to the README.

Editorial conclusion

Adopt mumuy/relationship if you are building a Chinese-language family tree, a form with kinship fields, or a chat assistant that has to answer 舅妈如何称呼外婆. Do not adopt it if you need a legally or genealogically authoritative mapping, or if you need a language other than Chinese, since the data table and the modifiers are built around Chinese titles. Before you commit, open src/ and read how the modifier syntax (&o, &l, #, [a|b]) is applied to your own family shapes, and check the setMode example against the regional vocabulary your users actually type. The README's own section on 分歧 is the honest part: it lists 大爷 as both 爷爷的哥哥 and 父亲的哥哥(北方), and says outright that it does not guarantee consistency with your region's usage.

Frequently asked questions

Official sources

1. License: MIT
2. mumuy/relationship on GitHub
3. Project website
4. README
5. Releases