trzsz.js

Making webshell and terminal supports trzsz ( trz / tsz ), which similar to ( rz / sz ), and compatible with tmux.

Why?

Considering laptop -> hostA -> hostB -> docker -> tmux, using scp or sftp is inconvenience.

In this case, lrzsz ( rz / sz ) is convenient to use, but unfortunately it's not compatible with tmux.

tmux is not going to support rz / sz ( 906, 1439 ), and creating a new tools is much easier than patching tmux.

trzsz.js is a js version of trzsz, which supports webshell running in browser, terminal built with electron, etc.

Getting Started

Install the module
```
npm install trzsz
```
or
```
yarn add trzsz
```

Use in Node.js

import { TrzszFilter } from "trzsz";

const { TrzszFilter } = require("trzsz");

Use in browser

<script src="node_modules/trzsz/lib/trzsz.js"></script>

Create TrzszFilter object

const trzszFilter = new TrzszFilter({
  // The trzsz options, see below
});

Generally, the output of the server is forwarded to the terminal. Pass the output through TrzszFilter.

const trzszFilter = new TrzszFilter({
  // The output will be forwarded back by TrzszFilter, unless the user runs ( trz / tsz ) on the server.
  writeToTerminal: (data) => terminal.write(typeof data === "string" ? data : new Uint8Array(data)),
});

// forward the output to TrzszFilter
webSocket.addEventListener("message", (ev) => trzszFilter.processServerOutput(ev.data));

Generally, the user input is forwarded to the server. Pass the user input through TrzszFilter.

const trzszFilter = new TrzszFilter({
  // The user input will be forwarded back by TrzszFilter, unless there are files being transferred.
  sendToServer: (data) => webSocket.send(data),
});

// forward the user input to TrzszFilter
terminal.onData((data) => trzszFilter.processTerminalInput(data));
// forward binary input to TrzszFilter
terminal.onBinary((data) => trzszFilter.processBinaryInput(data));

Let TrzszFilter know the terminal columns for rendering progress bar.

const trzszFilter = new TrzszFilter({
  // initialize the terminal columns
  terminalColumns: terminal.cols,
});

// reset the terminal columns
terminal.onResize((size) => trzszFilter.setTerminalColumns(size.cols));

If there is a windows shell, such as cmd and PowerShell.

const trzszFilter = new TrzszFilter({
  // There is a windows shell
  isWindowsShell: true,
});

If running in Node.js and TrzszFilter can require('fs'), chooseSendFiles and chooseSaveDirectory are required. If running in web browser, they will be ignored. Note that they are async functions.

const trzszFilter = new TrzszFilter({
  // call on the user runs trz ( upload files ) on the server and no error on require('fs').
  chooseSendFiles: async (directory) => {
    // if `directory` is `true`, allow to choose multiple directories and files.
    // otherwise, only allow to choose multiple files.
    // return `undefined` if the user cancels.
    // return an array of file paths choosed by the user.
    return ["/path/to/file1", "/path/to/file2", "/path/to/directory3"];
  },
  // call on the user runs tsz ( download files ) on the server and no error on require('fs').
  chooseSaveDirectory: async () => {
    // return `undefined` if the user cancels.
    // return a directory path choosed by the user.
    return "/path/to/directory";
  },
});

Support dragging files or directories to upload.

terminalHtmlElement.addEventListener("dragover", (event) => event.preventDefault());
terminalHtmlElement.addEventListener("drop", (event) => {
  event.preventDefault();
  trzszFilter
    .uploadFiles(event.dataTransfer.items)
    .then(() => console.log("upload success"))
    .catch((err) => console.log(err));
});

TrzszAddon is a wrapper for TrzszFilter. If you are using xterm-addon-attach, just replace AttachAddon with TrzszAddon.

import { Terminal } from 'xterm';
import { TrzszAddon } from 'trzsz';

const terminal = new Terminal();
const trzszAddon = new TrzszAddon(webSocket);
terminal.loadAddon(trzszAddon);

Examples

Browser web shell example.
Electron terminal app example.
TrzszAddon xterm addon example.

Screenshot

upload and download files in web browser

upload and download files in electron app

Contact

Feel free to email me lonnywong@qq.com.

xytoki/trzsz.js