@northscaler/better-enum
Version:
Better enumeration support for TypeScript than its `enum` keyword. This class is modeled after [Java's enumeration pattern](https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html), where enums are instances of classes. This library provides a base
181 lines (180 loc) • 8.18 kB
JavaScript
;
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.sortByOrdinal = exports.sortByName = exports._values = exports._of = exports.Enumeration = void 0;
const is_valid_javascript_identifier_1 = __importDefault(require("./is-valid-javascript-identifier"));
const errors_1 = require("./errors");
// key type is a class function; that is, given `class Foo {}`, then symbol `Foo`
const enums = new Map();
/**
* Base enumeration class for the pattern where enumerated values are represented by instances of classes rather than by scalar string or numeric values alone.
*
* Every subclass `T` has the following requirements.
*
* * `T` must not be extended.
*
* * `T` must define a `private` constructor whose first two arguments are `name: string, ordinal: number`,
* * where `name` is a valid JavaScript identifier that is the same as the instance's static identifier on `T`, and
* * where `ordinal` is an integral value that is unique amongst all instances.
*
* * `T` must define a `static` method `of(it: T | string | number): T` that returns an instance of `T` whose `name` or `ordinal` is equal to the given value, or that is identical to the instance of `T` given, and must throw {@link UnidentifiableEnumerationValueError} otherwise.
*
* > NOTE: {@link Enumeration} provides a convenient function that subclasses can delegate to in order to implement the required `of` method above.
* > Use `import { _of } from '@northscaler/better-enum' and delegate the subclass's `of()` method to it.
*
* * `T` must define a `static` method `values(): T[]` that returns all instances of `T`.
* No ordering is prescribed.
* However, you can use one of the convenient sorting functions provided by this class, {@link sortByName} or {@link sortByOrdinal}, to sort the instances, or write your own.
*
* > NOTE: {@link Enumeration} provides a convenient function that subclasses can delegate to in order to implement the required `values` method above.
* > Use `import { _values } from '@northscaler/better-enum' and delegate the subclass's `values()` method to it.
*/
class Enumeration {
/**
* Constructs an enumerated value.
* @param _name The symbolic name of this instance.
* It must be a valid JavaScript symbol and must be unique amongst all instances of this class's type.
* @param _ordinal The numeric ordinal of this instance.
* It must be an integer value and must be unique amongst instances of this class's type.
* @param _class The class function of the subclass calling this constructor.
* For example, given `class Bool extends Enumeration<Bool> { ... }`, the reference to the class's function is `Bool`.
* @throws InvalidEnumerationNameError If the `_name` parameter is not a valid JavaScript identifier.
* @throws InvalidEnumerationOrdinalError If the `_ordinal` parameter is not an integer.
* @throws DuplicateEnumerationDeclarationError If there is already a value with the given `_name` or `_ordinal` amongst all instances of this class's type.
* @protected
*/
constructor(_name, _ordinal,
// eslint-disable-next-line @typescript-eslint/ban-types
_class) {
this._name = _name;
this._ordinal = _ordinal;
this._class = _class;
if (Object.getPrototypeOf(Object.getPrototypeOf(this)).constructor.name !==
Enumeration.name) {
throw new errors_1.IllegallyExtendedEnumerationError({ context: { this_: this } });
}
if (!is_valid_javascript_identifier_1.default(_name)) {
throw new errors_1.InvalidEnumerationNameError({ context: { name: _name } });
}
const n = parseInt(String(_ordinal));
if (isNaN(n) || n !== _ordinal) {
throw new errors_1.InvalidEnumerationOrdinalError({
context: { ordinal: _ordinal },
});
}
let class_ = enums.get(this._class);
if (!class_) {
enums.set(this._class, (class_ = { byName: {}, byOrdinal: {} }));
}
if (class_.byName[_name] || class_.byOrdinal[_ordinal]) {
throw new errors_1.DuplicateEnumerationDeclarationError({
context: { name: _name, ordinal: _ordinal },
});
}
class_.byName[_name] = class_.byOrdinal[_ordinal] = this;
}
/**
* The symbolic name of this enumerated value.
*/
name() {
return this._name;
}
/**
* The integer ordinal of this enumerated value.
*/
ordinal() {
return this._ordinal;
}
/**
* Returns whether the given object has the same name, ordinal & constructor name as this object.
*/
equals(that) {
return (this.constructor.name === that.constructor.name &&
this.name() === that.name() &&
this.ordinal() === that.ordinal());
}
/**
* Returns the symbolic name of this enumerated value.
* @param fullyQualified Whether to return the return value of {@link toFullyQualifiedString} or just the symbolic name; defaults to `false`.
*/
toString(fullyQualified = false) {
return fullyQualified ? this.toFullyQualifiedString() : this._name;
}
/**
* Returns a colon-separated string of this class's name, its symbolic name, and its ordinal (like `Bool:TRUE:1`).
*/
toFullyQualifiedString() {
return `${this.constructor.name}:${this._name}:${this._ordinal}`;
}
/**
* Default `toJSON()` protocol method.
* Returns the symbolic name of this enumerated value.
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#tojson_behavior
*
* To implement a JSON [`reviver`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#using_the_reviver_parameter), use the static `of` method defined on your class.
*/
toJSON() {
return this.name();
}
}
exports.Enumeration = Enumeration;
/**
* A function that attempts to locate an enumerated value given its name or ordinal.
* If given an argument that is `typeof object`, it must be an enumerated value, which is simply returned.
* Any value that is not among the symbolic names, ordinals, or instances of the enumeration class will cause this method to throw an `UnidentifiableEnumerationValueError`.
*
* This function is only intended to be used by subclasses of {@link Enumeration}.
*
* @param it The value being used to identify the enumerated value.
* @param clazz A reference to the enumeration class (if `class Foo ... {}`, then the reference `Foo` should be given).
*/
function _of(it,
// eslint-disable-next-line @typescript-eslint/ban-types
clazz) {
let e;
const type = typeof it;
const f = enums.get(clazz);
if (!f) {
throw new errors_1.UnknownEnumerationClassError({ context: { clazz } });
}
if (type === 'string') {
e = f.byName[it];
}
else if (type === 'number') {
e = f.byOrdinal[it];
}
else if (it instanceof clazz) {
e = it;
}
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
if (e) {
return e;
}
throw new errors_1.UnidentifiableEnumerationValueError({
message: 'unidentifiable enumeration value',
context: { value: it },
});
}
exports._of = _of;
// eslint-disable-next-line @typescript-eslint/ban-types
function _values(clazz) {
const f = enums.get(clazz);
if (!f) {
throw new errors_1.UnknownEnumerationClassError({ context: { clazz } });
}
return Object.values(f.byName);
}
exports._values = _values;
/**
* Returns a convenient function to sort enumerations by their names.
*/
const sortByName = (a, b) => a.name().localeCompare(b.name());
exports.sortByName = sortByName;
/**
* Returns a convenient function to sort enumerations by their ordinals.
*/
const sortByOrdinal = (a, b) => a.ordinal() - b.ordinal();
exports.sortByOrdinal = sortByOrdinal;