https://github.com/exuanbo/ts-enum-utilx
Strictly typed utilities for working with TypeScript enums.
https://github.com/exuanbo/ts-enum-utilx
enum ts-enum-util tyepscript util
Last synced: 11 days ago
JSON representation
Strictly typed utilities for working with TypeScript enums.
- Host: GitHub
- URL: https://github.com/exuanbo/ts-enum-utilx
- Owner: exuanbo
- License: mit
- Created: 2024-08-19T16:07:10.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-25T14:09:07.000Z (over 1 year ago)
- Last Synced: 2025-12-13T21:41:23.333Z (2 months ago)
- Topics: enum, ts-enum-util, tyepscript, util
- Language: TypeScript
- Homepage: http://exuanbo.xyz/ts-enum-utilx/
- Size: 1.05 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ts-enum-utilx
[](https://www.npmjs.com/package/ts-enum-utilx)
[](https://bundlephobia.com/package/ts-enum-utilx)
[](https://github.com/exuanbo/ts-enum-utilx/actions)
[](https://app.codecov.io/gh/exuanbo/ts-enum-utilx/tree/main/src)
Strictly typed utilities for working with TypeScript enums inspired by [`ts-enum-util`](https://github.com/UselessPickles/ts-enum-util).
## Install
```sh
# npm
npm install ts-enum-utilx
# Yarn
yarn add ts-enum-utilx
# pnpm
pnpm add ts-enum-utilx
```
## Differences from ts-enum-util
- **Smaller Bundle Size**: `ts-enum-utilx` has a much smaller bundle size and is fully tree-shakable.
- **Functional Programming Approach**: Supports currying and functional programming paradigms.
- **Streamlined API**: Provides a set of essential functions without a wrapper class, making it more intuitive and easier to use. Additional functionalities can be easily achieved using modern JavaScript features or simple invariant libraries like [`tiny-invariant`](https://github.com/alexreardon/tiny-invariant).
## Usage
### Basic setup
Namespace import is recommended for better tree-shaking:
```ts
import * as E from "ts-enum-utilx";
enum Answer {
No = 0,
Yes = "YES",
}
```
### size
Get the number of keys in the enum:
```ts
E.size(Answer);
// => 2
```
### keys
Get an iterable of the enum keys:
```ts
const iter = E.keys(Answer);
// ^? IterableIterator<"No" | "Yes">
[...E.keys(Answer)];
// => ["No", "Yes"]
```
### values
Get an iterable of the enum values:
```ts
const iter = E.values(Answer);
// ^? IterableIterator
[...E.values(Answer)];
// => [0, "YES"]
```
### entries
Get an iterable of key-value pairs:
```ts
const iter = E.entries(Answer);
// ^? IterableIterator<[("No" | "Yes"), Answer]>
[...E.entries(Answer)];
// => [["No", 0], ["Yes", "YES"]]
```
### value
Get the value associated with a key:
```ts
E.value(Answer, "No");
// => 0
E.value(Answer, "Unknown");
// => undefined
const getValue = E.value(Answer);
// ^? (key: Nullable) => Answer | undefined
getValue("Yes");
// => "YES"
```
### key
Get the key associated with a value:
```ts
E.key(Answer, 0);
// => "No"
E.key(Answer, "Unknown");
// => undefined
const getKey = E.key(Answer);
// ^? (value: Nullable) => "No" | "Yes" | undefined
getKey("YES");
// => "Yes"
```
The `key` function is type-safe and will only accept values that are assignable to the enum values.
E.key type inference
```ts
enum NumberEnum {
One = 1,
}
// @ts-expect-error: Argument of type '"A"' is not assignable to parameter of type 'Nullable'
E.key(NumberEnum, "A");
enum StringEnum {
A = "A",
}
// @ts-expect-error: Argument of type '1' is not assignable to parameter of type 'Nullable'
E.key(StringEnum, 1);
enum HetEnum {
A = 1,
B = "B",
}
// @ts-expect-error: Argument of type 'true' is not assignable to parameter of type 'Nullable'
E.key(HetEnum, true);
```
### isKey
Check if a string is a key in the enum:
```ts
E.isKey(Answer, "No");
// => true
const key: string = "No";
if (E.isKey(Answer, key)) {
console.log(key);
// ^? "No" | "Yes"
}
const isKey = E.isKey(Answer);
// ^? (key: Nullable) => key is "No" | "Yes"
isKey("Yes");
// => true
```
### isValue
Check if a value is in the enum:
```ts
E.isValue(Answer, 0);
// => true
const value: string | number = 0;
if (E.isValue(Answer, value)) {
console.log(value);
// ^? Answer
}
const isValue = E.isValue(Answer);
// ^? (value: Nullable) => value is Answer
isValue("YES");
// => true
```
The `isValue` function is type-safe and will only accept values that are assignable to the enum values.
E.isValue type inference
```ts
enum NumberEnum {
One = 1,
}
// @ts-expect-error: Argument of type '"A"' is not assignable to parameter of type 'Nullable'.
E.isValue(NumberEnum, "A");
enum StringEnum {
A = "A",
}
// @ts-expect-error: Argument of type '1' is not assignable to parameter of type 'Nullable'.
E.isValue(StringEnum, 1);
enum HetEnum {
A = 1,
B = "B",
}
// @ts-expect-error: Argument of type 'true' is not assignable to parameter of type 'Nullable'.
E.isValue(HetEnum, true);
```
### forEach
Iterate over the enum:
```ts
E.forEach(Answer, (value, key, enumObj) => {
console.log(value);
// ^? Answer
console.log(key);
// ^? "No" | "Yes"
console.log(enumObj);
// ^? typeof Answer
});
const forEachAnswer = E.forEach(Answer);
// ^? (iteratee: (value: Answer, key: "No" | "Yes", enumObj: typeof Answer) => void) => void
const logEntries = E.forEach((value, key) => console.log([key, value]));
// ^? (enumObj: Record) => void
logEntries(Answer);
// => [ "No", 0 ]
// => [ "Yes", "YES" ]
```
## API
See the [API documentation](https://exuanbo.xyz/ts-enum-utilx/) for more details.
## License
[MIT License](https://github.com/exuanbo/ts-enum-utilx/blob/main/LICENSE) @ 2024-Present [Xuanbo Cheng](https://github.com/exuanbo)