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.