Usage Guide
Complete API reference for InteractiveManager and InteractiveStreamHook
InteractiveStreamHook
Hooks into a Node.js WriteStream to capture output for interactive terminal applications.
Constructor
import { InteractiveStreamHook } from "@visulima/interactive-manager";
const hook = new InteractiveStreamHook(process.stdout);Methods
active()
Activates the stream hook. All writes to the stream are captured in history.
hook.active();inactive(separateHistory?)
Deactivates the hook and replays captured output.
hook.inactive(); // Replay without separator
hook.inactive(true); // Add newline before replayerase(count)
Erases the specified number of lines from the terminal.
hook.erase(3); // Erase 3 linesrenew()
Restores the original stream write method and shows the cursor.
hook.renew();write(message)
Writes directly to the underlying stream, bypassing the hook.
hook.write("Direct output\n");InteractiveManager
Coordinates stdout and stderr stream hooks for interactive terminal output.
Constructor
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";
const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);Properties
isHooked
Whether the interactive hooks are currently active.
if (manager.isHooked) {
// Interactive mode is active
}isSuspended
Whether interactive mode is temporarily suspended.
if (manager.isSuspended) {
// Hooks are paused
}lastLength
Number of rows last written to the terminal.
console.log(manager.lastLength);outside
Number of rows beyond the terminal height.
console.log(manager.outside);Methods
hook()
Activates both stdout and stderr hooks.
manager.hook();unhook(separateHistory?)
Deactivates hooks and replays captured output.
manager.unhook(); // With history separator
manager.unhook(false); // Without separatorupdate(stream, rows, from?)
Updates the terminal output with new content.
manager.update("stdout", ["Line 1", "Line 2"]);
manager.update("stderr", ["Error output"]);
// Update starting from a specific line
manager.update("stdout", ["Updated"], 2);suspend(stream, erase?)
Temporarily suspends interactive mode.
manager.suspend("stdout"); // Suspend and erase
manager.suspend("stdout", false); // Suspend without erasingresume(stream, eraseRowCount?)
Resumes interactive mode after suspension.
manager.resume("stdout");
manager.resume("stdout", 3); // Erase 3 rows on resumeerase(stream, count?)
Erases lines from the terminal output.
manager.erase("stdout"); // Erase lastLength lines
manager.erase("stdout", 5); // Erase 5 linesStreamType
type StreamType = "stderr" | "stdout";Integration with Spinners
The interactive manager works with @visulima/spinner for animated spinner output:
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";
const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);
manager.hook();
// Render spinner frames
const frames = ["⠋", "⠙", "⠹", "⠸"];
let i = 0;
const interval = setInterval(() => {
manager.update("stdout", [`${frames[i % frames.length]} Loading...`]);
i++;
}, 80);
// Later...
clearInterval(interval);
manager.update("stdout", ["✓ Done!"]);
manager.unhook(false);Integration with Progress Bars
Works with @visulima/progress-bar for progress tracking:
import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";
import { ProgressBar } from "@visulima/progress-bar";
const stdoutHook = new InteractiveStreamHook(process.stdout);
const stderrHook = new InteractiveStreamHook(process.stderr);
const manager = new InteractiveManager(stdoutHook, stderrHook);
const bar = new ProgressBar({ total: 100 }, manager);
bar.start();
bar.update(50);
bar.stop();