scroll/src/common/types.ts

import { RunTimeType } from './runtime.ts';

export { Position } from './position.ts';

/**
 * The size of terminal in rows and columns
 */
export interface ITerminalSize {
	rows: number;
	cols: number;
}

/**
 * Which direction to search in the current document
 */
export enum SearchDirection {
	Forward = 1,
	Backward = -1,
}

// ----------------------------------------------------------------------------
// Runtime adapter interfaces
// ----------------------------------------------------------------------------

/**
 * Runtime-specific terminal functionality
 */
export interface ITerminal {
	/**
	 * The arguments passed to the program on launch
	 */
	argv: string[];

	/**
	 * The generator function returning chunks of input from the stdin stream
	 */
	inputLoop(): AsyncGenerator<Uint8Array, null>;

	/**
	 * Get the size of the terminal
	 */
	getTerminalSize(): Promise<ITerminalSize>;

	/**
	 * Get the current chunk of input, if it exists
	 */
	readStdin(): Promise<string | null>;

	/**
	 * Get the raw chunk of input
	 */
	readStdinRaw(): Promise<Uint8Array | null>;

	/**
	 * Pipe a string to stdout
	 */
	writeStdout(s: string): Promise<void>;
}

/**
 * Runtime-specific file system io
 */
export interface IFileIO {
	/**
	 * Open an entire file
	 *
	 * @param path
	 */
	openFile(path: string): Promise<string>;

	/**
	 * Append to a file, or create it if it doesn't exist
	 *
	 * @param path
	 * @param contents
	 */
	appendFile(path: string, contents: string): Promise<void>;

	/**
	 * Save a string into a file
	 *
	 * @param path
	 * @param contents
	 */
	saveFile(path: string, contents: string): Promise<void>;
}

/**
 * The common interface for runtime adapters
 */
export interface IRuntime {
	/**
	 * The name of the runtime
	 */
	name: RunTimeType;

	/**
	 * Runtime-specific terminal functionality
	 */
	term: ITerminal;

	/**
	 * Runtime-specific file system io
	 */
	file: IFileIO;

	/**
	 * Set up an event handler
	 *
	 * @param eventName - The event to listen for
	 * @param handler - The event handler
	 */
	onEvent: (
		eventName: string,
		handler: (e: Event | ErrorEvent) => void,
	) => void;

	/**
	 * Set a beforeExit/beforeUnload event handler for the runtime
	 * @param cb - The event handler
	 */
	onExit(cb: () => void): void;

	/**
	 * Stop execution
	 *
	 * @param code
	 */
	exit(code?: number): void;
}

// ----------------------------------------------------------------------------
// Testing
// ----------------------------------------------------------------------------

/**
 * The shared test interface, so tests can be run by both runtimes
 */
export interface ITestBase {
	/**
	 * The values (often objects) have all the same property values
	 *
	 * @param actual
	 * @param expected
	 */
	assertEquivalent(actual: unknown, expected: unknown): void;

	/**
	 * The value is not null or undefined
	 *
	 * @param actual
	 */
	assertExists(actual: unknown): void;

	/**
	 * The value is false
	 *
	 * @param actual
	 */
	assertFalse(actual: boolean): void;

	/**
	 * `actual` is an object implementing `expectedType`
	 *
	 * @param actual
	 * @param expectedType
	 */
	assertInstanceOf(actual: unknown, expectedType: any): void;

	/**
	 * The values are not exactly equal (Different instance, type, value, etc)
	 *
	 * @param actual
	 * @param expected
	 */
	assertNotEquals(actual: unknown, expected: unknown): void;

	/**
	 * The values are exactly the same
	 *
	 * @param actual
	 * @param expected
	 */
	assertEquals(actual: unknown, expected: unknown): void;

	/**
	 * The value is true
	 *
	 * @param actual
	 */
	assertTrue(actual: boolean): void;
	testSuite(testObj: any): void;
}