feat: incremental rendering

Author: wu-json

src/log-update.ts

@@ -10,7 +10,7 @@ export type LogUpdate = {
 };
 
 const create = (stream: Writable, {showCursor = false} = {}): LogUpdate => {
-	let previousLineCount = 0;
+	let previousLines: string[] = [];
 	let previousOutput = '';
 	let hasHiddenCursor = false;
 
@@ -25,20 +25,63 @@ const create = (stream: Writable, {showCursor = false} = {}): LogUpdate => {
 			return;
 		}
 
+		const previousLineCount = previousLines.length;
+		const lines = output.split('\n');
+		const lineCount = lines.length;
+
+		if (lineCount === 0 || previousLineCount === 0) {
+			stream.write(ansiEscapes.eraseLines(previousLineCount) + output);
+			previousOutput = output;
+			previousLines = lines;
+			return;
+		}
+
+		// We aggregate all chunks for incremental rendering into a buffer, and then write them to stdout at the end.
+		const buffer: string[] = [];
+		const commitBuffer = () => {
+			stream.write(buffer.join(''));
+		};
+
+		// Clear extra lines if the current content's line count is lower than the previous.
+		if (lineCount < previousLineCount) {
+			buffer.push(
+				ansiEscapes.eraseLines(previousLineCount - lineCount + 1),
+				ansiEscapes.cursorUp(lineCount),
+			);
+		} else {
+			buffer.push(ansiEscapes.cursorUp(previousLineCount));
+		}
+
+		for (let i = 0; i < lineCount; i++) {
+			// We do not write lines if the contents are the same. This prevents flickering during renders.
+			if (lines[i] === previousLines[i]) {
+				buffer.push(ansiEscapes.cursorNextLine);
+				continue;
+			}
+
+			if (i === lineCount - 1) {
+				buffer.push(ansiEscapes.eraseLine);
+				break;
+			}
+
+			buffer.push(ansiEscapes.eraseLine + (lines[i] ?? '') + '\n');
+		}
+
+		commitBuffer();
+
 		previousOutput = output;
-		stream.write(ansiEscapes.eraseLines(previousLineCount) + output);
-		previousLineCount = output.split('\n').length;
+		previousLines = lines;
 	};
 
 	render.clear = () => {
-		stream.write(ansiEscapes.eraseLines(previousLineCount));
+		stream.write(ansiEscapes.eraseLines(previousLines.length));
 		previousOutput = '';
-		previousLineCount = 0;
+		previousLines = [];
 	};
 
 	render.done = () => {
 		previousOutput = '';
-		previousLineCount = 0;
+		previousLines = [];
 
 		if (!showCursor) {
 			cliCursor.show();
@@ -49,7 +92,7 @@ const create = (stream: Writable, {showCursor = false} = {}): LogUpdate => {
 	render.sync = (str: string) => {
 		const output = str + '\n';
 		previousOutput = output;
-		previousLineCount = output.split('\n').length;
+		previousLines = output.split('\n');
 	};
 
 	return render;

test/log-update.tsx

@@ -0,0 +1,82 @@
+import test from 'ava';
+import ansiEscapes from 'ansi-escapes';
+import logUpdate from '../src/log-update.js';
+import createStdout from './helpers/create-stdout.js';
+
+test('renders and updates output', t => {
+	const stdout = createStdout();
+	const render = logUpdate.create(stdout);
+
+	render('Hello');
+	t.is((stdout.write as any).callCount, 1);
+	t.is((stdout.write as any).firstCall.args[0], 'Hello\n');
+
+	render('World');
+	t.is((stdout.write as any).callCount, 2);
+	t.true(
+		((stdout.write as any).secondCall.args[0] as string).includes('World'),
+	);
+});
+
+test('skips identical output', t => {
+	const stdout = createStdout();
+	const render = logUpdate.create(stdout);
+
+	render('Hello');
+	render('Hello');
+
+	t.is((stdout.write as any).callCount, 1);
+});
+
+test('incremental render (surgical updates)', t => {
+	const stdout = createStdout();
+	const render = logUpdate.create(stdout);
+
+	render('Line 1\nLine 2\nLine 3');
+	render('Line 1\nUpdated\nLine 3');
+
+	const secondCall = (stdout.write as any).secondCall.args[0] as string;
+	t.true(secondCall.includes(ansiEscapes.cursorNextLine)); // Skips unchanged lines
+	t.true(secondCall.includes('Updated')); // Only updates changed line
+	t.false(secondCall.includes('Line 1')); // Doesn't rewrite unchanged
+	t.false(secondCall.includes('Line 3')); // Doesn't rewrite unchanged
+});
+
+test('clears extra lines when output shrinks', t => {
+	const stdout = createStdout();
+	const render = logUpdate.create(stdout);
+
+	render('Line 1\nLine 2\nLine 3');
+	render('Line 1');
+
+	const secondCall = (stdout.write as any).secondCall.args[0] as string;
+	t.true(secondCall.includes(ansiEscapes.eraseLines(2))); // Erases 2 extra lines
+});
+
+test('incremental render when output grows', t => {
+	const stdout = createStdout();
+	const render = logUpdate.create(stdout);
+
+	render('Line 1');
+	render('Line 1\nLine 2\nLine 3');
+
+	const secondCall = (stdout.write as any).secondCall.args[0] as string;
+	t.true(secondCall.includes(ansiEscapes.cursorNextLine)); // Skips unchanged first line
+	t.true(secondCall.includes('Line 2')); // Adds new line
+	t.true(secondCall.includes('Line 3')); // Adds new line
+	t.false(secondCall.includes('Line 1')); // Doesn't rewrite unchanged
+});
+
+test('single write call with multiple surgical updates', t => {
+	const stdout = createStdout();
+	const render = logUpdate.create(stdout);
+
+	render(
+		'Line 1\nLine 2\nLine 3\nLine 4\nLine 5\nLine 6\nLine 7\nLine 8\nLine 9\nLine 10',
+	);
+	render(
+		'Line 1\nUpdated 2\nLine 3\nUpdated 4\nLine 5\nUpdated 6\nLine 7\nUpdated 8\nLine 9\nUpdated 10',
+	);
+
+	t.is((stdout.write as any).callCount, 2); // Only 2 writes total (initial + update)
+});

test/render.tsx

@@ -125,10 +125,16 @@ test.serial('erase screen where state changes', async t => {
 	const ps = term('erase-with-state-change', ['4']);
 	await ps.waitForExit();
 
-	const secondFrame = ps.output.split(ansiEscapes.eraseLines(3))[1];
+	const lastFrame = ps.output.split(ansiEscapes.cursorHide).at(-1);
+	if (!lastFrame) {
+		t.fail('lastFrame is undefined');
+		return;
+	}
+
+	const lastFrameContent = stripAnsi(lastFrame);
 
 	for (const letter of ['A', 'B', 'C']) {
-		t.false(secondFrame?.includes(letter));
+		t.false(lastFrameContent.includes(letter));
 	}
 });