{"id":12171,"library":"ts-enum-util","title":"TypeScript Enum Utilities","description":"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.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/UselessPickles/ts-enum-util","tags":["javascript","typescript","string","number","literal","union","enum","util"],"install":[{"cmd":"npm install ts-enum-util","lang":"bash","label":"npm"},{"cmd":"yarn add ts-enum-util","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-enum-util","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary utility function for wrapping enums and accessing visitor/mapper methods.","wrong":"const $enum = require('ts-enum-util').$enum;","symbol":"$enum","correct":"import { $enum } from 'ts-enum-util';"},{"note":"Type import for convenience wrapper, often used for explicit type declarations when working with numeric enums.","symbol":"NumberEnumWrapper","correct":"import type { NumberEnumWrapper } from 'ts-enum-util';"},{"note":"Type import for the base enum wrapper interface, rarely imported directly for common usage, as `$enum()` returns an instance of this type.","symbol":"EnumWrapper","correct":"import type { EnumWrapper } from 'ts-enum-util';"}],"quickstart":{"code":"import { $enum } from 'ts-enum-util';\n\nenum Color {\n    Red = 0,\n    Green = 1,\n    Blue = 2\n}\n\nenum Status {\n    Active = 'ACTIVE',\n    Inactive = 'INACTIVE',\n    Pending = 'PENDING'\n}\n\n// Use $enum() as a function to access Enum Wrapper Utilities\nconst colorValues = $enum(Color).getValues();\nconsole.log('Color Values:', colorValues); // Expected: [0, 1, 2]\n\nconst colorKeys = $enum(Color).getKeys();\nconsole.log('Color Keys:', colorKeys); // Expected: ['Red', 'Green', 'Blue']\n\n// Check if a value is valid for an enum at runtime\nconst isValidRed = $enum(Color).isValue(0);\nconsole.log('Is 0 a valid Color value?', isValidRed); // Expected: true\n\n// Use $enum.visitValue() for exhaustive handling of enum states\nfunction describeStatus(status: Status): string {\n    return $enum.visitValue(status).with({\n        [Status.Active]: () => 'The item is currently active.',\n        [Status.Inactive]: () => 'The item is not active.',\n        [Status.Pending]: () => 'The item is awaiting activation.'\n    });\n}\n\nconsole.log('Status description for Active:', describeStatus(Status.Active));","lang":"typescript","description":"Demonstrates importing the `$enum` utility, defining enums, and using wrapper methods like `getValues()`, `getKeys()`, `isValue()`, and the `visitValue()` pattern for exhaustive enum value handling."},"warnings":[{"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`.","message":"Version 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`.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Prior 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()`.","severity":"gotcha","affected_versions":"<4.0.1"},{"fix":"No direct code fix needed. Ensure your project explicitly declares its TypeScript dependency if strict versioning or specific tooling integration is required.","message":"As 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.","severity":"gotcha","affected_versions":">=4.0.2"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade to `ts-enum-util@4.0.1` or newer to obtain fixes for handling non-positive integer enum values correctly.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'getValues') OR similar runtime errors for numeric enums"},{"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`.","cause":"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.","error":"Error: Cannot find module 'ts-string-visitor'"},{"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.","cause":"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.","error":"Type 'any' is not assignable to type 'T' (or similar type incompatibility errors related to EnumWrapper types)"}],"ecosystem":"npm"}