0
# Keycode
1

2
Keycode is a JavaScript utility library that provides intelligent conversion between keyboard keycodes, key names, and keyboard events. It automatically detects input types and returns appropriate conversions, with comprehensive mappings for all standard keyboard keys and common aliases.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
ES modules:
18
```javascript
19
import keycode from 'keycode';
20
```
21

22
TypeScript:
23
```typescript
24
import keycode from 'keycode';
25
// or with explicit typing
26
import * as keycode from 'keycode';
27
```
28

29
## Basic Usage
30

31
```javascript
32
const keycode = require('keycode');
33

34
// Convert from keyboard event to key name
35
document.addEventListener('keydown', function(e) {
36
  console.log('You pressed:', keycode(e)); // e.g., "enter"
37
});
38

39
// Convert from keycode number to key name
40
console.log(keycode(13)); // => "enter"
41

42
// Convert from key name to keycode number
43
console.log(keycode('enter')); // => 13
44
console.log(keycode('Enter')); // => 13 (case insensitive)
45

46
// Test if event matches specific key
47
document.addEventListener('keydown', function(e) {
48
  if (keycode.isEventKey(e, 'enter')) {
49
    console.log('Enter key was pressed!');
50
  }
51
});
52
```
53

54
## Capabilities
55

56
### Main Conversion Function
57

58
The primary keycode function intelligently detects input type and returns appropriate conversion.
59

60
```javascript { .api }
61
/**
62
 * Main keycode conversion function with intelligent type detection
63
 * @param {Event|number|string} searchInput - Event object, numeric keycode, or key name
64
 * @returns {string|number|undefined} Converted value or undefined for unknown inputs
65
 */
66
function keycode(searchInput: Event): string;
67
function keycode(searchInput: number): string;
68
function keycode(searchInput: string): number;
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
// From keyboard event
75
document.addEventListener('keydown', (e) => {
76
  keycode(e); // => "enter", "space", "a", etc.
77
});
78

79
// From numeric keycode
80
keycode(13);    // => "enter"
81
keycode(32);    // => "space"
82
keycode(65);    // => "a"
83

84
// From key name (case insensitive)
85
keycode('enter');     // => 13
86
keycode('SPACE');     // => 32
87
keycode('ctrl');      // => 17
88
keycode('f1');        // => 112
89

90
// Single character strings
91
keycode('a');         // => 65
92
keycode('Z');         // => 90
93

94
// Unknown inputs
95
keycode('unknown');   // => undefined
96
keycode(999);         // => undefined
97
```
98

99
### Event Key Testing
100

101
Compares a keyboard event against a specific key name or keycode.
102

103
```javascript { .api }
104
/**
105
 * Tests if a keyboard event matches the given key name or keycode
106
 * @param {Event} event - Keyboard event to test
107
 * @param {string|number} nameOrCode - Key name or numeric keycode to compare
108
 * @returns {boolean} True if event matches the key, false otherwise
109
 */
110
keycode.isEventKey(event: Event, nameOrCode: string | number): boolean;
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
document.addEventListener('keydown', (e) => {
117
  // Test by key name
118
  if (keycode.isEventKey(e, 'enter')) {
119
    console.log('Enter pressed!');
120
  }
121
  
122
  // Test by keycode
123
  if (keycode.isEventKey(e, 13)) {
124
    console.log('Enter pressed!');
125
  }
126
  
127
  // Test with aliases
128
  if (keycode.isEventKey(e, 'ctrl') || keycode.isEventKey(e, 'control')) {
129
    console.log('Control key pressed!');
130
  }
131
});
132
```
133

134
### Key Mappings
135

136
Access to the underlying key mapping objects for direct lookups.
137

138
```javascript { .api }
139
/**
140
 * Map from key names to numeric keycodes
141
 */
142
keycode.codes: CodesMap;
143
keycode.code: CodesMap; // alias for codes
144

145
/**
146
 * Map of alternative key names to keycodes
147
 */
148
keycode.aliases: AliasesMap;
149

150
/**
151
 * Reverse map from numeric keycodes to key names
152
 */
153
keycode.names: InverseCodesMap;
154
keycode.title: InverseCodesMap; // alias for names (backward compatibility)
155
```
156

157
**Usage Examples:**
158

159
```javascript
160
// Direct code lookups
161
console.log(keycode.codes['enter']);    // => 13
162
console.log(keycode.codes['space']);    // => 32
163
console.log(keycode.codes['f1']);       // => 112
164

165
// Direct name lookups
166
console.log(keycode.names[13]);         // => "enter"
167
console.log(keycode.names[32]);         // => "space"
168

169
// Alias lookups
170
console.log(keycode.aliases['ctrl']);   // => 17
171
console.log(keycode.aliases['esc']);    // => 27
172
console.log(keycode.aliases['pgup']);   // => 33
173

174
// Iterate over all codes
175
for (const keyName in keycode.codes) {
176
  console.log(keyName, '=>', keycode.codes[keyName]);
177
}
178

179
// Iterate over all aliases
180
for (const alias in keycode.aliases) {
181
  console.log(alias, '=>', keycode.aliases[alias]);
182
}
183
```
184

185
## Types
186

187
```typescript { .api }
188
interface CodesMap {
189
  // Control keys
190
  'backspace': number;
191
  'tab': number;
192
  'enter': number;
193
  'shift': number;
194
  'ctrl': number;
195
  'alt': number;
196
  'pause/break': number;
197
  'caps lock': number;
198
  'esc': number;
199
  'space': number;
200
  'page up': number;
201
  'page down': number;
202
  'end': number;
203
  'home': number;
204
  
205
  // Arrow keys
206
  'left': number;
207
  'up': number;
208
  'right': number;
209
  'down': number;
210
  
211
  // Edit keys
212
  'insert': number;
213
  'delete': number;
214
  
215
  // Command keys
216
  'command': number;
217
  'left command': number;
218
  'right command': number;
219
  
220
  // Numpad keys
221
  'numpad *': number;
222
  'numpad +': number;
223
  'numpad -': number;
224
  'numpad .': number;
225
  'numpad /': number;
226
  'numpad 0': number;
227
  'numpad 1': number;
228
  'numpad 2': number;
229
  'numpad 3': number;
230
  'numpad 4': number;
231
  'numpad 5': number;
232
  'numpad 6': number;
233
  'numpad 7': number;
234
  'numpad 8': number;
235
  'numpad 9': number;
236
  
237
  // Lock keys
238
  'num lock': number;
239
  'scroll lock': number;
240
  
241
  // System keys
242
  'my computer': number;
243
  'my calculator': number;
244
  
245
  // Punctuation
246
  ';': number;
247
  '=': number;
248
  ',': number;
249
  '-': number;
250
  '.': number;
251
  '/': number;
252
  '`': number;
253
  '[': number;
254
  '\\': number;
255
  ']': number;
256
  "'": number;
257
  
258
  // Letters (a-z)
259
  'a': number;
260
  'b': number;
261
  'c': number;
262
  'd': number;
263
  'e': number;
264
  'f': number;
265
  'g': number;
266
  'h': number;
267
  'i': number;
268
  'j': number;
269
  'k': number;
270
  'l': number;
271
  'm': number;
272
  'n': number;
273
  'o': number;
274
  'p': number;
275
  'q': number;
276
  'r': number;
277
  's': number;
278
  't': number;
279
  'u': number;
280
  'v': number;
281
  'w': number;
282
  'x': number;
283
  'y': number;
284
  'z': number;
285
  
286
  // Numbers (0-9)
287
  '0': number;
288
  '1': number;
289
  '2': number;
290
  '3': number;
291
  '4': number;
292
  '5': number;
293
  '6': number;
294
  '7': number;
295
  '8': number;
296
  '9': number;
297
  
298
  // Function keys (f1-f12)
299
  'f1': number;
300
  'f2': number;
301
  'f3': number;
302
  'f4': number;
303
  'f5': number;
304
  'f6': number;
305
  'f7': number;
306
  'f8': number;
307
  'f9': number;
308
  'f10': number;
309
  'f11': number;
310
  'f12': number;
311
}
312

313
interface AliasesMap {
314
  // System keys
315
  'windows': number;
316
  
317
  // Unicode symbols
318
  '⇧': number;  // Shift
319
  '⌥': number;  // Option/Alt
320
  '⌃': number;  // Control
321
  '⌘': number;  // Command
322
  
323
  // Common aliases
324
  'ctl': number;
325
  'control': number;
326
  'option': number;
327
  'pause': number;
328
  'break': number;
329
  'caps': number;
330
  'return': number;
331
  'escape': number;
332
  'spc': number;
333
  'spacebar': number;
334
  'pgup': number;
335
  'pgdn': number;
336
  'ins': number;
337
  'del': number;
338
  'cmd': number;
339
}
340

341
interface InverseCodesMap {
342
  [key: number]: string;
343
}
344

345
interface Keycode {
346
  (event: Event): string;
347
  (keycode: number): string;
348
  (name: string): number;
349
  codes: CodesMap;
350
  code: CodesMap; // alias for codes
351
  aliases: AliasesMap;
352
  names: InverseCodesMap;
353
  title: InverseCodesMap; // alias for names (backward compatibility)
354
  isEventKey: (event: Event, nameOrCode: number | string) => boolean;
355
}
356
```
357

358
## Key Mappings Reference
359

360
### Standard Keys
361
The library includes mappings for all standard keyboard keys:
362

363
- **Control keys**: backspace (8), tab (9), enter (13), shift (16), ctrl (17), alt (18), etc.
364
- **Arrow keys**: left (37), up (38), right (39), down (40)
365
- **Function keys**: f1 (112) through f12 (123)
366
- **Letter keys**: a (65) through z (90)
367
- **Number keys**: 0 (48) through 9 (57)
368
- **Numpad keys**: numpad 0 (96) through numpad 9 (105), numpad operators
369
- **Punctuation**: All standard punctuation marks and symbols
370

371
### Aliases
372
Common alternative names are supported:
373

374
- **Control modifiers**: 'ctrl', 'ctl', 'control' → 17
375
- **System keys**: 'cmd', 'command' → 91; 'windows' → 91
376
- **Navigation**: 'pgup', 'pgdn' → 33, 34; 'ins', 'del' → 45, 46
377
- **Space variations**: 'spc', 'spacebar' → 32
378
- **Unicode symbols**: '⇧', '⌥', '⌃', '⌘' for modifier keys
379

380
### Special Features
381

382
- **Case insensitive**: Key name lookups work regardless of case
383
- **Event extraction**: Automatically extracts keycodes from Event objects using `which`, `keyCode`, or `charCode`
384
- **Character codes**: Single character strings return their character code
385
- **Error handling**: Returns `undefined` for unknown inputs instead of throwing errors