better-enum
Better enumeration support for TypeScript than its enum
keyword. This class is modeled
after Java's enumeration pattern, where enums are
instances of classes. This library provides a base Enumeration
class, along with some conventions and patterns
specific to the notion of enumerated values.
TL;DR
Here's a very simple "Hello, World!" enumeration.
import { _of, _values, Enumeration } from '@northscaler/better-enum' // 1️⃣
export default class HelloWorld extends Enumeration<HelloWorld> { // 2️⃣
static readonly HELLO = new HelloWorld('HELLO', 0) // 3️⃣
static readonly WORLD = new HelloWorld('WORLD', 1)
static of(it: HelloWorld | string | number): HelloWorld { // 4️⃣
return _of(it, HelloWorld)
}
static values(): HelloWorld[] { // 5️⃣
return _values<HellowWorld>(HelloWorld)
}
private constructor(name: string, ordinal: number) { // 6️⃣
super(name, ordinal, HelloWorld)
}
}
Enumeration
name
& ordinal
(additional, arbitrary properties are allowed, too)
static
of()
method that converts from string
names and number
ordinals to the enum instance
static
values()
method that returns all values of this enum type
private
constructor that takes the name
& ordinal
for an enum instance (again, additional properties
are allowed, too)
Now use it.
// mocha test examples
expect(HelloWorld.of('HELLO')).to.equal(HelloWorld.HELLO) // 1️⃣
expect(HelloWorld.of('WORLD')).to.equal(HelloWorld.WORLD)
expect(HelloWorld.of(0)).to.equal(HelloWorld.HELLO) // 2️⃣
expect(HelloWorld.of(1)).to.equal(HelloWorld.WORLD)
expect(`${HelloWorld.WORLD}`).to.equal('WORLD') // 3️⃣
expect(HelloWorld.WORLD.toFullyQualifiedString()).to.equal( // 4️⃣
'HelloWorld:WORLD:1'
)
expect(() => HelloWorld.of('')).to.throw( // 5️⃣
UnidentifiableEnumerationValueError
)
expect(() => HelloWorld.of(-42)).to.throw(
UnidentifiableEnumerationValueError
)
name
to its instance
ordinal
to its instance
name
name
& ordinal
UnidentifiableEnumerationValueError
thrown on argument that can't be converted to an enum instance
NOTE: There are helpful IDE-specific templates to assist you in following the patterns prescribed by this library. See ./src/templates for more information. If you don't see templates for your IDE, please submit a pull/merge request.
Features
name()
instance method
This is an instance method that returns the instances name
.
ordinal()
instance method
This is an instance method that returns the instance's ordinal
.
toJSON()
instance method
This is an instance method to return the enum as an object suitable for JSON stringification. It simply returns
the name
of this instance.
static values()
method
This is a static method on your enumeration class that returns all instances of the class.
static of()
method
This is a static method on your enumeration class that returns an instance of the class given its name
or ordinal
.
Convenient sorting functions
This package exports two convenient sorting functions, sortByName
& sortByOrdinal
to sort enumeration instances by
their name
or ordinal
, respectively.
Arbitrary additional properties & methods
Your enumeration class can define any additional properties or methods that you'd like.
Here's an example of a tri-state boolean (true, false or neither) with additional property definite
and toBoolean()
.
It also demonstrates the use of an incrementing ordinal
to assign the ordinal values.
import { _of, _values, Enumeration } from '@northscaler/better-enum'
let ordinal = -1 // convenient way to assign ordinals below
/**
* A tristate boolean.
*/
export default class Bool extends Enumeration<Bool> {
static readonly NEITHER = new Bool('NEITHER', ordinal++, false)
static readonly FALSE = new Bool('FALSE', ordinal++, true)
static readonly TRUE = new Bool('TRUE', ordinal++, true)
static of(it: Bool | string | number): Bool {
return _of(it, Bool)
}
static values(): Bool[] {
return _values<Bool>(Bool)
}
private constructor(
_name: string,
_ordinal: number,
private _definite: boolean
) {
super(_name, _ordinal, Bool)
}
/**
* Returns `true` of this enum is {@link Bool.TRUE} or {@link Bool.FALSE}.
* If this enum is {@link Bool.NEITHER}, returns `false`.
*/
get definite() {
return this._definite
}
/**
* Converts this {@link Bool} to a `boolean` if it's definite, else throws an `Error`.
*/
toBoolean() {
if (this === Bool.TRUE) return true
if (this === Bool.FALSE) return false
throw new Error('neither true nor false')
}
}
Now, you can use your arbitrary properties:
// mocha test examples
expect(Bool.TRUE.definite).to.be.true
expect(Bool.FALSE.definite).to.be.true
expect(Bool.NEITHER.definite).to.be.false
Planet
enum
Java's We ported Java's Planet
enum example at https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html to this library.
It makes significant use of custom properties & methods.
See the enum class and its test if you're curious.