Restore Cursor

Restore Cursor provides a utility function that gracefully restores the CLI cursor on process exit, preventing hidden cursors from remaining hidden if a process crashes. It automatically detects TTY context and does nothing when run in non-interactive environments.

Package Information

• Package Name: restore-cursor
• Package Type: npm
• Language: JavaScript (with TypeScript definitions)
• Installation: npm install restore-cursor

Core Imports

import restoreCursor from "restore-cursor";

For CommonJS:

const restoreCursor = require("restore-cursor");

Basic Usage

import restoreCursor from "restore-cursor";

// Call once to register the exit handler
restoreCursor();

// The cursor will be automatically restored when the process exits
// even if the process crashes or is terminated with SIGTERM/SIGINT

Architecture

Restore Cursor has a minimal, focused architecture designed around a single responsibility:

• Single Function Export: The package exports one default function for cursor restoration
• Dependency Integration: Leverages onetime for single execution and signal-exit for comprehensive exit handling
• TTY Detection: Automatically detects terminal context (stderr → stdout → no-op fallback)
• Exit Handler Registration: Registers cleanup handlers that execute during various process termination scenarios

The design prioritizes simplicity and reliability, ensuring cursor restoration works across different exit conditions without requiring complex configuration.

Capabilities

Cursor Restoration

Registers an exit handler that restores the CLI cursor visibility using ANSI escape sequences.

/**
 * Gracefully restore the CLI cursor on exit.
 * 
 * Prevent the cursor you have hidden interactively from remaining hidden if the process crashes.
 * It does nothing if run in a non-TTY context.
 * 
 * @returns void - No return value
 * @example
 * ```typescript
 * import restoreCursor from "restore-cursor";
 * 
 * restoreCursor();
 * ```
 */
function restoreCursor(): void;

Key Features:

• TTY Detection: Automatically detects if running in a TTY environment
  • Prefers process.stderr if it's a TTY
  • Falls back to process.stdout if it's a TTY
  • Does nothing (no-op) if neither is a TTY
• One-time Registration: Uses onetime wrapper to ensure handler is only registered once, even if called multiple times
• Comprehensive Exit Handling: Uses signal-exit to handle various process termination scenarios including:
  • Normal process exit
  • SIGTERM signals
  • SIGINT signals (Ctrl+C)
  • Process crashes
• Always Last: Exit handler runs with {alwaysLast: true} option to ensure cursor restoration happens after other cleanup
• ANSI Escape Sequence: Writes \u001B[?25h to show the cursor

Usage Patterns:

// Safe to call multiple times - only registers handler once
restoreCursor();
restoreCursor(); // No additional effect

// Works in any TTY context
console.log("Hiding cursor...");
process.stdout.write("\u001B[?25l"); // Hide cursor
restoreCursor(); // Will restore on exit

// Safe in non-TTY environments (does nothing)
restoreCursor(); // No effect when stdout/stderr are not TTY

Dependencies:

• onetime@^7.0.0: Ensures function runs only once
• signal-exit@^4.1.0: Handles various process exit scenarios