Ever since the release of Typescript 2.1, there has been a different approach available using the keyof operator.

The concept is simple. Due to the lack of string literal type information at runtime, you create a basic object with keys representing your string literals and then create a type based on those keys.

Here's an example:

// Values in this dictionary are not important
const myStrings = {
  A: "",
  B: ""
}

type MyStrings = keyof typeof myStrings;

isMyStrings(x: string): x is MyStrings {
  return myStrings.hasOwnProperty(x);
}

const a: string = "A";
if(isMyStrings(a)){
  // ... Treat a as if it was assigned with MyString type within this block: TypeScript compiler trusts our duck typing!
}

If your program contains multiple string union definitions that need runtime checking, you can use a generic function called StringUnion to create static types and type-checking methods for them.

Creating the Generic Function

// By using `extends string`, TypeScript infers a string union type from the literal values
// passed to this function. Without it, the values would be generalized to a common string type.
export const StringUnion = <UnionType extends string>(...values: UnionType[]) => {
  Object.freeze(values);
  const valueSet: Set<string> = new Set(values);

  const guard = (value: string): value is UnionType => {
    return valueSet.has(value);
  };

  const check = (value: string): UnionType => {
    if (!guard(value)) {
      const actual = JSON.stringify(value);
      const expected = values.map(s => JSON.stringify(s)).join(' | ');
      throw new TypeError(`Value '${actual}' is not assignable to type '${expected}'.`);
    }
    return value;
  };

  const unionNamespace = {guard, check, values};
  return Object.freeze(unionNamespace as typeof unionNamespace & {type: UnionType});
};

Usage Example

To merge the generated type definition with its namespace object and automatically have it available when imported into another module, add the following line of boilerplate code.

const Race = StringUnion(
  "orc",
  "human",
  "night elf",
  "undead",
);
type Race = typeof Race.type;

Example Scenario

At compile-time, the Race type functions just like a standard string union declaration with

"orc" | "human" | "night elf" | "undead"

. The .guard() function acts as a type guard, while .check() verifies validity and throws an error if necessary.

let r: Race;
const zerg = "zerg";

// Expected compiler error:
r = zerg;

// Expected run-time error:
r = Race.check(zerg);

// This block will not be executed:
if (Race.guard(zerg)) {
  r = zerg;
}

An Alternative Solution: runtypes

This method is inspired by the runtypes library, which offers similar functionality for defining various types in TypeScript and automatically generating run-time type checkers. It may require slightly more verbosity for this specific scenario but provides added flexibility.

Usage Example

import {Union, Literal, Static} from 'runtypes';

const Race = Union(
  Literal('orc'),
  Literal('human'),
  Literal('night elf'),
  Literal('undead'),
);
type Race = Static<typeof Race>;

The usage remains consistent with the previous example.

To handle this scenario, you can utilize the enum feature in TypeScript. This involves defining an enum with the possible decision options and then creating a type union to represent them.

export enum Decisions {
    approve = 'approve',
    reject = 'reject'
}

export type DecisionsTypeUnion =
    Decisions.approve |
    Decisions.reject;

if (decision in Decisions) {
  // This decision is valid
}

Implement a solution using the "array first" method, where you create string literals and simultaneously use Array.includes():

const StringsArray = ["X", "Y", "Z"] as const;
StringsArray.includes("X" as any); // true
StringsArray.includes("W" as any); // false

type MyStrings = typeof StringsArray[number];
let testing: MyStrings;

testing = "X"; // Acceptable
testing = "W"; // Compilation error

utilizing type is essentially creating Type Aliasing, however it does not appear in the compiled JavaScript code. Therefore, you cannot perform the following:

MyStrings.isAssignable("A");

Here's what you can achieve with it:

type MyStrings = "A" | "B" | "C";

let myString: MyStrings = getString();
switch (myString) {
    case "A":
        ...
        break;

    case "B":
        ...
        break;

    case "C":
        ...
        break;
        
    default:
        throw new Error("can only receive A, B or C")
}

In response to your query regarding isAssignable, you can do this:

function isAssignable(str: MyStrings): boolean {
    return str === "A" || str === "B" || str === "C";
}

My strategy involves creating a unique object type by utilizing the union type and initializing a placeholder instance of that object type. This allows for straightforward string type checking through type guards.

An advantage of this method is that whenever a new type is added or removed from the union, TypeScript will prompt us to update the object accordingly.

type MyLetters = "X" | "Y" | "Z";
type MyLettersObjectType = {
   [key in MyLetters ] : any
}
export const myLettersDummyObject : MyLettersObjectType = {
   X : "",
   Y : "",
   Z : "",
}
export const isValidLetter = (input: string): input is MyLetters => {
    return (input in myLettersDummyObject);
}

Usage :

if(isValidLetter("X")){  //true
   
}

if(isValidLetter("D")){  //false
   
}

Methods cannot be called on types during runtime, as types do not exist

MyStrings.isAssignable("A"); // This will not work — `MyStrings` is a string literal

Instead of this approach, it is recommended to create executable JavaScript code for input validation. It is the responsibility of the programmer to ensure that the function performs correctly.

function isMyString(candidate: string): candidate is MyStrings {
  return ["A", "B", "C"].includes(candidate);
}

Update

Following the suggestion from @jtschoonhoven, an exhaustive type guard can be created to verify if any string belongs to MyStrings.

Start by creating a function named enumerate which ensures all members of the MyStrings union are used. This will signal the need to update the type guard if the union is expanded in the future.

type ValueOf<T> = T[keyof T];

type IncludesEvery<T, U extends T[]> =
  T extends ValueOf<U>
    ? true
    : false;

type WhenIncludesEvery<T, U extends T[]> =
  IncludesEvery<T, U> extends true
    ? U
    : never;

export const enumerate = <T>() =>
  <U extends T[]>(...elements: WhenIncludesEvery<T, U>): U => elements;

The updated and enhanced type guard:

function isMyString(candidate: string): candidate is MyStrings {
  const valid = enumerate<MyStrings>()('A', 'B', 'C');

  return valid.some(value => candidate === value);
}

After exploring @jtschoonhoven's recommended approach, one can craft versatile factories to create parsing or validation functions:

const generateParserFactory = <DataType, T extends DataType>(data: readonly T[]): ((input: DataType) => T | null) => {
   return (input: DataType): T => {
       const match = data.find((item) => item === input)
       if (match) {
           return match
       }
       throw new InvalidDataError(data, input)
    }
}

Example of usage:

const catNames = ['Whiskers', 'Fluffy', 'Mittens'] as const
type CatName = typeof catNames[number]

const parseCatName = generateParserFactory(catNames)
let myCatName: CatName = parseCatName('Fluffy') // Valid
let willThrowError: CatName = parseCatName('Garfield') // Error thrown

Check out this working example on REPL

The challenge lies in ensuring the consistency of our type with how generateParserFactory constructs from our array of values.

Here's a different approach:

let myChoices = ['X', 'Y', 'Z'] as const;
type OptionsOne = typeof myChoices[number];

let moreChoices =  ['M', 'N', 'O'] as const;
type OptionsTwo = typeof moreChoices[number];

type AllOptions = OptionsOne | OptionsTwo;

let chosenOptions: Set<string> = new Set(myChoices);

function isChosen(option: AllOptions): option is OptionsOne {
  return chosenOptions.has(option);
}

This method offers better performance compared to using Array.find like some of the other suggestions.

There was a situation I encountered where I needed to validate all permitted query parameters and also implement type guards with the Union type for all allowed params.

My requirements were as follows:

1. The method should be generic and adaptable for APIs with varying sets of permitted parameters. For example, one API may accept online|offline, while another could allow full|partial.
2. An exception should be thrown if there's a parameter mismatch. Since this is used in an Express app, all API parameters need to be validated at runtime.
3. I wanted to adhere to DRY principles and avoid situations where the allowed params differ across implementations.
4. No reliance on external libraries 🙂

My solution meets all these criteria:

export function assertUnion<T extends string>(
    param: string,
    allowedValues: ReadonlyArray<T>
): param is T {
    if (!allowedValues.includes(param as T)) {
        throw new Error("Wrong value");
    }
    return true;
}

Here's how you can use it:

if (
    !assertUnion<"online" | "offline">(param, ["online", "offline"])
) {
    return;
}
console.log(param) // param will be of type "online" | "offline"

While it may seem like we're defining allowed types twice - once as a Union type and then in an array - because of the utility definition, you can add any additional parameter to the array. This ensures that your Union type remains the source of truth.

I would have liked to use

param is typeof allowedValues[number]

, but unfortunately, Typescript's const assertion only works with array literals and not with array parameters 😞