Terminal Emulator

-

Inspired by .

• Installation
• Documentation
• Example usage
  • Browser
  • React
• Do's and don'ts
• Performance

Installation

You can install it via your preferred package manager:

npm i --save unix-terminal-emulator

yarn add unix-terminal-emulator

You can use the CDN version for simple imports in HTML:

<script src="https://unpkg.com/unix-terminal-emulator@latest/dist/core.js"></script>

Documentation

Checkout the wiki of this repository for the documentation. Generated with TypeDoc!

Example usage

For more advanced examples, please click this link.

Browser

import UnixTerminalEmulator from "unix-terminal-emulator"

const terminal = new UnixTerminalEmulator()
const command = {
	text: "echo Hello, World!",
	writeSpeed: "neutral",
	output: "Hello, World!",
	pauseBeforeOutput: 500,
}
terminal.writeCommand(command).run(() => {
	console.log("Done!")
})

React

import React from "react"
import UnixTerminalEmulator from "unix-terminal-emulator"

export default function App() {
	const command = {
		text: "echo Hello, World!",
		writeSpeed: "neutral",
		output: "Hello, World!",
		pauseBeforeOutput: 500,
	}
	return (
		<div className="App">
			<UnixTerminalEmulator
				onInit={emulator => {
					emulator.writeCommand(command).run(() => {
						console.log("Done!")
					})
				}}
			/>
		</div>
	)
}

Do's and don'ts

Below are a few examples of do's and don'ts regarding building a command sequence.

const terminal = new UnixTerminalEmulator()

:heavy_check_mark: Chain the commands you want to run in sequence before calling run (this is by design):

// Chaining commands is by design
terminal
	.writeCommand({
		text: "echo foo",
		writeSpeed: "neutral",
		output: "foo",
		pauseBeforeOutput: 500,
	})
	.pause(1000)
	.writeCommand({
		text: "echo bar",
		writeSpeed: "neutral",
		output: "bar",
		pauseBeforeOutput: 500,
	})
	.run()

:heavy_check_mark: Call the sequence building commands in a non-chain fashion, as long as the run method is called last (this is by design):

terminal.writeCommand({
	text: "echo foo",
	writeSpeed: "neutral",
	output: "foo",
	pauseBeforeOutput: 500,
})
terminal.pause(1000)
terminal.writeCommand({
	text: "echo bar",
	writeSpeed: "neutral",
	output: "bar",
	pauseBeforeOutput: 500,
})
terminal.run()

:warning: Adding commands to the sequence BEFORE run has finished will queue them for the current sequence (this is timing dependent and not recommended).

terminal
	.writeCommand({
		text: "echo foo",
		writeSpeed: "neutral",
		output: "foo",
		pauseBeforeOutput: 500,
	})
	.run()
// The command added bellow will be added to the current sequence
terminal.writeCommand({
	text: "echo bar",
	writeSpeed: "neutral",
	output: "bar",
	pauseBeforeOutput: 500,
})
// The command bellow in the setTimeout will not run in the first sequence, a new call to the run method is required in order to run it
setTimeout(() => {
	terminal.writeCommand({
		text: "echo baz",
		writeSpeed: "neutral",
		output: "baz",
		pauseBeforeOutput: 500,
	})
}, 10000)

:x: Calling the run method on a terminal instance before the previous call has finished will result in unexpected behavior

terminal
	.writeCommand({
		text: "echo foo",
		writeSpeed: "neutral",
		output: "foo",
		pauseBeforeOutput: 500,
	})
	.writeCommand({
		text: "echo bar",
		writeSpeed: "neutral",
		output: "bar",
		pauseBeforeOutput: 500,
	})
	.run()
terminal.run() // this brakes the sequence and will result in unexpected behavior

:x: Creating 2 terminal instances with the same wrapper and cursor ID will result in unexpected behavior

const terminal1 = new UnixTerminalEmulator({
	wrapperId: "same-wrapper-id",
	cursorId: "same-cursor-id",
})
const terminal2 = new UnixTerminalEmulator({
	wrapperId: "same-wrapper-id",
	cursorId: "same-cursor-id",
})
terminal1
	.writeCommand({
		text: "echo foo",
		writeSpeed: "neutral",
		output: "foo",
		pauseBeforeOutput: 500,
	})
	.run()
terminal2
	.writeCommand({
		text: "echo foo",
		writeSpeed: "neutral",
		output: "foo",
		pauseBeforeOutput: 500,
	})
	.run()

Performance

Bellow are performance charts based on different versions of the app. Click here for a detailed explanation about how the performance was tested. Click here for an interactive version of the graphs.

| Time per Run in MS | Time per Command in MS | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | | |