Checking validity of string literal union type at runtime?

Since Typescript 2.1, you can do it the other way around with the keyof operator.

The idea is as follows. Since string literal type information isn't available in runtime, you will define a plain object with keys as your strings literals, and then make a type of the keys of that object.

As follows:

// Values of this dictionary are irrelevant
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)){
  // ... Use a as if it were typed MyString from assignment within this block: the TypeScript compiler trusts our duck typing!
}

As of Typescript 3.8.3 there isn't a clear best practice around this. There appear to be three solutions that don't depend on external libraries. In all cases you will need to store the strings in an object that is available at runtime (e.g. an array).

For these examples, assume we need a function to verify at runtime whether a string is any of the canonical sheep names, which we all know to be Capn Frisky, Mr. Snugs, Lambchop. Here are three ways to do this in a way that the Typescript compiler will understand.

1: Type Assertion (Easier)

Take your helmet off, verify the type yourself, and use an assertion.

const sheepNames = ['Capn Frisky', 'Mr. Snugs', 'Lambchop'] as const;
type SheepName = typeof sheepNames[number]; // "Capn Frisky" | "Mr. Snugs" | "Lambchop"

// This string will be read at runtime: the TS compiler can't know if it's a SheepName.
const unsafeJson = '"Capn Frisky"';

/**
 * Return a valid SheepName from a JSON-encoded string or throw.
 */
function parseSheepName(jsonString: string): SheepName {
    const maybeSheepName: unknown = JSON.parse(jsonString);
    // This if statement verifies that `maybeSheepName` is in `sheepNames` so
    // we can feel good about using a type assertion below.
    if (typeof maybeSheepName === 'string' && sheepNames.includes(maybeSheepName)) {
        return (maybeSheepName as SheepName); // type assertion satisfies compiler
    }
    throw new Error('That is not a sheep name.');
}

const definitelySheepName = parseSheepName(unsafeJson);

PRO: Simple, easy to understand.

CON: Fragile. Typescript is just taking your word for it that you have adequately verified maybeSheepName. If you accidentally remove the check, Typescript won't protect you from yourself.

2: Custom Type Guards (More Reusable)

This is a fancier, more generic version of the type assertion above, but it's still just a type assertion.

const sheepNames = ['Capn Frisky', 'Mr. Snugs', 'Lambchop'] as const;
type SheepName = typeof sheepNames[number];

const unsafeJson = '"Capn Frisky"';

/**
 * Define a custom type guard to assert whether an unknown object is a SheepName.
 */
function isSheepName(maybeSheepName: unknown): maybeSheepName is SheepName {
    return typeof maybeSheepName === 'string' && sheepNames.includes(maybeSheepName);
}

/**
 * Return a valid SheepName from a JSON-encoded string or throw.
 */
function parseSheepName(jsonString: string): SheepName {
    const maybeSheepName: unknown = JSON.parse(jsonString);
    if (isSheepName(maybeSheepName)) {
        // Our custom type guard asserts that this is a SheepName so TS is happy.
        return (maybeSheepName as SheepName);
    }
    throw new Error('That is not a sheep name.');
}

const definitelySheepName = parseSheepName(unsafeJson);

PRO: More reusable, marginally less fragile, arguably more readable.

CON: Typescript is still just taking your word for it. Seems like a lot of code for something so simple.

3: Use Array.find (Safest, Recommended)

This doesn't require type assertions, in case you (like me) don't trust yourself.

const sheepNames = ['Capn Frisky', 'Mr. Snugs', 'Lambchop'] as const;
type SheepName = typeof sheepNames[number];

const unsafeJson = '"Capn Frisky"';

/**
 * Return a valid SheepName from a JSON-encoded string or throw.
 */
function parseSheepName(jsonString: string): SheepName {
    const maybeSheepName: unknown = JSON.parse(jsonString);
    const sheepName = sheepNames.find((validName) => validName === maybeSheepName);
    if (sheepName) {
        // `sheepName` comes from the list of `sheepNames` so the compiler is happy.
        return sheepName;
    }
    throw new Error('That is not a sheep name.');
}

const definitelySheepName = parseSheepName(unsafeJson);

PRO: Doesn't require type assertions, the compiler is still doing all the validation. That's important to me, so I prefer this solution.

CON: It looks kinda weird. It's harder to optimize for performance.

So that's it. You can reasonably choose any of these strategies, or go with a 3rd party library that others have recommended.

Sticklers will correctly point out that using an array here is inefficient. You can optimize these solutions by casting the sheepNames array to a set for O(1) lookups. Worth it if you're dealing with thousands of potential sheep names (or whatever).

Tags:

Typescript

Recent Posts