`Array.includes` type is too narrow

[OliverJAsh]

TypeScript Version: 2.9.2

Search Terms: array includes es2016 widen

Code

Array.includes should allow the searchElement param to be a subtype of the array element type, e.g.

type A = 'foo' | 'bar' | 'baz'
type ASub = Extract<A, 'foo' | 'bar'>;
declare const aSubs: ASub[];
declare const a: A;
/*
Argument of type 'A' is not assignable to parameter of type '"foo" | "bar"'.
 Type '"baz"' is not assignable to type '"foo" | "bar"'.
*/
aSubs.includes(a);

Expected behavior:

No error.

[RyanCavanaugh]

'foo' | 'bar' | 'baz' is a supertype of 'foo' | 'bar', not a subtype (subtypes represent subdomains of their supertypes).

See #14520 for discussion of upper-bounded generics.

[OliverJAsh]

Thanks, closing as duplicate.

[chharvey]

Oliver Joseph Ash (@OliverJAsh) Ryan Cavanaugh (@RyanCavanaugh) : I’m not sure if this is an exact duplicate, but more to the point, Goal Number 7 says that all runtime behavior of JS should be preserved. Since in normal JS Array#includes always returns, you should be able to call [1,2,3].includes('four') in TS without getting a compile-time error.

Currently, the implementation is this:

interface Array<T> {
 includes(searchElement: T, fromIndex?: number): boolean;
}

but it could be this:

interface Array<T> {
 includes<U>(searchElement: U, fromIndex?: number): U extends T ? boolean : false;
}

That way, [1,2,3].includes('four') wouldn’t throw an error, but its type would be false.

The same goes for Set#has and Map#has:

interface Set<T> {
 has<U>(value: U): U extends T ? boolean : false;
}
interface Map<K, V> {
 has<U>(key: U): U extends K ? boolean : false;
}

[RyanCavanaugh]

Since in normal JS Array#includes always returns, you should be able to call [1,2,3].includes('four') in TS without getting a compile-time error.

Please read https://stackoverflow.com/questions/41750390/what-does-all-legal-javascript-is-legal-typescript-mean

[Benjamin-Dobell]

Ryan Cavanaugh (@RyanCavanaugh) Thanks for the link to Stackoverflow; as indicated on Stackoverflow:

TypeScript may issue type warnings on code that it considers incorrect.

However, I'm curious as to why TypeScript would consider:

includes(searchElement: any, fromIndex?: number): boolean;

to be incorrect?

The includes method[1] is defined as:

includes compares searchElement to the elements of the array, in ascending order, using the SameValueZero algorithm, and if found at any position, returns true; otherwise, false is returned.

The optional second argument fromIndex defaults to 0 (i.e. the whole array is searched). If it is greater than or equal to the length of the array, false is returned, i.e. the array will not be searched. If it is negative, it is used as the offset from the end of the array to compute fromIndex. If the computed index is less than 0, the whole array will be searched.

There's no indication this function should not be called with types that do not exist in the array. Somewhat to the contrary, the first step of the aforementioned SameValueZero[2] algorithm is:

If Type(x) is different from Type(y), return false.

As such includes offers behavior specifically guaranteed to return false if the type of searchElement matches no elements in the array. Given the function was designed and documented to have this behaviour, is there any particular reason why TypeScript won't allow us to utilize this function as documented?

At least based on my current understanding, it seems unusual to me that...:

const KNOWN_VALUES = Object.freeze(['a', 'b', 'c'])

function foo(input?: string | null) {
 if (KNOWN_VALUES.includes(input)) { // <== TS2345
 // ... Do thing
 }
}

gives the error...:

TS2345: Argument of type 'string | null | undefined' is not assignable to parameter of type 'string'. Type 'undefined' is not assignable to type 'string'.

given that the ECMAScript spec documents this as being a case in which I can safely expect includes to return false.

Granted, I understand TypeScript goes above and beyond JS; it's inherently adding type-safety to a language (and spec) that never had it in mind. The StackOverflow answer mentioned above even specifically calls out referring to the spec as an invalid reason to impact TypeScript's design. The entire point of TypeScript of course being that it adds additional safety. However, I'm not sure under which circumstances the above error provides additional type safety.

Somewhat to the contrary, to work around the error I must train myself to do something that is unsafe e.g. use a ! postfix or a cast. By definition calling includes does not cause any side effects, so I'm (presently) unsure what benefit this seemingly overly restrictive function type definition affords users of TypeScript. Especially given checking unsanitized input against a set of known values it a very common pattern.

Just to clarify, my query isn't specifically regarding null and undefined (despite the chosen example). I would expect the described pattern to work equally as well if input to foo is of type any i.e I'd want to use this pattern to safely determine whether input is a value my program knows about at runtime. I can then use this information to make further inferences (perhaps even type inferences) at runtime to provide sanitation/safety at runtime.

However, admittedly I'm approaching this from a particular mind-set based on my own experience and use-cases; which quite frankly may not be enough to understand the situation at large. Consequently, there may be something immediately apparent to others that I'm simply not seeing. As such, if I'm off base here, I would absolutely appreciate any time anyone is willing to afford me such that I can be better educated on the matter.

[1] https://www.ecma-international.org/ecma-262/9.0/index.html#sec-array.prototype.includes
[2] https://www.ecma-international.org/ecma-262/9.0/index.html#sec-samevaluezero

[Benjamin-Dobell]

Sorry, the tldr; of my post above is...

If the type definition of includes were to be changed to:

includes(searchElement: any, fromIndex?: number): boolean;

would it actually break (or cause someone to "break") a single piece of software written in TypeScript?

My current thinking, is no. However, that may be incorrect.

Even still, that alone isn't reason to change the signature. Assuming the change wouldn't break any real-world software. Would changing the signature worsen or improve code comprehension?

I'm of the opinion (at present) that it would actually significantly improve code comprehension as it would allow a common coding pattern to be utilized without littering code with unnecessary (and technically incorrect) casts and/or unnecessary type-checks and null checks.

[RyanCavanaugh]

There's no indication this function should not be called with types that do not exist in the array

⁉

... includes(searchElement: any, fromIndex?: number): boolean;

You're arguing is that this code is totally fine and has no obvious problems:

function foo(arr: string[], content: string, index: number) {
 if (arr.includes(index)) {
 // Do something important
 }
}

This code is in fact extremely suspicious! Type checking is not a valuable operation if it's not capable of identifying code that's very likely to be wrong.

If/when we do get upper-bounded constraints, it absolutely makes sense to make includes be a bivariant operation. Until then, the current definition is the best available.

would it actually break (or cause someone to "break") a single piece of software written in TypeScript?

Changing every built-in function to accept anys would also "break" no one, but that doesn't make it a good idea. Part of TypeScript's value proposition is to catch errors; failing to catch an error is a reduction in that value and is something we have to weigh carefully against "Well maybe I meant that" cases.

[Benjamin-Dobell]

Ryan Cavanaugh (@RyanCavanaugh) That's a fairly reasonable example of suspicious code, something I admittedly hadn't considered as being a possibility. I'm not sure how frequently this sort of thing would occur in practice. I suspect this would be highly infrequent, but honestly I can't back that up. If it does occur frequently, then it may well trump everything that follows...

However, my concern is that this function has been given a narrow type constraint simply because this is TypeScript, so there's a desire to add types to existing APIs. However, presumably this should only be done for the purpose of facilitating correctness, if the function already has well defined and well understood semantics, then altering these semantics may not be desirable. In this particular instance I believe it leads developers to write code that is non-obvious, unnatural, and therefore more likely to be error prone.

Take for example the sanitation use case. A developer wants to check if some input is in some collection (technically this applies to sets as well as primitive arrays). The natural way to write this code is:

const KNOWN_VALUES = Object.freeze(['a', 'b', 'c'])

function isKnownValue(input?: string | number) {
	return KNOWN_VALUES.includes(input)
}

It's not clever or complicated code, it matches the developers intention precisely, yet TypeScript rejects the code.

So, what does the developer do to correct this issue? A cast, a type check? Let's try the latter:

const KNOWN_VALUES = Object.freeze(['a', 'b', 'c'])

function isKnownValue(input?: string | number) {
	return typeof(input) === 'string' && KNOWN_VALUES.includes(input)
}

Great, it passes. We've got an extra check in there that will be compiled to JS, but "it's a small price to pay for type safety" 👍

Now consider we want to handle numbers in our known value set:

const KNOWN_VALUES = Object.freeze(['a', 'b', 'c', 1, 2, 3])

function isKnownValue(input?: string | number) {
	return typeof(input) === 'string' && KNOWN_VALUES.includes(input)
}

Uh oh!

This TypeScript compiles without errors, but it's not correct. Where as our original "naive" approach would have worked just fine. Why is that? Where is the breakdown here?

It's because TypeScript's type system got in the way of the developer's initial intent. It caused us to change our code from what we intended to what it allowed.

It was never the developer's intention to check that input was a string and a known value; the developer simply wanted to check whether input was a known value - but wasn't permitted to do so.

Generally TypeScript doesn't get in the way, for the most part it encourages correctness - honestly it's great. However, I think in this particular circumstance, it's not facilitating correctness or behaving how developers would expect.

Note: To work around the initial TS error, I could have used a cast instead of an explicit type-check. This would be even more unnatural as we'd essentially intentionally be performing a cast that we know may be inaccurate - however, it would have the benefit that the error above would have been averted. Of course, reading the code after adding in number handling would then be even more confusing.

Edit: Some details of my example were originally poorly chosen i.e. the example was constructed in a way that developer would probably have done a null check rather than a typeof comparison. I've addressed that now. My apologies to anyone who read this before-hand and thought the example seemed a bit too "fabricated".

[henryhobhouse]

I'm hitting a similar issue but in union types:

const allDogNames = {
 django: 'django',
 tom: 'tom',
 buster: 'buster',
} as const;

// type -> "django" | "tom" | "buster"
type AllDogNames = (typeof allDogNames)[keyof typeof allDogNames]; 

const checkDogOnShortlist = (name: AllDogNames): boolean => {
 return [allDogNames.django, allDogNames.tom].includes(name);
};

Error:(26, 57) TS2345: Argument of type '"django" | "tom" | "buster"' is not assignable to parameter of type '"django" | "tom"'. Type '"buster"' is not assignable to type '"django" | "tom"'.

To get around this you have to declare the shortlist type that it "could" be any of the names even if the defined array clearly is not:

const checkNameForDog = (name: AllDogNames): boolean => {
 // type -> ("django" | "tom" | "buster")[]
 const dogShortList: AllDogNames[] = [allDogNames.django, allDogNames.tom]; 
 return dogShortList.includes(name);
};

No error

Behaviour doesn't seem expected in that it would seem reasonable for typescript to determine if you are comparing against a list of string literals with a string literal then this is Ok?

[benneq]

How about using this signature?

function includes<T, U extends T>(arr: readonly U[], elem: T): elem is U {
 return arr.includes(elem as any);
}

This isn't too restrictive, and provides a nice type type guard.

const ARR = ['a', 'b', 'c'] as const;

const x = 'a'; // type is "a"
if (includes(ARR, x)) {
 console.log(x); // type is "a"
}

const x = 'x'; // type is "x"
if (includes(ARR, x)) {
 console.log(x); // type is never
}

const x = 'doesnt matter' as string; // type is string
if (includes(ARR, x)) {
 console.log(x); // type is "a" | "b" | "c"
}