Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

ts-enum-util

Package Overview
Dependencies
Maintainers
1
Versions
40
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

ts-enum-util - npm Package Compare versions

Comparing version 0.0.5 to 0.0.6

160

dist/commonjs/index.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
/**
* A generic wrapper for any enum-like value (see {@link EnumLike} type for more explanation).
* A generic wrapper for any enum-like object (see {@link EnumLike}).
* Provides utilities for runtime processing of an enum's values and keys, with strict compile-time

@@ -10,2 +10,3 @@ * type safety.

* instance:
* - {@link $enum}
* - {@link EnumWrapper.getCachedInstance}

@@ -53,6 +54,6 @@ * - {@link EnumWrapper.createUncachedInstance}

* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.

@@ -66,4 +67,4 @@ * @param enumObj - An enum-like object.

/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance

@@ -83,2 +84,8 @@ * will be quickly retrieved/reused on every subsequent call to get() for the same enum object.

};
/**
* @return "[object EnumWrapper]"
*/
EnumWrapper.prototype.toString = function () {
return "[object EnumWrapper]";
};
Object.defineProperty(EnumWrapper.prototype, "size", {

@@ -95,25 +102,25 @@ /**

/**
* Get a list of this enum's keys.
* @return A list of this enum's keys.
* Gets the enum value for the provided key.
* Returns undefined if the provided key is invalid.
* This is an alias for {@link EnumWrapper#getValueOrDefault} for the purpose
* of implementing a Map-like interface.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns undefined if the provided key is invalid.
*/
EnumWrapper.prototype.getKeys = function () {
return Array.from(this.keySet.values());
EnumWrapper.prototype.get = function (key) {
return this.getValueOrDefault(key, undefined);
};
/**
* Get a list of this enum's values.
* NOTE: If this enum has any duplicate values, only unique values will be returned, and the
* length of the list will be less than {@link EnumWrapper#size}.
* @return A list of this enum's values.
* Tests if the provided string is actually a valid key for this enum
* Acts as a type guard to confirm that the provided value is actually the enum key type.
* This is an alias for {@link EnumWrapper#isKey} for the purpose
* of implementing a Map-like interface.
* @param key - A potential key value for this enum.
* @return True if the provided key is a valid key for this enum.
*/
EnumWrapper.prototype.getValues = function () {
return Array.from(this.valueSet.values());
EnumWrapper.prototype.has = function (key) {
return this.isKey(key);
};
/**
* Get a list of this enum's entries as [key, value] tuples.
* @return A list of this enum's entries as [key, value] tuples.
*/
EnumWrapper.prototype.getEntries = function () {
return Array.from(this);
};
/**
* Get an iterator for this enum's keys.

@@ -185,2 +192,4 @@ * @return An iterator that iterates over this enum's keys.

* @return A new array containg the results of the iteratee.
*
* @template R - The of the mapped result for each entry.
*/

@@ -195,5 +204,41 @@ EnumWrapper.prototype.map = function (iteratee, context) {

};
/**
* Get a list of this enum's keys.
* @return A list of this enum's keys.
*/
EnumWrapper.prototype.getKeys = function () {
return Array.from(this.keySet.values());
};
/**
* Get a list of this enum's values.
* NOTE: If this enum has any duplicate values, only unique values will be returned, and the
* length of the list will be less than {@link EnumWrapper#size}.
* @return A list of this enum's values.
*/
EnumWrapper.prototype.getValues = function () {
return Array.from(this.valueSet.values());
};
/**
* Get a list of this enum's entries as [key, value] tuples.
* @return A list of this enum's entries as [key, value] tuples.
*/
EnumWrapper.prototype.getEntries = function () {
return Array.from(this);
};
/**
* Tests if the provided string is actually a valid key for this enum
* Acts as a type guard to confirm that the provided value is actually the enum key type.
* @param key - A potential key value for this enum.
* @return True if the provided key is a valid key for this enum.
*/
EnumWrapper.prototype.isKey = function (key) {
return key !== undefined && this.keySet.has(key);
return this.keySet.has(key);
};
/**
* Casts a string to a properly-typed key for this enum.
* Throws an error if the key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* @throws {Error} if the provided string is not a valid key for this enum.
*/
EnumWrapper.prototype.asKey = function (key) {

@@ -207,2 +252,9 @@ if (this.isKey(key)) {

};
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
EnumWrapper.prototype.asKeyOrDefault = function (key, defaultKey) {

@@ -216,5 +268,18 @@ if (this.isKey(key)) {

};
/**
* Tests if the provided value is a valid value for this enum.
* Acts as a type guard to confirm that the provided value is actually the enum value type.
* @param value - A potential value for this enum.
* @return True if the provided value is valid for this enum.
*/
EnumWrapper.prototype.isValue = function (value) {
return value !== undefined && this.valueSet.has(value);
};
/**
* Casts a value to a properly-typed value for this enum.
* Throws an error if the value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* @throws {Error} if the provided value is not a valid value for this enum.
*/
EnumWrapper.prototype.asValue = function (value) {

@@ -228,2 +293,9 @@ if (this.isValue(value)) {

};
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
EnumWrapper.prototype.asValueOrDefault = function (value, defaultValue) {

@@ -237,5 +309,23 @@ if (this.isValue(value)) {

};
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Throws an error if the value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* @throws {Error} if the provided value is not a valid value for this enum.
*/
EnumWrapper.prototype.getKey = function (value) {
return this.keysByValueMap.get(this.asValue(value));
};
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
EnumWrapper.prototype.getKeyOrDefault = function (value, defaultKey) {

@@ -249,9 +339,21 @@ if (this.isValue(value)) {

};
/**
* Gets the enum value for the provided key.
* Throws an error if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* @throws {Error} if the provided string is not a valid key for this enum.
*/
EnumWrapper.prototype.getValue = function (key) {
return this.enumObj[this.asKey(key)];
};
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
EnumWrapper.prototype.getValueOrDefault = function (key, defaultValue) {
if (this.isKey(key)) {
// type cast to "keyof T" is necessary until this bug is fixed:
// https://github.com/Microsoft/TypeScript/issues/21950
return this.enumObj[key];

@@ -271,2 +373,10 @@ }

exports.EnumWrapper = EnumWrapper;
/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*/
function $enum(enumObj, useCache) {

@@ -273,0 +383,0 @@ if (useCache === void 0) { useCache = true; }

160

dist/es/index.js
/**
* A generic wrapper for any enum-like value (see {@link EnumLike} type for more explanation).
* A generic wrapper for any enum-like object (see {@link EnumLike}).
* Provides utilities for runtime processing of an enum's values and keys, with strict compile-time

@@ -8,2 +8,3 @@ * type safety.

* instance:
* - {@link $enum}
* - {@link EnumWrapper.getCachedInstance}

@@ -51,6 +52,6 @@ * - {@link EnumWrapper.createUncachedInstance}

* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.

@@ -64,4 +65,4 @@ * @param enumObj - An enum-like object.

/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance

@@ -81,2 +82,8 @@ * will be quickly retrieved/reused on every subsequent call to get() for the same enum object.

};
/**
* @return "[object EnumWrapper]"
*/
EnumWrapper.prototype.toString = function () {
return "[object EnumWrapper]";
};
Object.defineProperty(EnumWrapper.prototype, "size", {

@@ -93,25 +100,25 @@ /**

/**
* Get a list of this enum's keys.
* @return A list of this enum's keys.
* Gets the enum value for the provided key.
* Returns undefined if the provided key is invalid.
* This is an alias for {@link EnumWrapper#getValueOrDefault} for the purpose
* of implementing a Map-like interface.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns undefined if the provided key is invalid.
*/
EnumWrapper.prototype.getKeys = function () {
return Array.from(this.keySet.values());
EnumWrapper.prototype.get = function (key) {
return this.getValueOrDefault(key, undefined);
};
/**
* Get a list of this enum's values.
* NOTE: If this enum has any duplicate values, only unique values will be returned, and the
* length of the list will be less than {@link EnumWrapper#size}.
* @return A list of this enum's values.
* Tests if the provided string is actually a valid key for this enum
* Acts as a type guard to confirm that the provided value is actually the enum key type.
* This is an alias for {@link EnumWrapper#isKey} for the purpose
* of implementing a Map-like interface.
* @param key - A potential key value for this enum.
* @return True if the provided key is a valid key for this enum.
*/
EnumWrapper.prototype.getValues = function () {
return Array.from(this.valueSet.values());
EnumWrapper.prototype.has = function (key) {
return this.isKey(key);
};
/**
* Get a list of this enum's entries as [key, value] tuples.
* @return A list of this enum's entries as [key, value] tuples.
*/
EnumWrapper.prototype.getEntries = function () {
return Array.from(this);
};
/**
* Get an iterator for this enum's keys.

@@ -183,2 +190,4 @@ * @return An iterator that iterates over this enum's keys.

* @return A new array containg the results of the iteratee.
*
* @template R - The of the mapped result for each entry.
*/

@@ -193,5 +202,41 @@ EnumWrapper.prototype.map = function (iteratee, context) {

};
/**
* Get a list of this enum's keys.
* @return A list of this enum's keys.
*/
EnumWrapper.prototype.getKeys = function () {
return Array.from(this.keySet.values());
};
/**
* Get a list of this enum's values.
* NOTE: If this enum has any duplicate values, only unique values will be returned, and the
* length of the list will be less than {@link EnumWrapper#size}.
* @return A list of this enum's values.
*/
EnumWrapper.prototype.getValues = function () {
return Array.from(this.valueSet.values());
};
/**
* Get a list of this enum's entries as [key, value] tuples.
* @return A list of this enum's entries as [key, value] tuples.
*/
EnumWrapper.prototype.getEntries = function () {
return Array.from(this);
};
/**
* Tests if the provided string is actually a valid key for this enum
* Acts as a type guard to confirm that the provided value is actually the enum key type.
* @param key - A potential key value for this enum.
* @return True if the provided key is a valid key for this enum.
*/
EnumWrapper.prototype.isKey = function (key) {
return key !== undefined && this.keySet.has(key);
return this.keySet.has(key);
};
/**
* Casts a string to a properly-typed key for this enum.
* Throws an error if the key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* @throws {Error} if the provided string is not a valid key for this enum.
*/
EnumWrapper.prototype.asKey = function (key) {

@@ -205,2 +250,9 @@ if (this.isKey(key)) {

};
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
EnumWrapper.prototype.asKeyOrDefault = function (key, defaultKey) {

@@ -214,5 +266,18 @@ if (this.isKey(key)) {

};
/**
* Tests if the provided value is a valid value for this enum.
* Acts as a type guard to confirm that the provided value is actually the enum value type.
* @param value - A potential value for this enum.
* @return True if the provided value is valid for this enum.
*/
EnumWrapper.prototype.isValue = function (value) {
return value !== undefined && this.valueSet.has(value);
};
/**
* Casts a value to a properly-typed value for this enum.
* Throws an error if the value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* @throws {Error} if the provided value is not a valid value for this enum.
*/
EnumWrapper.prototype.asValue = function (value) {

@@ -226,2 +291,9 @@ if (this.isValue(value)) {

};
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
EnumWrapper.prototype.asValueOrDefault = function (value, defaultValue) {

@@ -235,5 +307,23 @@ if (this.isValue(value)) {

};
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Throws an error if the value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* @throws {Error} if the provided value is not a valid value for this enum.
*/
EnumWrapper.prototype.getKey = function (value) {
return this.keysByValueMap.get(this.asValue(value));
};
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
EnumWrapper.prototype.getKeyOrDefault = function (value, defaultKey) {

@@ -247,9 +337,21 @@ if (this.isValue(value)) {

};
/**
* Gets the enum value for the provided key.
* Throws an error if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* @throws {Error} if the provided string is not a valid key for this enum.
*/
EnumWrapper.prototype.getValue = function (key) {
return this.enumObj[this.asKey(key)];
};
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
EnumWrapper.prototype.getValueOrDefault = function (key, defaultValue) {
if (this.isKey(key)) {
// type cast to "keyof T" is necessary until this bug is fixed:
// https://github.com/Microsoft/TypeScript/issues/21950
return this.enumObj[key];

@@ -269,2 +371,10 @@ }

export { EnumWrapper };
/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*/
export function $enum(enumObj, useCache) {

@@ -271,0 +381,0 @@ if (useCache === void 0) { useCache = true; }

359

dist/types/index.d.ts

@@ -11,3 +11,3 @@ /**

/**
* A generic wrapper for any enum-like value (see {@link EnumLike} type for more explanation).
* A generic wrapper for any enum-like object (see {@link EnumLike}).
* Provides utilities for runtime processing of an enum's values and keys, with strict compile-time

@@ -18,2 +18,3 @@ * type safety.

* instance:
* - {@link $enum}
* - {@link EnumWrapper.getCachedInstance}

@@ -46,62 +47,74 @@ * - {@link EnumWrapper.createUncachedInstance}

/**
* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* Creates a new EnumWrapper for an enum-like object with number values.
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with number values.
* @return A new instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
static createUncachedInstance<T extends EnumLike<number, keyof T>>(enumObj: T): EnumWrapper<number, T>;
/**
* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* Creates a new EnumWrapper for an enum-like object with string values.
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with string values.
* @return A new instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
static createUncachedInstance<T extends EnumLike<string, keyof T>>(enumObj: T): EnumWrapper<string, T>;
/**
* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* Creates a new EnumWrapper for an enum-like object with a mix of number and string values.
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with a mix of number and string values.
* @return A new instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
static createUncachedInstance<T extends EnumLike<number | string, keyof T>>(enumObj: T): EnumWrapper<number | string, T>;
/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object with number values.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance
* will be quickly retrieved/reused on every subsequent call to get() for the same enum object.
* Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with number values.
* @return An instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
static getCachedInstance<T extends EnumLike<number, keyof T>>(enumObj: T): EnumWrapper<number, T>;
/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object with string values.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance
* will be quickly retrieved/reused on every subsequent call to get() for the same enum object.
* Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with string values.
* @return An instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
static getCachedInstance<T extends EnumLike<string, keyof T>>(enumObj: T): EnumWrapper<string, T>;
/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object with a mixture of number and string values.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance
* will be quickly retrieved/reused on every subsequent call to get() for the same enum object.
* Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with a mixture of number and string values.
* @return An instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/

@@ -121,2 +134,6 @@ static getCachedInstance<T extends EnumLike<number | string, keyof T>>(enumObj: T): EnumWrapper<number | string, T>;

/**
* @return "[object EnumWrapper]"
*/
toString(): string;
/**
* The number of entries in this enum.

@@ -126,19 +143,21 @@ */

/**
* Get a list of this enum's keys.
* @return A list of this enum's keys.
* Gets the enum value for the provided key.
* Returns undefined if the provided key is invalid.
* This is an alias for {@link EnumWrapper#getValueOrDefault} for the purpose
* of implementing a Map-like interface.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns undefined if the provided key is invalid.
*/
getKeys(): (keyof T)[];
get(key: string): T[keyof T] | undefined;
/**
* Get a list of this enum's values.
* NOTE: If this enum has any duplicate values, only unique values will be returned, and the
* length of the list will be less than {@link EnumWrapper#size}.
* @return A list of this enum's values.
* Tests if the provided string is actually a valid key for this enum
* Acts as a type guard to confirm that the provided value is actually the enum key type.
* This is an alias for {@link EnumWrapper#isKey} for the purpose
* of implementing a Map-like interface.
* @param key - A potential key value for this enum.
* @return True if the provided key is a valid key for this enum.
*/
getValues(): T[keyof T][];
has(key: string): key is keyof T;
/**
* Get a list of this enum's entries as [key, value] tuples.
* @return A list of this enum's entries as [key, value] tuples.
*/
getEntries(): EnumWrapper.Entry<T>[];
/**
* Get an iterator for this enum's keys.

@@ -180,33 +199,259 @@ * @return An iterator that iterates over this enum's keys.

* @return A new array containg the results of the iteratee.
*
* @template R - The of the mapped result for each entry.
*/
map<R>(iteratee: EnumWrapper.Iteratee<V, T, R>, context?: any): R[];
isKey(key: string | undefined): key is keyof T;
asKey(key: string | undefined): keyof T;
asKeyOrDefault(key: string | undefined, defaultKey?: keyof T): keyof T | undefined;
asKeyOrDefault(key: string | undefined, defaultKey: keyof T): keyof T;
asKeyOrDefault(key: string | undefined, defaultKey: string): keyof T | string;
asKeyOrDefault(key: string | undefined, defaultKey: string | undefined): keyof T | string | undefined;
isValue(value: V | undefined): value is T[keyof T];
asValue(value: V | undefined): T[keyof T];
asValueOrDefault(value: V | undefined, defaultValue?: T[keyof T]): T[keyof T] | undefined;
asValueOrDefault(value: V | undefined, defaultValue: T[keyof T]): T[keyof T];
asValueOrDefault(value: V | undefined, defaultValue: V): T[keyof T] | V;
asValueOrDefault(value: V | undefined, defaultValue: V | undefined): T[keyof T] | V | undefined;
getKey(value: V | undefined): keyof T;
getKeyOrDefault(value: V | undefined, defaultKey?: keyof T): keyof T | undefined;
getKeyOrDefault(value: V | undefined, defaultKey: keyof T): keyof T;
getKeyOrDefault(value: V | undefined, defaultKey: string): keyof T | string;
getKeyOrDefault(value: V | undefined, defaultKey: string | undefined): keyof T | string | undefined;
getValue(key: string | undefined): T[keyof T];
getValueOrDefault(key: string | undefined, defaultValue?: T[keyof T]): T[keyof T] | undefined;
getValueOrDefault(key: string | undefined, defaultValue: T[keyof T]): T[keyof T];
getValueOrDefault(key: string | undefined, defaultValue: V): T[keyof T] | V;
getValueOrDefault(key: string | undefined, defaultValue: V | undefined): T[keyof T] | V | undefined;
/**
* Get a list of this enum's keys.
* @return A list of this enum's keys.
*/
getKeys(): (keyof T)[];
/**
* Get a list of this enum's values.
* NOTE: If this enum has any duplicate values, only unique values will be returned, and the
* length of the list will be less than {@link EnumWrapper#size}.
* @return A list of this enum's values.
*/
getValues(): T[keyof T][];
/**
* Get a list of this enum's entries as [key, value] tuples.
* @return A list of this enum's entries as [key, value] tuples.
*/
getEntries(): EnumWrapper.Entry<T>[];
/**
* Tests if the provided string is actually a valid key for this enum
* Acts as a type guard to confirm that the provided value is actually the enum key type.
* @param key - A potential key value for this enum.
* @return True if the provided key is a valid key for this enum.
*/
isKey(key: string): key is keyof T;
/**
* Casts a string to a properly-typed key for this enum.
* Throws an error if the key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* @throws {Error} if the provided string is not a valid key for this enum.
*/
asKey(key: string): keyof T;
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
asKeyOrDefault(key: string, defaultKey: keyof T): keyof T;
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
asKeyOrDefault(key: string, defaultKey?: keyof T): keyof T | undefined;
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
asKeyOrDefault(key: string, defaultKey: string): string;
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
asKeyOrDefault(key: string, defaultKey: string | undefined): string | undefined;
/**
* Tests if the provided value is a valid value for this enum.
* Acts as a type guard to confirm that the provided value is actually the enum value type.
* @param value - A potential value for this enum.
* @return True if the provided value is valid for this enum.
*/
isValue(value: V): value is T[keyof T];
/**
* Casts a value to a properly-typed value for this enum.
* Throws an error if the value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* @throws {Error} if the provided value is not a valid value for this enum.
*/
asValue(value: V): T[keyof T];
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
asValueOrDefault(value: V, defaultValue: T[keyof T]): T[keyof T];
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
asValueOrDefault(value: V, defaultValue?: T[keyof T]): T[keyof T] | undefined;
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
asValueOrDefault(value: V, defaultValue: V): V;
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
asValueOrDefault(value: V, defaultValue: V | undefined): V | undefined;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Throws an error if the value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* @throws {Error} if the provided value is not a valid value for this enum.
*/
getKey(value: V): keyof T;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
getKeyOrDefault(value: V, defaultKey: keyof T): keyof T;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
getKeyOrDefault(value: V, defaultKey?: keyof T): keyof T | undefined;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
getKeyOrDefault(value: V, defaultKey: string): string;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
getKeyOrDefault(value: V, defaultKey: string | undefined): string | undefined;
/**
* Gets the enum value for the provided key.
* Throws an error if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* @throws {Error} if the provided string is not a valid key for this enum.
*/
getValue(key: string): T[keyof T];
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
getValueOrDefault(key: string, defaultValue: T[keyof T]): T[keyof T];
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
getValueOrDefault(key: string, defaultValue?: T[keyof T]): T[keyof T] | undefined;
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
getValueOrDefault(key: string, defaultValue: V): V;
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
getValueOrDefault(key: string, defaultValue: V | undefined): V | undefined;
}
export declare namespace EnumWrapper {
/**
* A tuple containing the key and value of a single entry in an enum.
* @template T - Type of an enum-like object.
*/
type Entry<T> = [keyof T, T[keyof T]];
/**
* A function used in iterating all key/value entries in an enum.
* @param value - An enum value.
* @param key - An enum key.
* @param enumObj - The enum-like object that the key/value entrie belongs to.
* @return A result. The significance of the result depends on the type of iteration being performed.
*
* @template V - Type of the enum value.
* @template T - Type of the enum-like object that is being wrapped.
* @template R - The type of the result.
*/
type Iteratee<V extends number | string, T extends EnumLike<V, keyof T>, R> = (this: any, value: V, key: keyof T, enumObj: T) => R;
}
/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object with number values.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
export declare function $enum<T extends EnumLike<number, keyof T>>(enumObj: T, useCache?: boolean): EnumWrapper<number, T>;
/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object with string values.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
export declare function $enum<T extends EnumLike<string, keyof T>>(enumObj: T, useCache?: boolean): EnumWrapper<string, T>;
/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object with a mixture of number and string values.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
export declare function $enum<T extends EnumLike<number | string, keyof T>>(enumObj: T, useCache?: boolean): EnumWrapper<number | string, T>;

2

package.json
{
"name": "ts-enum-util",
"version": "0.0.5",
"version": "0.0.6",
"description": "TypeScript Enum Utilities",

@@ -5,0 +5,0 @@ "repository": {

184

README.md

@@ -7,4 +7,184 @@ [![npm version](https://img.shields.io/npm/v/ts-enum-util.svg)](https://www.npmjs.com/package/ts-enum-util)

# ts-enum-util
TypeScript Enum Utilities
Strictly typed utilities for working with TypeScript enums.
Work in progress...
# Contents
<!-- TOC depthFrom:2 -->
- [What is it?](#what-is-it)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage Example](#usage-example)
- [Requirements](#requirements)
- [General Concepts](#general-concepts)
- [Enum-Like Object](#enum-like-object)
- [EnumWrapper](#enumwrapper)
- [Specific Typing](#specific-typing)
- [Map-Like Interface](#map-like-interface)
- [Caching](#caching)
- [Reference](#reference)
- [Terminology](#terminology)
- [$enum](#enum)
- [EnumWrapper](#enumwrapper-1)
- [EnumWrapper.prototype.size](#enumwrapperprototypesize)
- [EnumWrapper.prototype.get](#enumwrapperprototypeget)
- [EnumWrapper.prototype.has](#enumwrapperprototypehas)
- [EnumWrapper.prototype.keys](#enumwrapperprototypekeys)
- [EnumWrapper.prototype.values](#enumwrapperprototypevalues)
- [EnumWrapper.prototype.entries](#enumwrapperprototypeentries)
- [EnumWrapper.prototype.getKeys](#enumwrapperprototypegetkeys)
- [EnumWrapper.prototype.getValues](#enumwrapperprototypegetvalues)
- [EnumWrapper.prototype.getEntries](#enumwrapperprototypegetentries)
- [Limitations](#limitations)
<!-- /TOC -->
## What is it?
`ts-enum-util` provides utilities to improve the usefulness of enums. Examples include getting a list of an enum's keys, values, or key/value pairs, reverse lookup of keys by value, run-time validation that a specified value or key is valid for a given enum, and more.
## Quick Start
### Installation
Install via [NPM](https://www.npmjs.com/package/ts-enum-util):
```
npm i -s ts-enum-util
```
### Usage Example
A quick example of some of `ts-enum-util`'s capabilities.
```ts
import {$enum} from "ts-enum-util";
enum RGB {
R,
G,
B
}
// type: ("R" | "G" | "B")[]
// value: ["R", "G", "B"]
const keys = $enum(RGB).getKeys();
// type: RGB[]
// value: [0, 1, 2]
const values = $enum(RGB).getValues();
// type: "R" | "G" | "B"
// value: "G"
const key = $enum(RGB).getKey(1);
// throws: Error("Unexpected value: 42. Expected one of: 0,1,2")
const key2 = $enum(RGB).getKey(42);
// type: "R" | "G" | "B" | undefined
// value: undefined
const key3 = $enum(RGB).getKeyOrDefault(42);
// type: "R" | "G" | "B"
// value: "R"
const key4 = $enum(RGB).getKeyOrDefault(42, "R");
// type: string
// value: "BLAH!"
const key4 = $enum(RGB).getKeyOrDefault(42, "BLAH!");
// A wrapped enum is iterable!
for (const [key, value] of $enum(RGB)) {
// type of key: "R" | "G" | "B"
// type of value: RGB
}
```
## Requirements
* *ES6 Features*: The following ES6 features are used by `ts-enum-util`, so they must exist (either natively or via polyfill) in the run-time environment: `Array.from()`, `Map`, `Set`, `Symbol.iterator`.
## General Concepts
### Enum-Like Object
`ts-enum-util` technically works with any "enum-like" object, which is any object whose property values are of type `string` or `number`.
The most obvious example is a TypeScript `enum`. It can be a standard enum of numeric values, a string enum, or even an enum with a mix of numeric and string values.
### EnumWrapper
The bulk of `ts-enum-util`'s functionality is implemented via an `EnumWrapper` class, which is instantiated with a reference to an enum-like object and implements all the useful utility methods for that enum.
You likely won't ever directly reference the `EnumWrapper` class because it's much more convenient to use the [$enum](#enum) function to obtain a reference to an `EnumWrapper` instance.
### Specific Typing
The various methods of `ts-enum-util` are generic and overloaded to ensure that params and results are as specifically-typed as possible.
For example, when obtaining a key or keys from an `EnumWrapper`, the data type will be a string literal union containing only the specific key names that exist in the enum.
This helps maximize the usefulness of `ts-enum-util` by making it compatible with other strictly typed code related to enums.
### Map-Like Interface
A subset of `EnumWrapper`'s interface overlaps with much of the ES6 `Map` interface. `EnumWrapper` is effectively a read-only `Map` of enum values, keyed by the enum names. The following Map-like features are implemented:
* `size` property.
* `has` and `get` methods.
* `keys`, `values`, and `entries` methods.
* `forEach` method.
* `@@iterator` method (`EnumWrapper` is iterable!).
### Caching
By default, `EnumWrapper` instances are cached for quick subsequent retrieval via the [$enum](#enum) function. This makes sense for typical enums.
The reasoning behind this is that enums are static constructs. A given project will have a relatively small finite number of enums that never change during execution. The combination of caching and the simple [$enum](#enum) function allows you to obtain an `EnumWrapper` instance conveniently whenever you need it, without maintaining a reference to it.
You may want to consider explicitly avoiding caching (via an optional param to `$enum`) if you are using `ts-enum-util` to work with an ad-hoc dynamically generated "enum-like" object. this is useful to avoid cluttering the cache and unnecessarily occupying memory with an `EnumWrapper` that will never be retrieved from the cache.
## Reference
See the source code or the distributed `index.d.ts` file for complete details of method signatures/overloads, detailed method/param documentation, etc.
The following reference is a work in progress.
### Terminology
Throughout this references, the following aliases for types will be used:
* `EnumLike`: An enum-like object type. See [Enum-Like Object](#enum-like-object).
* `KeyType`: The type of the enum's keys. This is usually a string literal union type of the enum's names, but may also simply be `string` if an `EnumWrapper` was created for an object whose possible property names are not known at compile time.
* `EnumType`: The specific enum type of the enum values. This is usually the enum type itself, but may also simply be the same as `ValueType` (see below) if a `EnumWrapper` was created for an object that is not actually an enum, but is only "enum-like".
* `ValueType`: The widened type of the enum's values. Will be `number`, `string`, or `number | string`, depending on whether the wrapped enum-like object contains only number, only string, or both number and string values.
### $enum
`function $enum(enumObj: EnumLike, useCache: boolean = true): EnumWrapper`
* `useCache` - False to prevent caching of the result.
This is where it all begins. Pass an "enum-like" object to this method and it returns an [EnumWrapper](#enum-wrapper-1) instance that provides useful utilities for that "enum-like" object.
See [Caching](#caching) for more about caching of `EnumWrapper` instances.
### EnumWrapper
`class EnumWrapper`
This is the class that implements all the enum utilities. It's a generic class that requires an overloaded helper function to properly instantiate, so the constructor is private. Use [$enum()](#enum) to get/create an instance of `EnumWrapper`.
### EnumWrapper.prototype.size
`EnumWrapper.prototype.size: number`
A read-only property containing the number of entries (key/value pairs) in the enum.
### EnumWrapper.prototype.get
`EnumWrapper.prototype.get(key: string): EnumType | undefined`
### EnumWrapper.prototype.has
`EnumWrapper.prototype.has(key: string): key is KeyType`
### EnumWrapper.prototype.keys
`EnumWrapper.prototype.keys(): IterableIterator<KeyType>`
### EnumWrapper.prototype.values
`EnumWrapper.prototype.values(): IterableIterator<EnumType>`
### EnumWrapper.prototype.entries
`EnumWrapper.prototype.entries(): IterableIterator<[KeyType, EnumType]>`
### EnumWrapper.prototype.getKeys
`EnumWrapper.prototype.getKeys(): KeyType[]`
### EnumWrapper.prototype.getValues
`EnumWrapper.prototype.getValues(): EnumType[]`
### EnumWrapper.prototype.getEntries
`EnumWrapper.prototype.getEntries(): [KeyType, EnumType][]`
## Limitations
Does not work with enums that are merged with a namespace containing values (variables, functions, etc.), or otherwise have any additional properties added to the enum's runtime object.

444

src/index.ts

@@ -12,3 +12,3 @@ /**

/**
* A generic wrapper for any enum-like value (see {@link EnumLike} type for more explanation).
* A generic wrapper for any enum-like object (see {@link EnumLike}).
* Provides utilities for runtime processing of an enum's values and keys, with strict compile-time

@@ -19,2 +19,3 @@ * type safety.

* instance:
* - {@link $enum}
* - {@link EnumWrapper.getCachedInstance}

@@ -53,10 +54,12 @@ * - {@link EnumWrapper.createUncachedInstance}

/**
* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* Creates a new EnumWrapper for an enum-like object with number values.
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with number values.
* @return A new instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/

@@ -67,10 +70,12 @@ public static createUncachedInstance<T extends EnumLike<number, keyof T>>(

/**
* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* Creates a new EnumWrapper for an enum-like object with string values.
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with string values.
* @return A new instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/

@@ -81,10 +86,12 @@ public static createUncachedInstance<T extends EnumLike<string, keyof T>>(

/**
* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* Creates a new EnumWrapper for an enum-like object with a mix of number and string values.
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with a mix of number and string values.
* @return A new instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/

@@ -96,6 +103,6 @@ public static createUncachedInstance<T extends EnumLike<number | string, keyof T>>(

* Creates a new EnumWrapper for an enum-like object.
* You probably want to use {@link EnumWrapper.getCachedInstance} for any typical enums, because it will
* You probably want to use {@link EnumWrapper.getCachedInstance} for typical enums, because it will
* cache the result.
* This method may be useful if you want an EnumWrapper for an enum-like object that is dynamically
* built at runtime, is used only within a limited/tranient context in the application, and is likely
* built at runtime, is used only within a limited/transient context in the application, and is likely
* to clutter the cache without ever being reused.

@@ -110,9 +117,11 @@ * @param enumObj - An enum-like object.

/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object with number values.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance
* will be quickly retrieved/reused on every subsequent call to get() for the same enum object.
* Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with number values.
* @return An instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/

@@ -123,9 +132,11 @@ public static getCachedInstance<T extends EnumLike<number, keyof T>>(

/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object with string values.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance
* will be quickly retrieved/reused on every subsequent call to get() for the same enum object.
* Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with string values.
* @return An instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/

@@ -136,9 +147,11 @@ public static getCachedInstance<T extends EnumLike<string, keyof T>>(

/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object with a mixture of number and string values.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance
* will be quickly retrieved/reused on every subsequent call to get() for the same enum object.
* Use {@link EnumWrapper.createUncachedInstance} if you don't want the EnumWrapper to be cached.
* @param enumObj - An enum-like object.
* @param enumObj - An enum-like object with a mixture of number and string values.
* @return An instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/

@@ -149,4 +162,4 @@ public static getCachedInstance<T extends EnumLike<number | string, keyof T>>(

/**
* Creates a new EnumWrapper, or returns a cached EnumWrapper if one has already been created for the same
* object via {@link EnumWrapper.getCachedInstance}.
* Gets a cached EnumWrapper for an enum-like object.
* Creates and caches a new EnumWrapper if one is not already cached.
* This is most useful for typical enums that are statically defined, because the cached EnumWrapper instance

@@ -197,32 +210,38 @@ * will be quickly retrieved/reused on every subsequent call to get() for the same enum object.

/**
* The number of entries in this enum.
* @return "[object EnumWrapper]"
*/
public get size(): number {
return this.keySet.size;
public toString(): string {
return "[object EnumWrapper]";
}
/**
* Get a list of this enum's keys.
* @return A list of this enum's keys.
* The number of entries in this enum.
*/
public getKeys(): (keyof T)[] {
return Array.from(this.keySet.values());
public get size(): number {
return this.keySet.size;
}
/**
* Get a list of this enum's values.
* NOTE: If this enum has any duplicate values, only unique values will be returned, and the
* length of the list will be less than {@link EnumWrapper#size}.
* @return A list of this enum's values.
* Gets the enum value for the provided key.
* Returns undefined if the provided key is invalid.
* This is an alias for {@link EnumWrapper#getValueOrDefault} for the purpose
* of implementing a Map-like interface.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns undefined if the provided key is invalid.
*/
public getValues(): T[keyof T][] {
return Array.from(this.valueSet.values());
public get(key: string): T[keyof T] | undefined {
return this.getValueOrDefault(key, undefined);
}
/**
* Get a list of this enum's entries as [key, value] tuples.
* @return A list of this enum's entries as [key, value] tuples.
* Tests if the provided string is actually a valid key for this enum
* Acts as a type guard to confirm that the provided value is actually the enum key type.
* This is an alias for {@link EnumWrapper#isKey} for the purpose
* of implementing a Map-like interface.
* @param key - A potential key value for this enum.
* @return True if the provided key is a valid key for this enum.
*/
public getEntries(): EnumWrapper.Entry<T>[] {
return Array.from(this);
public has(key: string): key is keyof T {
return this.isKey(key);
}

@@ -267,3 +286,3 @@

[Symbol.iterator]: function(): IterableIterator<EnumWrapper.Entry<T>> {
[Symbol.iterator](): IterableIterator<EnumWrapper.Entry<T>> {
return this;

@@ -302,2 +321,4 @@ }

* @return A new array containg the results of the iteratee.
*
* @template R - The of the mapped result for each entry.
*/

@@ -314,7 +335,46 @@ public map<R>(iteratee: EnumWrapper.Iteratee<V, T, R>, context?: any): R[] {

public isKey(key: string | undefined): key is keyof T {
return key !== undefined && this.keySet.has(key);
/**
* Get a list of this enum's keys.
* @return A list of this enum's keys.
*/
public getKeys(): (keyof T)[] {
return Array.from(this.keySet.values());
}
public asKey(key: string | undefined): keyof T {
/**
* Get a list of this enum's values.
* NOTE: If this enum has any duplicate values, only unique values will be returned, and the
* length of the list will be less than {@link EnumWrapper#size}.
* @return A list of this enum's values.
*/
public getValues(): T[keyof T][] {
return Array.from(this.valueSet.values());
}
/**
* Get a list of this enum's entries as [key, value] tuples.
* @return A list of this enum's entries as [key, value] tuples.
*/
public getEntries(): EnumWrapper.Entry<T>[] {
return Array.from(this);
}
/**
* Tests if the provided string is actually a valid key for this enum
* Acts as a type guard to confirm that the provided value is actually the enum key type.
* @param key - A potential key value for this enum.
* @return True if the provided key is a valid key for this enum.
*/
public isKey(key: string): key is keyof T {
return this.keySet.has(key);
}
/**
* Casts a string to a properly-typed key for this enum.
* Throws an error if the key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* @throws {Error} if the provided string is not a valid key for this enum.
*/
public asKey(key: string): keyof T {
if (this.isKey(key)) {

@@ -327,7 +387,42 @@ return key;

public asKeyOrDefault(key: string | undefined, defaultKey?: keyof T): keyof T | undefined;
public asKeyOrDefault(key: string | undefined, defaultKey: keyof T): keyof T;
public asKeyOrDefault(key: string | undefined, defaultKey: string): keyof T | string;
public asKeyOrDefault(key: string | undefined, defaultKey: string | undefined): keyof T | string | undefined;
public asKeyOrDefault(key: string | undefined, defaultKey?: keyof T | string): keyof T | string | undefined {
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
public asKeyOrDefault(key: string, defaultKey: keyof T): keyof T;
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
public asKeyOrDefault(key: string, defaultKey?: keyof T): keyof T | undefined;
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
public asKeyOrDefault(key: string, defaultKey: string): string;
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
public asKeyOrDefault(key: string, defaultKey: string | undefined): string | undefined;
/**
* Casts a string to a properly-typed key for this enum.
* Returns a default key if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The provided key value, cast to the type of this enum's keys.
* Returns `defaultKey` if the provided key is invalid.
*/
public asKeyOrDefault(key: string, defaultKey?: keyof T | string): string | undefined {
if (this.isKey(key)) {

@@ -338,10 +433,22 @@ return key;

}
}
public isValue(value: V | undefined): value is T[keyof T] {
/**
* Tests if the provided value is a valid value for this enum.
* Acts as a type guard to confirm that the provided value is actually the enum value type.
* @param value - A potential value for this enum.
* @return True if the provided value is valid for this enum.
*/
public isValue(value: V): value is T[keyof T] {
return value !== undefined && this.valueSet.has(value);
}
public asValue(value: V | undefined): T[keyof T] {
/**
* Casts a value to a properly-typed value for this enum.
* Throws an error if the value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* @throws {Error} if the provided value is not a valid value for this enum.
*/
public asValue(value: V): T[keyof T] {
if (this.isValue(value)) {

@@ -354,7 +461,42 @@ return value;

public asValueOrDefault(value: V | undefined, defaultValue?: T[keyof T]): T[keyof T] | undefined;
public asValueOrDefault(value: V | undefined, defaultValue: T[keyof T]): T[keyof T];
public asValueOrDefault(value: V | undefined, defaultValue: V): T[keyof T] | V;
public asValueOrDefault(value: V | undefined, defaultValue: V | undefined): T[keyof T] | V | undefined;
public asValueOrDefault(value: V | undefined, defaultValue?: T[keyof T] | V): T[keyof T] | V | undefined {
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
public asValueOrDefault(value: V, defaultValue: T[keyof T]): T[keyof T];
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
public asValueOrDefault(value: V, defaultValue?: T[keyof T]): T[keyof T] | undefined;
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
public asValueOrDefault(value: V, defaultValue: V): V;
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
public asValueOrDefault(value: V, defaultValue: V | undefined): V | undefined;
/**
* Casts a value to a properly-typed value for this enum.
* Returns a default value if the provided value is invalid.
* @param value - A potential value for this enum.
* @return The provided value, cast to the type of this enum's values.
* Returns `defaultValue` if the provided value is invalid.
*/
public asValueOrDefault(value: V, defaultValue?: T[keyof T] | V): V | undefined {
if (this.isValue(value)) {

@@ -367,11 +509,65 @@ return value;

public getKey(value: V | undefined): keyof T {
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Throws an error if the value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* @throws {Error} if the provided value is not a valid value for this enum.
*/
public getKey(value: V): keyof T {
return this.keysByValueMap.get(this.asValue(value));
}
public getKeyOrDefault(value: V | undefined, defaultKey?: keyof T): keyof T | undefined;
public getKeyOrDefault(value: V | undefined, defaultKey: keyof T): keyof T;
public getKeyOrDefault(value: V | undefined, defaultKey: string): keyof T | string;
public getKeyOrDefault(value: V | undefined, defaultKey: string | undefined): keyof T | string | undefined;
public getKeyOrDefault(value: V | undefined, defaultKey?: keyof T | string): keyof T | string | undefined {
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
public getKeyOrDefault(value: V, defaultKey: keyof T): keyof T;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
public getKeyOrDefault(value: V, defaultKey?: keyof T): keyof T | undefined;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
public getKeyOrDefault(value: V, defaultKey: string): string;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
public getKeyOrDefault(value: V, defaultKey: string | undefined): string | undefined;
/**
* Performs a reverse lookup from enum value to corresponding enum key.
* Returns a default key if the provided value is invalid.
* NOTE: If this enum has any duplicate values, then one of the keys for the duplicated value is
* arbitrarily returned.
* @param value - A potential value for this enum.
* @return The key for the provided value.
* Returns `defaultKey` if the provided value is invalid.
*/
public getKeyOrDefault(value: V, defaultKey?: keyof T | string): string | undefined {
if (this.isValue(value)) {

@@ -384,15 +580,55 @@ return this.keysByValueMap.get(value);

public getValue(key: string | undefined): T[keyof T] {
/**
* Gets the enum value for the provided key.
* Throws an error if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* @throws {Error} if the provided string is not a valid key for this enum.
*/
public getValue(key: string): T[keyof T] {
return this.enumObj[this.asKey(key)];
}
public getValueOrDefault(key: string | undefined, defaultValue?: T[keyof T]): T[keyof T] | undefined;
public getValueOrDefault(key: string | undefined, defaultValue: T[keyof T]): T[keyof T];
public getValueOrDefault(key: string | undefined, defaultValue: V): T[keyof T] | V;
public getValueOrDefault(key: string | undefined, defaultValue: V | undefined): T[keyof T] | V | undefined;
public getValueOrDefault(key: string | undefined, defaultValue?: T[keyof T] | V): T[keyof T] | V | undefined {
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
public getValueOrDefault(key: string, defaultValue: T[keyof T]): T[keyof T];
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
public getValueOrDefault(key: string, defaultValue?: T[keyof T]): T[keyof T] | undefined;
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
public getValueOrDefault(key: string, defaultValue: V): V;
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
public getValueOrDefault(key: string, defaultValue: V | undefined): V | undefined;
/**
* Gets the enum value for the provided key.
* Returns a default value if the provided key is invalid.
* @param key - A potential key value for this enum.
* @return The enum value for the provided key.
* Returns `defaultValue` if the provided key is invalid.
*/
public getValueOrDefault(key: string, defaultValue?: T[keyof T] | V): V | undefined {
if (this.isKey(key)) {
// type cast to "keyof T" is necessary until this bug is fixed:
// https://github.com/Microsoft/TypeScript/issues/21950
return this.enumObj[key as keyof T];
return this.enumObj[key];
} else {

@@ -405,7 +641,19 @@ return defaultValue;

export namespace EnumWrapper {
export type Entry<T> = [
keyof T,
T[keyof T]
];
/**
* A tuple containing the key and value of a single entry in an enum.
* @template T - Type of an enum-like object.
*/
export type Entry<T> = [keyof T, T[keyof T]];
/**
* A function used in iterating all key/value entries in an enum.
* @param value - An enum value.
* @param key - An enum key.
* @param enumObj - The enum-like object that the key/value entrie belongs to.
* @return A result. The significance of the result depends on the type of iteration being performed.
*
* @template V - Type of the enum value.
* @template T - Type of the enum-like object that is being wrapped.
* @template R - The type of the result.
*/
export type Iteratee<

@@ -418,11 +666,49 @@ V extends number | string,

/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object with number values.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
export function $enum<T extends EnumLike<number, keyof T>>(
enumObj: T, useCache?: boolean
): EnumWrapper<number, T>;
/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object with string values.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
export function $enum<T extends EnumLike<string, keyof T>>(
enumObj: T, useCache?: boolean
): EnumWrapper<string, T>;
/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object with a mixture of number and string values.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*
* @template T - Type of the enum-like object that is being wrapped.
*/
export function $enum<T extends EnumLike<number | string, keyof T>>(
enumObj: T, useCache?: boolean
): EnumWrapper<number | string, T>;
/**
* Convenience function for getting/creating an {@link EnumWrapper} instance.
* This is a short-hand way of calling {@link EnumWrapper.getCachedInstance}.
* or {@link EnumWrapper.createUnachedInstance}.
* @param enumObj - An enum-like object.
* @param useCache - If true, then a cached instance is created and/or returned.
* @return A new or cached instance of EnumWrapper for the provided enumObj.
*/
export function $enum(enumObj: any, useCache: boolean = true): EnumWrapper {

@@ -429,0 +715,0 @@ if (useCache) {

dist/commonjs/index.js.map

Sorry, the diff of this file is not supported yet

dist/es/index.js.map

Sorry, the diff of this file is not supported yet

LICENSE

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc