Fix: Accept capture streams in RenderOptions without a type assertion

Author: tomaspiaggio

readme.md

@@ -2595,21 +2595,25 @@ Type: `object`
 
 ###### stdout
 
-Type: `stream.Writable`\
+Type: `InkOutputStream`\
 Default: `process.stdout`
 
 Output stream where the app will be rendered.
 
+Any object with a `write()` method can be passed, like a stream that captures output in memory, so it doesn't have to be a terminal stream. The `InkOutputStream` type is exported for typing your own streams.
+
 ###### stdin
 
-Type: `stream.Readable`\
+Type: `InkInputStream`\
 Default: `process.stdin`
 
 Input stream where app will listen for input.
 
+Any object with `on()` and `read()` methods can be passed. The `InkInputStream` type is exported for typing your own streams.
+
 ###### stderr
 
-Type: `stream.Writable`\
+Type: `InkOutputStream`\
 Default: `process.stderr`
 
 Error stream.

src/index.ts

@@ -1,4 +1,9 @@
-export type {RenderOptions, Instance} from './render.js';
+export type {
+	RenderOptions,
+	Instance,
+	InkOutputStream,
+	InkInputStream,
+} from './render.js';
 export {default as render} from './render.js';
 export type {RenderToStringOptions} from './render-to-string.js';
 export {default as renderToString} from './render-to-string.js';

src/render.ts

@@ -5,26 +5,64 @@ import Ink, {type Options as InkOptions, type RenderMetrics} from './ink.js';
 import instances from './instances.js';
 import {type KittyKeyboardOptions} from './kitty-keyboard.js';
 
+/**
+Output stream that Ink can render to.
+
+Typed structurally, so any stream that captures output can be passed without a type assertion, not just a terminal stream. `process.stdout` satisfies this type.
+
+Everything except `write()` is optional, because Ink checks for their presence at runtime.
+*/
+export type InkOutputStream = {
+	columns?: number;
+	rows?: number;
+	isTTY?: boolean;
+	destroyed?: boolean;
+	writable?: boolean;
+	writableEnded?: boolean;
+	writableLength?: number;
+	write(data: string, ...rest: unknown[]): unknown;
+	on?(event: unknown, listener: unknown): unknown;
+	off?(event: unknown, listener: unknown): unknown;
+};
+
+/**
+Input stream that Ink can listen for input on.
+
+Typed structurally, like `InkOutputStream`. `process.stdin` satisfies this type.
+*/
+export type InkInputStream = {
+	isTTY?: boolean;
+	on(event: unknown, listener: unknown): unknown;
+	read(...args: unknown[]): unknown;
+	setRawMode?(mode: boolean): unknown;
+	setEncoding?(...args: unknown[]): unknown;
+	unshift?(...args: unknown[]): unknown;
+	addListener?(event: unknown, listener: unknown): unknown;
+	removeListener?(event: unknown, listener: unknown): unknown;
+	ref?(): unknown;
+	unref?(): unknown;
+};
+
 export type RenderOptions = {
 	/**
 	Output stream where the app will be rendered.
 
 	@default process.stdout
 	*/
-	stdout?: NodeJS.WriteStream;
+	stdout?: InkOutputStream;
 
 	/**
 	Input stream where app will listen for input.
 
 	@default process.stdin
 	*/
-	stdin?: NodeJS.ReadStream;
+	stdin?: InkInputStream;
 
 	/**
 	Error stream.
 	@default process.stderr
 	*/
-	stderr?: NodeJS.WriteStream;
+	stderr?: InkOutputStream;
 
 	/**
 	If true, each update will be rendered as separate output, without replacing the previous one.
@@ -198,20 +236,23 @@ Mount a component and render the output.
 */
 const render = (
 	node: ReactNode,
-	options?: NodeJS.WriteStream | RenderOptions,
+	options?: InkOutputStream | RenderOptions,
 ): Instance => {
+	const {stdout, stdin, stderr, ...restOptions} = getOptions(options);
+
 	const inkOptions: InkOptions = {
-		stdout: process.stdout,
-		stdin: process.stdin,
-		stderr: process.stderr,
 		debug: false,
 		exitOnCtrlC: true,
 		patchConsole: true,
 		maxFps: 30,
 		incrementalRendering: false,
 		concurrent: false,
 		alternateScreen: false,
-		...getOptions(options),
+		...restOptions,
+		// Ink internally uses Node's stream types, but only the members declared above.
+		stdout: (stdout ?? process.stdout) as NodeJS.WriteStream,
+		stdin: (stdin ?? process.stdin) as NodeJS.ReadStream,
+		stderr: (stderr ?? process.stderr) as NodeJS.WriteStream,
 	};
 
 	const instance: Ink = getInstance(
@@ -236,17 +277,27 @@ const render = (
 
 export default render;
 
+const isOutputStream = (
+	value: InkOutputStream | RenderOptions,
+): value is InkOutputStream => {
+	// Options objects never have a `write` method.
+	return (
+		value instanceof Stream ||
+		('write' in value && typeof value.write === 'function')
+	);
+};
+
 const getOptions = (
-	stdout: NodeJS.WriteStream | RenderOptions | undefined = {},
+	options: InkOutputStream | RenderOptions | undefined = {},
 ): RenderOptions => {
-	if (stdout instanceof Stream) {
+	if (isOutputStream(options)) {
 		return {
-			stdout,
+			stdout: options,
 			stdin: process.stdin,
 		};
 	}
 
-	return stdout;
+	return options;
 };
 
 const getInstance = (

test/components.tsx

@@ -773,8 +773,7 @@ test('disable raw mode when all input components are unmounted', async t => {
 
 	const {rerender} = render(
 		<Test renderFirstInput renderSecondInput />,
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-		options as any,
+		options,
 	);
 
 	t.true(stdin.setRawMode.calledOnce);
@@ -829,11 +828,7 @@ test('do not disable raw mode when swapping components that use useInput', async
 		return step === 1 ? <StepA /> : <StepB />;
 	}
 
-	const {rerender} = render(
-		<Test step={1} />,
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-		options as any,
-	);
+	const {rerender} = render(<Test step={1} />, options);
 
 	t.true(stdin.setRawMode.calledOnce);
 	t.true(stdin.ref.calledOnce);
@@ -887,11 +882,7 @@ test('clear pending input parser state when swapping components that use useInpu
 			return step === 1 ? <StepA /> : <StepB />;
 		}
 
-		const {rerender} = render(
-			<Test step={1} />,
-			// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-			options as any,
-		);
+		const {rerender} = render(<Test step={1} />, options);
 
 		emitReadable(stdin, '\u001B[');
 		rerender(<Test step={2} />);
@@ -942,11 +933,7 @@ test('re-ref stdin when input is used after previous unmount', t => {
 	const onSecondMountInput = spy();
 
 	// First render
-	const {unmount} = render(
-		<Test onInput={onFirstMountInput} />,
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-		options as any,
-	);
+	const {unmount} = render(<Test onInput={onFirstMountInput} />, options);
 
 	t.true(stdin.ref.calledOnce);
 	t.true(stdin.setRawMode.calledOnce);
@@ -965,8 +952,7 @@ test('re-ref stdin when input is used after previous unmount', t => {
 	// Second render with new Ink instance reusing the same stdin
 	const {unmount: unmount2} = render(
 		<Test onInput={onSecondMountInput} />,
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-		options as any,
+		options,
 	);
 
 	t.true(stdin.ref.calledTwice);
@@ -1084,8 +1070,7 @@ test('render different component based on whether stdin is a TTY or not', t => {
 
 	const {rerender} = render(
 		<Test renderFirstInput renderSecondInput />,
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-		options as any,
+		options,
 	);
 
 	t.false(stdin.setRawMode.called);

test/render.tsx

@@ -19,7 +19,15 @@ import ansiEscapes from 'ansi-escapes';
 import stripAnsi from 'strip-ansi';
 import boxen from 'boxen';
 import delay from 'delay';
-import {render, Box, Text, useApp, useCursor, useInput} from '../src/index.js';
+import {
+	render,
+	Box,
+	Text,
+	useApp,
+	useCursor,
+	useInput,
+	type RenderOptions,
+} from '../src/index.js';
 import {type RenderMetrics} from '../src/ink.js';
 import {bsu, esu} from '../src/write-synchronized.js';
 import {createStdin, emitReadable} from './helpers/create-stdin.js';
@@ -2111,3 +2119,71 @@ test.serial('bsu/esu wraps throttledLog trailing call', t => {
 		}
 	});
 });
+
+const createCaptureStream = () => {
+	const writes: string[] = [];
+
+	return {
+		columns: 100,
+		rows: 10,
+		// eslint-disable-next-line @typescript-eslint/naming-convention
+		isTTY: false,
+		write(data: string) {
+			writes.push(data);
+		},
+		output: () => writes.join(''),
+	};
+};
+
+test.serial('accept Node streams in render options', t => {
+	const options: RenderOptions = {
+		stdout: process.stdout,
+		stdin: process.stdin,
+		stderr: process.stderr,
+	};
+
+	t.is(options.stdout, process.stdout);
+	t.is(options.stdin, process.stdin);
+	t.is(options.stderr, process.stderr);
+});
+
+test.serial('render to a stream that only implements what Ink uses', t => {
+	const stdout = createCaptureStream();
+	const stderr = createCaptureStream();
+	const stdin = {
+		on() {},
+		read: () => null,
+	};
+
+	const {unmount} = render(<Text>Hello</Text>, {stdout, stderr, stdin});
+	unmount();
+
+	t.true(stdout.output().includes('Hello'));
+});
+
+test.serial('render to a stream passed as the second argument', t => {
+	const stdout = createCaptureStream();
+
+	const {unmount} = render(<Text>Hello</Text>, stdout);
+	unmount();
+
+	t.true(stdout.output().includes('Hello'));
+});
+
+test.serial(
+	'render to a Node stream passed as the second argument',
+	async t => {
+		const stdout = new PassThrough();
+		let output = '';
+
+		stdout.on('data', (chunk: Uint8Array) => {
+			output += textDecoder.decode(chunk);
+		});
+
+		const {unmount} = render(<Text>Hello</Text>, stdout);
+		unmount();
+		await delay(0);
+
+		t.true(output.includes('Hello'));
+	},
+);