hangul.dev

The Architecture of Korean Script

Hangul is not merely a writing system -- it is a feat of deliberate linguistic engineering. Designed in 1443 by King Sejong the Great and his scholars of the Jiphyeonjeon, each character maps precisely from mouth shape to visual form. Every stroke has purpose. Every block is a modular composition.

hangul.dev is a collection of tools and libraries for working with Hangul programmatically: decomposition, composition, romanization, phonetic analysis, and search indexing for the Korean script.

Modular by Design

Unlike alphabets where letters sit side by side in a line, Hangul organizes its letters -- called jamo -- into syllable blocks. Each block is a square composition of two or three jamo stacked and arranged according to precise rules.

An initial consonant (choseong) occupies the top or top-left. A vowel (jungseong) takes the right side or bottom-center. An optional final consonant (jongseong) anchors the bottom. This is not decoration -- it is information architecture at the glyph level.

Core API

The library exposes a minimal, composable interface for Hangul processing. Every function is pure -- no side effects, no mutable state. Pass Unicode in, get structured data out.

import { decompose, compose, isHangul } from 'hangul.dev'

// Decompose a syllable into jamo
decompose('한')
// → { choseong: 'ㅎ', jungseong: 'ㅏ', jongseong: 'ㄴ' }

// Compose jamo into a syllable
compose('ㅎ', 'ㅏ', 'ㄴ')
// → '한'

// Check if a character is Hangul
isHangul('한')  // → true
isHangul('A')   // → false

Romanization

Convert Hangul to Latin script using the Revised Romanization system (the official standard of the Republic of Korea) or McCune-Reischauer for academic contexts. Both systems are implemented with full phonological rule handling -- assimilation, palatalization, and tensification.

import { romanize } from 'hangul.dev/romanize'

romanize('한글')
// → 'hangeul'

romanize('독립문', { system: 'mcr' })
// → 'Tongnimmun'

romanize('같이', { phonetic: true })
// → 'gachi'

Search Indexing

Hangul's consonant-cluster search (chosung search) is a unique feature of Korean input methods. Users type only the initial consonants and expect matching results. hangul.dev provides first-class support for building search indices that understand this pattern.

import { chosungSearch } from 'hangul.dev/search'

const items = ['한글', '항공', '학교', '하늘']

chosungSearch('ㅎㄱ', items)
// → ['한글', '항공', '학교']

chosungSearch('ㅎㄴ', items)
// → ['하늘']

Phonetic Analysis

Korean phonology involves complex interactions between adjacent syllables. The library models these transformations faithfully: consonant assimilation at syllable boundaries, vowel harmony in verb conjugation, and the tensification rules that make Korean pronunciation systematic yet surprising.

import { phonetic } from 'hangul.dev/phonetic'

phonetic.analyze('독립')
// → { surface: '독립', pronounced: '동닙', rules: ['nasalization'] }

phonetic.analyze('같이')
// → { surface: '같이', pronounced: '가치', rules: ['palatalization'] }

The Philosophy

The Hunminjeongeum Haerye (1446) describes the design principles behind Hangul: consonants mirror the shape of the speech organs that produce them. ㄱ (giyeok) depicts the tongue touching the velum. ㄴ (nieun) shows the tongue touching the alveolar ridge. ㅁ (mieum) is the shape of closed lips.

Vowels encode a cosmological system: the dot (now a short stroke) represents the sun, the vertical line represents a standing human, and the horizontal line represents the flat earth. From these three elements -- heaven, human, earth -- all Korean vowels are constructed.

ㄱ ㄴ ㅁ ㅅ ㅇ

Get Started

npm install hangul.dev

Zero dependencies. Tree-shakeable ESM. Full TypeScript types. Works in Node.js, Deno, Bun, and all modern browsers.

Documentation, source code, and issue tracker on GitHub. Published under the MIT license.