A TypeScript string enum for compile-time safety when working with event.key
ts-key-enum
A TypeScript string enum for compile-time safety when working with event.key.
Install
npm install ts-key-enum --save
Purpose
Tired of referencing keyboard keys with a string?
onKeyPress = (ev) => {
// whoops, it's actually ArrowLeft!
if (ev.key === 'LeftArrow') {
...
}
}
Me too. With this module, you can do this instead (in a TypeScript file):
onKeyPress = (ev) => {
// much better
if (ev.key === Key.ArrowLeft) {
...
}
}
Background
This is similar to the ts-keycode-enum module, but it provides an enum with string values that correspond with the event.key values instead of number values that correspond to the deprecated event.which and event.keyCode values.
Usage
To use this module, import the Key enum at the top of your TypeScript file:
import { Key } from 'ts-key-enum';
You can now use the enum value in place of key strings throughout the file:
// if (ev.key === 'Escape') { ... }
if (ev.key === Key.Escape) { ... }
See Key.enum.ts for a complete list of available keys. This file is auto-generated from the list of keys found at MDN: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values.
What's included
The Key enum contains values for all standard non-printable keys such as "CapsLock", "Backspace", and "AudioVolumeMute". The enum does not contain values for printable keys such as "a", "A", "#", "é", or "¿", simply because the list of possible values is too vast to include in a single enum. To test for printable values, simply use a string comparison:
if (ev.key === 'é') { ... }
v2 vs v3
This package is published as two versions on NPM: v2.x and v3.x.
v2
v2.x defines the Key enum as a "basic" enum:
export enum Key { ... }
The end result is a JavaScript object that contains every enum value. You can see this object here: https://gitlab.com/nfriend/ts-key-enum/blob/v2/dist/js/Key.enum.js.
v3
v3.x defines the Key enum as a const enum:
export const enum Key { ... }
This allows the enum's definition to live entirely in the definition file https://gitlab.com/nfriend/ts-key-enum/blob/master/Key.enum.d.ts. Consumers can use this enum without including all of the enum's values in their own JavaScript bundle; only the values referenced in their code will be injected into their bundle.
Which version should I use?
It's advisable to use v3.x unless you have a reason to use v2.x. Some reasons you may need to use v2.x:
You are using this package as a JavaScript module (not a TypeScript module).
You are using TypeScript < 1.4, which doesn't support const enum.
Building
To build this module yourself, first install its dependencies using
npm install
Next, run the scraper script (scrapeMDNForKeys.ts) using
npm run scrape
This will overwrite Key.enum.ts with the updated list of keys found in MDN.
Finally, run the build using
npm run build
Build output is placed in the dist directory.
License
MIT
HomePage
Repository