Narrow types for certain cases of Array.includes

src/entrypoints/array-includes.d.ts

@@ -1,13 +1,35 @@
 /// <reference path="utils.d.ts" />
 
+type NarrowArrayElement<T, Found = never> = TSReset.IsUnion<T> extends true
+  ? never
+  : T extends readonly [infer A, ...infer B]
+  ? TSReset.IsStrictLiteral<A> extends true
+    ? NarrowArrayElement<B, Found | A>
+    : never
+  : Found;
+
 interface ReadonlyArray<T> {
+  includes(
+    searchElement: [NarrowArrayElement<this>] extends [never]
+      ? never
+      : T | (TSReset.WidenLiteral<T> & {}),
+    fromIndex?: number,
+  ): searchElement is NarrowArrayElement<this>;
+
   includes(
     searchElement: T | (TSReset.WidenLiteral<T> & {}),
     fromIndex?: number,
   ): boolean;
 }
 
 interface Array<T> {
+  includes(
+    searchElement: [NarrowArrayElement<this>] extends [never]
+      ? never
+      : T | (TSReset.WidenLiteral<T> & {}),
+    fromIndex?: number,
+  ): searchElement is NarrowArrayElement<this>;
+
   includes(
     searchElement: T | (TSReset.WidenLiteral<T> & {}),
     fromIndex?: number,

src/entrypoints/utils.d.ts

@@ -14,4 +14,16 @@ declare namespace TSReset {
     : T extends symbol
     ? symbol
     : T;
+
+  export type UnionToIntersection<U> = (
+    U extends any ? (k: U) => void : never
+  ) extends (k: infer I) => void
+    ? I
+    : never;
+
+  type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
+
+  type IsStrictLiteral<T> = WidenLiteral<UnionToIntersection<T>> extends T
+    ? false
+    : true;
 }

src/tests/array-includes.ts

@@ -64,3 +64,115 @@ doNotExecute(async () => {
     true,
   );
 });
+
+doNotExecute(async () => {
+  // All entries are well known => value is narrowed
+  const options = [1, 2, 3] as readonly [1, 2, 3];
+  const value = 2 as 2 | 3 | 4 | 5;
+
+  if (options.includes(value)) {
+    type tests = [Expect<Equal<typeof value, 2 | 3>>];
+  } else {
+    type tests = [Expect<Equal<typeof value, 4 | 5>>];
+  }
+});
+
+doNotExecute(async () => {
+  // Entries are not well known => value is not narrowed
+  const options = [1, 2, 3] as readonly number[];
+  const value = 2 as 2 | 3 | 4 | 5;
+
+  if (options.includes(value)) {
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  } else {
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  }
+});
+
+doNotExecute(async () => {
+  // Entries are not well known => value is not narrowed
+  const options = [1, 2, 3] as number[];
+  const value = 2 as 2 | 3 | 4 | 5;
+
+  if (options.includes(value)) {
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  } else {
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  }
+});
+
+doNotExecute(async () => {
+  // Entries are not well known => value is not narrowed
+  const options = [] as readonly 1[];
+  const value = 1 as 1 | 2;
+
+  if (options.includes(value)) {
+    type tests = [Expect<Equal<typeof value, 1 | 2>>];
+  } else {
+    type tests = [Expect<Equal<typeof value, 1 | 2>>];
+  }
+});
+
+doNotExecute(async () => {
+  // Entries are not well known => value is not narrowed
+  const options = [] as 1[];
+  const value = 1 as 1 | 2;
+
+  if (options.includes(value)) {
+    type tests = [Expect<Equal<typeof value, 1 | 2>>];
+  } else {
+    type tests = [Expect<Equal<typeof value, 1 | 2>>];
+  }
+});
+
+doNotExecute(async () => {
+  // Some entries are well known, others not => value is not narrowed
+  const options = [1, 2, 3] as readonly [1, 2, 3 | 4];
+  const value = 2 as 2 | 3 | 4 | 5;
+
+  if (options.includes(value)) {
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  } else {
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  }
+});
+
+doNotExecute(async () => {
+  // Some entries are well known, others not => value is not narrowed
+  const options = [1, 2, 3] as [1, 2, 3 | 4];
+  const value = 2 as 2 | 3 | 4 | 5;
+
+  if (options.includes(value)) {
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  } else {
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  }
+});
+
+doNotExecute(async () => {
+  // Union of arrays with well known entries => value is narrowed
+  const options = [1, 2, 3] as readonly [1, 2, 3] | readonly [1, 2, 4];
+  const value = 2 as 2 | 3 | 4 | 5;
+
+  if (options.includes(value)) {
+    // @ts-expect-error: Typescript limitation. TODO: fix when possible
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  } else {
+    // @ts-expect-error: Typescript limitation. TODO: fix when possible
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  }
+});
+
+doNotExecute(async () => {
+  // Union of arrays with well known entries => value is narrowed
+  const options = [1, 2, 3] as [1, 2, 3] | [1, 2, 4];
+  const value = 2 as 2 | 3 | 4 | 5;
+
+  if (options.includes(value)) {
+    // @ts-expect-error: Typescript limitation. TODO: fix when possible
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  } else {
+    // @ts-expect-error: Typescript limitation. TODO: fix when possible
+    type tests = [Expect<Equal<typeof value, 2 | 3 | 4 | 5>>];
+  }
+});