@peteanderson/ansi 0.2.2 → 0.2.3

package/README.md

@@ -18,6 +18,7 @@ console.log(ansi.bg.blue.combine(ansi.fg.white)("highlighted"));
 console.log(ansi.style.bold("important"));
 console.log(ansi.fg.rgb(5, 2, 0)("custom color"));
 console.log(ansi.strip("styled text")); // remove all ANSI codes
+console.log(ansi.visibleLength(styledText)); // get display width
 console.log(ansi.slice("styled text", 0, 5)); // slice by visible length
 console.log(ansi.simplify(styledText)); // combine adjacent SGR sequences
 ```
@@ -84,7 +85,7 @@ Removes all ANSI CSI sequences from a string.
 ### `slice(text, start, end)`
 
 Slices a string by visible characters, ignoring ANSI sequences. Works like `String.prototype.slice`
-but counts only visible characters.
+but counts only visible characters. Properly maintains terminal state at slice boundaries.
 
 ### `sanitize(text)`
 
@@ -95,6 +96,10 @@ Removes "unsafe" CSI sequences (non-SGR), leaving only color and style codes.
 Simplifies ANSI SGR sequences by combining adjacent sequences and removing redundant codes. Useful
 for optimizing styled strings.
 
+### `visibleLength(text)`
+
+Returns the visible length of a string with all ANSI sequences removed.
+
 ## License
 
 MIT

package/dist/ansi.d.ts

@@ -6,7 +6,8 @@ import { style } from "./sgr/style";
 import { fg } from "./sgr/color";
 import { bg } from "./sgr/color";
 import { strip } from "./strip";
+import { visibleLength } from "./strip";
 import { sanitize } from "./strip";
-import { slice } from "./strip";
+import { slice } from "./slice";
 import { simplify } from "./simplify/simplify";
-export { caret, erase, scroll, reset, style, fg, bg, strip, sanitize, slice, simplify };
+export { caret, erase, scroll, reset, style, fg, bg, strip, visibleLength, sanitize, slice, simplify };

package/dist/ansi.js

@@ -4,7 +4,8 @@ const erase = require("./erase");
 const scroll = require("./scroll");
 const { bg, fg, reset, style } = require("./sgr");
 const { simplify } = require("./simplify");
-const { sanitize, slice, strip } = require("./strip");
+const { slice } = require("./slice");
+const { sanitize, strip, visibleLength } = require("./strip");
 const ansi = {
     caret,
     erase,
@@ -14,6 +15,7 @@ const ansi = {
     fg,
     bg,
     strip,
+    visibleLength,
     sanitize,
     slice,
     simplify,

package/dist/index.d.ts

@@ -99,8 +99,9 @@ declare const _exports: {
         x256: (arg0: number, arg1?: number, arg2?: number) => (text: string) => string;
     };
     strip: (text: string) => string;
+    visibleLength: (text: string) => number;
     sanitize: (text: string) => string;
-    slice: typeof import("./strip").slice;
+    slice: typeof import("./slice").slice;
     simplify: typeof import("./simplify/simplify").simplify;
 };
 export = _exports;

package/dist/patterns.d.ts

@@ -0,0 +1,3 @@
+export const rxSGR: Readonly<RegExp>;
+export const rxCSI: Readonly<RegExp>;
+export const rxUnsafe: Readonly<RegExp>;

package/dist/patterns.js

@@ -0,0 +1,43 @@
+"use strict";
+/*
+I'm freezing these to prevent accidental mutation of the `lastIndex` property, which could keep
+future calls from starting at the beginning of the string.
+
+Code using these objects will have to clone them (with `new RegExp(rx)`) before using functions
+that modify `lastIndex` (such as `exec`). But according to my benchmarks, cloning the regex takes
+mere nanoseconds, and it wasn't even measurable when operating on longer strings. V8 clearly uses a
+global cache of compiled regexes. I assume that SpiderMonkey does the same thing.
+
+Here are my `timeit` benchmark results:
+
+```js
+const {timeit} = require("$timeit");
+
+const rxSGR = /\x1b\[[\d;]*m/g;
+const short = "\x1b[31mred \x1b[32mgreen \x1b[34mblue \x1b[0m";
+const long  = short.repeat(1000);
+
+timeit(() => short.replace(rxSGR, ""),                         {description: "short - no clone     "});
+timeit(() => short.replace(new RegExp(rxSGR), ""),             {description: "short - clone object "});
+timeit(() => short.replace(new RegExp(rxSGR.source, "g"), ""), {description: "short - clone source "});
+
+console.log();
+
+timeit(() => long .replace(rxSGR, ""),                         {description: "long  - no clone     "});
+timeit(() => long .replace(new RegExp(rxSGR), ""),             {description: "long  - clone object "});
+timeit(() => long .replace(new RegExp(rxSGR.source, "g"), ""), {description: "long  - clone source "});
+
+// Output:
+// short - no clone     : 82.73 ns (12,087,731 in 1.000016982 s)
+// short - clone object : 142.132 ns (7,035,692 in 1.0000001770000002 s)
+// short - clone source : 127.872 ns (7,820,293 in 1.00000017 s)
+//
+// long  - no clone     : 47.953 ųs (20,854 in 1.0000098149999999 s)
+// long  - clone object : 46.713 ųs (21,408 in 1.0000285520000003 s)
+// long  - clone source : 46.491 ųs (21,510 in 1.000026492 s)
+```
+*/
+const rxSGR = Object.freeze(/\x1b\[[\d;]*m/g);
+const rxCSI = Object.freeze(/\x1b\[[0-?]*[ -/]*[@-~]/g);
+const rxUnsafe = Object.freeze(/\x1b\[[0-?]*[ -/]*[@-ln-~]/g); // Everything except SGR codes (m).
+module.exports = { rxSGR, rxCSI, rxUnsafe };

package/dist/simplify/simplify.js

@@ -1,8 +1,9 @@
 "use strict";
+const { rxSGR } = require("../patterns");
 const { State } = require("./state");
-const rxSGR = /\x1b\[([0-9;]+)m/;
 /** @type {(text: string) => string} */
 function simplify(text) {
+    // `.split` doesn't modify `lastIndex`, so no clone is necessary here.
     const parts = text.split(rxSGR);
     const state = new State();
     let result = parts[0];

package/dist/slice.d.ts

@@ -0,0 +1 @@
+export function slice(text: string, start: number, end: number): string;

package/dist/slice.js

@@ -0,0 +1,83 @@
+"use strict";
+const { rxCSI, rxSGR } = require("./patterns");
+const { simplify } = require("./simplify");
+const { visibleLength } = require("./strip");
+/**
+@type {
+    (
+        text            : string,
+        fromStringIndex : number,
+        visibleCount    : number,
+    ) => {index: number, length: number}
+}
+*/
+function scanCSI(text, fromStringIndex, visibleCount) {
+    // We intentionally mutate `lastIndex` here, so we need a clone.
+    const rx = new RegExp(rxCSI);
+    let length = 0;
+    let index = fromStringIndex;
+    while (index < text.length && length < visibleCount) {
+        if (text[index] === "\x1b") {
+            rx.lastIndex = index;
+            const match = rx.exec(text);
+            if (match?.index === index) {
+                index += match[0].length;
+                continue;
+            }
+        }
+        index++;
+        length++;
+    }
+    return { index, length };
+}
+/** @type {(text: string, start: number, end?: number) => string} */
+function skippedSequences(text, start, end) {
+    const sequences = text.slice(start, end).match(new RegExp(rxSGR));
+    return sequences ? simplify(sequences.join("")) : "";
+}
+/**
+ * Return a slice of the given text, counting only visible characters (i.e. ignoring ANSI escape
+ * codes). The returned slice will include any ANSI escape codes from within the slice. In addition,
+ * SGR codes (m) from before and after the slice will be combined, simplified, and included so that
+ * the terminal state before and after the slice will be the same as if the whole string were
+ * printed. If you compose two or more slices together, there may be redundant SGR sequences at the
+ * boundaries, but the result will be correct. You can use `simplify` to remove the redundancies.
+ *
+ * Note the following caveats:
+ *
+ *   * Any non-SGR ANSI codes prior to or after the slice will be ignored.
+ *   * Control characters (such as newlines and backspaces) both outside and inside the slice are
+ *     counted as visible characters.
+ *
+ * These caveats mean that text may not appear on screen to be the same number of characters as the
+ * length of the slice, and that the terminal state may not be exactly the same at the start and end
+ * of the slice as it would be if the whole string were printed. This function is intended mostly
+ * for text that contains SGR codes, but no other ANSI codes or control characters.
+ *
+ * @type {(text: string, start: number, end: number) => string}
+ */
+function slice(text, start, end) {
+    /** @type {number | undefined} */
+    let textVisibleLength;
+    const getVisibleLength = () => textVisibleLength ??= visibleLength(text);
+    if (start < 0 || end < 0) {
+        textVisibleLength = getVisibleLength();
+        if (start < 0)
+            start = Math.max(0, textVisibleLength + start);
+        if (end < 0)
+            end = Math.max(0, textVisibleLength + end);
+    }
+    if (start > end)
+        return "";
+    if (start === 0 && (end >= text.length || end >= getVisibleLength()))
+        return text;
+    const { index: startIndex, length: visibleSkipped } = scanCSI(text, 0, start);
+    const endIndex = startIndex < text.length && visibleSkipped < end
+        ? scanCSI(text, startIndex, end - visibleSkipped).index
+        : text.length;
+    // Start and end the string in the same terminal state it would be in if the string weren't sliced.
+    const leadingSequences = skippedSequences(text, 0, startIndex);
+    const trailingSequences = skippedSequences(text, endIndex);
+    return leadingSequences + text.slice(startIndex, endIndex) + trailingSequences;
+}
+module.exports = { slice };

package/dist/strip.d.ts

@@ -3,9 +3,13 @@
  * @type {(text: string) => string}
  */
 export const strip: (text: string) => string;
+/**
+ * Calculate the visible length of a string with ANSI escape codes stripped.
+ * @type {(text: string) => number}
+ */
+export const visibleLength: (text: string) => number;
 /**
  * Remove all ANSI escape codes except SGR codes (m), which are used for color and styling.
  * @type {(text: string) => string}
  */
 export const sanitize: (text: string) => string;
-export function slice(text: string, start: number, end: number): string;

package/dist/strip.js

@@ -1,58 +1,18 @@
 "use strict";
-const { reset } = require("./sgr");
-const rxCSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
-const rxUnsafe = /\x1b\[[0-?]*[ -/]*[@-ln-~]/g; // Everything except SGR codes (m).
+const { rxCSI, rxUnsafe } = require("./patterns");
 /**
  * Remove all ANSI escape codes from the given text.
  * @type {(text: string) => string}
  */
-const strip = text => text.replace(rxCSI, '');
+const strip = text => text.replace(new RegExp(rxCSI), "");
+/**
+ * Calculate the visible length of a string with ANSI escape codes stripped.
+ * @type {(text: string) => number}
+ */
+const visibleLength = text => strip(text).length;
 /**
  * Remove all ANSI escape codes except SGR codes (m), which are used for color and styling.
  * @type {(text: string) => string}
  */
-const sanitize = text => text.replace(rxUnsafe, '');
-/** @type {(text: string, start: number, end: number) => string} */
-function slice(text, start, end) {
-    if (start < 0 || end < 0) {
-        const visibleLength = strip(text).length;
-        if (start < 0)
-            start = Math.max(0, visibleLength + start);
-        if (end < 0)
-            end = Math.max(0, visibleLength + end);
-    }
-    if (start > end)
-        return "";
-    let visibleIndex = 0;
-    let startIndex = 0;
-    while (startIndex < text.length && visibleIndex < start) {
-        if (text[startIndex] === "\x1b") {
-            rxCSI.lastIndex = startIndex;
-            const match = rxCSI.exec(text);
-            if (match?.index === startIndex) {
-                startIndex += match[0].length;
-                continue;
-            }
-        }
-        startIndex++;
-        visibleIndex++;
-    }
-    let endIndex = startIndex;
-    let hasAnsi = false;
-    while (endIndex < text.length && visibleIndex < end) {
-        if (text[endIndex] === "\x1b") {
-            rxCSI.lastIndex = endIndex;
-            const match = rxCSI.exec(text);
-            if (match?.index === endIndex) {
-                endIndex += match[0].length;
-                hasAnsi = true;
-                continue;
-            }
-        }
-        endIndex++;
-        visibleIndex++;
-    }
-    return text.slice(startIndex, endIndex) + (hasAnsi ? reset : "");
-}
-;
-module.exports = { strip, sanitize, slice };
+const sanitize = text => text.replace(new RegExp(rxUnsafe), "");
+module.exports = { strip, visibleLength, sanitize };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name"            : "@peteanderson/ansi",
-	"version"         : "0.2.2",
+	"version"         : "0.2.3",
 	"description"     : "ANSI escape sequence generation with automatic feature detection",
 	"author"          : {
 		"name"  : "Pete Anderson",

package/src/ansi.js

@@ -1,11 +1,12 @@
 "use strict";
 
-const caret                    = require("./caret");
-const erase                    = require("./erase");
-const scroll                   = require("./scroll");
-const {bg, fg, reset, style}   = require("./sgr");
-const {simplify}               = require("./simplify");
-const {sanitize, slice, strip} = require("./strip");
+const caret                            = require("./caret");
+const erase                            = require("./erase");
+const scroll                           = require("./scroll");
+const {bg, fg, reset, style}           = require("./sgr");
+const {simplify}                       = require("./simplify");
+const {slice}                          = require("./slice");
+const {sanitize, strip, visibleLength} = require("./strip");
 
 const ansi = {
 	caret,
@@ -18,6 +19,7 @@ const ansi = {
 	bg,
 
 	strip,
+	visibleLength,
 	sanitize,
 	slice,
 	simplify,

package/src/patterns.js

@@ -0,0 +1,44 @@
+/*
+I'm freezing these to prevent accidental mutation of the `lastIndex` property, which could keep
+future calls from starting at the beginning of the string.
+
+Code using these objects will have to clone them (with `new RegExp(rx)`) before using functions
+that modify `lastIndex` (such as `exec`). But according to my benchmarks, cloning the regex takes
+mere nanoseconds, and it wasn't even measurable when operating on longer strings. V8 clearly uses a
+global cache of compiled regexes. I assume that SpiderMonkey does the same thing.
+
+Here are my `timeit` benchmark results:
+
+```js
+const {timeit} = require("$timeit");
+
+const rxSGR = /\x1b\[[\d;]*m/g;
+const short = "\x1b[31mred \x1b[32mgreen \x1b[34mblue \x1b[0m";
+const long  = short.repeat(1000);
+
+timeit(() => short.replace(rxSGR, ""),                         {description: "short - no clone     "});
+timeit(() => short.replace(new RegExp(rxSGR), ""),             {description: "short - clone object "});
+timeit(() => short.replace(new RegExp(rxSGR.source, "g"), ""), {description: "short - clone source "});
+
+console.log();
+
+timeit(() => long .replace(rxSGR, ""),                         {description: "long  - no clone     "});
+timeit(() => long .replace(new RegExp(rxSGR), ""),             {description: "long  - clone object "});
+timeit(() => long .replace(new RegExp(rxSGR.source, "g"), ""), {description: "long  - clone source "});
+
+// Output:
+// short - no clone     : 82.73 ns (12,087,731 in 1.000016982 s)
+// short - clone object : 142.132 ns (7,035,692 in 1.0000001770000002 s)
+// short - clone source : 127.872 ns (7,820,293 in 1.00000017 s)
+//
+// long  - no clone     : 47.953 ųs (20,854 in 1.0000098149999999 s)
+// long  - clone object : 46.713 ųs (21,408 in 1.0000285520000003 s)
+// long  - clone source : 46.491 ųs (21,510 in 1.000026492 s)
+```
+*/
+
+const rxSGR    = Object.freeze(/\x1b\[[\d;]*m/g);
+const rxCSI    = Object.freeze(/\x1b\[[0-?]*[ -/]*[@-~]/g);
+const rxUnsafe = Object.freeze(/\x1b\[[0-?]*[ -/]*[@-ln-~]/g); // Everything except SGR codes (m).
+
+module.exports = {rxSGR, rxCSI, rxUnsafe};

package/src/simplify/simplify.js

@@ -1,11 +1,11 @@
 "use strict";
 
+const {rxSGR} = require("../patterns");
 const {State} = require("./state");
 
-const rxSGR = /\x1b\[([0-9;]+)m/;
-
 /** @type {(text: string) => string} */
 function simplify(text) {
+	// `.split` doesn't modify `lastIndex`, so no clone is necessary here.
 	const parts = text.split(rxSGR);
 
 	const state  = new State();

package/src/slice.js

@@ -0,0 +1,99 @@
+"use strict";
+
+const {rxCSI, rxSGR}  = require("./patterns");
+const {simplify}      = require("./simplify");
+const {visibleLength} = require("./strip");
+
+/**
+@type {
+	(
+		text            : string,
+		fromStringIndex : number,
+		visibleCount    : number,
+	) => {index: number, length: number}
+}
+*/
+function scanCSI(text, fromStringIndex, visibleCount) {
+	// We intentionally mutate `lastIndex` here, so we need a clone.
+	const rx = new RegExp(rxCSI);
+
+	let length = 0;
+	let index  = fromStringIndex;
+
+	while (index < text.length && length < visibleCount) {
+		if (text[index] === "\x1b") {
+			rx.lastIndex = index;
+			const match = rx.exec(text);
+			if (match?.index === index) {
+				index += match[0].length;
+				continue;
+			}
+		}
+
+		index++;
+		length++;
+	}
+
+	return {index, length};
+}
+
+/** @type {(text: string, start: number, end?: number) => string} */
+function skippedSequences(text, start, end) {
+	const sequences = text.slice(start, end).match(new RegExp(rxSGR));
+	return sequences ? simplify(sequences.join("")) : "";
+}
+
+/**
+ * Return a slice of the given text, counting only visible characters (i.e. ignoring ANSI escape
+ * codes). The returned slice will include any ANSI escape codes from within the slice. In addition,
+ * SGR codes (m) from before and after the slice will be combined, simplified, and included so that
+ * the terminal state before and after the slice will be the same as if the whole string were
+ * printed. If you compose two or more slices together, there may be redundant SGR sequences at the
+ * boundaries, but the result will be correct. You can use `simplify` to remove the redundancies.
+ *
+ * Note the following caveats:
+ *
+ *   * Any non-SGR ANSI codes prior to or after the slice will be ignored.
+ *   * Control characters (such as newlines and backspaces) both outside and inside the slice are
+ *     counted as visible characters.
+ *
+ * These caveats mean that text may not appear on screen to be the same number of characters as the
+ * length of the slice, and that the terminal state may not be exactly the same at the start and end
+ * of the slice as it would be if the whole string were printed. This function is intended mostly
+ * for text that contains SGR codes, but no other ANSI codes or control characters.
+ *
+ * @type {(text: string, start: number, end: number) => string}
+ */
+function slice(text, start, end) {
+	/** @type {number | undefined} */
+	let textVisibleLength;
+	const getVisibleLength = () => textVisibleLength ??= visibleLength(text);
+
+	if (start < 0 || end < 0) {
+		textVisibleLength = getVisibleLength();
+		if (start < 0)
+			start = Math.max(0, textVisibleLength + start);
+		if (end < 0)
+			end = Math.max(0, textVisibleLength + end);
+	}
+	if (start > end)
+		return "";
+
+	if (start === 0 && (end >= text.length || end >= getVisibleLength()))
+		return text;
+
+	const {index: startIndex, length: visibleSkipped} = scanCSI(text, 0, start);
+
+	const endIndex =
+		startIndex < text.length && visibleSkipped < end
+			? scanCSI(text, startIndex, end - visibleSkipped).index
+			: text.length;
+
+	// Start and end the string in the same terminal state it would be in if the string weren't sliced.
+	const leadingSequences  = skippedSequences(text, 0, startIndex);
+	const trailingSequences = skippedSequences(text, endIndex);
+
+	return leadingSequences + text.slice(startIndex, endIndex) + trailingSequences;
+}
+
+module.exports = {slice};

package/src/strip.js

@@ -1,69 +1,23 @@
 "use strict";
 
-const {reset} = require("./sgr");
-
-const rxCSI    = /\x1b\[[0-?]*[ -/]*[@-~]/g;
-const rxUnsafe = /\x1b\[[0-?]*[ -/]*[@-ln-~]/g; // Everything except SGR codes (m).
+const {rxCSI, rxUnsafe} = require("./patterns");
 
 /**
  * Remove all ANSI escape codes from the given text.
  * @type {(text: string) => string}
  */
-const strip = text => text.replace(rxCSI, '');
+const strip = text => text.replace(new RegExp(rxCSI), "");
+
+/**
+ * Calculate the visible length of a string with ANSI escape codes stripped.
+ * @type {(text: string) => number}
+ */
+const visibleLength = text => strip(text).length;
 
 /**
  * Remove all ANSI escape codes except SGR codes (m), which are used for color and styling.
  * @type {(text: string) => string}
  */
-const sanitize = text => text.replace(rxUnsafe, '');
-
-/** @type {(text: string, start: number, end: number) => string} */
-function slice(text, start, end) {
-	if (start < 0 || end < 0) {
-		const visibleLength = strip(text).length;
-		if (start < 0)
-			start = Math.max(0, visibleLength + start);
-		if (end < 0)
-			end = Math.max(0, visibleLength + end);
-	}
-	if (start > end)
-		return "";
-
-	let visibleIndex = 0;
-	let startIndex   = 0;
-
-	while (startIndex < text.length && visibleIndex < start) {
-		if (text[startIndex] === "\x1b") {
-			rxCSI.lastIndex = startIndex;
-			const match = rxCSI.exec(text);
-			if (match?.index === startIndex) {
-				startIndex += match[0].length;
-				continue;
-			}
-		}
-
-		startIndex++;
-		visibleIndex++;
-	}
-
-	let endIndex = startIndex;
-	let hasAnsi  = false;
-	while (endIndex < text.length && visibleIndex < end) {
-		if (text[endIndex] === "\x1b") {
-			rxCSI.lastIndex = endIndex;
-			const match = rxCSI.exec(text);
-			if (match?.index === endIndex) {
-				endIndex += match[0].length;
-				hasAnsi = true;
-				continue;
-			}
-		}
-
-		endIndex++;
-		visibleIndex++;
-	}
-
-	return text.slice(startIndex, endIndex) + (hasAnsi ? reset : "");
-};
+const sanitize = text => text.replace(new RegExp(rxUnsafe), "");
 
-module.exports = {strip, sanitize, slice};
+module.exports = {strip, visibleLength, sanitize};