@readable-code/korean

Korean-like Hangul word generator for readable-code share codes.

Generates pronounceable, natural-reading Hangul pseudo-words — not dictionary words, not secret tokens. Built on es-hangul.

Install

npm install @readable-code/korean

Usage

import { hangul } from "@readable-code/korean";

hangul(3).dash().digits(4).build();
// "가노미-4821"

hangul(3).dash().hangul(4).dash().digits(4).build();
// "가노미-라보수혼-7520"

build() is the finalizer. It joins the chained fragments and returns the code string.

How words are generated

Each syllable is composed from constrained jamo lists:

initial + medial + optional final

The lists deliberately avoid the full Hangul space. Random complete Hangul reads as noise (쟁헹웅항), so jamo are constrained and weighted by how they read:

• Initial consonant (choseong) — common consonants weighted up; ㅊㅋㅌㅍ kept rare.
• Medial vowel (jungseong) — clear open vowels weighted up.
• Final consonant (jongseong) — mostly open syllables; only soft finals ㄴ ㄹ ㅁ ㅇ, never two finals in a row.

A final consonant (batchim) is never placed two syllables in a row, and the onset after one is constrained to avoid consonant assimilation across the boundary (for example 신라 → 실라), so the written form matches how it is read.

API

hangul(length, options?)

Primary fluent API. Returns a builder with one Hangul pseudo-word already added, so you can keep chaining.

hangul(3).build();                  // "가노미"
hangul(3).dash().hangul(4).build(); // "가노미-라보수혼"
hangul(3, { finalConsonants: false }).dash().digits(4).build();

Builder methods: hangul(length), dash(), digits(length) / nums(length), add(value), build(), toString().

koWord(length, options?) => string

Lower-level helper that generates one Hangul pseudo-word and returns it as a plain string — no builder, no chaining, no separators or digits attached. Where hangul() starts a fluent chain, koWord() is the raw primitive underneath it: hangul(n) is essentially code().add(koWord(n)).

Reach for koWord() when you want the bare word to drop into your own composition — a custom template, an existing string, a non-CodeBuilder pipeline, or when you only need the word itself with no suffix.

import { koWord } from "@readable-code/korean";

koWord(3);                             // "가노미"
koWord(3, { finalConsonants: false }); // open syllables only, no final consonant
koWord(0);                             // "" — length 0 yields an empty string

The phonotactic smoothing (no two final consonants in a row, assimilation-safe onsets) is applied per word, so each koWord() call returns a self-consistent, readable string. Compose it manually via the core builder, or with plain string ops:

import { code } from "@readable-code/core";
import { koWord } from "@readable-code/korean";

// Equivalent to hangul(3).dash().digits(4)
code().add(koWord(3)).dash().digits(4).build();

// Or your own format, no builder at all:
`order-${koWord(3)}`;                  // "order-가노미"

Parameters

• length (number, required) — number of Hangul syllables. Must be a non-negative integer; throws RangeError otherwise.

Options

• finalConsonants?: boolean — whether final consonants (batchim) may appear. Defaults to true. Set false for open syllables only (every syllable ends in a vowel).
• random?: RandomSource — custom random source from @readable-code/core for deterministic output (see below). Defaults to secureRandom (crypto.getRandomValues).

Deterministic output

Pass a custom RandomSource from @readable-code/core for reproducible tests:

import { type RandomSource } from "@readable-code/core";
import { hangul } from "@readable-code/korean";

const random: RandomSource = () => 0;
hangul(3, { random }).dash().digits(4).build();

Concept

Readable public share codes, not secret tokens. Keep uniqueness separate from the readable part — store codes under a database UNIQUE constraint and retry on collision.

License

MIT