ttty

A dead simple lightweight TypeScript terminal "emulator" that mimics terminal behaviour in browser.

Features:

Tiny, dependency-free and built with modern JS
Easy-to-add custom commands
Events
Command history
Command arguments with validation
"Foreground processes" imitation

Usage

With module bundler

Add the latest release with:

npm install ttty or yarn add ttty

Initialize the terminal in a particular DOM element with:

import { initTerminal } from 'ttty'

// ...

const terminal = initTerminal({ /* settings */ })

In a browser directly

<!-- As a global JS file -->
<script src="https://unpkg.com/ttty/dist/ttty.iife.js"></script>

ttty.initTerminal({ /* settings */ })

Initialize with parameters:

const settings = {
    host: document.querySelector("#terminal"),
    prompt: "user@ttty:~$ ",
    commands: {
        echo: {
            name: "echo", 
            description: "a test command with one echo arg", 
            argDescriptions: ["a string to be echoed in console"],
            func: ({ print }, argument) => { print(argument) } 
        },
        test: {
            name: "test", 
            description: "a test command with no args", 
            func: ({ print }) => { print("foo") } 
        },
        multiply: {
            name: "multiply",
            description: "Multiply two numbers",
            argDescriptions: ["number one", "number two"],
            func: ({ print }, one, two) => { print(Number(one) * Number(two)) }
        }
    }
}

initTerminal(settings)

Working with the terminal

help - Display a list of all commands with descriptions

command - Execute a command. Will display "Usage: command [parameter 1 description] [parameter 2 description], etc.", when it requires arguments but is called without them.

API

initTerminal

Method	Description	Parameters
`init(settings)`	Initialize a terminal in a given DOM element	`settings` object.

terminal

An object that's being passed to every command function & returned by initTerminal

Method	Description	Parameters
`print(text, isCommand, scrollIntoView)`	Prints a given text in the terminal (accepts raw HTML)	`text` - String, `isCommand` - Boolean, optional, defaults to false. Count given string as a command (displays prompt & syntax highlight)
`run(text)`	Emulates a command execution in a terminal (acts the same way as a user would have typed and pressed Enter)	`text` - String
`start()`	Starts a "foreground process": user input is blocked and command prompt never appears.
`stop()`	Stops "foreground process".
`type(text, speed, isCommand) => Promise<boolean>`	Prints a text with "typing" effect. Hides and blocks user input while typing. Resolves to either `true` or `false` depending on process interruption by the user.	`text` - String, text to be printed. `speed` - integer, miliseconds. The higher the number, the slower. `isCommand` - Boolean, optional, defaults to false. Count given string as a command (displays prompt & syntax highlight)
`setPrompt()`	Set terminal prompt	`newPrompt` - String

settings object

Parameter	Description	Default
`host`: DOM element	A DOM element to initialize terminal in.
`welcomeMessage`: string	A welcome message that is being printed on initialization
`enableHelp`: boolean	Toggle default `help` command that lists all the available commands and their descriptions.	true
`prompt`: string	Terminal prompt	'$: '
`historyLength`: number	A maximum amount of commands that can be stored in the terminal history	50
`history`: string[]	A default value for terminal history (can be used to preserve history across sessions)	[]
`commands`: object	`commands` object

commands object

Parameter	Description
`name`: string	Command name.
`description`: string	Command description, used for the default `help` command (when enabled).
`argDescriptions`: string array	Array of strings that describe command line arguments in order of appearance.
`func`: function(terminal, ...arguments)	Function. Accepts an array of parameters in order of appearance (i.e. `function(terminal, one, two)` will correspond to two arguments passed as `command one two`)

Events

Event	Description
`onInit`	Terminal initialization
`onCommand`	Existing command executed
`onCommand404`	Non-existing command executed
`onProcessStart`	Process started
`onProcessStop`	Process stopped
`onProcessInterrupt`	Process interrupted with a keyboard

Events are being dispatched by the DOM element passed on init, for example:

const term = document.getElementById('terminal');
term.addEventListener('onCommand', e => console.log("known command executed!"));

Custom styling

You can customize the look defining custom CSS variables. If you have multiple instances, you can even have each instance in its' own style!

Variable	Description
`--terminal-bg-color`	Background color
`--terminal-fg-color`	Text color
`--terminal-font`	Terminal font-family
`--terminal-accent-color`	Accent color
`--terminal-error-color`	Error color

Browser compatibility

ttty is built and distributed with ES6 in mind (including the minified package). You can always transpile & bundle it targeting your browser set of choice.

Browsers that do not support CSS variables (IE < 11) might not be able to make use of custom themes. In order to use ttty with older browsers please rebuild this with custom properties removed.

mkrl/ttty