TypeScript String Enums

Common errors

• Type 'string' is not assignable to type '"RED" | "GREEN" | "BLUE" | "PUCE"'.

  cause Attempting to assign a plain `string` type to a variable typed as the enum without using `Enum.isType` as a guard.
  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.

• Type '"hello"' is not assignable to type '"RUNNING" | "STOPPED"'.

  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.
  fix Only assign values that are explicitly part of the enum's allowed string literals, or validate user input using `Enum.isType` before assignment.

• Module not found: Error: Can't resolve 'typescript-string-enums'

  cause The package `typescript-string-enums` is not installed or not correctly referenced in `package.json`.
  fix Run `npm install --save typescript-string-enums` or `yarn add typescript-string-enums` to add the package to your project dependencies.

Warnings

• breaking 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.
  Fix: Migrate to native TypeScript string enums (e.g., `enum Status { Running = "running", Stopped = "stopped" }`).
• breaking The npm artifact for version `0.3.0` was broken. Do not use this specific version.
  Fix: Upgrade to version `0.3.1` or later to avoid corrupted packages.
• gotcha This library requires TypeScript 2.2 or later. For TypeScript 2.1 compatibility, you must use version 0.2.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.
• gotcha 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.
  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" })`.
• gotcha 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.
  Fix: Always define a corresponding type alias, e.g., `export const Status = Enum(...); export type Status = Enum<typeof Status>;`

Install

• npm install typescript-string-enums npm
• yarn add typescript-string-enums yarn
• pnpm add typescript-string-enums pnpm

Imports

• Enum
  wrong:

  const Enum = require('typescript-string-enums').Enum;

  correct:

  import { Enum } from 'typescript-string-enums';

  Primary factory function for creating enums. The library is ESM-first in modern versions.
• MyEnum
  wrong:

  import MyEnum from './my-enum-file';

  correct:

  import { MyEnum } from './my-enum-file';

  User-defined enums created with `Enum()` are typically exported as named constants.
• Enum<typeof MyEnum>
  wrong:

  type MyEnumType = MyEnum;

  correct:

  type MyEnumType = Enum<typeof MyEnum>;

  To achieve type safety for enum values, a TypeScript type alias is created using `Enum<typeof MyEnum>`.

Quickstart

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()`.

import { Enum } from "typescript-string-enums";

// Define an enum with mapped values and JSDoc comments
export const StatusCode = Enum({
  /**
   * The operation completed successfully.
   */
  OK: "success",
  /**
   * An error occurred during the operation.
   */
  ERROR: "failure",
  PENDING: "in_progress",
});
// Create a type alias for compile-time type safety
export type StatusCode = Enum<typeof StatusCode>;

console.log(`OK status value: ${StatusCode.OK}`); // Expected: "success"

function processStatus(statusString: string) {
  // Use Enum.isType as a type guard for runtime validation and type narrowing
  if (Enum.isType(StatusCode, statusString)) {
    // Inside this block, statusString is narrowed to StatusCode type
    console.log(`Processing valid status: ${statusString}`);
    if (statusString === StatusCode.OK) {
      console.log("Operation was successful!");
    } else if (statusString === StatusCode.ERROR) {
      console.log("Operation failed.");
    }
  } else {
    console.warn(`Invalid status received: ${statusString}`);
  }
}

// Example usage with valid and invalid inputs
processStatus("success"); // Valid
processStatus("in_progress"); // Valid
processStatus("unknown_status"); // Invalid

// Demonstrating Enum.keys() and Enum.values()
const keys = Enum.keys(StatusCode);
console.log("Enum keys:", keys); // Expected: ["OK", "ERROR", "PENDING"]

const values = Enum.values(StatusCode);
console.log("Enum values:", values); // Expected: ["success", "failure", "in_progress"]