jamomatic

Jamomatic

A library dedicated to working with the Korean alphabet, Hangul.

⚠️ This library is still under development and breaking changes may be many until a v1.0.0 version is released. Use with caution.

🥲 Unfortunately, after many attempts, the package name hangul, despite being squatted on, is not being released by NPM. This project is now named jamomatic.

Installation

npm install jamomatic

Usage

This package comes with many useful functions, and more to come!

• endsWith
• getFinal
• getInitial
• getMedial
• isAspirated
• isCompatibility
• isCompositeConsonant
• isCompositeVowel
• isConsonant
• isConsonantCluster
• isDiphthong
• isDoubleConsonant
• isFinal
• isFortis
• isHangul
• isInitial
• isIotized
• isLenis
• isMedial
• isNonCompatibility
• isSyllable
• isVowel
• join
• split
• startsWith
• toAspirated
• toCompatibility
• toDouble
• toFinal
• toFortis
• toInitial
• toIotized
• toLenis
• toMedial
• toSingle

endsWith 🔝

Checks if the given search string exists at the end of the given operation string.

Signature

function endsWith(
	str: string,
	options?: {
		decouple: boolean
	}
): boolean

Options

Name	Default Value	Description
decouple	true	Decouples the composite letters before performing the search

Example

endsWith("한글", "글") // true
endsWith("한글", "ㅡㄹ") // true
endsWith("한글", "한") // false
endsWith("늙다", "ㄱ다") // true
endsWith("늙다", "ㄱ다", { decouple: false }) // false

getFinal 🔝

Extracts the final letter from the given Hangul syllable block.

Signature

function getFinal(
	str: string,
	options?: {
		compatibility: boolean
	}
): string

Options

Name	Default Value	Description
compatibility	true	Converts the final letter into its compatibility form

Example

getFinal("한") // "ㄴ"
getFinal("한", { compatibility: false }) // "ᆫ"
getFinal("하") // ""

getInitial 🔝

Extracts the initial letter from the given Hangul syllable block.

Signature

function getInitial(
	str: string,
	options?: {
		compatibility: boolean
	}
): string

Options

Name	Default Value	Description
compatibility	true	Converts the initial letter into its compatibility form

Example

getInitial("한") // "ㅎ"
getInitial("한", { compatibility: false }) // "ᄒ"

getMedial 🔝

Extracts the medial letter from the given Hangul syllable block.

Signature

function getMedial(
	str: string,
	options?: {
		compatibility: boolean
	}
): string

Options

Name	Default Value	Description
compatibility	true	Converts the medial letter into its compatibility form

Example

getMedial("한") // "ㅏ"
getMedial("한", { compatibility: false }) // "ᅡ"

isAspirated 🔝

Checks if the given value is an aspirated consonant.

Signature

function isAspirated(value: unknown): boolean

Example

isAspirated("ㅋ") // true
isAspirated("ㄱ") // false

isCompatibility 🔝

Checks if the given value is a compatibility letter.

Signature

function isCompatibility(value: unknown): boolean

Example

isCompatibility("ㄱ") // true
isCompatibility("ᄀ") // false

isCompositeConsonant 🔝

➡️ isConsonantCluster

Checks if the given value is a consonant cluster, a cluster of two consonants as one letter.

Signature

function isCompositeConsonant(value: unknown): boolean

Example

isCompositeConsonant("ㄳ") // true
isCompositeConsonant("ㄱ") // false

isCompositeVowel 🔝

➡️ isDiphthong

Checks if the given value is a diphthong, a cluster of two vowels as one letter.

Signature

function isCompositeVowel(value: unknown): boolean

Example

isCompositeVowel("ㅘ") // true
isCompositeVowel("ㅏ") // false

isConsonant 🔝

Checks if the given value is consonant.

Signature

function isConsonant(value: unknown): boolean

Example

isConsonant("ㄱ") // true
isConsonant("ㅏ") // false

isConsonantCluster 🔝

➡️ isCompositeConsonant

Checks if the given value is a consonant cluster, a cluster of two consonants as one letter.

Signature

function isConsonantCluster(value: unknown): boolean

Example

isConsonantCluster("ㄳ") // true
isConsonantCluster("ㄱ") // false

isDiphthong 🔝

➡️ isCompositeVowel

Checks if the given value is a diphthong, a cluster of two vowels as one letter.

Signature

function isDiphthong(value: unknown): boolean

Example

isDiphthong("ㅘ") // true
isDiphthong("ㅏ") // false

isDoubleConsonant 🔝

Checks if the given value is a double consonant, a cluster of two identical consonants as one letter.

Signature

function isDoubleConsonant(value: unknown): boolean

Example

isDoubleConsonant("ㄲ") // true
isDoubleConsonant("ㄳ") // false

isFinal 🔝

Checks if the given value is a non-compatibility, final consonant.

Signature

function isFinal(value: unknown): boolean

Example

isFinal("ᆨ") // true
isFinal("ㄱ") // false

isFortis 🔝

Checks if the given value is a fortis (tensed) consonant.

Signature

function isFortis(value: unknown): boolean

Example

isFortis("ㄲ") // true
isFortis("ㄱ") // false

isHangul 🔝

Checks if the given value is some sort of Hangul characters, either a loose letter or a syllable block. By default, symbols and numbers are allowed to pass. Use the options.strict boolean to disallow this behavior.

Signature

function isHangul(
	value: unknown,
	options?: {
		strict: boolean
	}
): boolean

Options

Name	Default Value	Description
strict	false	Disallows symbols and numbers from being considered valid Hangul characters

Example

isHangul("안녕하세요!") // true
isHangul("안녕하세요!", { strict: true }) // false

isInitial 🔝

Checks if the given value is a non-compatibility, initial consonant.

Signature

function isInitial(value: unknown): boolean

Example

isInitial("ᄀ") // true
isInitial("ㄱ") // false

isIotized 🔝

Checks if the given value is an iotized vowel, one that begins with the /j/ phoneme.

Signature

function isIotized(value: unknown): boolean

Example

isIotized("ㅑ") // true
isIotized("ㅏ") // false

isLenis 🔝

Checks if the given value is a lenis (soft) consonant.

Signature

function isLenis(value: unknown): boolean

Example

isLenis("ㄱ") // true
isLenis("ㄲ") // false

isMedial 🔝

Checks if the given value is a non-compatibility, medial vowel.

Signature

function isMedial(value: unknown): boolean

Example

isMedial("ᅡ") // true
isMedial("ㅏ") // false

isNonCompatibility 🔝

Checks if the given value is a non-compatibility letter.

Signature

function isNonCompatibility(value: unknown): boolean

Example

isNonCompatibility("ᅡ") // true
isNonCompatibility("ㅏ") // false

isSyllable 🔝

Checks if the given value is a Hangul syllable block.

Signature

function isSyllable(value: unknown): boolean

Example

isSyllable("한") // true
isSyllable("ㅎ") // false

isVowel 🔝

Checks if the given value is a vowel.

Signature

function isVowel

Example

isVowel("ㅏ") // true
isVowel("ㄱ") // false

join 🔝

Joins the given string in a way that would resemble dubeolsik (두벌식) typing. Converts all non-compatibility letters to compatibility letters during this process.

options.split is an important consideration as it could drastically change the output. When true, this function will deconstruct all valid syllable blocks, then evaluate each individual letter as if they were typed separately. When false, however, each syllable block will be parsed as-is. See the examples for an illustration of what this actually looks like.

Signature

function join(
	str: string,
	options?: {
		split: boolean
	}
): string

Options

Name	Default Value	Description
split	true	Splits the string before parsing

Example

join("ㅎㅏㄴ") // 한
join("ㄱ가") // 까
join("ㄱ가", { split: false }) // ㄱ가

split 🔝

Splits the given string, deconstructing all of the hangul syllables into their constituent letters.

Signature

function split(
	str: string,
	options?: {
		group: boolean
		decouple: boolean
		compatibility: boolean
	}
): string[] | string[][]

Options

Name	Default Value	Description
group	false	Groups each syllable/grapheme into its own array
decouple	false	Decomposes composite letters into their constituent letters
compatibility	true	Converts all letters from non-compatibility letters to compatibility letters

Example

split("하다") // ["ㅎ", "ㅏ", "ㄷ", "ㅏ"]
split("했다") // ["ㅎ", "ㅐ", "ㅆ", "ㄷ", "ㅏ"]
split("했다", { decouple: true, compatibility: false }) // ["ᄒ", "ᅢ", "ᆺ", "ᆺ", "ᄃ", "ᅡ"]

startsWith 🔝

Checks if the given search string exists at the beginning of the given operation string.

Signature

function startsWith(
	str: string,
	options?: {
		decouple: boolean
	}
): boolean

Options

Name	Default Value	Description
decouple	true	Decouples the composite letters before performing the search

Example

startsWith("한글", "한") // true
startsWith("한글", "ㅎㅏ") // true
startsWith("한글", "글") // false
startsWith("늙다", "늘") // true
startsWith("늙다", "늘", { decouple: false }) // false

toAspirated 🔝

Converts all consonants into their aspirated form.

Signature

function toAspirated(str: string): string

Example

toAspirated("ㄱ") // "ㅋ"
toAspirated("ㄲ") // "ㅋ"
toAspirated("한국") // "한쿸"

toCompatibility 🔝

Converts all letters into their compatibility form.

Signature

function toCompatibility(str: string): string

Example

toCompatibility("ᆨ") // "ㄱ"
toCompatibility("ᆩ") // "ㄲ"

toDouble 🔝

Converts all consonants into their double consonant form.

Signature

function toDouble(str: string): string

Example

toDouble("ㄱ") // "ㄱ"
toDouble("ㄲ") // "ㄱ"
toDouble("가") // "까"

toFinal 🔝

Converts all consonants into their final form.

Signature

function toFinal(str: string): string

Example

toFinal("ㄱ") // "ᆨ"
toFinal("ㄲ") // "ᆩ"

toFortis 🔝

Converts all consonants into their fortis (tensed) form.

Signature

function toFortis(str: string): string

Example

toFortis("ㄱ") // "ㄲ"
toFortis("ㄲ") // "ㄲ"
toFortis("한국") // "한꾺"

toInitial 🔝

Converts all consonants into their initial form.

Signature

function toInitial(str: string): string

Example

toInitial("ㄱ") // "ᄀ"
toInitial("ㄲ") // "ᄁ"

toIotized 🔝

Converts all vowels that can be iotized within the given string.

Signature

function toIotized(str: string): string

Example

toIotized("ㅏ") // "ㅑ"
toIotized("한국") // "햔귝"

toLenis 🔝

Converts all consonants into their lenis (soft) form.

Signature

function toLenis(str: string): string

Example

toLenis("ㄱ") // "ㅋ"
toLenis("ㄲ") // "ㅋ"
toLenis("한국") // "한쿸"

toMedial 🔝

Converts all vowels into their medial form.

Signature

function toMedial(str: string): string

Example

toMedial("ㅏ") // "ᅡ"
toMedial("ㅔ") // "ᅦ"

toSingle 🔝

Converts all consonants into their single consonant form.

Signature

function toSingle(str: string): string

Example

toSingle("ㄱ") // "ㄱ"
toSingle("ㄲ") // "ㄱ"
toSingle("까") // "가"

©️ 2024 Jacob Lockett