🧩 segment-string

A lightweight, intuitive wrapper around Intl.Segmenter for seamless segment-aware string operations in TypeScript and JavaScript.

---

Key Features

• Intuitive Intl.Segmenter Wrapper: Simplifies text segmentation with a clean API.
• Standards-Based: Built on native Intl.Segmenter for robust compatibility.
• Lightweight & Tree-Shakeable: Minimal footprint with optimal bundling.
• Highly Performant: Uses iterators for efficient, on-demand processing.
• Full TypeScript Support: Strict types for safe, predictable usage.

---

Installation

npm install segment-string

Getting Started

segment-string is a lightweight wrapper for Intl.Segmenter, designed to simplify locale-sensitive text segmentation in JavaScript and TypeScript. It lets you easily segment and manipulate text by graphemes, words, or sentences, ideal for handling complex cases like multi-character emojis or language-specific boundaries.

import{SegmentString}from"segment-string";conststr=newSegmentString("Hello, world! 👩‍👩‍👧‍👦🌍🌈");// Segment by graphemeconsole.log([...str.graphemes()]);// ['H', 'e', 'l', 'l', 'o', ',', ' ', 'w', 'o', 'r', 'l', 'd', '!', ' ', '👩‍👩‍👧‍👦', '🌍', '🌈']

---

SegmentString Class

The SegmentString class encapsulates a string and provides methods for segmentation, counting, and retrieving segments at specified indices with locale and granularity options.

Constructor

newSegmentString(str: string,locales?: Intl.LocalesArgument);

• str: The string to segment.
• locales: Optional locales argument for segmentation.

Methods

segments(granularity: Granularity, options?: SegmentationOptions | WordSegmentationOptions): Iterable<string>

Segments the string by the specified granularity and returns the segments as strings.

rawSegments(granularity: Granularity, options?: SegmentationOptions | WordSegmentationOptions): Intl.Segments | Iterable<Intl.SegmentData>

Returns raw Intl.SegmentData objects based on granularity and options.

segmentCount(granularity: Granularity, options?: SegmentationOptions | WordSegmentationOptions): number

Counts segments in the string based on the specified granularity.

segmentAt(index: number, granularity: Granularity, options?: SegmentationOptions | WordSegmentationOptions): string | undefined

Retrieves the segment at a specific index, supporting negative indices.

rawSegmentAt(index: number, granularity: Granularity, options?: SegmentationOptions | WordSegmentationOptions): Intl.SegmentData | undefined

Returns the raw segment data at a specific index, supporting negative indices.

graphemes(options?: SegmentationOptions): Iterable<string>

Returns an iterable of grapheme segments as strings.

rawGraphemes(options?: SegmentationOptions): Iterable<Intl.SegmentData>

Returns an iterable of raw grapheme segments.

graphemeCount(options?: SegmentationOptions): number

Counts grapheme segments in the string.

graphemeAt(index: number, options?: SegmentationOptions): string | undefined

Returns the grapheme at a specific index, supporting negative indices.

rawGraphemeAt(index: number, options?: SegmentationOptions): Intl.SegmentData | undefined

Returns the raw grapheme data at a specific index, supporting negative indices.

words(options?: WordSegmentationOptions): Iterable<string>

Returns an iterable of word segments, with optional filtering for word-like segments.

rawWords(options?: WordSegmentationOptions): Iterable<Intl.SegmentData>

Returns an iterable of raw word segments, with optional filtering for word-like segments.

wordCount(options?: WordSegmentationOptions): number

Counts word segments in the string.

wordAt(index: number, options?: WordSegmentationOptions): string | undefined

Returns the word at a specific index, supporting negative indices.

rawWordAt(index: number, options?: WordSegmentationOptions): Intl.SegmentData | undefined

Returns the raw word data at a specific index, supporting negative indices.

sentences(options?: SegmentationOptions): Iterable<string>

Returns an iterable of sentence segments.

rawSentences(options?: SegmentationOptions): Iterable<Intl.SegmentData>

Returns an iterable of raw sentence segments.

sentenceCount(options?: SegmentationOptions): number

Counts sentence segments in the string.

sentenceAt(index: number, options?: SegmentationOptions): string | undefined

Returns the sentence at a specific index, supporting negative indices.

rawSentenceAt(index: number, options?: SegmentationOptions): Intl.SegmentData | undefined

Returns the raw sentence data at a specific index, supporting negative indices.

[Symbol.iterator](): Iterator<string>

Returns an iterator over the graphemes of the string.

---

Example Usage

import{SegmentString}from"segment-string";consttext=newSegmentString("Hello, world! 👩‍👩‍👧‍👦🌍🌈");// Segmenting by wordsfor(constwordoftext.words()){console.log(word);// 'Hello', ',', ' ', 'world', '!', ' 👩‍👩‍👧‍👦🌍🌈'}// Segmenting graphemes and countingconsole.log([...text.graphemes()]);// ['H', 'e', 'l', 'l', 'o', ',', ' ', 'w', 'o', 'r', 'l', 'd', '!', ' ', '👩‍👩‍👧‍👦', '🌍', '🌈']console.log("Grapheme count:",text.graphemeCount());// 17console.log("String length:",text.toString().length);// 29// Accessing a specific wordconstsecondWord=text.wordAt(1,{isWordLike: true});// 'world'console.log(secondWord);

---

SegmentSplitter Class

Alternatively, the SegmentSplitter class allows you to create an instance that can be directly used with JavaScript's String.prototype.split method for basic segmentation.

Constructor

newSegmentSplitter<TextendsGranularity>(granularity: T,options?: SegmentationOptions<T>);

• granularity: Specifies the segmentation granularity level ('grapheme', 'word', 'sentence', etc.).
• options: Optional settings to customize the segmentation for the given granularity.

Example Usage

conststr="Hello, world!";constwordSplitter=newSegmentSplitter("word",{isWordLike: true});constwords=str.split(wordSplitter);console.log(words);// ["Hello", "world"]

---

Individual Functions

getRawSegments

functiongetRawSegments(str: string,granularity: Granularity,options?: SegmentationOptions|WordSegmentationOptions,): Intl.Segments|Iterable<Intl.SegmentData>;

• Description: Returns raw Intl.SegmentData objects based on granularity and options.
• Parameters:
  • str: The string to segment.
  • granularity: Specifies the segmentation level ('grapheme', 'word', or 'sentence').
  • options: Includes locales for specifying locale and isWordLike for filtering word-like segments.
• Returns: An iterable of raw Intl.SegmentData.

getSegments

functiongetSegments(str: string,granularity: Granularity,options?: SegmentationOptions|WordSegmentationOptions,): Iterable<string>;

• Description: Returns segments of the string as plain strings.
• Parameters: Similar to getRawSegments.
• Returns: An iterable of segments as strings.

segmentCount

functionsegmentCount(str: string,granularity: Granularity,options?: SegmentationOptions|WordSegmentationOptions,): number;

• Description: Returns the count of segments based on granularity and options.
• Parameters: Similar to getRawSegments.
• Returns: Number of segments.

rawSegmentAt

functionrawSegmentAt(str: string,index: number,granularity: Granularity,options?: SegmentationOptions|WordSegmentationOptions,): Intl.SegmentData|undefined;

• Description: Returns the raw segment data at a specified index, supporting negative indices.
• Parameters: Similar to getRawSegments, plus an index parameter.
• Returns: The Intl.SegmentData at the specified index, or undefined if out of bounds.

segmentAt

functionsegmentAt(str: string,index: number,granularity: Granularity,options?: SegmentationOptions|WordSegmentationOptions,): string|undefined;

• Description: Returns the segment at a specified index, supporting negative indices.
• Parameters: Similar to getRawSegments, plus an index parameter.
• Returns: The segment at the specified index or undefined if out of bounds.

filterRawWordLikeSegments

functionfilterRawWordLikeSegments(segments: Intl.Segments,): Iterable<Intl.SegmentData>;

• Description: Filters and returns an iterable of raw word-like segment data where isWordLike is true.
• Parameters:
  • segments: The segments to filter.
• Returns: An iterable of Intl.SegmentData for each word-like segment.

filterWordLikeSegments

functionfilterWordLikeSegments(segments: Intl.Segments): Iterable<string>;

• Description: Filters and returns an iterable of word-like segments as strings where isWordLike is true.
• Parameters:
  • segments: The segments to filter.
• Returns: An iterable of strings for each word-like segment.

---

💙 This package was templated with create-typescript-app.