{"id":12255,"library":"typescript-string-enums","title":"TypeScript String Enums","description":"The `typescript-string-enums` library, currently at stable version 1.0.0, provided a mechanism for creating typesafe string enums in TypeScript environments prior to version 2.4. Its primary utility was to overcome limitations of native TypeScript number enums and the lack of native string enums, offering compile-time type safety for string values. Key features include the `Enum` factory function to define enums with either direct string values or mapped key-value pairs, helper functions like `Enum.isType()` for type guarding, and `Enum.keys()` and `Enum.values()` for strictly typed access to enum keys and values. The library also supports JSDoc comments for enum members and allows creating enums where keys are automatically mirrored as values using `Enum.ofKeys()`. While the library had a steady release cadence up to 0.3.x, development has largely ceased, with the 1.0.0 release being a commitment to stability rather than new features. This library is now largely superseded by native string enums introduced in TypeScript 2.4, which offer similar functionality without a third-party dependency. It is recommended to use native string enums in modern TypeScript projects.","status":"deprecated","version":"1.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/dphilipson/typescript-string-enums","tags":["javascript","typescript","string","enum"],"install":[{"cmd":"npm install typescript-string-enums","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-string-enums","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-string-enums","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary factory function for creating enums. The library is ESM-first in modern versions.","wrong":"const Enum = require('typescript-string-enums').Enum;","symbol":"Enum","correct":"import { Enum } from 'typescript-string-enums';"},{"note":"User-defined enums created with `Enum()` are typically exported as named constants.","wrong":"import MyEnum from './my-enum-file';","symbol":"MyEnum","correct":"import { MyEnum } from './my-enum-file';"},{"note":"To achieve type safety for enum values, a TypeScript type alias is created using `Enum<typeof MyEnum>`.","wrong":"type MyEnumType = MyEnum;","symbol":"Enum<typeof MyEnum>","correct":"type MyEnumType = Enum<typeof MyEnum>;"}],"quickstart":{"code":"import { Enum } from \"typescript-string-enums\";\n\n// Define an enum with mapped values and JSDoc comments\nexport const StatusCode = Enum({\n  /**\n   * The operation completed successfully.\n   */\n  OK: \"success\",\n  /**\n   * An error occurred during the operation.\n   */\n  ERROR: \"failure\",\n  PENDING: \"in_progress\",\n});\n// Create a type alias for compile-time type safety\nexport type StatusCode = Enum<typeof StatusCode>;\n\nconsole.log(`OK status value: ${StatusCode.OK}`); // Expected: \"success\"\n\nfunction processStatus(statusString: string) {\n  // Use Enum.isType as a type guard for runtime validation and type narrowing\n  if (Enum.isType(StatusCode, statusString)) {\n    // Inside this block, statusString is narrowed to StatusCode type\n    console.log(`Processing valid status: ${statusString}`);\n    if (statusString === StatusCode.OK) {\n      console.log(\"Operation was successful!\");\n    } else if (statusString === StatusCode.ERROR) {\n      console.log(\"Operation failed.\");\n    }\n  } else {\n    console.warn(`Invalid status received: ${statusString}`);\n  }\n}\n\n// Example usage with valid and invalid inputs\nprocessStatus(\"success\"); // Valid\nprocessStatus(\"in_progress\"); // Valid\nprocessStatus(\"unknown_status\"); // Invalid\n\n// Demonstrating Enum.keys() and Enum.values()\nconst keys = Enum.keys(StatusCode);\nconsole.log(\"Enum keys:\", keys); // Expected: [\"OK\", \"ERROR\", \"PENDING\"]\n\nconst values = Enum.values(StatusCode);\nconsole.log(\"Enum values:\", values); // Expected: [\"success\", \"failure\", \"in_progress\"]\n","lang":"typescript","description":"Demonstrates creating a string enum with mapped values, accessing enum members, using JSDoc, and leveraging `Enum.isType` for type-safe validation and narrowing. Also shows `Enum.keys()` and `Enum.values()`."},"warnings":[{"fix":"Migrate to native TypeScript string enums (e.g., `enum Status { Running = \"running\", Stopped = \"stopped\" }`).","message":"This library is largely superseded by native string enums introduced in TypeScript 2.4. It is strongly recommended to use native string enums for new projects or when upgrading TypeScript.","severity":"breaking","affected_versions":">=2.4 (TypeScript)"},{"fix":"Upgrade to version `0.3.1` or later to avoid corrupted packages.","message":"The npm artifact for version `0.3.0` was broken. Do not use this specific version.","severity":"breaking","affected_versions":"0.3.0"},{"fix":"Ensure your project's `typescript` dependency is version 2.2 or higher, or explicitly downgrade `typescript-string-enums` to `0.2.0` for older TypeScript versions.","message":"This library requires TypeScript 2.2 or later. For TypeScript 2.1 compatibility, you must use version 0.2.0.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Be mindful of the behavior of `Enum.ofKeys()` when choosing which enum creation method to use. If you need distinct string values, use `Enum({ KEY: \"value\" })`.","message":"When defining an enum using `Enum.ofKeys(object)`, the values of the enum are explicitly set to be identical to its keys, which is different from standard `Enum()` behavior where keys map to custom string values. This is for specific string comparison scenarios.","severity":"gotcha","affected_versions":">=0.3.3"},{"fix":"Always define a corresponding type alias, e.g., `export const Status = Enum(...); export type Status = Enum<typeof Status>;`","message":"For type-safety, it is crucial to define a TypeScript type alias using `type MyEnumType = Enum<typeof MyEnum>;` after creating an enum constant. Without this alias, TypeScript will treat assignments as potentially just 'string' rather than the narrow union type.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Wrap the assignment or usage in an `if (Enum.isType(MyEnum, myString))` guard, or ensure the string literal is directly one of the enum values.","cause":"Attempting to assign a plain `string` type to a variable typed as the enum without using `Enum.isType` as a guard.","error":"Type 'string' is not assignable to type '\"RED\" | \"GREEN\" | \"BLUE\" | \"PUCE\"'."},{"fix":"Only assign values that are explicitly part of the enum's allowed string literals, or validate user input using `Enum.isType` before assignment.","cause":"Attempting to assign a string literal that is not one of the defined enum values to a variable typed with the enum's union type.","error":"Type '\"hello\"' is not assignable to type '\"RUNNING\" | \"STOPPED\"'."},{"fix":"Run `npm install --save typescript-string-enums` or `yarn add typescript-string-enums` to add the package to your project dependencies.","cause":"The package `typescript-string-enums` is not installed or not correctly referenced in `package.json`.","error":"Module not found: Error: Can't resolve 'typescript-string-enums'"}],"ecosystem":"npm"}