ThaiBreak for JavaScript & TypeScript

ThaiBreak (thai-break) is a high-performance, dictionary-based Thai word segmentation and typographic line breaking engine for JavaScript and TypeScript (Node.js, Deno, Bun, and modern browsers).

It implements the Unicode Line Breaking Algorithm (UAX #14) and W3C Thai Layout Requirements, making it ideal for web typesetting, PDF generation, terminal text formatting, and NLP applications.

Features

• ⚡ Ultra Fast: ~0.3 ms per sentence in Node.js (~25,000 sentences/sec per core).
• 💾 Compact DAWG Dictionary (v1.1.0): 171 KB binary Directed Acyclic Word Graph (words.dawg), 0.7 ms instant load, < 0.3 MB RAM, and 31.8M lookups/sec with zero external dependencies.
• 🎯 High Accuracy: Viterbi dynamic programming on a Directed Acyclic Graph (DAG) with Bigram transition scoring, achieving high word-boundary F1-score.
• 📐 Unicode UAX #14 Typographic Rules:
  • LB13: Never break before punctuation, closing brackets, or solidus (/).
  • LB23: Keep Latin letters and numbers together (e.g. WP01, ISO29110 never break mid-code).
  • Attached leading vowels (เ, แ, โ, ใ, ไ) to initial consonants.
• 📏 Thai Visual Display Width: Accurately computes visual terminal/column width by treating above/below combining vowels and tone marks as zero-width.
• 🏷️ HTML Safe: Safely inserts soft breaks inside HTML strings while preserving tags, comments, and scripts (<script>, <style>).
• 🛡️ Clean & Open: Public Domain word list (25,804 entries) with word weights counted on the Prachathai-67k news corpus (Apache-2.0), all released under Apache-2.0.

Installation

npm install thai-break

Usage

1. Word Tokenization

import { words, tokenize, join } from 'thai-break';

// Segment into word tokens
const tokens = words('ภาษาไทยเข้าใจง่าย');
console.log(tokens);
// Output: ['ภาษา', 'ไทย', 'เข้าใจ', 'ง่าย']

// Join with delimiter
console.log(join('ภาษาไทยเข้าใจง่าย', '|'));
// Output: ภาษา|ไทย|เข้าใจ|ง่าย

2. Typographic Line Breaking

Inserts Zero-Width Space (\u200B) at valid line-break positions according to Unicode UAX #14:

import { lines } from 'thai-break';

// Plain text (inserts Zero-Width Space \u200B)
const broken = lines('ข้อความภาษาไทยขนาดยาวเพื่อทดสอบการตัดบรรทัด');

// With HTML tag preservation (or pass custom marker like '<wbr>')
const html = '<p>สวัสดี <b>ประเทศไทย</b></p>';
const brokenHtml = lines(html, '<wbr>', true);
console.log(brokenHtml);
// Output: <p>สวัสดี <b>ประเทศ<wbr>ไทย</b></p>

3. Visual Display Width & Text Wrapping

import { displayWidth, wrap } from 'thai-break';

// Thai combining vowels and tone marks do not consume visual column width
console.log(displayWidth('ภาษาไทย')); // 7 columns (8 characters minus 1 upper vowel)

// Soft-wrap text to fit target visual width
const wrapped = wrap('ฉันรักภาษาไทยมากที่สุดในโลก', 12);
console.log(wrapped);

4. Custom Dictionary & Initialization

By default, ThaiBreak loads the bundled 171 KB words.dawg dictionary automatically. You can also customize the dictionary:

import { init } from 'thai-break';
import * as fs from 'fs';

// Option A: Load custom binary DAWG (recommended)
init({ dictBinary: fs.readFileSync('path/to/words.dawg') });

// Option B: Load custom TSV text
// init({ dictTsv: 'คำที่หนึ่ง\t1.0\nคำที่สอง\t1.0' });

API Reference

| Function | Description | | :--- | :--- | | words(text, keepWhitespace?) | Tokenize Thai string into an array of words | | tokenize(text, keepWhitespace?) | Alias of words | | lines(text, marker?, isHtml?) | Insert break markers (default \u200B) adhering to UAX #14 | | wrap(text, width, delimiter?, isHtml?) | Soft-wrap text to maximum visual column width | | displayWidth(text) | Calculate visual column width ignoring combining marks | | join(text, delimiter) | Tokenize and join words with delimiter |

License

Apache-2.0 © Kamthorn Krairaksa