widthnamespacenamespace widthDisplay width: how many columns of a terminal a text takes, and a text cut to a number of columns (commons 0006-signals FR-023). An escape sequence takes none and is never split; a grapheme (what a person sees as one character, found with Intl.Segmenter) is never split either; a wide character or an emoji takes two columns.
The width of a grapheme is an approximation of what terminals do (as wcwidth and the string-width package approximate it):
Emoji_Presentation property (✅ ❌ 👉), when it carries the emoji variation selector U+FE0F (⏭️ ⏹️ ⚠️, keycaps such as 1️⃣), or when it is a zero-width-joiner sequence (one glyph of two columns, however many code points it joins); the text variation selector U+FE0E makes it 1;WIDE, which follow Unicode's EastAsianWidth.txt in blocks rather than code point by code point (JavaScript has no property escape for it);import { cutToWidth, displayWidth } from "./width.ts";
displayWidth("✅ 测试"); // 7
cutToWidth("✅ 测试", 6); // "✅ 测"
cutToWidth("\u001b[31mfailed badly\u001b[0m", 7, "…"); // "\u001b[31mfailed…\u001b[0m"widthnamespacenamespace widthwidth.Tokentypeno test imports ittype Token = { readonly kind: "escape"; readonly text: string } | { readonly kind: "text"; readonly text: string };A piece of a text: an escape sequence, or a run of text between them.
width.tokensfunctionno test imports itfunction tokens(text: string): readonly Token[]A text split into its escape sequences and the runs of text between them, in order; joined, the pieces are the text again.
width.graphemesfunctionno test imports itfunction graphemes(text: string): readonly string[]The graphemes of a text with no escape sequence, in order (extended grapheme clusters, by Intl.Segmenter).
width.graphemeWidthfunctionno test imports itfunction graphemeWidth(grapheme: string): 0 | 1 | 2The columns one grapheme takes: 0, 1 or 2 (see the module's rules).
width.displayWidthfunctionno test imports itfunction displayWidth(text: string): numberThe columns a text takes on a terminal: its graphemes' widths summed; escape sequences take none.
width.Splittypeno test imports ittype Split = {
/** The longest beginning that takes at most the columns asked for, with every escape sequence before the cut. */
readonly head: string;
/** The rest: `head + tail` is the text. */
readonly tail: string;
};A text split in two at a number of columns.
width.splitAtWidthfunctionno test imports itfunction splitAtWidth(text: string, width: number): SplitA text split where it reaches width columns, between two graphemes or escape sequences, never inside one: a wide character that would cross the edge goes to the tail. Escape sequences up to the first grapheme that does not fit stay in the head.
width.sgrParamsfunctionno test imports itfunction sgrParams(escape: string): readonly number[] | undefinedThe parameters of an SGR sequence (ESC [ ... m), or undefined for another sequence.
width.RESETconstno test imports itconst RESET: stringThe SGR sequence that turns every style off.
width.cutToWidthfunctionno test imports itfunction cutToWidth(text: string, width: number, ellipsis?: string): stringA text cut to at most width columns. A text that fits is returned as it is. Otherwise it is cut between graphemes so that it and the ellipsis (none by default; "…" is the usual one) fit; the escape sequences before the cut are kept, those after are dropped, and where a colour or another style was still on at the cut, the result ends with a reset so that the style does not run on. An ellipsis wider than width is left out.
Tokentypeno test imports ittype Token = { readonly kind: "escape"; readonly text: string } | { readonly kind: "text"; readonly text: string };A piece of a text: an escape sequence, or a run of text between them.
tokensfunctionfunction tokens(text: string): readonly Token[]A text split into its escape sequences and the runs of text between them, in order; joined, the pieces are the text again.
graphemesfunctionfunction graphemes(text: string): readonly string[]The graphemes of a text with no escape sequence, in order (extended grapheme clusters, by Intl.Segmenter).
graphemeWidthfunctionfunction graphemeWidth(grapheme: string): 0 | 1 | 2The columns one grapheme takes: 0, 1 or 2 (see the module's rules).
displayWidthfunctionfunction displayWidth(text: string): numberThe columns a text takes on a terminal: its graphemes' widths summed; escape sequences take none.
Splittypeno test imports ittype Split = {
/** The longest beginning that takes at most the columns asked for, with every escape sequence before the cut. */
readonly head: string;
/** The rest: `head + tail` is the text. */
readonly tail: string;
};A text split in two at a number of columns.
splitAtWidthfunctionfunction splitAtWidth(text: string, width: number): SplitA text split where it reaches width columns, between two graphemes or escape sequences, never inside one: a wide character that would cross the edge goes to the tail. Escape sequences up to the first grapheme that does not fit stay in the head.
sgrParamsfunctionfunction sgrParams(escape: string): readonly number[] | undefinedThe parameters of an SGR sequence (ESC [ ... m), or undefined for another sequence.
RESETconstconst RESET: stringThe SGR sequence that turns every style off.
cutToWidthfunctionfunction cutToWidth(text: string, width: number, ellipsis?: string): stringA text cut to at most width columns. A text that fits is returned as it is. Otherwise it is cut between graphemes so that it and the ellipsis (none by default; "…" is the usual one) fit; the escape sequences before the cut are kept, those after are dropped, and where a colour or another style was still on at the cut, the result ends with a reset so that the style does not run on. An ellipsis wider than width is left out.