# はじめに
昨今のReactのフォームライブラリではスタンダードになっているReact Hook Form (v7) と、これもReactのプロジェクトではよく用いられるMUI (v5)の各種入力部品を組み合わせて、汎用的に使用できる入力部品を作ってみた。テキストの入力においては純粋なテキスト (string型) の入力と、数値 (number型) の入力を分けたくなるのが常なので、MUIの `TextField` をベースに、`MuiTextField` と `MuiNumericField` の2つを用意してこれらを区別した。また、数値の入力部品では入力値をフォーマットして表示したい場面も多いので、`MuiNumericField` にはreact-number-formatも組み込んで、入力値のフォーマットができるようにした。

> info:執筆時の依存バージョン (最終更新2022/12/17)
> 
> - React v18.2.0
> - MUI v5.8.4
> - React Hook Form v7.30.0
> - react-number-format v5.1.2

先に最終的なデモを貼っておく。

<iframe src="https://yukiyokotani.github.io/react-hook-form/"
  style="width:100%; height:630px; border:0; border-radius: 4px; overflow:hidden;"
  title="MUI Input Components Linked to React Hook Form"
  allow="accelerometer; camera; encrypted-media; geolocation; gyroscope; midi; payment; usb; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

一連のファイルを置いたGitHubリポジトリは以下になる。

https://github.com/yukiyokotani/react-hook-form

**現状形になっている部品一覧**

- [MuiTextField](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiTextField.tsx)
- [MuiNumericField](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiNumericField.tsx)
- [MuiDatePicker](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiDatePicker.tsx)
- [MuiCheckbox](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiCheckbox.tsx)
- [MuiSelect](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiSelect.tsx)
- [MuiAutocomplete](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiAutocomplete.tsx)

以降では今回のインターフェース設計の思想と、実装時に得られた雑多な情報について軽く書きとめおく。この汎用部品を使いたい方はすぐ後の「利用者側から見たインターフェース」で使い方の雰囲気だけさっと眺めてGitHubに置いた[サンプルのフォーム実装](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/MuiForm.tsx)を見てもらうのがいいと思う。

# インターフェース
## 利用者側から見たインターフェース
インターフェースを紹介するために、一番シンプルな `MuiTextField` (string型のテキスト入力部品) の利用方法を紹介する。`MuiTextField` 以外の部品も同じインターフェイス設計になっているので、`MuiTextField` が分かれば他の部品も簡単に利用できるようになっている。

今回の汎用部品は型引数としてフォームオブジェクトの型を取るようにした。フォームの型はTypeScriptでReact Hook Formを使う場合は必ず定義する (そして `useForm` の型引数に渡す) ことになるので、同じものをそのまま渡せば良い。ここで型を渡すと、入力部品の `name` のPropsに渡した文字列が、ちゃんとフォームのkeyとして存在するかチェックされる。

```javascript:MuiTextFieldの使用例
<MuiTextField<FormData>
  name='name'
  control={control}
  rules={{
    required: '必須項目です。',
    maxLength: {
      value: 5,
      message: '5文字以内で入力してください。'
    }
  }}
  config={{
    displayErrorMessage: true
  }}
  muiProps={{
    textFieldProps: {
      label: '名前',
      fullWidth: true
    }
  }}
/>
```

上記の通り、Propsは大きく3つに分けて設計した。
- **React Hook Formで定義されているProps**  
  今回はこれを入力部品のベースのインターフェースとする
- **MUIの部品に対して定義されているProps**  
  今回はこれを `muiProps` としてまとめる
- **部品の提供者が追加で提供する設定項目のProps**  
  今回はこれを `config` としてまとめる

上の例で言うと、`name`, `control`, `rules`がReact Hook Form向けのインターフェイスである。今回の汎用部品ではこれを設計のベースにしているので、ネストしないPropsとして渡すことができる。このうち `control` と `name` はReact Hook Formによる制御において必須なので、Propsとしても必須にしている。一方で `rules` は必須ではなく、[Zod](https://github.com/colinhacks/zod)等のschemaライブラリを使ってフォームのschemaを定義し、`useForm` にschemaを渡す形でもバリデーションが実現できるようになっている。勿論バリデーションなしでも良い。

## 提供者側から見たインターフェース
とにかくPropsが多いので、3つの大きなまとまりで分けて管理するようにした。一つ目は今回主役となっているReact Hook FormのProps、2つ目はMUIのComponentのProps、3つ目が部品を提供する側が独自で組み込みたいオプションを提供するためのPropsである。

### React Hook FormのProps
React Hook Formのインターフェイスは `UseControllerProps` としてライブラリから提供されている。このPropsはインターフェースとして最表面に出ていて欲しい（ネストして欲しくない）ので、今回作る部品のPropsはこの型との交差型にすることにした。上記のサンプルで言うと、`name`, `control`, `rules`はReact Hook Formが公開しているインターフェイスで定義されたPropsである。

### MUI ComponentのProps
MUIのPropsは部品によっては複数必要になる。例えばAutocompleteではAutocomplete自体のPropsに加えて、内部に持つTextFieldのProps　（フォームの幅やラベルなど）　も渡せるようにしたい。よって、これらはオブジェクトに整理して、PropsのmuiPropsという口で渡せるようにした。React Hook FormのPropsとMUIのPropsは同名のものが多く衝突する可能性が高い（そして意図せず衝突するとバグる）ので、最初から分けてバグを生む可能性を排除した。

### 部品提供者が独自に提供する設定項目
提供者が独自で組み込みたいオプションを提供するためのPropsについても、MUIのPropsと同様、オブジェクトにまとめて、configという口で渡せるようにした。react-number-formatのProps (`NumberFormatPropsBase`) は意味的にはここに収まるのが良いと考えたので、`MuiNumberField` のconfigについては `NumberFormatPropsBase` との交差型になっている。


# Introduction
I tried to create an input component that can be used universally by combining React Hook Form (v7), which has become a standard in the recent React form libraries, and various input components of MUI (v5), which is also commonly used in React projects. In the text input, it is always necessary to separate pure text (string type) input from numeric (number type) input, so based on the MUI `TextField`, I prepared two input components, `MuiTextField` and `MuiNumericField`, to distinguish between them. Also, since there are many situations where you want to format and display input values in numeric input parts, I also incorporated react-number-format into `MuiNumericField` so that you can format the input values.

> info:Dependent version at the time of writing (last updated on Dec. 17, 2022)
> 
> - React v18.2.0
> - MUI v5.8.4
> - React Hook Form v7.30.0
> - react-number-format v5.1.2

I'll post the final demo first. (Sorry for the Japanese sample.)

<iframe src="https://yukiyokotani.github.io/react-hook-form/"
  style="width:100%; height:630px; border:0; border-radius: 4px; overflow:hidden;"
  title="MUI Input Components Linked to React Hook Form"
  allow="accelerometer; camera; encrypted-media; geolocation; gyroscope; midi; payment; usb; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

GitHub repository is below. (Commented in English.)

**List of currently available parts**.

- [MuiTextField](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiTextField.tsx)
- [MuiNumericField](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiNumericField.tsx)
- [MuiDatePicker](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiDatePicker.tsx)
- [MuiCheckbox](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiCheckbox.tsx)
- [MuiSelect](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiSelect.tsx)
- [MuiAutocomplete](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/components/MuiAutocomplete.tsx)

From here, we will summarize the philosophy behind the interface design, the information we obtained for each library while creating this component, and the points that stuck out in the implementation.　If you want to use the generic input component implemented here, you can have a quick look at the "Interface from the User's Point of View" to get an idea of how to use it, and then look at the [sample form implementation](https://github.com/yukiyokotani/react-hook-form/blob/main/src/mui-form/MuiForm.tsx) on GitHub.

## Interfaces
## Interface from the User's Point of View
To introduce the interface, we will show you how to use the simplest `MuiTextField` (a text input component of type `string`). The other components except for `MuiTextField` have the same interface design, so if you know `MuiTextField`, you can use the other components easily.

The component now takes the type of the form object as its type argument. The type of the form is always defined (and passed to the type argument of `useForm`) when using React Hook Form in TypeScript, so you can pass the same type as it is. If you pass the type here, it will be checked if the string you pass to the `name` props of the input component exists as a key of the form.

```javascript:Example of MuiTextField use
<MuiTextField<FormData, 'username'>
  name='username'
  control={control}
  rules={{
    required: 'Enter your username.',
    maxLength: {
      value: 10,
      message: 'Enter up to 10 characters.'
    }
  }}
  config={{
    displayErrorMessage: true
  }}
  muiProps={{
    textFieldProps: {
      label: 'Username',
      fullWidth: true
    }
  }}
/>
```

Props can be divided into three main categories.
- Props defined in React Hook Form. We will use this as the base interface for input components.
- Props defined for MUI components. This time, we will group them as `muiProps`.
- Additional configuration items for the part provided by the part provider. We will summarize this as `config`.

In the example above, `name`, `control`, and `rules` are the interfaces for the React Hook Form. In this generic part, since this is the base of the design, we can pass them as non-nested props. Among them, `control` and `name` are required for control by React Hook Form, so they are also required as Props. On the other hand, `rules` is not required, and validation can be realized by defining a form schema using a schema library such as [Zod](https://github.com/colinhacks/zod) and passing the schema to `useForm`. Of course, it is also possible without validation.

## Interface from the Provider's Point of View
Since there are a lot of Proposals, I decided to divide them into three major groups to manage them. The first is the React Hook Form Prop, which is the main component of this project, the second is the MUI Component Prop, and the third is the Prop to provide options that the component provider wants to incorporate on their own.

### Props of React Hook Form
The interface of React Hook Form is provided by the library as `UseControllerProps`. Since I want this Props to be on the top surface as an interface (I don't want it to be nested), I decided to make the Props of the part I'm going to create an intersection type with this type. In the above sample, `name`, `control`, and `rules` are Props defined in the interface exposed by React Hook Form.

### Props for MUI Component
Some parts require multiple MUI props. For example, in Autocomplete, in addition to Autocomplete's own Props, we want to be able to pass the internal TextField's Props (form width, label, etc.). Therefore, we organized them into objects, and made it possible to pass them through a mouth called muiProps of Props. Therefore, we have eliminated the possibility of creating bugs by separating them from the beginning.

### Configuration items provided independently by component providers
Props to provide options that providers want to incorporate into their own components are also grouped into an object and can be passed as config, just like props in the MUI. (`NumberFormatPropsBase`) is semantically better to fit here, so the `MuiNumberField` config is crossed with `NumberFormatPropsBase`.


Create an input component that combines React Hook Form with MUI, react-number-format

React Hook Form, MUI, react-number-formatを組み合わせた汎用入力部品を作る

# はじめに

動的フォームを除いた部分で一般的に必要な機能を盛り込んだミニマムなサンプルを作ることができたので、その際に得た知見をまとめておく。タイトルの通り、フォームの実装にはReactive Formsを使っている。最終的なコードとデモは以下。

https://github.com/yukiyokotani/study-angular/tree/master/src/app/form-with-ngx-mask

https://yukiyokotani.github.io/study-angular/#/form-with-ngx-mask

# Reactive Formにおける登場人物

Reactive Formでいくつか部品が出てくるので、概念をまとめておく。登場するのは `FormGroup`, `FormControl`, `Validator` の3つで、親子関係として下図のようになる。

```
FormGroup
  ├─ FormControl (1)
  |    ├─ Validator (1-i)
  |    └─ Validator (1-ii)
  |
  ├─ FormControl (2)
  |    └─ Validator (2-i)
  |
  └─ Cross-field Validator (1)
```

まず `FormGroup` はフォームを司る存在で、HTMLの `<form>` と対応する。`FormGroup` は子として `FormControl` と `Cross-field Validator` を持つ。

`FormControl` はHTMLの `<input>` をViewとするならば、そのModelというべき存在で、`<input>` と一対一に対応し入力値を管理する。このとき、各 `<input>` に対するバリデーションは `FormControl` に `Validator` を設定することで実現できる。`FormControl` に `Validator` が設定されている場合、バリデーションが発火するのは `FormControl` に値がセットされるタイミングである。このセットのタイミングは `FormControl` の `updatedOn` のプロパティで設定することができる。

最後に `FormGroup` の子で説明を飛ばした `Cross-field Validator` について説明する。これは特定の `<input>` と一対一では紐付かない、複数の `<input>` を跨いで実行されるバリデーションを定義する。役割から自然なようにこれは `FormGroup` の直接の持ち物になる。

# Custom Validationの実装

## 単一のinputに対するCustom Validation

必須チェックや、文字列の長さの最大最小、数値の最大最小のような、基本的なValidatorについては`@angular/forms` の `Validator` クラスが提供している。それ以外のValidatorを用意したいときに、Validatorの実装が必要になる。

ここでは例として、日付のチェックのValidator実装を載せる。具体的には、FormControlにセットされた文字列が「`YYYY/MM/DD` のフォーマットになっているか」、「実際に存在する日付かどうか」の2点を判定し、どちらか一方でも不適なら不正な日付としてエラーオブジェクトを返す。

```typescript: dateValidator
// dayjsを使用している
export const dateValidator: ValidatorFn = (
  control: AbstractControl
): ValidationErrors | null => {
  const format = 'YYYY/MM/DD';
  const date = control.value;
  const isValid =
    typeof date === 'string' && dayjs(date, format).format(format) === date;
  return isValid ? null : { invalidDate: true };
};
```

FormControlにセットするためのValidatorなので、引数の `control` にはFormControlが入るものとして実装する。AngularのValidatorの仕様として返り値の型は `ValidatorFn` である必要がある。

> 上のサンプルではエラーがないときの返り値を `null` にしているが、 実装上 `undefined` のほうが良いと考えている。というのも、のちのちエラーメッセージの表示制御を行うときに、入力値にエラーがあるかどうかの状態をFormControlから取らないといけないのだが、FormControlのプロパティは至るところがNullableになっており、Optional Chainingした結果が `undefined` に化ける可能性がある。よって、最後の判定で `null` でもなく、`undefined` でもない、みたいなロジックを書かないといけなくなる。（`*ngIf`に渡すためには `boolean` に変換する必要がある）

## 複数のinputにまたがるValidation

### Validatorの定義

例としてパスワードを確認用も含めて2回入力させるフォームを考える。このとき両者は一致する必要があるが、このバリデーションは2つの `<input>` に跨るためCross-field Validationになる。単一の場合と同じくCross-field Validationも返り値の型は `ValidatorFn` になる。

```typescript: matchPasswordValidator
export const matchPasswordValidator: ValidatorFn = (
  control: AbstractControl
): ValidationErrors | null => {
  const password = control.get('password');
  const verifyPassword = control.get('verifyPassword');

  return password && verifyPassword && password.value !== verifyPassword.value
    ? { notMatchPassword: true }
    : null;
};
```

FormGroupにセットするValidatorなので、引数の `control` にはFormGroupが入るものとして実装する。

### ErrorStateMatcherの定義

Cross-field Validationにおいて追加で考えないといけないのが、ErrorStateMathcerの実装である。Cross-field Validationはそれだけではどの `<input>` とも紐付いていないので、エラーになったときにフォームとしてはエラー状態になるが、その原因となっている `<input>` （より正確には `<mat-form-field>`）がエラー状態にならない。`<mat-form-field>` がエラー状態にならないと、 `<mat-error>` のようなコンポーネントは表面的な `*ngIf` のロジック等に関わらず、エラーメッセージを表示しない作りになっている。よって、Cross-field Validationの対象となる `<input>` に対しては自分でErrorStateMathcerを定義して、エラー状態を適切に管理する必要がある。

サンプルは確認用パスワードのフォームに向けたErrorStateMatcherである。大雑把に言うと、「自分のFormControlがエラー状態になっている」もしくは「FormGroupが持つエラーを見て、当該のCross-field Validationがエラーになっている」場合にはエラー状態であることを示す `true` を返している。

```typescript: VerifyPasswordFormErrorStateMatcher
export class VerifyPasswordFormErrorStateMatcher implements ErrorStateMatcher {
  isErrorState(
    control: FormControl | null,
    form: FormGroupDirective | NgForm | null
  ): boolean {
    const isSubmitted = form && form.submitted;
    return (
      isSubmitted === true &&
      control !== null &&
      (control.errors !== null ||
        (form?.form?.errors?.notMatchPassword ?? false))
    );
  }
}
```

# 入力値のフォーマット（フィルタリング）

以下のように入力値に特定のフォーマットを強制したい場合は、`ngx-mask` を使うと便利である。

- 日付の入力で `2021/11/13` のように `/` 区切りのフォーマットを強制したい場合
- 数値の入力で表示上は `1,000,000` のように `,` (いわゆるthousands separator) を表示したい場合

https://www.npmjs.com/package/ngx-mask

`ngx-mask` はオプションで入力中にplaceholderを表示するかどうかや、最終的にFormControlにセットする値にフォーマットのための文字 (`/` や `,`) を含めるかどうかも設定することができる。

また、値のフィルタリングも簡単に実装することができる。

# 入力値のトリミング・フィルタリング（独自実装）

少し別の視点で、独自に入力値をトリミング、フィルタリングしたい場合のDirectiveの実装について書く。ただ、この内容は `ngx-mask` を利用していれば基本的に不要な話ではある。

このあと実装をベタッと貼り長くなるため、先に説明する。FormControlが `<input>` にアクセスするために、VlueAccessorというクラスを経由している。無意識でフォーム実装しているうちは、基本的にValueAccessorはデフォルトのものが使われているが、一部Angular MaterialのDatePickerなんかはVlueAccessorを独自にProvideしていたりする。

このDirectiveは `<input>` のレイヤーでカスタマイズしたValueAccessorをProvideし、FormControlが `<input>` にアクセスする処理に介入する。

知っておくべきことは3つで、
- DefaultValueAccessorを継承して実装する
- View → Model方向の更新は `'change'`, `'blur'` イベントをトリガーに行い、superクラス (DefaultValueAccessor) の `onChange`, `onTouched` を利用する
- Model → View方向の更新はsuperクラスの `writeValue` をオーバーライドして定義する

興味があればコピーして `<input>` にセットしてみて欲しい。  
引数はフィルタリングしたい文字の配列を渡す。例えば、以下のように使う。

```typescript:typescript
removeCharacters = ['-', '^', ',', '.', '\\', '/', ' '];
```

```html:html
<input
  matInput
  placeholder="ユーザー名"
  id="name"
  name="name"
  formControlName="name"
  [appTrimValue]="removeCharacters"
/>
```

Directiveの実装

```typescript: TrimValueDirective
import {
  Directive,
  HostListener,
  forwardRef,
  Provider,
  Input,
} from '@angular/core';
import { DefaultValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

const TRIM_VALUE_ACCESSOR: Provider = {
  provide: NG_VALUE_ACCESSOR,
  useExisting: forwardRef(() => TrimValueDirective),
  multi: true,
};

/**
 * テキスト入力フォームの入力値をblur時にトリム・フィルタリングするためのDirective
 */
@Directive({
  selector: `[appTrimValue]`,
  providers: [TRIM_VALUE_ACCESSOR],
})
export class TrimValueDirective extends DefaultValueAccessor {
  private needEscapeCharacters = [
    '/', '\\', "'", '"', '.', '*', '+', '?', '^', '$', '-', '|', '(', ')', '{', '}', '{', '}',
  ];

  /** filterしたいパターンのリスト */
  private _filterPattern?: RegExp;
  @Input() set appTrimCustomValue(trimPattern: string[]) {
    this._filterPattern = new RegExp(
      `(${trimPattern.reduce((prev, curr) => {
        const escapedCurr = this.needEscapeCharacters.includes(curr)
          ? '\\' + curr
          : curr;
        return `${prev}|${escapedCurr}`;
      }, '')})+`,
      'g'
    );
  }

  @HostListener('input', ['$event.target.value'])
  ngOnChange = (val: string) => {
    let filteredVal = val;
    if (this._filterPattern) {
      filteredVal = filteredVal.replace(this._filterPattern, '');
    }
    this.onChange(filteredVal.trim());
  };

  @HostListener('blur', ['$event.target.value'])
  ngOnBlur = (val: string) => {
    let filteredVal = val;
    if (this._filterPattern) {
      filteredVal = filteredVal.replace(this._filterPattern, '');
    }
    this.writeValue(filteredVal.trim());
    this.onTouched();
  };

  writeValue(value: any): void {
    if (typeof value === 'string') {
      value = value.trim();
    }

    super.writeValue(value);
  }
}
```

上記Directive実装の参考：

https://github.com/khashayar/ng-trim-value-accessor/blob/master/src/trim-value-accessor.ts

# 送信済みフラグ

最後にフォームの送信済みフラグの実装について書く。Angularの[AbstractControl](https://angular.io/api/forms/AbstractControl)（FormGroup, FormControlの基底クラス）は `touched` （フォーカスされたかどうか）、`dirty`（編集されたかどうか）のフラグは持っているものの、フォームが送信されたかどうかのフラグを持っていない。しかし、フォームの実装上、エラーメッセージの表示条件などで初期値が `false` でフォームが送信されたときに `true` になるようなフラグが欲しい場合がある。このようなフラグはテンプレートの `<form>` タグにテンプレート変数を埋め込んで参照を持ち（`#ngForm="ngForm"`）、`ngForm.submitted` を見る方法が一般的なようである。個人的には `formGroup` に加えて `ngForm` を `<form>` に渡すのが参照関係を複雑化させているようで好きではなかったので、単純にComponentにboolean型のメンバー変数、例えば `isSubmitted` を定義して使うだけでもよいのではないかと思ってそうしている。その場合には、`isSubmitted` の `true` への書き換えは `(ngSubmit)` にバインドした送信のメソッドで行う。また、送信後にフォームが再編集されたら `isSubmitted` を `false` に更新したいといった要件にも対応することができる。この場合は、FormGroupが持つ `valueChanges` というObservableを購読し、そのsubscriber関数の中で `false` への更新を行う。

AngularのReactive Formsを使ったフォーム実装まとめ

# はじめに

TypeScriptで引数と返り値が配列となる関数に型付けする方法についてまとめる。この記事の内容は先日Qiitaに書いた以下の記事がベースになっているが、あちらは最終的な結果から逆算して必要最低限で書いたところがあった。なので、こちらではもう少し初歩の内容から始めて、色々書いていきたいと思う。

https://qiita.com/yokotani/items/2ce52e2f47dbd892c591

# TypeScriptで配列を引数に取り配列を返す関数を型定義する

## 配列の要素がプリミティブ型の場合

まず初歩の内容として、`string[]` 型の配列を引数に取り、そのまま `string[]` 型の配列を返すような関数を考える。この関数は以下のように型定義できる。

> 本記事では引数の配列を `beforeList`, 返り値の配列を `afterList` と名付け、関数の名前を `convert` としている。

```typescript
function convert(beforeList: string[]): string[];
```

これは配列の記法を知っていれば書けるのでなんてことはないと思う。では次に配列の要素が複数の型を取りうる場合について考える。

## 配列の要素を複数のプリミティブ型に対応させる場合

複数の型に対応することを考えると、自分がどういう型を定義したいのかもう少し詳細を詰める必要がある。例えば、「引数の配列の要素は `string` 型でも `number` 型でも良く、返り値の配列には引数と同じ型をつける」ということを考えたときに、以下の2つの場合が考えられる。

- 配列の要素に `string` 型と `number` 型が入り乱れている場合
- 配列の要素は `string` 型か `number` 型のどちらか一方である場合

### 配列の要素にstring型とnumber型が入り乱れている場合

これも初歩的な知識で書くことができる。

```typescript
function convert(beforeList: Array<string | number>): Array<string | number>;

const afterlist = convert([1, 'a', 2, 'b']); // afterList は Array<string | number> 型になる
```

Union型を使うことで、`string` 型もしくは `number` 型という要素の型を表現できる。

### 配列の要素はstring型かnumber型のどちらか一方である場合

この場合は先程の型定義でも問題ないが、より良いのはジェネリクスを使って型定義する方法である。この例は先程の例とは異なり関数の使用時に要素の型を `string` 型もしくは `number` 型のどちらかに絞り込むことができるはずである。よって型でもそれを表現したい。ジェネリクスを使うことで、「`string` 型の配列を受けて `string` 型の配列を返す関数」と「`number` 型の配列を受けて `number` 型の配列を返す関数」を1つの型定義で表現することができる。そして、`string` 型なのか `number` 型なのか、の絞り込みはその関数が使用されるときに引数の型から推論する。引数から型を推論するために、ここでは引数の型を型変数 `T` で受けることにする。

```typescript
function convert<T>(beforeList: T): T; // 返り値は引数と同じ T 型とする
```

上の例では、先程まで `string | number` で定義していた関数の引数を `T` という型変数で受けている。`T` が型変数であることを示すために、関数引数 `()` の前に `<T>` という宣言を追加している。引数の型を `T` という変数で受けたことで、返り値の型にその型情報を使うことができる。

これでこの `convert` という関数は引数にどんな型でも取ることができ、それはそのまま返り値の型となった。しかし、この例でやりたかったことは `string` 型の配列、もしくは `number` 型の配列を受け取り、返り値としてそれぞれ引数と同じ型の配列を返すことだった。「引数にどんな型でも取ることができる」というのでは型として緩い。そこで型引数 `T` に次のようにして制約を与える。

```typescript
function convert<T extends string[] | number[]>(beforeList: T): T;
```

これにより、先程宣言した型引数 `T` は `extends string[] | number[]` という制約を満たさなければならなくなった。この `extends` が意味するところは、`T` 型が `string[] | number[]` の部分型かどうか、言い換えると、`T` 型を `string[] | number[]` 型に代入できるかどうか、を引数の制約にするということである。いま、引数に想定しているのは `string[]` 型、もしくは `number[]` 型なので、これらは `string[] | number[]` の部分型という条件を満たしている。逆に、例えば `T` に `any` や `string` が入ると、それらは `string[] | number[]` の部分型ではないので、制約違反ということになり、型エラーになる。よって、これは狙い通りの制約である。

> React のような完成されたライブラリを使っている限りは、このレベルの型定義が必要になる場面はまず無いので、この辺りがTypeScript型パズルの最初のハードルになると思っている。自分がそうだったけれど、型定義自体を目的に勉強しているうちはなかなか身につかず、手段として必要になったときに意外とすっと習得できたりする。

## 配列の要素にstring型とnumber型が入り乱れている場合の発展

ここからは前に考えた `string` 型と `number` 型が入り乱れている場合の発展として、その個々の要素の型情報を維持したまま返り値に型をつける方法を考える。これを実現するためには、これまでの配列型ではなく、Tuple型を使う必要がある。Tuple型に起因する制限として、これから定義する関数はプログラム実行時に動的に生成した配列を引数に渡すことはできない。ただ、コーディング時に要素数が確定している配列に対してはそれをTuple型で定義することで引数に渡すことができる。

> TypeScriptのTuple型は配列型の特殊系で、要素数が固定されており、それぞれの要素の型が定義されたものと捉えることができる

このような型はVariadic Tuple TypesというTypeScriptの機能を使って以下のように書くことができる。

```typescript
function convert<T extends ReadonlyArray<string | number>>(beforeList: [...T]): [
    ...{ [K in keyof T]: T[K] extends string ? string : number}
];

const afterList = convert([1, 'a', 1]) // afterList は [number, string, number] 型になる
```

上では `convert` の引数の中で `[1, 'a', 1]` と書いているので、これがTuple型と判断されている。Variadic Tuple Typesのポイントは 引数を `[...T]` という型で受けることができている点である。つまり、引数は何かしらのTuple Tを展開したものであるとして、引数の要素全体を `T` で受ける。受けた後は `T` の各要素にインデックスアクセスすることができ、例のように `extends` で `stirng` の部分型かどうかを見て、返り値の型を出し分けることができる。

なお、引数のタプルを関数の外で定義する場合は以下のように書く。

```typescript
const beforeList: [number, string, number] = [1, 'a', 1];
const afterList = convert(beforeList);
```

## 配列の要素がジェネリック型の場合

上の例をもう少し応用して、あるジェネリック型のTupleを引数に取り、型変数を引き継いだまま別のジェネリック型のTupleを返す関数を型定義することができる。これについては最初にも貼った以下の記事で書いているので、結果だけ書くことにする。

https://qiita.com/yokotani/items/2ce52e2f47dbd892c591

```typescript
// サンプルとして Before<T> 型と After<T> 型を定義
type Before<T> = {
    type: 'before',
    value: T,
}

type After<T> = {
    type: 'after',
    value: T,
}

// convert の型定義 (関数本体の実装は省略)
function convert<T extends ReadonlyArray<Before<unknown>>>(beforeList: [...T]): [
    ...{ [K in keyof T]: T[K] extends Before<infer U> ? After<U> : never }
]

// テスト
const before1: Before<number> = {
    type: 'before',
    value: 1,
}

const before2: Before<string> = {
    type: 'before',
    value: 'string',
}

const afterList = convert([before1, before2]); // [After<number>, After<string>] 型になっている
```

Tuple型で定義できるもの、という制約はあるものの、JSライブラリの中にはオブジェクトの配列から別オブジェクトの配列を作る関数を提供しているものがあったりするので、そういう関数に型定義する場面ではこの方法は役に立つことがあると思う。

# Overview

In this article, I will show how to type a function whose arguments and return values are arrays by TypeScript. This content is based on the following article I wrote on Qiita the other day, but since that article was written with the minimum necessary content based on the final result, I'd like to start with some more elementary content and write about various things here.

https://qiita.com/yokotani/items/2ce52e2f47dbd892c591

# Type-defining a function that takes an array as an argument and returns an array in TypeScript

## When array elements are of primitive type

First of all, let's consider a function that takes an array of type `string[]` as an argument and returns an array of type `string[]`. This function can be typed as follows.

> In this article, the array of arguments is named `beforeList`, the array of return values is named `afterList`, and the name of the function is `convert`.

```typescript
function convert(beforeList: string[]): string[];
```

This can be written if you know array notation, so it should be no problem. Next, let's consider the case where the elements of an array can be of multiple types.

## When multiple primitives appear as elements of an array

Considering the support for multiple types, you need to work out a little more details about what type you want to define. For example, if you think "the elements of the array of arguments can be of type `string` or `number`", the following two cases are possible.

- When `string` and `number` types are mixed in array elements
- If you have an array whose elements are either `string` or `number`, but you want to support both cases with a single type definition

### When array elements of type string and number are mixed together

This can also be written with elementary knowledge.

```typescript
function convert(beforeList: Array<string | number>): Array<string | number>;

const afterlist = convert([1, 'a', 2, 'b']); // AfterList will be of type Array<string | number
```

Since we only use the Union type, the level of detail is the same as in the first example.

### If the elements of an array are of either string or number type, but you want to support both cases with a single type definition

In this case, the previous type definition is fine, but a better way is to use generics to define the type. The difference between the previous example and this one is that in this case, we want to narrow down the type of the element to either `string` or `number`, while the previous example leaves the ambiguity of choosing either `string` or `number` for the array element. To do this, we need to infer the type from the arguments. For this purpose, we will take the type of the argument as the type variable `T`.

```typescript
function convert<T>(beforeList: T): T; // The return value should be the same type as the argument, T.
```

In the above example, the argument of the function which was defined as `string | number` is received as a type variable `T`. To show that `T` is a type variable, the declaration `<T>` is added before the function argument `()`. Because the type of the argument is received in the variable `T`, the information can be used for the type of the return value.

Now the function `convert` can take any type as an argument, and it will be the type of the return value. However, what we initially wanted to do was to take an array of type `string` or `number` and return an array of the same type as the arguments. If the argument can be any type, it is too loose a type. So, to constrain the type argument `T`, we write it as follows.

```typescript
function convert<T extends string[] | number[]>(beforeList: T): T;
```

Now, the type argument `T` that we just declared must satisfy the constraint `extends string[] | number[]`. What this `extends` means is that the constraint of the argument is whether `T` is a subtype of `string[] | number[]`, in other words, whether `T` can be assigned to `string[] | number[]`. Now, we assume that the arguments are of type `string[]` or `number[]`, so they satisfy the condition that they are subtypes of `string[] | number[]`. On the other hand, if, for example, `T` contains `any` or `string`, they are not subtypes of `string[] | number[]`, so the constraint is violated and a type error occurs. Therefore, this is the constraint we are aiming for.

> As long as you're using a complete library like React, you're unlikely to need this level of type definition, so I think this will be the first hurdle for TypeScript type puzzles. As I did, it's hard to learn type definitions when you're studying them for their own sake, but when you need them as a means to an end, you can learn them surprisingly quickly.

## Development of the case where array elements of type string and number are mixed up

In this section, we will consider how to add a type to the return value while maintaining the type information of each element, as an extension of the case where the `string` and `number` types are mixed up. In order to achieve this, we need to use the Tuple type instead of the array type. Therefore, the function we are going to define cannot pass a dynamically generated array as an argument at program execution time. However, if the number of elements in the array is fixed at the time of coding, it can be passed as an argument by defining it with the Tuple type.

> The TypeScript tuple type can be thought of as an array type in which the number of elements is fixed and the type of each element is defined.

Such types can be written as follows using a TypeScript feature called Variadic Tuple Types.

```typescript
function convert<T extends ReadonlyArray<string | number>>(beforeList: [...T]): [
    ...{ [K in keyof T]: T[K] extends string ? string : number}
];

const afterList = convert([1, 'a', 1]) // afterList will be of type [number, string, number].
```

In the above, `[1, 'a', 1]` is written in the argument of `convert`, so it is judged to be a tuple type. The point of Variadic Tuple Types is that the argument can be received in the type `[...T]`. That is, the argument is assumed to be an expansion of some Tuple T, and the whole element of the argument is received in `T`. After receiving the argument, each element of `T` can be indexed, and the type of the return value can be determined by checking whether it is a subtype of `stirng` with `extends`, as shown in the example.

If you want to define the tuple of arguments outside the function, write as follows.

```typescript
const beforeList: [number, string, number] = [1, 'a', 1];
const afterList = convert(beforeList);
```

## When the array elements are of generic type

By applying the above example a little more, we can take a Tuple of a generic type as an argument and type it into a function that returns a Tuple of another generic type while keeping the type variable inherited. I have written about this in the following article, which I also posted at the beginning of this article, so I will just write the result.

https://qiita.com/yokotani/items/2ce52e2f47dbd892c591

```typescript
// Define the Before<T> and After<T> types as samples
type Before<T> = {
    type: 'before',
    value: T,
}

type After<T> = {
    type: 'after',
    value: T,
}

// Type definition of convert (implementation of the function body is omitted)
function convert<T extends ReadonlyArray<Before<unknown>>>(beforeList: [...T]): [
    ...{ [K in keyof T]: T[K] extends Before<infer U> ? After<U> : never }
]

// Test
const before1: Before<number> = {
    type: 'before',
    value: 1,
}

const before2: Before<string> = {
    type: 'before',
    value: 'string',
}

const afterList = convert([before1, before2]); // This is of type [After<number>, After<string>].
```

Although there are restrictions on what can be defined with the Tuple type, some JS libraries provide functions that create an array of other objects from an array of objects, so I think this method may be useful in situations where you need to define types for such functions.


Type-defining a function that takes an array as an argument and returns an array by TypeScript

TypeScriptで配列を引数に取り配列を返す関数を型定義する

前の記事で少し触れたように、Contentfulでは自分で設計した `Content` に対してTypeScriptの型を自動生成してAPIクライアントに型付けすることができる。この記事ではその方法と、それを利用してコンテンツを取得し、Next.jsでSSGするまでの流れについて書きたいと思う。

> 何の装飾もない[ミニマムなブログサンプルをGitHubに公開している](https://github.com/yukiyokotani/contentful-nextjs-blog-sample)のでよかったらそちらも参考にしてください。

# TypeScriptの型を生成する
## 必要なパッケージをインストールする
- `contentful`
- `contentful-management`
- `contentful-typescript-codegen`
- `@contentful/rich-text-types`

の4つのパッケージをインストールする。ここでは `npm` を利用する。

```
npm i contentful contentful-management contentful-typescript-codegen @contentful/rich-text-types
```

`package.json` に次のnpmスクリプトを定義する。
```
"contentful-typescript-codegen": "contentful-typescript-codegen --output @types/generated/contentful.d.ts"
```

## Management APIのtokenを取得する
Contentfulの `Setting` から `API Keys` を開く。`Content management tokens` のタブを選択し、`Generate personal token` から `token` を作成する。

コピーした `token` をフロントエンドプロジェクトの環境変数ファイルにペーストする。自分の場合、プロジェクトに [`dotenv`](https://www.npmjs.com/package/dotenv) をインストールした上で `.env` ファイルを作成し、以下のような形で用意した。

```env:.env
CONTENTFUL_SPACE_ID = ****
CONTENTFUL_ENVIRONMENT = ****
CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN = ****
```

`CONTENTFUL_SPACE_ID` と `CONTENTFUL_ENVIRONMENT` は、名前の通りContentfulのスペースIDと環境名である。これらもAPIのページから確認できる。

## TypeScriptの型生成
[`contentful-typescript-codegen` の `README` に倣い](https://github.com/intercom/contentful-typescript-codegen)、プロジェクトのルートに `getContentfulEnvironment.js` として以下のJSファイルを作成する。

```javascript:getContentfulEnvironment.js
require('dotenv').config();

const contentfulManagement = require('contentful-management');

module.exports = function () {
  const contentfulClient = contentfulManagement.createClient({
    accessToken: process.env.CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN,
  });

  return contentfulClient
    .getSpace(process.env.CONTENTFUL_SPACE_ID)
    .then((space) => space.getEnvironment(process.env.CONTENTFUL_ENVIRONMENT));
};
```

保存したら、`npm run contentful-typescript-codegen` を実行する。成功すれば `@types/generated` 下に `contentful.d.ts` として型定義ファイルが生成されている。

# APIクライアントを定義する
自分はプロジェクトに `utils` ディレクトリを作り、そこに `client.ts` として定義した。

```typescript:client.ts
import { createClient } from 'contentful';

// contentful の APIクライアント
const client = createClient({
  accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN || '',
  space: process.env.CONTENTFUL_SPACE_ID || '',
});

export default client;
```

上のAPIクライアントではいくつかの環境変数を参照している。Next.jsの場合、`.env.local` ファイルを作成し、以下のように用意しておけば良い。ここでも中身はContentfulのAPIページからtokenをコピペしておく。

```env:.env.local
CONTENTFUL_SPACE_ID = ****
CONTENTFUL_ENVIRONMENT = ****
CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN = ****
CONTENTFUL_DELIVERY_TOKEN = ****
CONTENTFUL_PREVIEW_TOKEN = ****
```

# Next.jsでSSGする
ここからの内容は自分がContentfulに用意したコンテツのフィールド名に依存している。ここではブログを作るという想定で、`Post` という `Content type` を定義したとして進める。なので、コンテンツタイプは `post` になっているし、TypeScriptの型は `Post` をベースとした名前で生成されている。

## 記事一覧の取得
SSGによってレンダリングする記事一覧ページのコンポーネントは以下のようになる。

```typescript:Home.tsx
interface Props {
  posts: EntryCollection<IPostFields>;
};

const Home: React.FC<Props> = ({ posts }) => (
  // 省略
)

export default Home;

// Next.js の SSG のためのコード
export const getStaticProps: GetStaticProps<Props> = async () => {
  const posts = await client
    .getEntries<IPostFields>({
      content_type: 'post',
    })
    .then((result) => {
      return result;
    });
  return {
    props: {
      posts,
    },
  };
};

```

一覧の取得はAPIクライアントで `getEntries()` というメソッドを利用する。引数にコンテンツタイプ（ここでは 'post'）を指定することで、目的の種類のコンテンツだけを取得することができる。

Contentfulが返すコンテンツは、自分が定義したコンテツが入る `fields` プロパティの他に、`sys` というプロパティで、投稿日やIDなどシステム側で設定された値を持っている。別コンテンツへリンクを作成する際にはこのIDを使用することになる。

エラーハンドリングができていないところがまだイマイチだけど、こんなイメージで使用できる。

## 1件の記事の取得
```typescript:Post.tsx
interface Props {
  post: Entry<IPostFields>;
}

const Post: React.FC<Props> = ({ post }) => (
  // 省略
)

export default Post;

interface Params extends ParsedUrlQuery {
  id: string;
}

export const getStaticPaths: GetStaticPaths = async () => {
  const posts = await client.getEntries<IPostFields>().then((result) => {
    return result;
  });
  const paths = posts.items.map((item) => `/blog/${item.sys.id}`);
  return { paths, fallback: false };
};

export const getStaticProps: GetStaticProps<Props, Params> = async (
  context
) => {
  const id = context.params?.id || '';
  const post = await client.getEntry<IPostFields>(id).then((result) => {
    return result;
  });
  return {
    props: {
      post,
    },
  };
};
```

ビルド時にページのパスを決定するための `getStaticPaths` と、Porpsを渡すための `getStaticProps` を定義している。こちらもエラーハンドリングができていなかったり、IDが `undefined` のときに空文字を充てているなど、まだまだイケてないところがある。

# さいごに
Contentfulは柔軟にコンテンツを構成できる一方で、APIから帰ってくるオブジェクトも複雑なネスト構造になりやすい。しかし、型があることでそんなネスト構造は知らなくとも、サジェストに従っていけば迷わず目的のコンテンツを参照することができる。コンテンツ構造を変えたときにも、型を自動生成すれば修正も楽である。JSONとにらめっこしながらオブジェクトに潜っていく必要はない。


Articles

React Hook Form, MUI, react-number-formatを組み合わせた汎用入力部品を作る

AngularのReactive Formsを使ったフォーム実装まとめ

TypeScriptで配列を引数に取り配列を返す関数を型定義する

Contentfulで型安全にコンテンツを取得する