trzsz2 1.0.0

package/dist/cjs-full/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+export { trzszVersion } from './comm';
+export type { TrzszFile, TrzszFileReader, TrzszFileWriter, OpenSaveFile, ProgressCallback, TmuxModeType } from './comm';
+export type { TrzszOptions } from './options';
+export { TrzszError } from './comm';
+export { TrzszBuffer } from './buffer';
+export { TrzszTransfer } from './transfer';
+export { TextProgressBar } from './progress';
+export { strToUint8, uint8ToStr, strToArrBuf, encodeBuffer, decodeBuffer, checkDuplicateNames, isArrayOfType, isVT100End, stripServerOutput, formatSavedFiles, stripTmuxStatusLine, TmuxMode } from './comm';
+export { getEscapeChars, escapeCharsToCodes, escapeData, unescapeData } from './escape';
+export { getEllipsisString } from './progress';

package/dist/cjs-full/options.d.ts

@@ -0,0 +1,57 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+/**
+ * The trzsz options interface.
+ */
+export interface TrzszOptions {
+    /**
+     * Write the server output to the terminal.
+     * @param output - The server output.
+     */
+    writeToTerminal?: (output: string | ArrayBuffer | Uint8Array | Blob) => void;
+    /**
+     * Send the terminal input (aka: user input) to the server.
+     * @param input - The terminal input (aka: user input).
+     */
+    sendToServer?: (input: string | Uint8Array) => void;
+    /**
+     * Choose some files to be sent to the server.
+     * No need for webshell or which running in a browser.
+     * @param directory - choose directories and files, or just files.
+     * @return The file paths array to be sent.
+     *         undefined means the user has cancelled.
+     */
+    chooseSendFiles?: (directory?: boolean) => Promise<string[] | undefined>;
+    /**
+     * Choose a directory to save the received files.
+     * No need for webshell or which running in a browser.
+     * @return The directory to save the received files.
+     *         undefined means the user has cancelled.
+     */
+    chooseSaveDirectory?: () => Promise<string | undefined>;
+    /**
+     * @deprecated A user event may be required to open the save dialog in browsers.
+     * No need for nodejs environment ( e.g.: electron preload.js )
+     * @param fileName - The file name going to download.
+     * @return open the save dialog or cancel the download.
+     */
+    requireUserPermission?: (fileName: string) => Promise<boolean>;
+    /**
+     * The columns of terminal.
+     */
+    terminalColumns?: number;
+    /**
+     * Is there a windows shell? Such as `cmd` and `PowerShell`.
+     */
+    isWindowsShell?: boolean;
+    /**
+     * The timeout in milliseconds for initializing drag and drop files to upload.
+     * Default is 3000.
+     */
+    dragInitTimeout?: number | undefined | null;
+}

package/dist/cjs-full/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs-full/progress.d.ts

@@ -0,0 +1,100 @@
+import { ProgressCallback } from './comm';
+/**
+ * Get ellipsis string if the string is too long.
+ * @param str - The input string.
+ * @param max - The maximum length.
+ * @return The ellipsis string and its length.
+ */
+export declare function getEllipsisString(str: string, max: number): {
+    sub: string;
+    len: number;
+};
+/**
+ * TextProgressBar class for displaying file transfer progress.
+ */
+export declare class TextProgressBar implements ProgressCallback {
+    private readonly writer;
+    private lastUpdateTime;
+    private columns;
+    private fileCount;
+    private fileIdx;
+    private fileName;
+    private fileSize;
+    private fileStep;
+    private startTime;
+    private tmuxPaneColumns;
+    private firstWrite;
+    private speedCnt;
+    private speedIdx;
+    private timeArray;
+    private stepArray;
+    /**
+     * Create a TextProgressBar.
+     * @param writer - The output writer function.
+     * @param columns - The terminal columns.
+     * @param tmuxPaneColumns - The tmux pane columns (optional).
+     */
+    constructor(writer: (output: string) => void, columns: number, tmuxPaneColumns?: number | undefined);
+    /**
+     * Set the terminal columns.
+     * @param columns - The terminal columns.
+     */
+    setTerminalColumns(columns: number): void;
+    /**
+     * Called when the number of files is known.
+     * @param num - The number of files.
+     */
+    onNum(num: number): void;
+    /**
+     * Called when a file name is known.
+     * @param name - The file name.
+     */
+    onName(name: string): void;
+    /**
+     * Called when the file size is known.
+     * @param size - The file size.
+     */
+    onSize(size: number): void;
+    /**
+     * Called when a step is completed.
+     * @param step - The step number.
+     */
+    onStep(step: number): void;
+    /**
+     * Hide the cursor.
+     */
+    hideCursor(): void;
+    /**
+     * Show the cursor.
+     */
+    showCursor(): void;
+    /**
+     * Show the progress.
+     */
+    private showProgress;
+    /**
+     * Get the current transfer speed.
+     * @param now - The current time.
+     * @return The speed in bytes per second.
+     */
+    private getSpeed;
+    /**
+     * Get the progress text.
+     * @param percentage - The percentage string.
+     * @param total - The total string.
+     * @param speed - The speed string.
+     * @param eta - The ETA string.
+     * @return The progress text.
+     */
+    private getProgressText;
+    /**
+     * Get the progress bar string.
+     * @param len - The length of the bar.
+     * @return The progress bar string.
+     */
+    private getProgressBar;
+    /**
+     * Called when the transfer is done.
+     */
+    onDone(): void;
+}

package/dist/cjs-full/transfer.d.ts

@@ -0,0 +1,259 @@
+import { OpenSaveFile, TrzszFileReader, ProgressCallback } from './comm';
+/**
+ * TrzszTransfer class for handling file transfer protocol.
+ */
+export declare class TrzszTransfer {
+    private readonly buffer;
+    private readonly writer;
+    private readonly isWindowsShell;
+    private remoteIsWindows;
+    private lastInputTime;
+    private readonly openedFiles;
+    private readonly createdFiles;
+    private tmuxOutputJunk;
+    private cleanTimeoutInMilliseconds;
+    private transferConfig;
+    private stopped;
+    private maxChunkTimeInMilliseconds;
+    private protocolNewline;
+    /**
+     * Create a TrzszTransfer.
+     * @param writer - The output writer function.
+     * @param isWindowsShell - Whether the shell is Windows.
+     */
+    constructor(writer: (data: string | Uint8Array) => void, isWindowsShell?: boolean);
+    /**
+     * Cleanup resources.
+     */
+    cleanup(): void;
+    /**
+     * Add received data to the buffer.
+     * @param data - The received data.
+     */
+    addReceivedData(data: string | ArrayBuffer | Uint8Array | Blob): void;
+    /**
+     * Stop transferring.
+     */
+    stopTransferring(): Promise<void>;
+    /**
+     * Clean input buffer.
+     * @param timeoutInMilliseconds - The timeout in milliseconds.
+     */
+    private cleanInput;
+    /**
+     * Send a line.
+     * @param typ - The type.
+     * @param buf - The buffer.
+     */
+    private sendLine;
+    /**
+     * Receive a line.
+     * @param expectType - The expected type.
+     * @param mayHasJunk - Whether there may be junk.
+     */
+    private recvLine;
+    /**
+     * Receive and check a line.
+     * @param expectType - The expected type.
+     * @param mayHasJunk - Whether there may be junk.
+     */
+    private recvCheck;
+    /**
+     * Send an integer.
+     * @param typ - The type.
+     * @param val - The value.
+     */
+    private sendInteger;
+    /**
+     * Receive an integer.
+     * @param typ - The type.
+     * @param mayHasJunk - Whether there may be junk.
+     */
+    private recvInteger;
+    /**
+     * Check an integer.
+     * @param expect - The expected value.
+     */
+    private checkInteger;
+    /**
+     * Send a string.
+     * @param typ - The type.
+     * @param str - The string.
+     */
+    private sendString;
+    /**
+     * Receive a string.
+     * @param typ - The type.
+     * @param mayHasJunk - Whether there may be junk.
+     */
+    private recvString;
+    /**
+     * Check a string.
+     * @param expect - The expected string.
+     */
+    protected checkString(expect: string): Promise<void>;
+    /**
+     * Send binary data.
+     * @param typ - The type.
+     * @param buf - The buffer.
+     */
+    private sendBinary;
+    /**
+     * Receive binary data.
+     * @param typ - The type.
+     * @param mayHasJunk - Whether there may be junk.
+     */
+    private recvBinary;
+    /**
+     * Check binary data.
+     * @param expect - The expected buffer.
+     */
+    private checkBinary;
+    /**
+     * Send data.
+     * @param data - The data.
+     * @param binary - Whether to use binary mode.
+     * @param escapeCodes - The escape codes.
+     */
+    private sendData;
+    /**
+     * Receive data.
+     * @param binary - Whether to use binary mode.
+     * @param escapeCodes - The escape codes.
+     * @param timeoutInMilliseconds - The timeout in milliseconds.
+     */
+    private recvData;
+    /**
+     * Send action.
+     * @param confirm - Whether to confirm.
+     * @param remoteIsWindows - Whether the remote is Windows.
+     */
+    sendAction(confirm: boolean, remoteIsWindows: boolean): Promise<void>;
+    /**
+     * Receive action.
+     */
+    recvAction(): Promise<Record<string, unknown>>;
+    /**
+     * Send config.
+     * @param args - The config arguments.
+     * @param escapeChars - The escape characters.
+     * @param tmuxMode - The tmux mode.
+     * @param tmuxPaneWidth - The tmux pane width.
+     */
+    sendConfig(args: Record<string, unknown>, escapeChars: string[][], tmuxMode: number, tmuxPaneWidth: number): Promise<void>;
+    /**
+     * Receive config.
+     */
+    recvConfig(): Promise<Record<string, unknown>>;
+    /**
+     * Send client exit.
+     * @param msg - The message.
+     */
+    clientExit(msg: string): Promise<void>;
+    /**
+     * Receive exit.
+     */
+    recvExit(): Promise<string>;
+    /**
+     * Delete created files.
+     */
+    private deleteCreatedFiles;
+    /**
+     * Handle client error.
+     * @param err - The error.
+     */
+    clientError(err: Error): Promise<void>;
+    /**
+     * Handle server error.
+     * @param err - The error.
+     */
+    serverError(err: Error): Promise<void>;
+    /**
+     * Server exit - to be implemented by subclass or user.
+     * @param msg - The message.
+     */
+    serverExit(_msg: string): Promise<void>;
+    /**
+     * Send file number.
+     * @param num - The number of files.
+     * @param progressCallback - The progress callback.
+     */
+    private sendFileNum;
+    /**
+     * Send file name.
+     * @param file - The file reader.
+     * @param directory - Whether it's a directory.
+     * @param progressCallback - The progress callback.
+     */
+    private sendFileName;
+    /**
+     * Send file size.
+     * @param size - The file size.
+     * @param progressCallback - The progress callback.
+     */
+    private sendFileSize;
+    /**
+     * Send file data.
+     * @param file - The file reader.
+     * @param size - The file size.
+     * @param binary - Whether to use binary mode.
+     * @param escapeCodes - The escape codes.
+     * @param maxBufSize - The maximum buffer size.
+     * @param progressCallback - The progress callback.
+     */
+    private sendFileData;
+    /**
+     * Send file MD5.
+     * @param digest - The MD5 digest.
+     * @param progressCallback - The progress callback.
+     */
+    private sendFileMD5;
+    /**
+     * Send files.
+     * @param files - The file readers.
+     * @param progressCallback - The progress callback.
+     */
+    sendFiles(files: TrzszFileReader[], progressCallback: ProgressCallback | null): Promise<string[]>;
+    /**
+     * Receive file number.
+     * @param progressCallback - The progress callback.
+     */
+    private recvFileNum;
+    /**
+     * Receive file name.
+     * @param saveParam - The save parameter.
+     * @param openSaveFile - The open save file function.
+     * @param directory - Whether it's a directory.
+     * @param overwrite - Whether to overwrite.
+     * @param progressCallback - The progress callback.
+     */
+    private recvFileName;
+    /**
+     * Receive file size.
+     * @param progressCallback - The progress callback.
+     */
+    private recvFileSize;
+    /**
+     * Receive file data.
+     * @param file - The file writer.
+     * @param size - The file size.
+     * @param binary - Whether to use binary mode.
+     * @param escapeCodes - The escape codes.
+     * @param timeoutInMilliseconds - The timeout in milliseconds.
+     * @param progressCallback - The progress callback.
+     */
+    private recvFileData;
+    /**
+     * Receive file MD5.
+     * @param digest - The MD5 digest.
+     * @param progressCallback - The progress callback.
+     */
+    private recvFileMD5;
+    /**
+     * Receive files.
+     * @param saveParam - The save parameter.
+     * @param openSaveFile - The open save file function.
+     * @param progressCallback - The progress callback.
+     */
+    recvFiles(saveParam: unknown, openSaveFile: OpenSaveFile, progressCallback: ProgressCallback | null): Promise<string[]>;
+}

package/dist/comm.d.ts

@@ -0,0 +1,162 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+/**
+ * trzsz version
+ */
+export declare const trzszVersion = "2.0.0";
+/**
+ * Convert a string to Uint8Array.
+ * @param {string} str - The input string.
+ * @return {Uint8Array} The resulting Uint8Array.
+ */
+export declare function strToUint8(str: string): Uint8Array;
+/**
+ * Convert a Uint8Array to string.
+ * @param {Uint8Array} buf - The input buffer.
+ * @param {string} encoding - The encoding to use.
+ * @return {Promise<string>} The resulting string.
+ */
+export declare function uint8ToStr(buf: Uint8Array, encoding?: string): Promise<string>;
+/**
+ * Convert a string to ArrayBuffer.
+ * @param {string} str - The input string.
+ * @return {ArrayBuffer} The resulting ArrayBuffer.
+ */
+export declare function strToArrBuf(str: string): ArrayBuffer;
+/**
+ * Encode a buffer (compress and base64).
+ * @param {string | Uint8Array} buf - The input buffer.
+ * @return {string} The encoded string.
+ */
+export declare function encodeBuffer(buf: string | Uint8Array): string;
+/**
+ * Decode a buffer (base64 and decompress).
+ * @param {string} buf - The encoded string.
+ * @return {Uint8Array} The decoded buffer.
+ */
+export declare function decodeBuffer(buf: string): Uint8Array;
+/**
+ * Custom error class for trzsz operations.
+ */
+export declare class TrzszError extends Error {
+    private readonly type;
+    private readonly trace;
+    constructor(message: string, type?: string | null, trace?: boolean);
+    /**
+     * Check if the error should include traceback.
+     * @return {boolean} True if traceback should be included.
+     */
+    isTraceBack(): boolean;
+    /**
+     * Check if the error is a remote exit.
+     * @return {boolean} True if remote exit.
+     */
+    isRemoteExit(): boolean;
+    /**
+     * Check if the error is a remote failure.
+     * @return {boolean} True if remote failure.
+     */
+    isRemoteFail(): boolean;
+    /**
+     * Check if the error indicates stop and delete.
+     * @return {boolean} True if stop and delete.
+     */
+    isStopAndDelete(): boolean;
+    /**
+     * Get the error message.
+     * @param {Error} err - The error object.
+     * @return {string} The error message.
+     */
+    static getErrorMessage(err: Error): string;
+}
+/**
+ * Interface for trzsz file operations.
+ */
+export interface TrzszFile {
+    closeFile: () => void;
+}
+/**
+ * Interface for trzsz file reader.
+ */
+export interface TrzszFileReader extends TrzszFile {
+    getPathId: () => number;
+    getRelPath: () => string[];
+    isDir: () => boolean;
+    getSize: () => number;
+    readFile: (buf: ArrayBuffer) => Promise<Uint8Array>;
+}
+/**
+ * Interface for trzsz file writer.
+ */
+export interface TrzszFileWriter extends TrzszFile {
+    getFileName: () => string;
+    getLocalName: () => string;
+    isDir: () => boolean;
+    writeFile: (buf: Uint8Array) => Promise<void>;
+    deleteFile: () => Promise<string>;
+}
+/**
+ * Type for opening save file.
+ */
+export type OpenSaveFile = (saveParam: any, fileName: string, directory: boolean, overwrite: boolean) => Promise<TrzszFileWriter>;
+/**
+ * Interface for progress callback.
+ */
+export interface ProgressCallback {
+    onNum: (num: number) => void;
+    onName: (name: string) => void;
+    onSize: (size: number) => void;
+    onStep: (step: number) => void;
+    onDone: () => void;
+}
+/**
+ * Check for duplicate file names.
+ * @param {TrzszFileReader[]} files - The files to check.
+ */
+export declare function checkDuplicateNames(files: TrzszFileReader[]): void;
+/**
+ * Check if an array contains only elements of a specific type.
+ * @param {any} arr - The array to check.
+ * @param {string} type - The type to check for.
+ * @return {boolean} True if all elements are of the specified type.
+ */
+export declare function isArrayOfType(arr: any, type: string): boolean;
+/**
+ * Check if a character is a VT100 end character.
+ * @param {number} c - The character code.
+ * @return {boolean} True if it's a VT100 end character.
+ */
+export declare function isVT100End(c: number): boolean;
+/**
+ * Strip VT100 escape sequences from server output.
+ * @param {string | ArrayBuffer | Uint8Array | Blob} output - The server output.
+ * @return {string | ArrayBuffer | Uint8Array | Blob} The stripped output.
+ */
+export declare function stripServerOutput(output: string | ArrayBuffer | Uint8Array | Blob): string | ArrayBuffer | Uint8Array | Blob;
+/**
+ * Tmux mode constants.
+ */
+export declare const TmuxMode: {
+    readonly NoTmux: 0;
+    readonly TmuxNormalMode: 1;
+    readonly TmuxControlMode: 2;
+};
+export type TmuxModeType = (typeof TmuxMode)[keyof typeof TmuxMode];
+/**
+ * Format saved files message.
+ * @param {string[]} fileNames - The file names.
+ * @param {string} destPath - The destination path.
+ * @return {string} The formatted message.
+ */
+export declare function formatSavedFiles(fileNames: string[], destPath: string): string;
+/**
+ * Strip tmux status line from buffer.
+ * @param {string} buf - The input buffer.
+ * @return {string} The stripped buffer.
+ */
+export declare function stripTmuxStatusLine(buf: string): string;

package/dist/escape.d.ts

@@ -0,0 +1,33 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+/**
+ * Get escape characters for trzsz protocol.
+ * @param escapeAll - Whether to escape all special characters.
+ * @return Array of escape character pairs.
+ */
+export declare function getEscapeChars(escapeAll: boolean): string[][];
+/**
+ * Convert escape characters to codes.
+ * @param escapeChars - Array of escape character pairs.
+ * @return Array of escape code triplets.
+ */
+export declare function escapeCharsToCodes(escapeChars: string[][]): number[][];
+/**
+ * Escape data using escape codes.
+ * @param data - The data to escape.
+ * @param escapeCodes - Array of escape code triplets.
+ * @return The escaped data.
+ */
+export declare function escapeData(data: Uint8Array, escapeCodes: number[][]): Uint8Array;
+/**
+ * Unescape data using escape codes.
+ * @param data - The data to unescape.
+ * @param escapeCodes - Array of escape code triplets.
+ * @return The unescaped data.
+ */
+export declare function unescapeData(data: Uint8Array, escapeCodes: number[][]): Uint8Array;