[feature request] Better `Array.prototype.includes`

[ssssota]

The standard TypeScript type requires the first argument of the includes function to be a value in an array.
This requires that the type of the argument be known beforehand for union-type arrays (e.g. [1,2,3] as const).
We can see that this is not a semantic error, but we may find this inconvenient.

So please consider introducing the following types into this project:

interface Array<T> {
  /**
   * Determines whether an array includes a certain element, returning true or false as appropriate.
   * @param searchElement The element to search for.
   * @param fromIndex The position in this array at which to begin searching for searchElement.
   */
  includes(searchElement: any, fromIndex?: number): searchElement is T;
}

interface ReadonlyArray<T> {
  /**
   * Determines whether an array includes a certain element, returning true or false as appropriate.
   * @param searchElement The element to search for.
   * @param fromIndex The position in this array at which to begin searching for searchElement.
   */
  includes(searchElement: any, fromIndex?: number): searchElement is T;
}

[uhyo]

Thank you for suggestion!

I see that the suggested signatures make include much more convenient.
It would indeed start to allow some mistakes (like strings.includes(num)), but it wouldn't deviate from type safety.

Let's add this.

[graphemecluster]

@uhyo Wait – By adding this it means that we will also need to deal with methods like findIndex – see microsoft/TypeScript#36554 (comment) and microsoft/TypeScript#26255. To maintain type safety, perhaps we can use a generic until microsoft/TypeScript#9252 is implemented:

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

[uhyo]

@graphemecluster Thank you for pointing this out. Personally I wouldn't extend this to methods like findIndex because we need to corrently type callback parameters. Anyway the generics approach is nice 🙂

[uhyo]

I tacked this and couldn't get to a perfectly working implementation. 😇 As mentioned above, we should only narrow in then-branch of include checks but it doesn't seem currently possible. Concretely the below testcase cannot pass.

  function checkNarrowing(val: "pika" | "chu" | "pikachu") {
    const strarr: ("pika" | "chu")[] = [];
    if (strarr.includes(val)) {
      expectType<"pika" | "chu">(val);
    } else {
      expectType<"pika" | "chu" | "pikachu">(val);
    }
  }

[aaditmshah]

I tacked this and couldn't get to a perfectly working implementation. 😇 As mentioned above, we should only narrow in then-branch of include checks but it doesn't seem currently possible. Concretely the below testcase cannot pass.

  function checkNarrowing(val: "pika" | "chu" | "pikachu") {
    const strarr: ("pika" | "chu")[] = [];
    if (strarr.includes(val)) {
      expectType<"pika" | "chu">(val);
    } else {
      expectType<"pika" | "chu" | "pikachu">(val);
    }
  }

I think it's all right to narrow the type in the else branch as well. If strarr.includes(val) is false then we know that val can't be "pika" or "chu". Hence, the type of val can be narrowed to just "pikachu".

Consider the following example. Playground Link

const expectType = <A>(a: A): A => a;

type Subtype<A, B> = A extends B ? A : never;

type Supertype<A, B> = A extends B ? B : unknown;

interface Includes<A> {
    includes: <B>(searchElement: Supertype<A, B>) => searchElement is Subtype<A, B>;
}

declare const array: Includes<"foo" | "bar">;

declare const subtypeElement: "foo";

declare const sametypeElement: "foo" | "bar";

declare const supertypeElement: "foo" | "bar" | "baz";

declare const othertypeElement: "baz";

if (array.includes(subtypeElement)) {
    expectType<"foo">(subtypeElement);
} else {
    expectType<never>(subtypeElement);
}

if (array.includes(sametypeElement)) {
    expectType<"foo" | "bar">(sametypeElement);
} else {
    expectType<never>(sametypeElement);
}

if (array.includes(supertypeElement)) {
    expectType<"foo" | "bar">(supertypeElement);
} else {
    expectType<"baz">(supertypeElement);
}

if (array.includes(othertypeElement)) {
    expectType<never>(othertypeElement);
} else {
    expectType<"baz">(othertypeElement);
}

[aaditmshah]

Oh, wait. No, I'm mistaken. Didn't see that strarr is empty here. Nevermind. Disregard my previous comment.

[aaditmshah]

@ssssota You might not require narrowing at all. Consider using the following find function instead of Array#includes.

Playground Link

type Option<A> = { some: A } | null;

const find = <A>(needle: unknown, haystack: A[]): Option<A> => {
    for (const element of haystack) {
        if (element === needle) {
            return { some: element };
        }
    }
    return null;
};

declare const haystack: ("foo" | "bar")[];

declare const needle: "foo" | "bar" | "baz";

const option = find(needle, haystack);

const expectType = <A>(a: A): A => a;

if (option !== null) {
    expectType<{ some: "foo" | "bar" }>(option);
    expectType<"foo" | "bar" | "baz">(needle);
} else {
    expectType<null>(option);
    expectType<"foo" | "bar" | "baz">(needle);
}

[ssssota]

@aaditmshah
Of course!
This Issue was created only as a "nice to have".
Naturally, it cannot be used in actual coding, so we have taken workarounds.
@uhyo
If this issue is not feasible, please feel free to close it.
The discussion here has been very useful to me. Thank you!

[graphemecluster]

I just revisited this and thought of a solution (which’s overly ordinary that you may even have thought of it before) while replying @cm-ayf’s post tweet:
https://twitter.com/graphemecluster/status/1700470364000956844
However, the defect is that this doesn’t give any error directly; it just types the parameter never instead if T is not related to U.
I am not sure if there are any pitfalls though.
I have tried producing an error if T & U is never but none of my trials work. So I guess it’s still the best to play around with the compiler – my first thought is to add type ErrorIfNever<T> = T; to a library file and let the compiler handle the remaining things.
_{お二人とも東大生だ、憧れます……}