Grapheme Cluster Break (JavaScript/WebAssembly)

A high-performance JavaScript library (powered by WebAssembly) for segmenting Unicode strings into grapheme clusters (user-perceived characters) according to UAX #29: Unicode Text Segmentation.

Installation

npm install grapheme-cluster-break

Usage

ES Modules

import { segmentGraphemeClusters } from "grapheme-cluster-break";

// Basic usage
const clusters = segmentGraphemeClusters("Hello");
console.log(clusters);  // ['H', 'e', 'l', 'l', 'o']

// Emoji ZWJ sequences
const family = segmentGraphemeClusters("👨‍👩‍👧‍👦");
console.log(family);  // ['👨‍👩‍👧‍👦']

// Combining characters
const accent = segmentGraphemeClusters("é");  // e + combining acute
console.log(accent);  // ['é']

// Regional indicators (flags)
const flags = segmentGraphemeClusters("🇨🇳🇺🇸");
console.log(flags);  // ['🇨🇳', '🇺🇸']

// Indic conjuncts
const indic = segmentGraphemeClusters("क्ष");
console.log(indic);  // ['क्ष']

// CJK characters
const cjk = segmentGraphemeClusters("你好世界");
console.log(cjk);  // ['你', '好', '世', '界']

// Hangul
const hangul = segmentGraphemeClusters("한글");
console.log(hangul);  // ['한', '글']

TypeScript

Full TypeScript support with type definitions included:

import { segmentGraphemeClusters } from "grapheme-cluster-break";

const clusters: string[] = segmentGraphemeClusters("👨‍👩‍👧‍👦");

API Reference

init(): Promise<void>

Initializes the WebAssembly module. Must be called once before using segmentGraphemeClusters.

segmentGraphemeClusters(s: string, extended?: boolean): string[]

Segments a string into grapheme clusters.

Parameters:

• s - The input string to segment.
• extended (optional, default: true) - If true, uses extended grapheme cluster rules. If false, uses legacy rules.

Returns:

• An array of strings, each representing one grapheme cluster.

Throws:

• Error if init() has not been called.

Building from Source

Prerequisites

• Emscripten
• Node.js 18+
• CMake 4.0+

Build Commands

# Build WASM
npm run build

# Run tests
npm test

# Lint
npm run lint

Browser Usage

The library works in modern browsers that support WebAssembly and ES modules:

<script type="module">
  import { segmentGraphemeClusters } from "./node_modules/grapheme-cluster-break/index.js";

  console.log(segmentGraphemeClusters("👨‍👩‍👧‍👦"));
</script>

License

MIT License