Add onRender hook (#795)

Author: shishu314

readme.md

@@ -2035,6 +2035,13 @@ That way, both are visible and don't overlap each other.
 
 This functionality is powered by [patch-console](https://github.com/vadimdemedes/patch-console), so if you need to disable Ink's interception of output but want to build something custom, you can use that.
 
+###### onRender
+
+Type: `(renderTime: number) => void`\
+Default: `undefined`
+
+Runs the given callback after each render and re-render with a renderResult object.
+
 ###### debug
 
 Type: `boolean`\

src/ink.tsx

@@ -20,13 +20,18 @@ import {accessibilityContext as AccessibilityContext} from './components/Accessi
 
 const noop = () => {};
 
+export type RenderResult = {
+	renderTime: number;
+};
+
 export type Options = {
 	stdout: NodeJS.WriteStream;
 	stdin: NodeJS.ReadStream;
 	stderr: NodeJS.WriteStream;
 	debug: boolean;
 	exitOnCtrlC: boolean;
 	patchConsole: boolean;
+	onRender?: (renderTime: RenderResult) => void;
 	isScreenReaderEnabled?: boolean;
 	waitUntilExit?: () => Promise<void>;
 	maxFps?: number;
@@ -163,10 +168,14 @@ export default class Ink {
 			return;
 		}
 
+		const startTime = performance.now();
 		const {output, outputHeight, staticOutput} = render(
 			this.rootNode,
 			this.isScreenReaderEnabled,
 		);
+		if (this.options.onRender) {
+			this.options.onRender({renderTime: performance.now() - startTime});
+		}
 
 		// If <Static> output isn't empty, it means new children have been added to it
 		const hasStaticOutput = staticOutput && staticOutput !== '\n';
@@ -278,12 +287,17 @@ export default class Ink {
 			</AccessibilityContext.Provider>
 		);
 
+		const start = performance.now();
 		// @ts-expect-error the types for `react-reconciler` are not up to date with the library.
 		// eslint-disable-next-line @typescript-eslint/no-unsafe-call
 		reconciler.updateContainerSync(tree, this.container, null, noop);
 		// @ts-expect-error the types for `react-reconciler` are not up to date with the library.
 		// eslint-disable-next-line @typescript-eslint/no-unsafe-call
 		reconciler.flushSyncWork();
+		if (this.options.onRender) {
+			const end = performance.now();
+			this.options.onRender({renderTime: end - start});
+		}
 	}
 
 	writeToStdout(data: string): void {

src/render.ts

@@ -1,7 +1,7 @@
 import {Stream} from 'node:stream';
 import process from 'node:process';
 import type {ReactNode} from 'react';
-import Ink, {type Options as InkOptions} from './ink.js';
+import Ink, {type Options as InkOptions, type RenderResult} from './ink.js';
 import instances from './instances.js';
 
 export type RenderOptions = {
@@ -46,6 +46,11 @@ export type RenderOptions = {
 	*/
 	patchConsole?: boolean;
 
+	/**
+	Runs the given callback after each render and re-render with a RenderResult object.
+	*/
+	onRender?: (renderTime: RenderResult) => void;
+
 	/**
 	Enable screen reader support. See https://github.com/vadimdemedes/ink/blob/master/readme.md#screen-reader-support
 

test/render.tsx

@@ -1,15 +1,18 @@
+import EventEmitter from 'node:events';
 import process from 'node:process';
 import url from 'node:url';
 import * as path from 'node:path';
 import {createRequire} from 'node:module';
 import FakeTimers from '@sinonjs/fake-timers';
+import {stub} from 'sinon';
 import test from 'ava';
-import React from 'react';
+import React, {useEffect, useState} from 'react';
 import ansiEscapes from 'ansi-escapes';
 import stripAnsi from 'strip-ansi';
 import boxen from 'boxen';
 import delay from 'delay';
-import {render, Box, Text} from '../src/index.js';
+import {render, Box, Text, useInput} from '../src/index.js';
+import {type RenderResult} from '../src/ink.js';
 import createStdout from './helpers/create-stdout.js';
 
 const require = createRequire(import.meta.url);
@@ -19,6 +22,28 @@ const {spawn} = require('node-pty') as typeof import('node-pty');
 
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
 
+const createStdin = () => {
+	const stdin = new EventEmitter() as unknown as NodeJS.WriteStream;
+	stdin.isTTY = true;
+	stdin.setRawMode = stub();
+	stdin.setEncoding = () => {};
+	stdin.read = stub();
+	stdin.unref = () => {};
+	stdin.ref = () => {};
+
+	return stdin;
+};
+
+const emitReadable = (stdin: NodeJS.WriteStream, chunk: string) => {
+	/* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment */
+	const read = stdin.read as ReturnType<typeof stub>;
+	read.onCall(0).returns(chunk);
+	read.onCall(1).returns(null);
+	stdin.emit('readable');
+	read.reset();
+	/* eslint-enable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment */
+};
+
 const term = (fixture: string, args: string[] = []) => {
 	let resolve: (value?: unknown) => void;
 	let reject: (error: Error) => void;
@@ -274,6 +299,68 @@ test.serial('throttle renders to maxFps', t => {
 	}
 });
 
+test.serial('outputs renderTime when onRender is passed', async t => {
+	const clock = FakeTimers.install(); // Controls timers + Date.now()
+	let lastRenderTime = -1;
+	let tickTime = 100;
+	const funcObj = {
+		onRender(renderResult: RenderResult) {
+			const {renderTime} = renderResult;
+			lastRenderTime = renderTime;
+		},
+	};
+
+	const onRenderStub = stub(funcObj, 'onRender').callThrough();
+
+	function Nested({text}) {
+		clock.tick(tickTime);
+		return <Text>{text}</Text>;
+	}
+
+	function Test() {
+		const [text, setText] = useState('Test');
+		useEffect(() => {
+			clock.tick(tickTime);
+		});
+
+		useInput(input => {
+			setText(input);
+		});
+
+		return (
+			<Box borderStyle="round">
+				<Text>{text}</Text>
+				<Nested text={text} />
+			</Box>
+		);
+	}
+
+	const stdin = createStdin();
+	const {unmount, rerender} = render(<Test />, {
+		onRender: onRenderStub,
+		stdin,
+	});
+
+	t.is(onRenderStub.callCount, 2);
+
+	onRenderStub.resetHistory();
+	tickTime = 200;
+	rerender(<Test />);
+
+	t.is(onRenderStub.callCount, 2);
+
+	onRenderStub.resetHistory();
+	emitReadable(stdin, 'a');
+	await delay(100);
+
+	t.is(lastRenderTime, 0);
+	t.is(onRenderStub.callCount, 1);
+
+	unmount();
+
+	clock.uninstall();
+});
+
 test.serial('no throttled renders after unmount', t => {
 	const clock = FakeTimers.install();
 	try {