ts-enum-util
Advanced tools
Comparing version 0.0.10 to 0.0.11
@@ -190,4 +190,4 @@ "use strict"; | ||
var _this = this; | ||
this.keySet.forEach(function (key) { | ||
iteratee.call(context, _this.enumObj[key], key, _this.enumObj); | ||
Array.prototype.forEach.call(this, function (entry, index) { | ||
iteratee.call(context, entry[1], entry[0], _this, index); | ||
}); | ||
@@ -208,7 +208,5 @@ }; | ||
var _this = this; | ||
var result = []; | ||
this.keySet.forEach(function (key) { | ||
result.push(iteratee.call(context, _this.enumObj[key], key, _this.enumObj)); | ||
return Array.prototype.map.call(this, function (entry, index) { | ||
return iteratee.call(context, entry[1], entry[0], _this, index); | ||
}); | ||
return result; | ||
}; | ||
@@ -221,3 +219,6 @@ /** | ||
EnumWrapper.prototype.getKeys = function () { | ||
return Array.from(this.keys()); | ||
// Taking advantage of "this" being ArrayLike<EnumWrapper.Entry>. | ||
return Array.prototype.map.call(this, function (entry) { | ||
return entry[0]; | ||
}); | ||
}; | ||
@@ -232,3 +233,5 @@ /** | ||
EnumWrapper.prototype.getValues = function () { | ||
return Array.from(this.values()); | ||
return Array.prototype.map.call(this, function (entry) { | ||
return entry[1]; | ||
}); | ||
}; | ||
@@ -241,3 +244,5 @@ /** | ||
EnumWrapper.prototype.getEntries = function () { | ||
return Array.from(this); | ||
return Array.prototype.map.call(this, function (entry) { | ||
return [entry[0], entry[1]]; | ||
}); | ||
}; | ||
@@ -277,2 +282,4 @@ /** | ||
if (this.isKey(key)) { | ||
// type cast require to work around TypeScript bug: | ||
// https://github.com/Microsoft/TypeScript/issues/21950 | ||
return key; | ||
@@ -291,3 +298,3 @@ } | ||
EnumWrapper.prototype.isValue = function (value) { | ||
return value !== undefined && this.keysByValueMap.has(value); | ||
return value != null && this.keysByValueMap.has(value); | ||
}; | ||
@@ -372,2 +379,4 @@ /** | ||
if (this.isKey(key)) { | ||
// type cast require to work around TypeScript bug: | ||
// https://github.com/Microsoft/TypeScript/issues/21950 | ||
return this.enumObj[key]; | ||
@@ -374,0 +383,0 @@ } |
@@ -188,4 +188,4 @@ /** | ||
var _this = this; | ||
this.keySet.forEach(function (key) { | ||
iteratee.call(context, _this.enumObj[key], key, _this.enumObj); | ||
Array.prototype.forEach.call(this, function (entry, index) { | ||
iteratee.call(context, entry[1], entry[0], _this, index); | ||
}); | ||
@@ -206,7 +206,5 @@ }; | ||
var _this = this; | ||
var result = []; | ||
this.keySet.forEach(function (key) { | ||
result.push(iteratee.call(context, _this.enumObj[key], key, _this.enumObj)); | ||
return Array.prototype.map.call(this, function (entry, index) { | ||
return iteratee.call(context, entry[1], entry[0], _this, index); | ||
}); | ||
return result; | ||
}; | ||
@@ -219,3 +217,6 @@ /** | ||
EnumWrapper.prototype.getKeys = function () { | ||
return Array.from(this.keys()); | ||
// Taking advantage of "this" being ArrayLike<EnumWrapper.Entry>. | ||
return Array.prototype.map.call(this, function (entry) { | ||
return entry[0]; | ||
}); | ||
}; | ||
@@ -230,3 +231,5 @@ /** | ||
EnumWrapper.prototype.getValues = function () { | ||
return Array.from(this.values()); | ||
return Array.prototype.map.call(this, function (entry) { | ||
return entry[1]; | ||
}); | ||
}; | ||
@@ -239,3 +242,5 @@ /** | ||
EnumWrapper.prototype.getEntries = function () { | ||
return Array.from(this); | ||
return Array.prototype.map.call(this, function (entry) { | ||
return [entry[0], entry[1]]; | ||
}); | ||
}; | ||
@@ -275,2 +280,4 @@ /** | ||
if (this.isKey(key)) { | ||
// type cast require to work around TypeScript bug: | ||
// https://github.com/Microsoft/TypeScript/issues/21950 | ||
return key; | ||
@@ -289,3 +296,3 @@ } | ||
EnumWrapper.prototype.isValue = function (value) { | ||
return value !== undefined && this.keysByValueMap.has(value); | ||
return value != null && this.keysByValueMap.has(value); | ||
}; | ||
@@ -370,2 +377,4 @@ /** | ||
if (this.isKey(key)) { | ||
// type cast require to work around TypeScript bug: | ||
// https://github.com/Microsoft/TypeScript/issues/21950 | ||
return this.enumObj[key]; | ||
@@ -372,0 +381,0 @@ } |
@@ -154,3 +154,3 @@ /** | ||
*/ | ||
get(key: string): T[keyof T] | undefined; | ||
get(key: string | null | undefined): T[keyof T] | undefined; | ||
/** | ||
@@ -164,3 +164,3 @@ * Tests if the provided string is actually a valid key for this enum | ||
*/ | ||
has(key: string): key is keyof T; | ||
has(key: string | null | undefined): key is keyof T; | ||
/** | ||
@@ -241,3 +241,3 @@ * Get an iterator for this enum's keys. | ||
*/ | ||
isKey(key: string): key is keyof T; | ||
isKey(key: string | null | undefined): key is keyof T; | ||
/** | ||
@@ -250,3 +250,3 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
asKey(key: string): keyof T; | ||
asKey(key: string | null | undefined): keyof T; | ||
/** | ||
@@ -259,3 +259,3 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
asKeyOrDefault(key: string, defaultKey: keyof T): keyof T; | ||
asKeyOrDefault(key: string | null | undefined, defaultKey: keyof T): keyof T; | ||
/** | ||
@@ -268,3 +268,3 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
asKeyOrDefault(key: string, defaultKey?: keyof T): keyof T | undefined; | ||
asKeyOrDefault(key: string | null | undefined, defaultKey?: keyof T): keyof T | undefined; | ||
/** | ||
@@ -277,3 +277,3 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
asKeyOrDefault(key: string, defaultKey: string): string; | ||
asKeyOrDefault(key: string | null | undefined, defaultKey: string): string; | ||
/** | ||
@@ -286,3 +286,3 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
asKeyOrDefault(key: string, defaultKey: string | undefined): string | undefined; | ||
asKeyOrDefault(key: string | null | undefined, defaultKey: string | undefined): string | undefined; | ||
/** | ||
@@ -294,3 +294,3 @@ * Tests if the provided value is a valid value for this enum. | ||
*/ | ||
isValue(value: V): value is T[keyof T]; | ||
isValue(value: V | null | undefined): value is T[keyof T]; | ||
/** | ||
@@ -303,3 +303,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
asValue(value: V): T[keyof T]; | ||
asValue(value: V | null | undefined): T[keyof T]; | ||
/** | ||
@@ -312,3 +312,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
asValueOrDefault(value: V, defaultValue: T[keyof T]): T[keyof T]; | ||
asValueOrDefault(value: V | null | undefined, defaultValue: T[keyof T]): T[keyof T]; | ||
/** | ||
@@ -321,3 +321,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
asValueOrDefault(value: V, defaultValue?: T[keyof T]): T[keyof T] | undefined; | ||
asValueOrDefault(value: V | null | undefined, defaultValue?: T[keyof T]): T[keyof T] | undefined; | ||
/** | ||
@@ -330,3 +330,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
asValueOrDefault(value: V, defaultValue: V): V; | ||
asValueOrDefault(value: V | null | undefined, defaultValue: V): V; | ||
/** | ||
@@ -339,3 +339,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
asValueOrDefault(value: V, defaultValue: V | undefined): V | undefined; | ||
asValueOrDefault(value: V | null | undefined, defaultValue: V | undefined): V | undefined; | ||
/** | ||
@@ -350,3 +350,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
getKey(value: V): keyof T; | ||
getKey(value: V | null | undefined): keyof T; | ||
/** | ||
@@ -361,3 +361,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
getKeyOrDefault(value: V, defaultKey: keyof T): keyof T; | ||
getKeyOrDefault(value: V | null | undefined, defaultKey: keyof T): keyof T; | ||
/** | ||
@@ -372,3 +372,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
getKeyOrDefault(value: V, defaultKey?: keyof T): keyof T | undefined; | ||
getKeyOrDefault(value: V | null | undefined, defaultKey?: keyof T): keyof T | undefined; | ||
/** | ||
@@ -383,3 +383,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
getKeyOrDefault(value: V, defaultKey: string): string; | ||
getKeyOrDefault(value: V | null | undefined, defaultKey: string): string; | ||
/** | ||
@@ -394,3 +394,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
getKeyOrDefault(value: V, defaultKey: string | undefined): string | undefined; | ||
getKeyOrDefault(value: V | null | undefined, defaultKey: string | undefined): string | undefined; | ||
/** | ||
@@ -403,3 +403,3 @@ * Gets the enum value for the provided key. | ||
*/ | ||
getValue(key: string): T[keyof T]; | ||
getValue(key: string | null | undefined): T[keyof T]; | ||
/** | ||
@@ -412,3 +412,3 @@ * Gets the enum value for the provided key. | ||
*/ | ||
getValueOrDefault(key: string, defaultValue: T[keyof T]): T[keyof T]; | ||
getValueOrDefault(key: string | null | undefined, defaultValue: T[keyof T]): T[keyof T]; | ||
/** | ||
@@ -421,3 +421,3 @@ * Gets the enum value for the provided key. | ||
*/ | ||
getValueOrDefault(key: string, defaultValue?: T[keyof T]): T[keyof T] | undefined; | ||
getValueOrDefault(key: string | null | undefined, defaultValue?: T[keyof T]): T[keyof T] | undefined; | ||
/** | ||
@@ -430,3 +430,3 @@ * Gets the enum value for the provided key. | ||
*/ | ||
getValueOrDefault(key: string, defaultValue: V): V; | ||
getValueOrDefault(key: string | null | undefined, defaultValue: V): V; | ||
/** | ||
@@ -439,3 +439,3 @@ * Gets the enum value for the provided key. | ||
*/ | ||
getValueOrDefault(key: string, defaultValue: V | undefined): V | undefined; | ||
getValueOrDefault(key: string | null | undefined, defaultValue: V | undefined): V | undefined; | ||
} | ||
@@ -454,2 +454,3 @@ export declare namespace EnumWrapper { | ||
* @param enumObj - The enum-like object that the key/value entrie belongs to. | ||
* @param index - The index of the enum entry, based on sorted order of keys. | ||
* @return A result. The significance of the result depends on the type of iteration being performed. | ||
@@ -461,3 +462,3 @@ * | ||
*/ | ||
type Iteratee<R = any, V extends number | string = number | string, T extends EnumLike<V, keyof T> = any> = (this: any, value: V, key: keyof T, enumObj: T) => R; | ||
type Iteratee<R = any, V extends number | string = number | string, T extends EnumLike<V, keyof T> = any> = (this: any, value: V, key: keyof T, enumWrapper: EnumWrapper<V, T>, index: number) => R; | ||
} | ||
@@ -464,0 +465,0 @@ /** |
{ | ||
"name": "ts-enum-util", | ||
"version": "0.0.10", | ||
"version": "0.0.11", | ||
"description": "TypeScript Enum Utilities", | ||
@@ -5,0 +5,0 @@ "repository": { |
263
README.md
@@ -13,16 +13,17 @@ [![npm version](https://img.shields.io/npm/v/ts-enum-util.svg)](https://www.npmjs.com/package/ts-enum-util) | ||
- [What is it?](#what-is-it) | ||
- [Quick Start](#quick-start) | ||
- [Installation](#installation) | ||
- [Usage Examples](#usage-examples) | ||
- [Basic setup for all examples](#basic-setup-for-all-examples) | ||
- [Get count of enum entries](#get-count-of-enum-entries) | ||
- [Get lists of enum data](#get-lists-of-enum-data) | ||
- [Lookup value by key](#lookup-value-by-key) | ||
- [Reverse lookup key by value](#reverse-lookup-key-by-value) | ||
- [Validate/convert enum keys](#validateconvert-enum-keys) | ||
- [Validate/convert enum values](#validateconvert-enum-values) | ||
- [Iteration and mapping](#iteration-and-mapping) | ||
- [Wrapped enums are Array-Like](#wrapped-enums-are-array-like) | ||
- [Wrapped enums are Map-Like](#wrapped-enums-are-map-like) | ||
- [Installation](#installation) | ||
- [Usage Examples](#usage-examples) | ||
- [Basic setup for all examples](#basic-setup-for-all-examples) | ||
- [Get an `EnumWrapper` instance for an enum](#get-an-enumwrapper-instance-for-an-enum) | ||
- [Get count of enum entries](#get-count-of-enum-entries) | ||
- [Get lists of enum data](#get-lists-of-enum-data) | ||
- [Lookup value by key](#lookup-value-by-key) | ||
- [Reverse lookup key by value](#reverse-lookup-key-by-value) | ||
- [Validate/convert enum keys](#validateconvert-enum-keys) | ||
- [Validate/convert enum values](#validateconvert-enum-values) | ||
- [Iteration and Mapping](#iteration-and-mapping) | ||
- [Wrapped enums are Array-Like](#wrapped-enums-are-array-like) | ||
- [Wrapped enums are Map-Like](#wrapped-enums-are-map-like) | ||
- [Requirements](#requirements) | ||
- [Limitations](#limitations) | ||
- [General Concepts](#general-concepts) | ||
@@ -33,3 +34,3 @@ - [Enum-Like Object](#enum-like-object) | ||
- [Map-Like Interface](#map-like-interface) | ||
- [ArrayLike Interface](#arraylike-interface) | ||
- [Array-Like Interface](#array-like-interface) | ||
- [Guaranteed Order of Iteration](#guaranteed-order-of-iteration) | ||
@@ -66,3 +67,2 @@ - [Caching](#caching) | ||
- [EnumWrapper.prototype.getValueOrDefault](#enumwrapperprototypegetvalueordefault) | ||
- [Limitations](#limitations) | ||
@@ -82,4 +82,3 @@ <!-- /TOC --> | ||
## Quick Start | ||
### Installation | ||
## Installation | ||
Install via [NPM](https://www.npmjs.com/package/ts-enum-util): | ||
@@ -90,3 +89,3 @@ ``` | ||
### Usage Examples | ||
## Usage Examples | ||
Several small examples `ts-enum-util`'s capabilities to give you a quick overview of what it can do, as well as an organized "by example" reference. | ||
@@ -98,3 +97,3 @@ | ||
#### Basic setup for all examples | ||
### Basic setup for all examples | ||
```ts | ||
@@ -114,3 +113,12 @@ // import the $enum helper function | ||
#### Get count of enum entries | ||
### Get an `EnumWrapper` instance for an enum | ||
Use the [$eunum](#enum) function to get an `EnumWrapper` instance for a particular enum. | ||
Read about how `EnumWrapper` instances are cached: [Caching](#caching). | ||
```ts | ||
// type: EnumWrapper<string, RGB> | ||
const wrappedRgb = $enum(RGB); | ||
``` | ||
### Get count of enum entries | ||
See also: | ||
@@ -129,3 +137,3 @@ - [Wrapped enums are Array-Like](#wrapped-enums-are-array-like) | ||
#### Get lists of enum data | ||
### Get lists of enum data | ||
See also: | ||
@@ -150,3 +158,3 @@ - [Guaranteed Order of Iteration](#guaranteed-order-of-iteration) | ||
#### Lookup value by key | ||
### Lookup value by key | ||
See also: | ||
@@ -175,3 +183,3 @@ - [Wrapped enums are Map-Like](#wrapped-enums-are-map-like) | ||
#### Reverse lookup key by value | ||
### Reverse lookup key by value | ||
```ts | ||
@@ -198,3 +206,3 @@ // type: ("R" | "G" | "B") | ||
#### Validate/convert enum keys | ||
### Validate/convert enum keys | ||
```ts | ||
@@ -223,3 +231,3 @@ // Some arbitrary string | ||
#### Validate/convert enum values | ||
### Validate/convert enum values | ||
```ts | ||
@@ -248,11 +256,14 @@ // Some arbitrary string | ||
#### Iteration and mapping | ||
### Iteration and Mapping | ||
See also: | ||
- [Guaranteed Order of Iteration](#guaranteed-order-of-iteration) | ||
```ts | ||
const wrappedRgb = $enum(RGB); | ||
// iterate all entries in the enum | ||
$enum(RGB).forEach((value, key, rgbRef) => { | ||
wrappedRgb.forEach((value, key, wrappedEnum, index) => { | ||
// type of value is RGB | ||
// type of key is ("R" | "G" | "B") | ||
// rgbRef is a reference to RGB object, type is (typeof RBG) | ||
// wrappedEnum is a reference to wrappedRgb | ||
// index is based on sorted key order | ||
}); | ||
@@ -262,6 +273,7 @@ | ||
// value: ["R: r", "G: g", "B: b"] | ||
const mapped = $enum(RGB).map((value, key, rgbRef) => { | ||
const mapped = wrappedRgb.map((value, key, wrappedEnum, index) => { | ||
// type of value is RGB | ||
// type of key is ("R" | "G" | "B") | ||
// rgbRef is a reference to RGB object, type is (typeof RBG) | ||
// wrappedEnum is a reference to wrappedRgb | ||
// index is based on sorted key order | ||
return `${key}: ${value}`; | ||
@@ -271,3 +283,3 @@ }); | ||
#### Wrapped enums are Array-Like | ||
### Wrapped enums are Array-Like | ||
A wrapped enum can be treated like an array of enum "entry" tuples. | ||
@@ -289,3 +301,3 @@ | ||
#### Wrapped enums are Map-Like | ||
### Wrapped enums are Map-Like | ||
A wrapped enum is effectively a read-only `Map` of enum "entry" tuples. | ||
@@ -321,5 +333,9 @@ | ||
## 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`. | ||
* For certain `Iterable` features of `WrappedEnum` to work, you must either compile with a target of `es6` or higher, or enable the `downlevelIteration` compiler option. | ||
- *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`. | ||
## 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. | ||
- Requires the `preserveConstEnums` TypeScript compiler option to work with `const enums`. | ||
- For certain `Iterable` features of `WrappedEnum` to work, you must either compile with a target of `es6` or higher, or enable the `downlevelIteration` compiler option. | ||
## General Concepts | ||
@@ -351,4 +367,4 @@ ### Enum-Like Object | ||
### ArrayLike Interface | ||
`EnumWrapper` implements the `ArrayLike`. It is usable as a readonly array of [EnumWrapper.Entry](#enumwrapperentry), which allows you to pass an `EnumWrapper` instance to any method that is designed read/iterate an array-like value, such as most of [lodash](#https://lodash.com/)'s methods for collections and arrays. | ||
### Array-Like Interface | ||
`EnumWrapper` implements the `ArrayLike` interface. It is usable as a readonly array of [EnumWrapper.Entry](#enumwrapperentry). This allows you to pass an `EnumWrapper` instance to any method that is designed read/iterate an array-like value, such as most of [lodash](#https://lodash.com/)'s methods for collections and arrays. | ||
@@ -379,3 +395,3 @@ ### Guaranteed Order of Iteration | ||
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 worrying about maintaining a reference to it. Of course, it's still good practice to store a reference to the `EnumWrapper` within certain code contexts where you heavily use a particular enum's wrapper. | ||
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 worrying about maintaining a global reference to it. Of course, it's still good practice to at least temporarily store a reference to the `EnumWrapper` instance within certain code contexts where you heavily use a particular enum's wrapper. | ||
@@ -394,10 +410,15 @@ 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 that is specific to a particular function execution, class instance, etc.. This is useful to avoid cluttering the cache and unnecessarily occupying memory with an `EnumWrapper` that will never be retrieved from the cache. | ||
Throughout this reference, 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. | ||
- `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. | ||
```ts | ||
function $enum( | ||
enumObj: EnumLike, | ||
useCache: boolean = true | ||
): EnumWrapper | ||
``` | ||
- `useCache` - False to force a new instance of `EnumWrapper` to be created and returned without any caching. | ||
@@ -409,3 +430,5 @@ 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. | ||
### EnumWrapper | ||
`class EnumWrapper` | ||
```ts | ||
class EnumWrapper | ||
``` | ||
@@ -415,3 +438,5 @@ 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.Entry | ||
`type EnumWrapper.Entry = Readonly<[KeyType, EnumType]>` | ||
```ts | ||
type EnumWrapper.Entry = Readonly<[KeyType, EnumType]> | ||
``` | ||
@@ -421,8 +446,17 @@ A generic type alias for a tuple containing a key and value pair, representing a complete "entry" in the enum. The tuple is defined as `Readonly` to prevent accidental corruption of the `EnumWrapper` instance's data. | ||
### EnumWrapper.Iteratee | ||
`type EnumWrapper.Iteratee = (value: EnumType, key: KeyType, enumObj: EnumLike) => R` | ||
```ts | ||
type EnumWrapper.Iteratee = ( | ||
value: EnumType, | ||
key: KeyType, | ||
enumWrapper: EnumWrapper, | ||
index: number | ||
) => R | ||
``` | ||
A generic type alias for a function signature to be used in iteration methods. | ||
A generic type alias for a function signature to be used in iteration methods. This is compliant with the signature of an iteratee for a `Map<KeyType, EnumType>.forEach()` method, except that it has an additional `index` param at the end of the parameter list. | ||
### EnumWrapper.prototype.size | ||
`EnumWrapper.prototype.size: number` | ||
```ts | ||
EnumWrapper.prototype.size: number | ||
``` | ||
@@ -432,3 +466,5 @@ A read-only property containing the number of entries (key/value pairs) in the enum. | ||
### EnumWrapper.prototype.length | ||
`EnumWrapper.prototype.length: number` | ||
```ts | ||
EnumWrapper.prototype.length: number | ||
``` | ||
@@ -438,66 +474,145 @@ 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` | ||
```ts | ||
EnumWrapper.prototype.get( | ||
key: string | null | undefined | ||
): EnumType | undefined | ||
``` | ||
### EnumWrapper.prototype.has | ||
`EnumWrapper.prototype.has(key: string): key is KeyType` | ||
```ts | ||
EnumWrapper.prototype.has( | ||
key: string | null | undefined | ||
): key is KeyType | ||
``` | ||
### EnumWrapper.prototype.keys | ||
`EnumWrapper.prototype.keys(): IterableIterator<KeyType>` | ||
```ts | ||
EnumWrapper.prototype.keys( | ||
): IterableIterator<KeyType> | ||
``` | ||
### EnumWrapper.prototype.values | ||
`EnumWrapper.prototype.values(): IterableIterator<EnumType>` | ||
```ts | ||
EnumWrapper.prototype.values( | ||
): IterableIterator<EnumType> | ||
``` | ||
### EnumWrapper.prototype.entries | ||
`EnumWrapper.prototype.entries(): IterableIterator<EnumWrapper.Entry>` | ||
```ts | ||
EnumWrapper.prototype.entries( | ||
): IterableIterator<EnumWrapper.Entry> | ||
``` | ||
### EnumWrapper.prototype.@@iterator | ||
`EnumWrapper.prototype.@@iterator(): IterableIterator<EnumWrapper.Entry>` | ||
```ts | ||
EnumWrapper.prototype.@@iterator( | ||
): IterableIterator<EnumWrapper.Entry> | ||
``` | ||
### EnumWrapper.prototype.forEach | ||
`EnumWrapper.prototype.forEach(iteratee: EnumWrapper.Iteratee, context?: any): void` | ||
```ts | ||
EnumWrapper.prototype.forEach( | ||
iteratee: EnumWrapper.Iteratee, | ||
context?: any | ||
): void | ||
``` | ||
### EnumWrapper.prototype.map | ||
`EnumWrapper.prototype.map<R>(iteratee: EnumWrapper.Iteratee, context?: any): R[]` | ||
```ts | ||
EnumWrapper.prototype.map<R>( | ||
iteratee: EnumWrapper.Iteratee, | ||
context?: any | ||
): R[] | ||
``` | ||
### EnumWrapper.prototype.getKeys | ||
`EnumWrapper.prototype.getKeys(): KeyType[]` | ||
```ts | ||
EnumWrapper.prototype.getKeys( | ||
): KeyType[] | ||
``` | ||
### EnumWrapper.prototype.getValues | ||
`EnumWrapper.prototype.getValues(): EnumType[]` | ||
```ts | ||
EnumWrapper.prototype.getValues( | ||
): EnumType[] | ||
``` | ||
### EnumWrapper.prototype.getEntries | ||
`EnumWrapper.prototype.getEntries(): EnumWrapper.Entry[]` | ||
```ts | ||
EnumWrapper.prototype.getEntries( | ||
): EnumWrapper.Entry[] | ||
``` | ||
### EnumWrapper.prototype.isKey | ||
`EnumWrapper.prototype.isKey(key: string): key is KeyType` | ||
```ts | ||
EnumWrapper.prototype.isKey( | ||
key: string | null | undefined | ||
): key is KeyType | ||
``` | ||
### EnumWrapper.prototype.asKey | ||
`EnumWrapper.prototype.asKey(key: string): KeyType` | ||
```ts | ||
EnumWrapper.prototype.asKey( | ||
key: string | null | undefined | ||
): KeyType | ||
``` | ||
### EnumWrapper.prototype.asKeyOrDefault | ||
`EnumWrapper.prototype.asKeyOrDefault(key: string, defaultKey?: KeyType | string): KeyType | string | undefined` | ||
```ts | ||
EnumWrapper.prototype.asKeyOrDefault( | ||
key: string | null | undefined, | ||
defaultKey?: KeyType | string | ||
): KeyType | string | undefined | ||
``` | ||
### EnumWrapper.prototype.isValue | ||
`EnumWrapper.prototype.isValue(value: ValueType): key is EnumType` | ||
```ts | ||
EnumWrapper.prototype.isValue( | ||
value: ValueType | null | undefined | ||
): key is EnumType | ||
``` | ||
### EnumWrapper.prototype.asValue | ||
`EnumWrapper.prototype.asValue(value: ValueType): EnumType` | ||
```ts | ||
EnumWrapper.prototype.asValue( | ||
value: ValueType | null | undefined | ||
): EnumType | ||
``` | ||
### EnumWrapper.prototype.asValueOrDefault | ||
`EnumWrapper.prototype.asValueOrDefault(value: ValueType, defaultValue?: EnumType | ValueType): EnumType | ValueType | undefined` | ||
```ts | ||
EnumWrapper.prototype.asValueOrDefault( | ||
value: ValueType | null | undefined, | ||
defaultValue?: EnumType | ValueType | ||
): EnumType | ValueType | undefined | ||
``` | ||
### EnumWrapper.prototype.getKey | ||
`EnumWrapper.prototype.getKey(value: ValueType): KeyType` | ||
```ts | ||
EnumWrapper.prototype.getKey( | ||
value: ValueType | null | undefined | ||
): KeyType | ||
``` | ||
### EnumWrapper.prototype.getKeyOrDefault | ||
`EnumWrapper.prototype.getKeyOrDefault(value: ValueType, defaultKey?: KeyType | string): KeyType | string | undefined` | ||
```ts | ||
EnumWrapper.prototype.getKeyOrDefault( | ||
value: ValueType | null | undefined, | ||
defaultKey?: KeyType | string | ||
): KeyType | string | undefined | ||
``` | ||
### EnumWrapper.prototype.getValue | ||
`EnumWrapper.prototype.getValue(key: string): EnumType` | ||
```ts | ||
EnumWrapper.prototype.getValue( | ||
key: string | null | undefined | ||
): EnumType | ||
``` | ||
### EnumWrapper.prototype.getValueOrDefault | ||
`EnumWrapper.prototype.getValueOrDefault(key: string, defaultValue?: EnumType | ValueType): EnumType | ValueType | undefined` | ||
## 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. | ||
- Requires the `preserveConstEnums` TypeScript compiler option to work with `const enums`. | ||
```ts | ||
EnumWrapper.prototype.getValueOrDefault( | ||
key: string | null | undefined, | ||
defaultValue?: EnumType | ValueType | ||
): EnumType | ValueType | undefined | ||
``` |
104
src/index.ts
@@ -236,3 +236,3 @@ /** | ||
*/ | ||
public get(key: string): T[keyof T] | undefined { | ||
public get(key: string | null | undefined): T[keyof T] | undefined { | ||
return this.getValueOrDefault(key, undefined); | ||
@@ -249,3 +249,3 @@ } | ||
*/ | ||
public has(key: string): key is keyof T { | ||
public has(key: string | null | undefined): key is keyof T { | ||
return this.isKey(key); | ||
@@ -343,5 +343,8 @@ } | ||
public forEach(iteratee: EnumWrapper.Iteratee<void, V, T>, context?: any): void { | ||
this.keySet.forEach((key) => { | ||
iteratee.call(context, this.enumObj[key], key, this.enumObj); | ||
}); | ||
Array.prototype.forEach.call( | ||
this, | ||
(entry: EnumWrapper.Entry<V, T>, index: number): void => { | ||
iteratee.call(context, entry[1], entry[0], this, index); | ||
} | ||
); | ||
} | ||
@@ -361,9 +364,8 @@ | ||
public map<R>(iteratee: EnumWrapper.Iteratee<R, V, T>, context?: any): R[] { | ||
const result: R[] = []; | ||
this.keySet.forEach((key) => { | ||
result.push(iteratee.call(context, this.enumObj[key], key, this.enumObj)); | ||
}); | ||
return result; | ||
return Array.prototype.map.call( | ||
this, | ||
(entry: EnumWrapper.Entry<V, T>, index: number): R => { | ||
return iteratee.call(context, entry[1], entry[0], this, index); | ||
} | ||
); | ||
} | ||
@@ -377,3 +379,6 @@ | ||
public getKeys(): (keyof T)[] { | ||
return Array.from(this.keys()); | ||
// Taking advantage of "this" being ArrayLike<EnumWrapper.Entry>. | ||
return Array.prototype.map.call(this, (entry: EnumWrapper.Entry<V, T>) => { | ||
return entry[0]; | ||
}); | ||
} | ||
@@ -389,3 +394,5 @@ | ||
public getValues(): T[keyof T][] { | ||
return Array.from(this.values()); | ||
return Array.prototype.map.call(this, (entry: EnumWrapper.Entry<V, T>) => { | ||
return entry[1]; | ||
}); | ||
} | ||
@@ -399,3 +406,5 @@ | ||
public getEntries(): EnumWrapper.Entry<V, T>[] { | ||
return Array.from(this); | ||
return Array.prototype.map.call(this, (entry: EnumWrapper.Entry<V, T>) => { | ||
return [entry[0], entry[1]]; | ||
}); | ||
} | ||
@@ -409,3 +418,3 @@ | ||
*/ | ||
public isKey(key: string): key is keyof T { | ||
public isKey(key: string | null | undefined): key is keyof T { | ||
return this.keySet.has(key); | ||
@@ -421,3 +430,3 @@ } | ||
*/ | ||
public asKey(key: string): keyof T { | ||
public asKey(key: string | null | undefined): keyof T { | ||
if (this.isKey(key)) { | ||
@@ -437,3 +446,3 @@ return key; | ||
*/ | ||
public asKeyOrDefault(key: string, defaultKey: keyof T): keyof T; | ||
public asKeyOrDefault(key: string | null | undefined, defaultKey: keyof T): keyof T; | ||
/** | ||
@@ -446,3 +455,3 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
public asKeyOrDefault(key: string, defaultKey?: keyof T): keyof T | undefined; | ||
public asKeyOrDefault(key: string | null | undefined, defaultKey?: keyof T): keyof T | undefined; | ||
/** | ||
@@ -455,3 +464,3 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
public asKeyOrDefault(key: string, defaultKey: string): string; | ||
public asKeyOrDefault(key: string | null | undefined, defaultKey: string): string; | ||
/** | ||
@@ -464,3 +473,3 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
public asKeyOrDefault(key: string, defaultKey: string | undefined): string | undefined; | ||
public asKeyOrDefault(key: string | null | undefined, defaultKey: string | undefined): string | undefined; | ||
/** | ||
@@ -473,5 +482,7 @@ * Casts a string to a properly-typed key for this enum. | ||
*/ | ||
public asKeyOrDefault(key: string, defaultKey?: keyof T | string): string | undefined { | ||
public asKeyOrDefault(key: string | null | undefined, defaultKey?: keyof T | string): string | undefined { | ||
if (this.isKey(key)) { | ||
return key; | ||
// type cast require to work around TypeScript bug: | ||
// https://github.com/Microsoft/TypeScript/issues/21950 | ||
return key as keyof T; | ||
} else { | ||
@@ -488,4 +499,4 @@ return defaultKey; | ||
*/ | ||
public isValue(value: V): value is T[keyof T] { | ||
return value !== undefined && this.keysByValueMap.has(value); | ||
public isValue(value: V | null | undefined): value is T[keyof T] { | ||
return value != null && this.keysByValueMap.has(value); | ||
} | ||
@@ -500,3 +511,3 @@ | ||
*/ | ||
public asValue(value: V): T[keyof T] { | ||
public asValue(value: V | null | undefined): T[keyof T] { | ||
if (this.isValue(value)) { | ||
@@ -516,3 +527,3 @@ return value; | ||
*/ | ||
public asValueOrDefault(value: V, defaultValue: T[keyof T]): T[keyof T]; | ||
public asValueOrDefault(value: V | null | undefined, defaultValue: T[keyof T]): T[keyof T]; | ||
/** | ||
@@ -525,3 +536,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
public asValueOrDefault(value: V, defaultValue?: T[keyof T]): T[keyof T] | undefined; | ||
public asValueOrDefault(value: V | null | undefined, defaultValue?: T[keyof T]): T[keyof T] | undefined; | ||
/** | ||
@@ -534,3 +545,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
public asValueOrDefault(value: V, defaultValue: V): V; | ||
public asValueOrDefault(value: V | null | undefined, defaultValue: V): V; | ||
/** | ||
@@ -543,3 +554,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
public asValueOrDefault(value: V, defaultValue: V | undefined): V | undefined; | ||
public asValueOrDefault(value: V | null | undefined, defaultValue: V | undefined): V | undefined; | ||
/** | ||
@@ -552,3 +563,3 @@ * Casts a value to a properly-typed value for this enum. | ||
*/ | ||
public asValueOrDefault(value: V, defaultValue?: T[keyof T] | V): V | undefined { | ||
public asValueOrDefault(value: V | null | undefined, defaultValue?: T[keyof T] | V): V | undefined { | ||
if (this.isValue(value)) { | ||
@@ -570,3 +581,3 @@ return value; | ||
*/ | ||
public getKey(value: V): keyof T { | ||
public getKey(value: V | null | undefined): keyof T { | ||
return this.keysByValueMap.get(this.asValue(value)); | ||
@@ -584,3 +595,3 @@ } | ||
*/ | ||
public getKeyOrDefault(value: V, defaultKey: keyof T): keyof T; | ||
public getKeyOrDefault(value: V | null | undefined, defaultKey: keyof T): keyof T; | ||
/** | ||
@@ -595,3 +606,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
public getKeyOrDefault(value: V, defaultKey?: keyof T): keyof T | undefined; | ||
public getKeyOrDefault(value: V | null | undefined, defaultKey?: keyof T): keyof T | undefined; | ||
/** | ||
@@ -606,3 +617,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
public getKeyOrDefault(value: V, defaultKey: string): string; | ||
public getKeyOrDefault(value: V | null | undefined, defaultKey: string): string; | ||
/** | ||
@@ -617,3 +628,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
public getKeyOrDefault(value: V, defaultKey: string | undefined): string | undefined; | ||
public getKeyOrDefault(value: V | null | undefined, defaultKey: string | undefined): string | undefined; | ||
/** | ||
@@ -628,3 +639,3 @@ * Performs a reverse lookup from enum value to corresponding enum key. | ||
*/ | ||
public getKeyOrDefault(value: V, defaultKey?: keyof T | string): string | undefined { | ||
public getKeyOrDefault(value: V | null | undefined, defaultKey?: keyof T | string): string | undefined { | ||
if (this.isValue(value)) { | ||
@@ -644,3 +655,3 @@ return this.keysByValueMap.get(value); | ||
*/ | ||
public getValue(key: string): T[keyof T] { | ||
public getValue(key: string | null | undefined): T[keyof T] { | ||
return this.enumObj[this.asKey(key)]; | ||
@@ -656,3 +667,3 @@ } | ||
*/ | ||
public getValueOrDefault(key: string, defaultValue: T[keyof T]): T[keyof T]; | ||
public getValueOrDefault(key: string | null | undefined, defaultValue: T[keyof T]): T[keyof T]; | ||
/** | ||
@@ -665,3 +676,3 @@ * Gets the enum value for the provided key. | ||
*/ | ||
public getValueOrDefault(key: string, defaultValue?: T[keyof T]): T[keyof T] | undefined; | ||
public getValueOrDefault(key: string | null | undefined, defaultValue?: T[keyof T]): T[keyof T] | undefined; | ||
/** | ||
@@ -674,3 +685,3 @@ * Gets the enum value for the provided key. | ||
*/ | ||
public getValueOrDefault(key: string, defaultValue: V): V; | ||
public getValueOrDefault(key: string | null | undefined, defaultValue: V): V; | ||
/** | ||
@@ -683,3 +694,3 @@ * Gets the enum value for the provided key. | ||
*/ | ||
public getValueOrDefault(key: string, defaultValue: V | undefined): V | undefined; | ||
public getValueOrDefault(key: string | null | undefined, defaultValue: V | undefined): V | undefined; | ||
/** | ||
@@ -692,5 +703,7 @@ * Gets the enum value for the provided key. | ||
*/ | ||
public getValueOrDefault(key: string, defaultValue?: T[keyof T] | V): V | undefined { | ||
public getValueOrDefault(key: string | null | undefined, defaultValue?: T[keyof T] | V): V | undefined { | ||
if (this.isKey(key)) { | ||
return this.enumObj[key]; | ||
// type cast require to work around TypeScript bug: | ||
// https://github.com/Microsoft/TypeScript/issues/21950 | ||
return this.enumObj[key as keyof T]; | ||
} else { | ||
@@ -718,2 +731,3 @@ return defaultValue; | ||
* @param enumObj - The enum-like object that the key/value entrie belongs to. | ||
* @param index - The index of the enum entry, based on sorted order of keys. | ||
* @return A result. The significance of the result depends on the type of iteration being performed. | ||
@@ -729,3 +743,3 @@ * | ||
T extends EnumLike<V, keyof T> = any | ||
> = (this: any, value: V, key: keyof T, enumObj: T) => R; | ||
> = (this: any, value: V, key: keyof T, enumWrapper: EnumWrapper<V, T>, index: number) => R; | ||
} | ||
@@ -732,0 +746,0 @@ |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
139012
2176
594