ts-enum-util

library4.1.0jsnpmunverified

ts-enum-util is a strictly typed utility library designed to enhance the usability and safety of TypeScript enums, as well as string and number literal union types. It provides two core functionalities: Enum Wrapper Utilities and Enum Value Visitor/Mapper. The Enum Wrapper offers type-safe methods for runtime inspection and manipulation of enums, such as retrieving keys, values, performing lookups with validation, and treating enums like arrays or maps. The Value Visitor/Mapper implements a visitor pattern, forcing exhaustive handling of all possible enum or literal union values, similar to a comprehensive switch statement, which helps prevent bugs from unhandled cases. The library is actively maintained, with the current stable version being 4.1.0, and new features or bug fixes are regularly released. Its key differentiators include strong compile-time type safety for enum operations and the exhaustive visitor pattern for robust code.

type-stubs

npm install ts-enum-util

github ↗package ↗

INSTALL

IMPORT

SIG · TS-ENUM-UTIL

ts-enum-util

type-stubsjavascriptv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

$enum

✓ import { $enum } from 'ts-enum-util';

✗ const $enum = require('ts-enum-util').$enum;

The primary utility function for wrapping enums and accessing visitor/mapper methods.

NumberEnumWrapper

✓ import type { NumberEnumWrapper } from 'ts-enum-util';

Type import for convenience wrapper, often used for explicit type declarations when working with numeric enums.

EnumWrapper

✓ import type { EnumWrapper } from 'ts-enum-util';

Type import for the base enum wrapper interface, rarely imported directly for common usage, as `$enum()` returns an instance of this type.

Demonstrates importing the `$enum` utility, defining enums, and using wrapper methods like `getValues()`, `getKeys()`, `isValue()`, and the `visitValue()` pattern for exhaustive enum value handling.

import { $enum } from 'ts-enum-util'; enum Color { Red = 0, Green = 1, Blue = 2 } enum Status { Active = 'ACTIVE', Inactive = 'INACTIVE', Pending = 'PENDING' } // Use $enum() as a function to access Enum Wrapper Utilities const colorValues = $enum(Color).getValues(); console.log('Color Values:', colorValues); // Expected: [0, 1, 2] const colorKeys = $enum(Color).getKeys(); console.log('Color Keys:', colorKeys); // Expected: ['Red', 'Green', 'Blue'] // Check if a value is valid for an enum at runtime const isValidRed = $enum(Color).isValue(0); console.log('Is 0 a valid Color value?', isValidRed); // Expected: true // Use $enum.visitValue() for exhaustive handling of enum states function describeStatus(status: Status): string { return $enum.visitValue(status).with({ [Status.Active]: () => 'The item is currently active.', [Status.Inactive]: () => 'The item is not active.', [Status.Pending]: () => 'The item is awaiting activation.' }); } console.log('Status description for Active:', describeStatus(Status.Active));

Debug

Known issues

breakingVersion 4.0.0 introduced significant breaking changes by merging the `ts-string-visitor` package's functionality directly into `ts-enum-util`. Users previously relying on `ts-string-visitor` for visitor/mapper patterns will need to migrate their code to use the new `$enum.visitValue()` or `$enum.mapValue()` methods within `ts-enum-util`.

fix

Consult the `ts-enum-util` README for specific migration guidance, and refactor existing `ts-string-visitor` code to use `$enum.visitValue()` or `$enum.mapValue()` from `ts-enum-util`.

affects: >=4.0.0

gotchaPrior to version 4.0.1, `ts-enum-util` made incorrect assumptions about numeric enum values. It could misinterpret non-positive integers (e.g., negative numbers, floating-point numbers) in enums, leading to unexpected behavior or errors during operations like `getKeys()` or `getValues()`.

fix

Upgrade to `ts-enum-util@4.0.1` or newer to ensure correct processing of all valid numeric enum values, including negative numbers and floats.

affects: <4.0.1

gotchaAs of version 4.0.2, the `typescript` peer dependency has been removed. While this simplifies installation for many projects, it means `ts-enum-util` no longer directly enforces a TypeScript version through its `package.json`. Projects relying on this peer dependency for tooling or CI/CD pipelines might need to adjust their configuration.

fix

No direct code fix needed. Ensure your project explicitly declares its TypeScript dependency if strict versioning or specific tooling integration is required.

affects: >=4.0.2

gotchaThe library has specific requirements for supported TypeScript versions. Always consult the 'Requirements' section in the `ts-enum-util` README to ensure compatibility with your project's TypeScript version, as using an unsupported version can lead to compilation issues.

fix

Refer to the 'Requirements' section in the `ts-enum-util` README for the exact supported TypeScript versions and adjust your project's TypeScript dependency accordingly.

affects: *

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'getValues') OR similar runtime errors for numeric enums

In versions prior to 4.0.1, `ts-enum-util` incorrectly assumed that all numeric enum values were positive integers. This could lead to internal data corruption or failure to correctly process enums containing negative numbers, zero, or floating-point values during runtime operations.

fix

Upgrade to `ts-enum-util@4.0.1` or newer to obtain fixes for handling non-positive integer enum values correctly.

Error: Cannot find module 'ts-string-visitor'

With the release of `ts-enum-util@4.0.0`, the separate `ts-string-visitor` package was deprecated and its functionality was merged directly into `ts-enum-util`. Direct imports of `ts-string-visitor` will no longer be resolved.

fix

Migrate your code from using `ts-string-visitor` to utilizing the integrated visitor/mapper functionality available through `$enum.visitValue()` or `$enum.mapValue()` from `ts-enum-util`.

Type 'any' is not assignable to type 'T' (or similar type incompatibility errors related to EnumWrapper types)

In `ts-enum-util` versions prior to `3.0.5` (and `2.0.5`), convenience types like `NumberEnumWrapper`, `StringEnumWrapper`, and `MixedEnumWrapper` were incorrectly defined using the `any` type. This caused a loss of type safety and could lead to compilation errors in strict TypeScript projects.

fix

Upgrade to `ts-enum-util@3.0.5` (or `2.0.5` for the `2.x` branch) or newer to benefit from corrected and type-safe definitions for these wrapper types.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/UselessPickles/ts-enum-util ↗

packagehttps://www.npmjs.com/package/ts-enum-util ↗