Creates simple and immutables sets of names (strings).
These sets are guaranteed to be immutable. Moreover, if you ever mispell a name, an error will be raised immediately, instead of letting undefined
cripple and damage your running program in unexpected ways, thus following a fail-fast approach.
npm install string-enum
import StringEnum from "string-enum"; // ES6 modules
// or
const StringEnum = require("string-enum"); // Classic way
const eyeColors = StringEnum(
"brown",
"blue",
"green",
"hazel");
console.log(eyeColors.brown); // brown
console.log(eyeColors.green); // green
console.log(eyeColors.bronw); // Error, undefined eye color.
eyeColors.brown = "blue"; // Error, cant modify existing color
eyeColors.red = "red"; // Error, cant add new color
delete eyeColors.brown; // Error, cant delete color
<script src="path/to/string-enum.js"></script>
<!-- or -->
<script src="path/to/string-enum-min.js"></script>
<!-- or -->
<script src="https://unpkg.com/string-enum"></script>
<!-- or -->
<script src="https://unpkg.com/string-enum/dist/string-enum-min.js"></script>
<script>
const eyeColors = StringEnum (
"brown",
"blue",
"green",
"hazel");
alert(`You have beautiful ${eyeColors.hazel} eyes!`);
</script>
To create a new set of enum values, all the followings are equivalent :
const eyeColors = StringEnum("brown", "blue", "green", "hazel");
const eyeColors = StringEnum( ["brown", "blue", "green", "hazel"] );
const eyeColors = new StringEnum("brown", "blue", "green", "hazel");
Enum elements should be strings :
const numbers = StringEnum(1, 2, 3); // TypeError
Strings that dont qualify as valid JS identifiers are allowed, but then you must use bracket notation to access them in your code later on :
const otherColors = StringEnum('light-blue', 'lime-green');
otherColors['light-blue'] // OK
otherColors.light-blue // Not working
Enum elements cant be repeated :
const colors = StringEnum('red', 'blue', 'red'); // Error
Enum elements are just normal strings, hence:
eyeColors.blue === 'blue'; // true
Enum elements are iterable with either for... of...
or for... in...
:
for(const color in eyeColors) { ... }
for(const color of eyeColors) { ... }
To check beforehand if an element is part of the Enum set, you may use the in
operator:
'blue' in eyeColors; // true
'red' in eyeColors; // false
StringEnum
are objects and as such do own special objects properties, e.g. __proto__
and constructor
, just like most other JS objects. However, StringEnum
permits you to override these objects, because most of the time the user don't care about them. However, if they are not overridden, they behave normally. Note that the in
operator has been modified to respond only to the enum elements.
eyeColors.__proto__ // prototype
eyeColors.constructor // constructor
eyeColors.toString() // string conversion
'constructor' in eyeColors // false
const specials = StringEnum('constructor', 'toString');
specials.constructor // "constructor"
specials.toString // "toString"
specials.valueOf() // value conversion
'constructor' in specials // true
'valueOf' in specials // false
eyeColors instanceof StringEnum; // true
Object.keys(eyeColors) // ['browns', etc.]
Object.values(eyeColors) // ['browns', etc.]
[...eyeColors] // ['browns', etc.]
{...eyeColors} // { brown:'brown', etc. }
The package also exists in ES6 module versions to be used on the web or with Node. Note that the -module
versions may be used on a server that cant properly serve .mjs
extension as a JavaScript MIME type.
There are many other enum packages available on npm. Most of them are useful for their particular use cases but none of them provides precisely what StringEnum
means to do. StringEnum
has been developed as part of another project that needed just what it does. The motivation was to furnish an immutable set of predefined names that catches most errors and (stupid) mistakes. It is a very simple code and very simple to use.
MIT