0
# Restore Cursor
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: restore-cursor
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install restore-cursor`
10

11
## Core Imports
12

13
```typescript
14
import restoreCursor from "restore-cursor";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const restoreCursor = require("restore-cursor");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import restoreCursor from "restore-cursor";
27

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

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

35
## Architecture
36

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

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

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

46
## Capabilities
47

48
### Cursor Restoration
49

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

52
```typescript { .api }
53
/**
54
 * Gracefully restore the CLI cursor on exit.
55
 * 
56
 * Prevent the cursor you have hidden interactively from remaining hidden if the process crashes.
57
 * It does nothing if run in a non-TTY context.
58
 * 
59
 * @returns void - No return value
60
 * @example
61
 * ```typescript
62
 * import restoreCursor from "restore-cursor";
63
 * 
64
 * restoreCursor();
65
 * ```
66
 */
67
function restoreCursor(): void;
68
```
69

70
**Key Features:**
71

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

85
**Usage Patterns:**
86

87
```typescript
88
// Safe to call multiple times - only registers handler once
89
restoreCursor();
90
restoreCursor(); // No additional effect
91

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

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

101
**Dependencies:**
102

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