0
# keypress
1

2
The keypress module provides functionality to make any Node.js ReadableStream emit "keypress" events. It extracts the internal keypress logic from Node.js core's readline module and extends it with mouse event support, enabling developers to build interactive terminal applications.
3

4
## Package Information
5

6
- **Package Name**: keypress
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install keypress`
10

11
## Core Imports
12

13
```javascript
14
const keypress = require('keypress');
15
```
16

17
For individual functions:
18

19
```javascript
20
const { enableMouse, disableMouse } = require('keypress');
21
```
22

23
## Basic Usage
24

25
```javascript
26
const keypress = require('keypress');
27

28
// Make process.stdin emit keypress events
29
keypress(process.stdin);
30

31
// Listen for keypress events
32
process.stdin.on('keypress', function (ch, key) {
33
  console.log('Key pressed:', key);
34
  if (key && key.ctrl && key.name == 'c') {
35
    process.stdin.pause();
36
  }
37
});
38

39
// Enable raw mode to capture individual keystrokes
40
process.stdin.setRawMode(true);
41
process.stdin.resume();
42
```
43

44
## Capabilities
45

46
### Stream Enhancement
47

48
Enable keypress and mousepress event emission on any readable stream.
49

50
```javascript { .api }
51
/**
52
 * Make a readable stream emit "keypress" events
53
 * @param {ReadableStream} stream - A readable stream instance to enhance (e.g. process.stdin)
54
 * @returns {undefined}
55
 */
56
function keypress(stream);
57
```
58

59
**Usage Example:**
60

61
```javascript
62
const keypress = require('keypress');
63

64
// Enhance process.stdin
65
keypress(process.stdin);
66

67
// Listen for keypress events
68
process.stdin.on('keypress', function (ch, key) {
69
  console.log('Character:', ch);
70
  console.log('Key object:', key);
71
});
72

73
process.stdin.setRawMode(true);
74
process.stdin.resume();
75
```
76

77
### Mouse Event Control
78

79
Enable and disable mouse event tracking for terminal applications.
80

81
```javascript { .api }
82
/**
83
 * Enable mousepress events on the input stream
84
 * @param {WritableStream} stream - A writable stream instance (typically process.stdout)
85
 * @returns {undefined}
86
 */
87
function enableMouse(stream);
88

89
/**
90
 * Disable mousepress events from being sent to the input stream
91
 * @param {WritableStream} stream - A writable stream instance (typically process.stdout)
92
 * @returns {undefined}
93
 */
94
function disableMouse(stream);
95
```
96

97
**Usage Example:**
98

99
```javascript
100
const keypress = require('keypress');
101

102
// Enable keypress events
103
keypress(process.stdin);
104

105
// Enable mouse tracking
106
keypress.enableMouse(process.stdout);
107

108
// Listen for mouse events
109
process.stdin.on('mousepress', function (mouse) {
110
  console.log('Mouse event at', mouse.x, mouse.y);
111
  console.log('Button:', mouse.button);
112
  if (mouse.release) {
113
    console.log('Mouse button released');
114
  }
115
});
116

117
// Cleanup on exit
118
process.on('exit', function () {
119
  keypress.disableMouse(process.stdout);
120
});
121

122
process.stdin.setRawMode(true);
123
process.stdin.resume();
124
```
125

126
## Events
127

128
### keypress Event
129

130
Emitted when a key is pressed after calling the keypress function on a stream.
131

132
```javascript { .api }
133
/**
134
 * Keypress event handler
135
 * @param {string|undefined} ch - The character pressed (undefined for special keys)
136
 * @param {KeyInfo} key - Key information object
137
 */
138
stream.on('keypress', function(ch, key) { });
139

140
interface KeyInfo {
141
  /** Key name (e.g., 'a', 'return', 'escape', 'up', 'f1') */
142
  name: string;
143
  /** Whether Ctrl key was held */
144
  ctrl: boolean;
145
  /** Whether Meta/Alt key was held */
146
  meta: boolean;
147
  /** Whether Shift key was held */
148
  shift: boolean;
149
  /** Raw escape sequence */
150
  sequence: string;
151
  /** ANSI code for function keys */
152
  code?: string;
153
}
154
```
155

156
**Key Names:**
157

158
- **Standard keys**: `a`-`z`, `0`-`9`
159
- **Special keys**: `return`, `enter`, `tab`, `backspace`, `escape`, `space`
160
- **Arrow keys**: `up`, `down`, `left`, `right`
161
- **Function keys**: `f1`-`f12`
162
- **Navigation**: `home`, `end`, `pageup`, `pagedown`, `insert`, `delete`
163

164
### mousepress Event
165

166
Emitted when mouse events are enabled and a mouse action occurs.
167

168
```javascript { .api }
169
/**
170
 * Mousepress event handler
171
 * @param {MouseInfo} mouse - Mouse event information
172
 */
173
stream.on('mousepress', function(mouse) { });
174

175
interface MouseInfo {
176
  /** Always 'mouse' */
177
  name: string;
178
  /** X coordinate */
179
  x: number;
180
  /** Y coordinate */
181
  y: number;
182
  /** Mouse button (0=left, 1=middle, 2=right), undefined for release/scroll events */
183
  button?: number;
184
  /** Whether Ctrl key was held */
185
  ctrl: boolean;
186
  /** Whether Meta/Alt key was held */
187
  meta: boolean;
188
  /** Whether Shift key was held */
189
  shift: boolean;
190
  /** Whether this is a button release event */
191
  release: boolean;
192
  /** Scroll direction (1=up, -1=down, 0=none) */
193
  scroll: number;
194
  /** Raw escape sequence */
195
  sequence: string;
196
}
197
```
198

199
## Complete Example
200

201
```javascript
202
const keypress = require('keypress');
203

204
// Make stdin emit keypress events
205
keypress(process.stdin);
206

207
// Enable mouse tracking
208
keypress.enableMouse(process.stdout);
209

210
// Handle keyboard input
211
process.stdin.on('keypress', function (ch, key) {
212
  if (key) {
213
    console.log('Key pressed:', {
214
      name: key.name,
215
      char: ch,
216
      ctrl: key.ctrl,
217
      meta: key.meta,
218
      shift: key.shift
219
    });
220

221
    // Exit on Ctrl+C
222
    if (key.ctrl && key.name === 'c') {
223
      console.log('Exiting...');
224
      process.stdin.pause();
225
    }
226
  }
227
});
228

229
// Handle mouse input
230
process.stdin.on('mousepress', function (mouse) {
231
  console.log('Mouse event:', {
232
    x: mouse.x,
233
    y: mouse.y,
234
    button: mouse.button,
235
    release: mouse.release,
236
    scroll: mouse.scroll
237
  });
238
});
239

240
// Cleanup on exit
241
process.on('exit', function () {
242
  keypress.disableMouse(process.stdout);
243
});
244

245
// Start listening
246
process.stdin.setRawMode(true);
247
process.stdin.resume();
248

249
console.log('Press any key or move the mouse. Press Ctrl+C to exit.');
250
```