Why does the argument for Array.prototype.includes(searchElement) need the same type as array elements?

Question

I honestly don't know if something is wrong with my settings or of if this is a typescript feature. In the following example:

type AllowedChars = 'x' | 'y' | 'z';
const exampleArr: AllowedChars[] = ['x', 'y', 'z'];

function checkKey(e: KeyboardEvent) { 
    if (exampleArr.includes(e.key)) { // <-- here
        // ...
    } 
}

The typescript compiler complains that Argument of type 'string' is not assignable to parameter of type 'AllowedChars'. But where am I assigning? Array.prototype.includes returns a boolean (which I am not storing). I could silence the error by a type assertion, like this:

if (exampleArr.includes(e.key as AllowedChars)) {}

But how is that correct, I am expecing user input which could be anything. I don't understand why a function (Array.prototype.includes()) made to check if an element is found in an array, should have knowledge about the type of input to expect.

My tsconfig.json (typescript v3.1.3):

 {
    "compilerOptions": {
      "target": "esnext",
      "moduleResolution": "node",
      "allowJs": true,
      "noEmit": true,
      "strict": true,
      "isolatedModules": true,
      "esModuleInterop": true,
      "jsx": "preserve",
    },
    "include": [
      "src"
    ],
    "exclude": [
      "node_modules",
      "**/__tests__/**"
    ]
  }

Any help would be appreciated!

By calling the function .includes(), you're effectively assigning e.key to the parameter. You declared the array as being an array of the AllowedChars type, and e.key is not of that type. — Pointy
– Pointy, Commented Oct 28, 2018 at 16:50

jcalz · Accepted Answer · 2025-02-17 18:54:09Z

39

See microsoft/TypeScript#26255 for a full discussion on Array.prototype.includes() and supertypes.

Yes, technically it should be safe to allow the searchElement parameter in Array<T>.includes() to be a supertype of T, but the standard TypeScript library declaration assumes that it is just T. For most purposes, this is a good assumption, since you don't usually want to compare completely unrelated types as @GustavoLopes mentions. But your type isn't completely unrelated, is it?

There are different ways to deal with this. The assertion you've made is probably the least correct one because you are asserting that a string is an AllowedChars even though it might not be. It "gets the job done" but you're right to feel uneasy about it.

Another way is to locally override the standard library via declaration merging to accept supertypes, which is a bit complicated because TypeScript doesn't support supertype constraints (see ms/TS#14520 for the feature request). Instead, the declaration uses conditional types to emulate a supertype constraint:

// remove "declare global" if you are writing your code in global scope to begin with
declare global {
  interface Array<T> {
    includes<U extends ([T] extends [U] ? unknown : never)>(
      searchElement: U, fromIndex?: number): boolean;
  }
}

Then your original code will just work:

if (exampleArr.includes(e.key)) {} // okay
// call to includes inspects as
// (method) Array<AllowedChars>.includes<string>(
//    searchElement: string, fromIndex?: number | undefined): boolean (+1 overload)

while still preventing the comparison of completely unrelated types:

if (exampleArr.includes(123)) {} // error
// Argument of type '123' is not assignable to parameter of type 'AllowedChars'.

But the easiest and still correct way to deal with this is to widen the type of exampleArr to readonly string[]:

const stringArr: readonly string[] = exampleArr; // no assertion
if (stringArr.includes(e.key)) {}  // okay

Or more succinctly like:

if ((exampleArr as readonly string[]).includes(e.key)) {} // okay

Widening to readonly string[] is fine, but be careful widening to string[], which is a little more dangerous because TypeScript unsafely treats Array<T> as covariant in T for convenience. This is fine for reading, but when you write properties you run into problems:

(exampleArr as string[]).push("oops"); // actually writing to an AllowedChars[]

But since you're just reading from the array it's perfectly safe, and why readonly is recommended.

Playground link to code

edited Feb 17 at 18:54

answered Oct 28, 2018 at 18:58

jcalz

339k29 gold badges452 silver badges449 bronze badges

Sign up to request clarification or add additional context in comments.

8 Comments

axm__ Over a year ago

Thank you for your elaborate answer!

Aluan Haddad Over a year ago

That's a really nice use of conditional types. However, if you want narrowing, it raises an error and you have to use a this type annotation instead. In Playground

Coderer Over a year ago

If you don't like being forced to cast the array to convince the typechecker you know what you're doing, you can go give a thumbs-up to this issue to show an interest in a mechanism that would allow these methods to be defined more accurately.

Henny Lee Over a year ago

Excellent and well explained answer!

ErikE Over a year ago

@jcalz Must be my mistake, commenting on the wrong answer (there are two questions answering this issue with multiple answers having similar but not-identical solutions).

|

Gustavo Lopes · Accepted Answer · 2018-10-28 18:06:24Z

1

If you are comparing two different types, then they are naturally different.

Imagine you have:

type A = {paramA: string};
type B = {paramB: number};

const valuesA: A[] = [{paramA: 'whatever'}];
const valueB: B = {paramB: 5};

valuesA.includes(valueB); // This will always be false, so it does not even make sense

In your case, the compiler threats AllowedChars as a completely different type from string. You have to "cast" the string you are receiving to AllowedChars.

But how is that correct, I am expecing user input which could be anything.

The compiler has no idea what you're trying to accomplish with the includes. It only knows they have different types, therefore they shouldn't be compared.

answered Oct 28, 2018 at 18:06

Gustavo Lopes

4,2534 gold badges24 silver badges63 bronze badges

1 Comment

parse Over a year ago

"You have to "cast" the string you are receiving to AllowedChars" 👍

Luis Antonio Canettoli Ordoñez · Accepted Answer · 2022-09-14 08:37:09Z

1

Eventually just using .some instead of .includes did the trick for me. Here's the playground.

const FRUITS = ["apple", "banana", "orange"] as const
type Fruit = typeof FRUITS[number]

const isFruit = (value: string): value is Fruit =>
    FRUITS.some(fruit => fruit === value)

edited Sep 14, 2022 at 8:37

answered Sep 13, 2022 at 6:53

Luis Antonio Canettoli Ordoñez

1,09512 silver badges15 bronze badges

Collectives™ on Stack Overflow

Why does the argument for Array.prototype.includes(searchElement) need the same type as array elements?

3 Answers 3

8 Comments

1 Comment

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

8 Comments

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related