ReadonlyArray.includesで型ガード

TypeScriptで以下のようなコードを書いてイラッときたことはないですか？私はあります。

```ts
const KEYS = ['aaa', 'bbb', 'ccc'] as const;
function f1(key: string) {
  if (KEYS.includes(key)) {
    //              ~~~
    // Argument of type 'string' is not assignable to parameter of type '"aaa" | "bbb" | "ccc"'.
  }
}
```

指定された文字列が`KEYS`の中にあるかどうかを確認したいのに`includes`に指定できるのは`"aaa" | "bbb" | "ccc"`、つまり`KEYS`に含まれる文字列だけ?何という理不尽...

そこでどうにかならないか考えてみました。

## TL;DR

以下の内容を`types.d.ts`などの名前でプロジェクトに置くだけで上記の問題が解決します!

```ts
declare global {
  interface ReadonlyArray<T> {
    includes<U>(
      s: U,
      ...args: IsLiteralArray<this> extends true
        ? T extends U
          ? [fromIndex?: number]
          : never
        : never
    ): s is IsLiteralArray<this> extends true
      ? T extends U
        ? T
        : never
      : never;
    includes<U>(
      s: U,
      ...args: T extends U ? [fromIndex?: number] : never
    ): boolean;
  }

  interface Array<T> {
    includes<U>(
      s: U,
      ...args: T extends U ? [fromIndex?: number] : never
    ): T extends U ? boolean : false;
  }
}

type IsUnion<T> = (T extends T ? (p: T) => 0 : never) extends (p: T) => 0
  ? false
  : true;
type IsLiteral<T> = IsUnion<T> extends true
  ? false
  : T extends null | undefined | boolean
  ? true
  : T extends PropertyKey
  ? {} extends Record<T, unknown>
    ? false
    : true
  : T extends bigint
  ? {} extends Record<`${T}`, unknown>
    ? false
    : true
  : false;
type IsLiteralArray<T extends readonly unknown[]> = IsUnion<T> extends true
  ? false
  : IsLiteral<T['length']> extends true
  ? T extends readonly [infer F, ...infer R]
    ? IsLiteral<F> extends true
      ? IsLiteralArray<R>
      : false
    : true
  : false;

export {};
```

## 解決までの道のり

### 解決案1: unknown型にする

まずはReadonlyArrayでのincludesの定義を見てみます。

```ts
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: T, fromIndex?: number): boolean;
}
```

これを

```ts
const KEYS = ['aaa', 'bbb', 'ccc'] as const;
```

に適用するとKEYSはReadonlyArrayとしてみると`ReadonlyArray<"aaa" | "bbb" | "ccc">`になるのでincludesは`includes(searchElement: "aaa" | "bbb" | "ccc", fromIndex?: number): boolean;`となるので、`"aaa" | "bbb" | "ccc"`でないと第1引数に指定できないのです。

ならばこれを何でも受け付ける`unknown`にしてしまえばいい、ということでこんなふうにしてみました。

```ts
declare global {
  interface ReadonlyArray<T> {
    includes(searchElement: unknown, fromIndex?: number): searchElement is T;
  }
}

export {};
```

こうすると

```ts
const KEYS = ['aaa', 'bbb', 'ccc'] as const;
function f1(key: string) {
  if (KEYS.includes(key)) {
    key; // 'aaa' | 'bbb' | 'ccc'
  }
}
```

とこのコードだけ見ると思ったとおりになってくれます。

### 解決案1の問題点

この解決方法では2つ問題があります。

1. 型チェックが効かなくなる
1. 型ガードが誤判定を起こす

#### 型チェックが効かなくなる

たとえば先程の例のKEYSに対して数値型の変数を間違って渡してしまったとしましょう。

```ts
function f2(key: number) {
  if (KEYS.includes(key)) {
    key; // 'aaa' | 'bbb' | 'ccc'
  }
}
```

KEYSは文字列型の配列なのに、数値型を渡してしまってもエラーにならなくなってしまいました。

#### 型ガードが誤判定を起こす

型ガード関数としてtrueを返すときは問題ないのですが、falseを返したときの型が…

```ts
function f3(keys: ReadonlyArray<'aaa' | 'bbb' | 'ccc'>, key: 'aaa' | 'ddd') {
    if (keys.includes(key)) {
        key; // "aaa" <- OK
    } else {
        key; // "ddd" <- NG
        // KEYSに’aaa’が含まれていない場合はkeyが’aaa’である可能性がある
    }
}
```

ReadonlyArrayはその型パラメーターであるすべての値を持っているとは限りません。includesがfalseを返すからと言ってT型ではないと判定されてしまっては困ることがあるのです。

### 解決案2: Genericsを使う

型チェックが効かなくなるのはunknownにしてしまうからです。includesの第1引数がeadonlyArrayの方パラメーターであるTのスーパータイプであれば誤って指定したわけではない、と考えても良いでしょうからそのような制約をつけてみたいと思います。

#### スーパータイプの制約

Genericsを使えば、型パラメーターが特定の型のサブタイプであること、という制約をつけることができますが、今回行いたいのは型パラメーターがTのスーパータイプであることという制約なので型制約をつけたいところですが、そのような方制約は何度かIssueに上がってはいるものの適用には至っていないようです。

ただ関数の引数でのみ使用できるスーパータイプで制約する方法を見つけました。

```ts
interface ReadonlyArray<T> {
  includes<U>(
    s: U,
    ...args: T extends U ? [fromIndex?: number] : never
  ): s is T extends U ? T : never;
}
```

残りの引数をConditionTypeでneverとしてしまうことで、制約にマッチしない場合はコンパイルエラーになるようにできました。

```ts
const KEYS = ['aaa', 'bbb', 'ccc'] as const;

function f1(key: string) {
    if (KEYS.includes(key)) {
        key; // key: "aaa" | "bbb" | "ccc"
    } else {
        key; // key: string
    }
}

function f2(key: number) {
    if (KEYS.includes(key)) { // ここでエラー
        key; // key: never
    }
}
```

[Playground](https://www.typescriptlang.org/ja/play/?#code/JYOwLgpgTgZghgYwgAgEoTgEwPYgDYCeAglFHAQDwAqAfMgN4BQyyoCeArphAM4UCqNABTMWyHgC5k-ADSiWAOiVwoAc0nIqyCAA9IITD2nIA-MgDaMKNgC2ASQO6TUkBxsAjaAF1kLiADdoUQBKKSNgIy1dfUNjMy0-QKgAbkYAX0ZGBFweMGQAaQBRAE0AZWQAXgsAcjg66plkavcWhqaEDuqfOCNskFzUxhgOEAQwYFxkGABGIQBrCAIwsChQVWCGeVYYZCEisoU2Tm4eecXgjaYxa+QFgmTkAHpH28WpACI6uHfkAB9kd4tdw-f7vDoId5bNLaPA8FBXG4sO4PZ6vJbiFZrKHpTLDUbjSYwABMZ3Rrg80EuW2AOz2JVKh1Gx14pIuDCeL0AygycwDmDIAKhkAlwyAH4YttdkRy0YkgtcMmkgA)

### 解決案3: as constをつけた配列だけを対象とする

型ガードが誤判定を起こす、という点については現在の型ガードの仕様上ReadonlyArray型の全てにこのオーバーロードを適用してしまっては、解決の方法がありません。なぜならReadonlyArrayは空も許容される配列型であり、空であればincludesが常にfalseを返すことになり、never型にしかならないことになります。

```ts
const LIST: ReadonlyArray<unknown> = [];
function f3(key: unknown) {
    if (LIST.includes(key)) {
        key; // key: unknown だけどこちらにはこない
    }else{
        key; // key: never　こちらには来るけどnever型になって使えない
    }
}
```

であれば割り切って「リテラルだけを持つas constが付けられた配列」だけに限定してしまうことにします。

リテラルだけを持つas constが付けられた配列を判別する型関数は以下のようになります。

```ts
type IsLiteralArray<T extends readonly unknown[]> = IsUnion<T> extends true
  ? false
  : IsLiteral<T['length']> extends true
  ? T extends readonly [infer F, ...infer R]
    ? IsLiteral<F> extends true
      ? IsLiteralArray<R>
      : false
    : true
  : false;

type IsLiteral<T> = IsUnion<T> extends true
  ? false
  : T extends null | undefined | boolean
  ? true
  : T extends PropertyKey
  ? {} extends Record<T, unknown>
    ? false
    : true
  : T extends bigint
  ? {} extends Record<`${T}`, unknown>
    ? false
    : true
  : false;

type IsUnion<T> = (T extends T ? (p: T) => 0 : never) extends (p: T) => 0
  ? false
  : true;
```

これを先程の型制約もどきに追加してやると

```ts
interface ReadonlyArray<T> {
  includes<U>(
    s: U,
    ...args: IsLiteralArray<this> extends true
        ? T extends U ? [fromIndex?: number] : never : never
  ): s is T extends U ? T : never;
}
```

先程の例に適用すると

```ts
const LIST: ReadonlyArray<unknown> = [];
function f3(key: unknown) {
    if (LIST.includes(key)) { // LISTはas const付きの配列ではないのでincludesは型ガードではない
        key; // key: unknown だけどこちらにはこない
    }else{
        key; // key: unknown 型ガードではないのでunknownのまま
    }
}
```

[Playground](https://www.typescriptlang.org/ja/play/?ssl=53&ssc=1&pln=60&pc=2#code/JYOwLgpgTgZghgYwgAgEoTgEwPYgDYCeAglFHAQDwAqAfMgN4BQyyoCeArphAM4UCqNABTMWyHgC5k-ADSiWAOiVwoAc0nIAkjwAywSGTwkylMAAtgPOhAAekEJh7IwUDhHliWAfmRVkt+0dpZB8AbRgobABbTQdbLykQDiiAI2gAXWREiAA3aCzkEFzoUQBKKSdLX387CAcnfhDq7LyoAG5GAF9GRjACAAcUbX4QYFxqOgBeZCE-ALqgvx8hfqkqUuRJugAGAqLWjfn6mdXfDa3kbdEfeDwedxYpFzcOvsGtXX1oODwJzY+RmMQH8jkFng8mrd7qI1jVAk4kng8MgAD7IDhxGCgCCYVHIFLYbB4DAga7OVwQ2GgpwABUigygfQA0hACGT6J04QsnOgENgoJhqDJ0SAANYgbAAdxANA8Nx+0M8TwpMOq1PxwFUoDA7M56t5-MFAAMACT0KidI3CjHiqUyuXIKEQx7ktyqp2vAZDT4GH7GcjULnHKAYHD4Agi23S0LpKYA0bjWhBsEq7yOhWUj56X2-KihADkxJAqnM+djyac4LJc1qwdDuEIyFCoBg+QAYsKlAoW-lUOkHdps99fm3rLWU27PGnB19DP7KKhZVOCk6PMrJyuMx0eow+SAeGBkEyAKIATQAyv8C3Ab-nhfmUo+78h8wg32XkHAnHuD9uYBiEDAIFHQARiEUVWQqFxQFUDYmE8YAYBmE8L27EB2C4XhwNZUo4I8TwIIINpkAAehI5BCKkAAiG84CovEqMfFJ6LRKi3wQKiPD1O4UHg5cKNZYiyIEggoKgGCuK6Hp-3QoDcEdAAmbDRMKZI0igPCEKQoQUPPNCMO4HhlNwhhSPIwBlBnMwBzBkACoZAEuGQAfhnwsRCKE8jKMKYooEk7pd1wA9kB0TRzyoKR0CwBtiFIAMbQlaU4xjDoZMA4CYAAZmUqRYrtTSxEQmYgpC-TOEM4y4LMwLgqoQB7Bi-ZAfzAQANuUAWQZADsGQBZRMAdCUrOqwArBkAEQZWqstgSt4arAGj1QAahgcwBJhh6gbnJYVyKo87LpWQQADBkARQZAEsGczAEMGQBIhkAawZqvMhbPE6CAeL45dluE1axTikBkCm2b5sGqy1pAVrAD8GX6fKAA)

誤判定がなくなりました。

### 最終型

型ガードが誤判定を起こす、というのは型ガードにしなければ起こらない話なので型ガードでない版のincludesも用意します。ついでにreadonlyのつかないArrayにも用意しましょう。

それからモジュールを使っていると`declare global`で囲む必要があります。また`declare global`を使うには明示的にモジュールを使うということを宣言する必要があるので何もエクスポートしない`export {}`をつけておきます。

## 本家の反応

TypeScriptの本体に取り込んでもらおうと[Issue](https://github.com/microsoft/TypeScript/issues/61618)を立てたんですが、「複雑過ぎて何やってるかわかんないよ(意訳)」[^1]ということで拒否されちゃいました。トホホ

というわけで供養のために投稿します。

[^1]: 標準ライブラリは可能な限りシンプルにするという設計理念だそうなので納得はしています。