@jeongpd/korean-kinship 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tiger-dreams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# korean-kinship
+
+**Resolve any Korean family-relationship path to its correct kinship term, reverse
+term, and 촌수 (degree of kinship) — including in-laws and 사돈.**
+
+[![npm version](https://img.shields.io/npm/v/@jeongpd/korean-kinship.svg)](https://www.npmjs.com/package/@jeongpd/korean-kinship)
+[![license](https://img.shields.io/npm/l/@jeongpd/korean-kinship.svg)](https://github.com/tiger-dreams/korean-kinship/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@jeongpd/korean-kinship.svg)](https://www.npmjs.com/package/@jeongpd/korean-kinship)
+
+Korean kinship terms depend on blood vs. marriage (혈족/인척), 친가/외가/처가/시가
+side, birth order, and generation — genuinely easy to get wrong, and there was no
+open-source library that solved this for Korean (the closest equivalent,
+[`mumuy/relationship`](https://github.com/mumuy/relationship), solves it for Chinese
+kinship and has 3,700+ stars).
+
+## Install
+
+```bash
+npm install @jeongpd/korean-kinship
+```
+
+## Usage
+
+```js
+import { resolve } from '@jeongpd/korean-kinship';
+
+resolve(['father', 'olderBro', 'spouse']);
+// → {
+//     path: ['father', 'olderBro', 'spouse'],
+//     label: '큰어머니',
+//     reverseLabel: '조카',
+//     chon: 3,
+//     formal: '백모',
+//     note: '큰아버지의 아내',
+//     relationClass: 'inlaw',
+//     source: 'golden'
+//   }
+
+resolve(['spouse'], { selfGender: 'F' });
+// → {
+//     path: ['spouse'],
+//     label: '남편',
+//     reverseLabel: '아내',
+//     chon: 0,
+//     formal: '부군',
+//     note: '인척',
+//     relationClass: 'inlaw',
+//     source: 'golden'
+//   }
+```
+
+A relation path is an ordered array built from these 9 base relations:
+
+`father`, `mother`, `olderBro`, `olderSis`, `youngerBro`, `youngerSis`, `son`,
+`daughter`, `spouse`
+
+Chain them to describe any relative — `['mother', 'olderSis', 'spouse']` is "어머니의
+언니의 남편" (이모부). `resolve()` returns:
+
+| field | meaning |
+|---|---|
+| `path` | the input path echoed back |
+| `label` | the kinship term |
+| `reverseLabel` | what that relative would call you back (when known) |
+| `chon` | 촌수 — degree of kinship |
+| `relationClass` | `'blood'` or `'inlaw'` — any spouse hop in the path makes it `'inlaw'` |
+| `formal` | a more formal/written variant of the term, where one exists |
+| `note` | a short usage note (present on golden-table entries, omitted elsewhere) |
+| `source` | `'golden'` (exact match against 145 validated real-usage entries), `'fallback-table'`, or `'generic'` (computed pattern for anything past common terminology) |
+
+`opts.selfGender` (`'M'` or `'F'`) disambiguates terms that depend on the speaker's own
+gender — e.g. your spouse is 아내 if you're male, 남편 if you're female.
+
+## Other exports
+
+Alongside `resolve`, the package exports the underlying data so you can drive your own
+UI off it directly rather than through the function.
+
+### `relationIds`
+
+The array of the 9 valid relation ids, in a sensible display order — everything
+`resolve()` will accept in a path. Useful for building a relation picker; this is
+exactly what the bundled demo does:
+
+```js
+import { relationIds } from '@jeongpd/korean-kinship';
+
+relationIds;
+// → ['father', 'mother', 'olderBro', 'olderSis', 'youngerBro', 'youngerSis',
+//    'son', 'daughter', 'spouse']
+
+for (const id of relationIds) {
+  const option = document.createElement('option');
+  option.value = id;
+  option.textContent = LABELS[id]; // your own Korean display labels
+  picker.appendChild(option);
+}
+```
+
+See [`demo/demo.js`](./demo/demo.js) for the full version.
+
+### `termTable`
+
+The raw 145-entry golden table, keyed by dot-joined relation path, with each entry's
+original fields intact (`M`, `F`, `rev_M`, `rev_F`, `formal`/`formal_M`/`formal_F`,
+`chon`, `note`). Handy for inspecting the data, generating your own lookup structures,
+or rendering a browsable table of every known relationship:
+
+```js
+import { termTable } from '@jeongpd/korean-kinship';
+
+termTable['father.olderBro.spouse'];
+// → { M: '큰어머니', F: '큰어머니', rev_M: '조카', rev_F: '조카',
+//     formal: '백모', chon: 3, note: '큰아버지의 아내' }
+
+Object.keys(termTable).length; // → 145
+```
+
+It's plain data with no behavior attached — treat it as read-only.
+
+## Where this data comes from
+
+The core ~145 relationship entries aren't guessed — they're ported from a real, live
+Korean family-tree app, validated against actual usage. See
+[`docs/DATA_PROVENANCE.md`](./docs/DATA_PROVENANCE.md) for details, or
+`scripts/import-golden-terms.mjs` for the exact extraction method.
+
+## Why not just a lookup table?
+
+For the ~145 most common relationships, it is exactly a lookup table — that's Tier 1,
+and it's returned verbatim because it encodes real, occasionally non-obvious Korean
+usage conventions (for example: your sibling's spouse and your spouse's parents are
+conventionally given `chon: 0`, "just family," while your uncle's wife keeps your
+uncle's own `chon: 3` — these aren't derivable from one clean formula). For anything
+past that table, `resolve()` falls back to a compositional algorithm that computes
+촌수 and blood/in-law class from the path directly, so arbitrarily deep or unusual
+relationship chains still get a sensible answer instead of an error.
+
+## License
+
+MIT © [tiger-dreams](https://github.com/tiger-dreams) — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@jeongpd/korean-kinship",
+  "version": "0.1.0",
+  "description": "Resolve any Korean family-relationship path to its correct kinship term, reverse term, and 촌수 (degree of kinship) — including in-laws and 사돈.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "korean",
+    "kinship",
+    "family-tree",
+    "chon",
+    "촌수",
+    "genealogy"
+  ],
+  "author": "tiger-dreams",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tiger-dreams/korean-kinship.git"
+  },
+  "homepage": "https://github.com/tiger-dreams/korean-kinship#readme",
+  "bugs": {
+    "url": "https://github.com/tiger-dreams/korean-kinship/issues"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/data/fallback-terms.js

@@ -0,0 +1,66 @@
+// Tier-2 supplementary term table. Starts empty on purpose (YAGNI) — every entry in
+// the ported golden table (src/data/golden-terms.js) already covers common usage
+// including most in-law/사돈 vocabulary. Add an entry here only when you have a real,
+// justifiable standard term for a specific canonical descriptor (see resolve.js for
+// the descriptor key format); otherwise let genericFallback() handle it.
+export const FALLBACK_TERMS = {};
+
+// Base terms by generation distance. Korean does not use one word for "any ancestor"
+// and another for "any descendant" — the term changes with how many generations away
+// the relative is — so the base term is picked from |generationDelta|, not its sign.
+// The `X` column is the gender-unknown form, only reachable when a path is nothing but
+// spouse hops (there is no gendered person to anchor on).
+const SAME_GENERATION = { M: '형제', F: '자매', X: '형제자매' };
+
+const ASCENDING = [
+  null, // |delta| 0 is handled by SAME_GENERATION
+  { M: '아저씨', F: '아주머니', X: '어른' },
+  { M: '할아버지', F: '할머니', X: '조부모' },
+  { M: '증조할아버지', F: '증조할머니', X: '증조부모' },
+  { M: '고조할아버지', F: '고조할머니', X: '고조부모' },
+];
+
+const DESCENDING = [
+  null, // |delta| 0 is handled by SAME_GENERATION
+  { M: '조카', F: '조카딸', X: '조카' },
+  { M: '손자', F: '손녀', X: '손주' },
+  { M: '증손자', F: '증손녀', X: '증손' },
+  { M: '고손자', F: '고손녀', X: '고손' },
+];
+
+// Past 고조/고손 (4 generations) Korean switches to the counted forms 'N대조부/N대조모'
+// and 'N대손', which is exactly what genealogical usage does for distant ancestors and
+// descendants.
+function distantAncestor(n, key) {
+  if (key === 'F') return `${n}대조모`;
+  if (key === 'M') return `${n}대조부`;
+  return `${n}대조`;
+}
+
+function baseTerm(generationDelta, terminalGender) {
+  const key = terminalGender ?? 'X';
+  const n = Math.abs(generationDelta);
+
+  if (n === 0) return SAME_GENERATION[key];
+  if (generationDelta > 0) {
+    return n <= 4 ? ASCENDING[n][key] : distantAncestor(n, key);
+  }
+  return n <= 4 ? DESCENDING[n][key] : `${n}대손`;
+}
+
+/**
+ * Last-resort label for a path with no Tier-1 or Tier-2 entry.
+ *
+ * `chon: 0` means "close family, no numeral" in this codebase's convention (the golden
+ * entries with chon 0 — 장인어른, 며느리, 동서 — never carry a number), so the numeral
+ * is omitted entirely rather than rendered as a nonsensical "0촌".
+ */
+export function genericFallback({ chon, generationDelta, relationClass, terminalGender }) {
+  const base = baseTerm(generationDelta, terminalGender);
+  const numeral = chon > 0 ? `${chon}촌 ` : '';
+
+  if (relationClass === 'inlaw') {
+    return chon > 0 ? `인척 ${numeral}${base}` : `가까운 인척 ${base}`;
+  }
+  return `${numeral}${base}`;
+}