shunshi-kangxi-core

📖 Offline 康熙字典 (Kangxi Dictionary, 1716) engine — Kangxi stroke counts, radicals, Five Elements, pinyin, Bopomofo, glyph structure, modern definitions and verbatim source text for 20794 Chinese characters.

Zero runtime dependencies. No network calls. No API key. The data ships in the package.

Part of kangxi-mcp — see the repo README in English · 简体中文 · 日本語 · 한국어.

Install

npm install shunshi-kangxi-core

Why Kangxi stroke counts

There are three correct stroke counts for a Chinese character and they routinely disagree:

| Character | 简体笔画 | 繁体笔画 | 康熙笔画 | |---|---|---|---| | 万 | 3 | 12 (萬) | 15 | | 与 | 3 | 13 (與) | 14 | | 学 | 8 | 16 (學) | 16 |

Chinese name numerology (五格剖象), seal carving and classical philology all use 康熙笔画, which follows Kangxi radical conventions — 氵 counts as 水 (4), 艹 as 艸 (6), 忄 as 心 (4). You cannot recover it by counting strokes on screen, which is exactly why this table exists.

API

charDetail(char: string): CharDetail | null

Full dictionary entry. Accepts simplified, traditional or variant forms; input is normalised to the head entry where the two agree on stroke count (see the caveat under Data notes), and both forms come back.

import { charDetail } from 'shunshi-kangxi-core';

const d = charDetail('顧');
// {
//   char: '顾', 简体: '顾', 繁体: '顧',
//   康熙笔画: 21, 简体笔画: 10, 繁体笔画: 21,
//   部首: '页', 五行: '木', 拼音: 'gù', 注音: 'ㄍㄨˋ',
//   结构: '左右', 释义: '回头看，泛指看…',
//   康熙原文: '【戌集下】【頁字部】 顧 …',
//   康熙部居: '戌集下', 康熙字部: '頁字部',
// }

Returns null for characters outside the table.

searchChars(filter: SearchFilter): SearchHit[]

Search by stroke count, element, radical and/or reading — the query naming actually needs.

import { searchChars } from 'shunshi-kangxi-core';

searchChars({ strokes: 12, wuxing: '木', limit: 10 });
searchChars({ strokesMin: 8, strokesMax: 12, radical: '水' });
searchChars({ pinyin: 'zhi', commonOnly: false, limit: 100 });

| Field | Type | Default | Meaning | |---|---|---|---| | strokes | number | — | 康熙笔画, exact match | | strokesMin / strokesMax | number | — | 康熙笔画 range, inclusive | | wuxing | '金'\|'木'\|'水'\|'火'\|'土' | — | Five Elements | | radical | string | — | Radical, e.g. '水' | | pinyin | string | — | Tone-insensitive prefix ('zhi' matches zhī/zhí/zhǐ/zhì) | | commonOnly | boolean | true | Restrict to the 6346-character common base set | | limit | number | 50 | Max results |

Results are sorted by stroke count, then Unicode order — stable across calls.

analyzeText(text: string)

Per-character breakdown of a whole string. Unknown characters come back as null rather than being dropped, so a caller knows which character is missing.

totalKangxiStrokes(text: string): number | null

Total 康熙笔画 — the figure 五格 is built on. Returns null if any character is missing from the table, because a partial sum would silently produce a wrong chart.

toBopomofo(pinyin: string | null): string | null

Tone-marked pinyin → 注音符號. Returns null when the syllable cannot be resolved.

stats()

Dataset size: { 总字数: 20794, 常用字数: 6346, 康熙原文条数: 17034 }.

Data notes

• 五行 is missing for ~40% of the table — mostly rare characters where the classical schools disagree. Those return null rather than an invented element, and never match a 五行 filter.
• One-simplified-to-many-traditional pairs stay separate (于/於, 余/餘, 了/瞭, 准/準). They are genuinely different characters that simplification collapsed, and 姓名学 counts them separately.
• Traditional→simplified folding is conditional. A traditional form folds to its simplified head entry only when both sides agree on the Kangxi stroke count — 顧→顾, 學→学, 麗→丽 fold. About 100 pairs disagree and do not fold; that is correct for the genuinely-different pairs above, but leaves a few true equivalents (萬 among them) resolving to their own mirror entry with a different count. Prefer looking characters up by their simplified form.
• 康熙笔画 and 康熙原文 answer different questions. 康熙笔画 is the count 姓名学 needs, taken from the traditional form, so 万 reports 15 (from 萬). 康熙原文 is the Kangxi entry for the glyph you passed in, so 万's entry reads 「康熙筆画：3」, describing 万 as a character in its own right. Both are correct.
• Loading is lazy. The 3 MB Kangxi source text is only read if you ask for it — a caller that just needs stroke counts pays for the 183 KB character table alone.

License

MIT © Shunshi.AI

The 《康熙字典》 (1716) source text is in the public domain.