TypeScript Handbook を読む (16. Module Resolution)

[TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/basic-types.html) を読み進めていく第十六回目。

1. [Basic Types](http://qiita.com/murank/items/9c1f633545842c953947)
1. [Variable Declarations](http://qiita.com/murank/items/913f1c1e4e725047436c)
1. [Interfaces](http://qiita.com/murank/items/553276c3dc2eec9bfe47)
1. [Classes](http://qiita.com/murank/items/7e8f15225bc8259e9bf3)
1. [Functions](http://qiita.com/murank/items/e310ce68ed5a0058d42d)
1. [Generics](http://qiita.com/murank/items/144b686d34fd433a97a3)
1. [Enums](http://qiita.com/murank/items/cc487562b21bae3728ba)
1. [Type Inference](http://qiita.com/murank/items/e67ad7426020321228e9)
1. [Type Compatibility](http://qiita.com/murank/items/e06efb0615294a6826e3)
1. [Advanced Types](http://qiita.com/murank/items/bc1776efbecbd2120d94)
1. [Symbols](http://qiita.com/murank/items/04b3b31caa677750f240)
1. [Iterators and Generators](http://qiita.com/murank/items/7ceec53dde886f31a682)
1. [Modules](http://qiita.com/murank/items/0fc4e059be8ea5e1c274)
1. [Namwspaces](http://qiita.com/murank/items/0dfad4a0bb91aaa6c97b)
1. [Namespaces and Modules](http://qiita.com/murank/items/0be1978a3515fc76e7ba)
1. Module Resolution (今ココ)
1. [Declaration Merging](http://qiita.com/murank/items/ec90ba04edab1ea3718e)
1. [JSX](http://qiita.com/murank/items/90164aa9a3bed3c49a80)
1. [Decorators](https://qiita.com/murank/items/580e34883e0832ca7aed)
1. [Mixins](https://qiita.com/murank/items/e77ad8359ed1fd82822d)
1. [Triple-Slash Directives](https://qiita.com/murank/items/faff57883338ebdeda12)
1. [Type Checking JavaScript Files](https://qiita.com/murank/items/588eaddfe8af59914658)


# Module Resolution
[原文](https://www.typescriptlang.org/docs/handbook/module-resolution.html)

*モジュールの解決* はコンパイラがインポート対象を見つけ出すためのプロセスです。
例えば `import { a } from "moduleA"` というインポート文があった場合に、`a` を使用するためには `moduleA` の定義を参照し、それが何であるか調べる必要があります。

コンパイラは [Classic](#classic) 方式と [Node](#node) 方式の 2 通りの方法でインポートされたモジュールの場所を検索します。
もし検索に失敗し、かつ、モジュール名が相対パスでない ("moduleA" といった表記である) 場合には、[アンビエントモジュール宣言](http://qiita.com/murank/items/0fc4e059be8ea5e1c274#ambient-modules) の検索を試みます。
それでもモジュールを解決できなかった場合、`error TS2307: Cannot find module 'moduleA'` といったエラーが出力されます。


## Relative vs. Non-relative module imports
モジュールの参照先が相対パスかどうかに応じて、異なる方法でモジュールの解決が行われます。

*相対インポート* とは、以下のように `/`、`./`、`../`のいずれかから始まるものを指します。

- `import Entry from "./components/Entry";`
- `import { DefaultHeaders } from "../constants/http";`
- `import "/mod";`

以下のような、それ以外のインポート文は **非相対インポート** として扱われます。

- `import * as $ from "jquery";`
- `import { Component } from "@angular/core";`

相対インポートはインポート対象ファイルのパスを相対的に解決しようとするため、アンビエントモジュール宣言は検索 *されません*。
そのため、ファイルの場所を自分で管理できる自作モジュールに対して使用するべきです。

非相対インポートは `baseUrl` からの相対パスが用いられる他、[アンビエントモジュール宣言](http://qiita.com/murank/items/0fc4e059be8ea5e1c274#ambient-modules) も検索対象となります。
そのため、非相対インポートは外部ライブラリをインポートする時に使用してください。


## Module Resolution Strategies
モジュールの解決方法には [Node](#node) 方式と [Classic](#classic) 方式の 2 通りの方法が存在します。
どちらを使用するかは `--moduleResolution` フラグを使用することで指定可能です。
何も指定しなかった場合、`--module AMD | System | ES2015` の場合は [Classic](#classic) 方式が、それ以外の場合は [Node](#node) 方式が採用されます。
>`--module` のデフォルトは `target === "ES6" ? "ES6" : "CommonJS"` で、`--target` のデフォルトは `"ES3"` なので、何も考えなければ Node 方式が採用される

### Classic
これは後方互換性のために残されている方式です。

この方式では、相対インポートはインポート元のファイルからの相対パスを検索します。
つまり、`/root/src/folder/A.ts` で `import { b } from "./moduleB"` と記述した場合、以下のファイルが検索対象となります。

1. `/root/src/folder/moduleB.ts`
2. `/root/src/folder/moduleB.d.ts`

非相対インポートの場合、ソースファイルを含むディレクトリからディレクトリツリーを遡ってインポート対象のファイルを検索します。
例えば ` /root/src/folder/A.ts` で `import { b } from "moduleB"` と記述した場合、以下のファイルが検索対象となります。

1. `/root/src/folder/moduleB.ts`
2. `/root/src/folder/moduleB.d.ts`
3. `/root/src/moduleB.ts`
4. `/root/src/moduleB.d.ts`
5. `/root/moduleB.ts`
6. `/root/moduleB.d.ts`
7. `/moduleB.ts`
8. `/moduleB.d.ts`

### Node
この方式は [Node.js](https://nodejs.org/) のモジュール解決方式を模倣したものであり、アルゴリズム全体の説明は [Node.js のドキュメント](https://nodejs.org/api/modules.html#modules_all_together) に記載されています。

#### How Node.js resolves modules
伝統的に、Node.js でのインポートは `require` 関数を呼び出すことで行われます。
この時、`require` に相対パスと非相対パスのどちらを指定するかによって Node.js の振る舞いが変わります。

相対パスを指定した場合は単純明快で、例えば `/root/src/moduleA.js` で `var x = require("./moduleB");` とした場合、Node.js は次の順番でモジュールの解決を試みます。

1. `/root/src/moduleB.js`
2. `/root/src/moduleB/package.json` の `"main"` モジュールに指定されたパス  
   (例: `{ "main": "lib/mainModule.js" }` の場合、`/root/src/moduleB/lib/mainModule.js`)
3. `/root/src/moduleB/index.js`

より詳しい情報は Node.js の [ファイルモジュール](https://nodejs.org/api/modules.html#modules_file_modules) と [フォルダモジュール](https://nodejs.org/api/modules.html#modules_folders_as_modules) のドキュメントを参照してください。

[非相対パス](#relative-vs-non-relative-module-imports) を指定した場合、モジュール解決時に `node_modules` フォルダを検索するようになります。
`node_modules` フォルダはソースファイルと同じ階層か、より上位のフォルダに配置することができ、Node はそれらのフォルダを対象のモジュールが見つかるまで下から順番に検索していきます。

例えば `/root/src/moduleA.js` で `var x = require("moduleB");` とした場合、`moduleB` は以下の順で検索されます。

1. `/root/src/node_modules/moduleB.js`
2. `/root/src/node_modules/moduleB/package.json` (`"main"` プロパティが指定されている場合)
3. `/root/src/node_modules/moduleB/index.js`
4. `/root/node_modules/moduleB.js`
5. `/root/node_modules/moduleB/package.json` (`"main"` プロパティが指定されている場合)
6. `/root/node_modules/moduleB/index.js`
7. `/node_modules/moduleB.js`
8. `/node_modules/moduleB/package.json` (`"main"` プロパティが指定されている場合)
9. `/node_modules/moduleB/index.js`


より詳しい情報は Node.js のドキュメントの [`node_modules` からのモジュール読み込み](https://nodejs.org/api/modules.html#modules_loading_from_node_modules_folders) を参照してください。

#### How TypeScript resolves modules
TypeScript はコンパイル時に定義ファイルの場所を解決するために Node.js のモジュール解決方式を模倣しており、違いは拡張子が `.ts`、`.tsx`、`.d.ts` のソースファイルも検索対象とする点です。
また、`package.json` について、`"main"` プロパティと同じ用途で `"types"` プロパティを使用します。

例えば、`/root/src/moduleA.ts` で `import { b } from "./moduleB"` とした場合、`"./moduleB" は以下の場所から検索されます。

1. `/root/src/moduleB.ts`
2. `/root/src/moduleB.tsx`
3. `/root/src/moduleB.d.ts`
4. `/root/src/moduleB/package.json`(`"types"` プロパティが指定されている場合)
5. `/root/src/moduleB/index.ts`
6. `/root/src/moduleB/index.tsx`
7. `/root/src/moduleB/index.d.ts`

非相対パスの解決は Node.js と似ています。
`/root/src/moduleA.ts` で `import { b } from "moduleB"` とした場合、以下の順で検索が行われます。

1. `/root/src/node_modules/moduleB.ts`
2. `/root/src/node_modules/moduleB.tsx`
3. `/root/src/node_modules/moduleB.d.ts`
4. `/root/src/node_modules/moduleB/package.json` (`"types"` プロパティが指定されている場合)
5. `/root/src/node_modules/moduleB/index.ts`
6. `/root/src/node_modules/moduleB/index.tsx`
7. `/root/src/node_modules/moduleB/index.d.ts`
8. `/root/node_modules/moduleB.ts`
9. `/root/node_modules/moduleB.tsx`
10. `/root/node_modules/moduleB.d.ts`
11. `/root/node_modules/moduleB/package.json` (`"types"` プロパティが指定されている場合)
12. `/root/node_modules/moduleB/index.ts`
13. `/root/node_modules/moduleB/index.tsx`
14. `/root/node_modules/moduleB/index.d.ts`
15. `/node_modules/moduleB.ts`
16. `/node_modules/moduleB.tsx`
17. `/node_modules/moduleB.d.ts`
18. `/node_modules/moduleB/package.json` (`"types"` プロパティが指定されている場合)
19. `/node_modules/moduleB/index.ts`
20. `/node_modules/moduleB/index.tsx`
21. `/node_modules/moduleB/index.d.ts`

ステップが多いように見えますが、実際にはステップ (8) と (15) の 2 回しかディレクトリを遡っておらず、Node.js と比べても特に複雑というわけではありません。
>実際には、ディレクトリごとに `モジュール名と同じファイル名のファイル` → `pakage.json` → `index.*` の順で定義ファイルを検索してるだけ


### Additional module resolution flags
出力ファイルのディレクトリ構成は必ずしもソースファイルのディレクトリ構成と同じとは限りません。
例えば、`.ts` ファイルを `.js` にコンパイルした後に依存ファイルとまとめて一つの場所に出力することもあるでしょう。
その場合、モジュールはソースファイルとは別の名前になる他、モジュールの場所もソースファイルのあった場所とは別の場所になるでしょう。

TypeScript コンパイラには最終出力ファイルを生成する際に使用する情報を渡すためのフラグが用意されています。

ただし、これらのフラグはソースファイルの変換には影響 *しない* ことに注意してください。
あくまでもモジュール定義ファイルの場所を解決するための参考情報として使用されるだけです。

#### Base URL
`baseUrl` は AMD モジュールローダーを使用し、各モジュールを同じフォルダに "デプロイ" する場合によく使用されます。
その場合、ソースファイルが異なる場所にあってもコンパイル結果のファイルは同じフォルダへ出力されます。

`baseUrl` を指定すると、非相対パスで指定されたインポートはすべて `baseUrl` からの相対パスとして扱われます。

*baseUrl* の値は以下のいずれかの方法で指定可能です。

- *baseUrl* コマンドライン引数  
  (相対パスが指定された場合、カレントディレクトリからの相対パスとみなされます)
- 'tsconfig.json' の *baseUrl* プロパティ  
  (相対パスが指定された場合、'tsconfig.json' の場所からの相対パスとみなされます)

相対パスでのインポートは baseUrl の設定の影響を受けません。
相対パスでのインポートは常にインポート元のファイルからの相対パスとなります。

より詳しくは [RequireJS](http://requirejs.org/docs/api.html#config-baseUrl) や [SystemJS](https://github.com/systemjs/systemjs/blob/master/docs/config-api.md#baseurl) のドキュメントを参照してください。


#### Path mapping
場合によってはモジュールが *baseUrl* 配下に直接配置されているとは限らないこともあるでしょう。
例えば `"jquery"` モジュールが `"node_modules/jquery/dist/jquery.slim.min.js"` に配置されているような場合です。
この場合、モジュールローダーはモジュール名とファイルの場所とのマッピング情報を使用します。
詳しくは [RequireJS](http://requirejs.org/docs/api.html#config-paths) や [SystemJS](https://github.com/systemjs/systemjs/blob/master/docs/config-api.md#paths) の情報を参照してください。

TypeScript では `tsconfig.json ` の `"paths"` プロパティを使用してこのマッピング情報を定義することが可能です。
先ほどの `jquery` の例であれば、以下のように記述します。

```js:tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".", // "paths" を指定する場合、必須
    "paths": {
      "jquery": ["node_modules/jquery/dist/jquery"] // これは "baseUrl" からの相対パス
    }
  }
}
```
`"paths"` は `"baseUrl"` からの相対パスとして扱われることに注意してください。
上記の例で `"baseUrl": "./src"` とした場合、jquery は `"../node_modules/jquery/dist/jquery"` にマッピングされます。
>おそらく `./src/node_modules/jquery/dist/jquery"` の間違い

`"paths"` には複数のフォールバックを指定することも可能です。
例えば、以下のようにあるモジュールだけが特定のディレクトリに配置されており、それ以外が別のディレクトリに配置されているような場合を考えてみましょう。

```
projectRoot
├── folder1
│   ├── file1.ts ('folder1/file2' と 'folder2/file3' をインポートしている)
│   └── file2.ts
├── generated
│   ├── folder1
│   └── folder2
│       └── file3.ts
└── tsconfig.json
```

この場合、`tsconfig.json` は以下のようになります。

```js:tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "*": [
        "*",
        "generated/*"
      ]
    }
  }
}
```

これにより、コンパイラは `"*"` に一致するモジュール (つまり全モジュール) を次の 2 箇所からインポートするようになります。

- `"*"`: モジュール名をそのまま使用する  
  `<moduleName>` => `<baseUrl>/<moduleName>`
- `"generated/*"`: モジュール名の前に "generated" を付与する  
  `<moduleName>` => `<baseUrl>/generated/<moduleName>`

そのため、'folder1/file2' と 'folder2/file3' のインポートはそれぞれ以下のように解決されます。

- 'folder1/file2'
  1. パターン '*' に一致する
  2. 最初のマッピングにモジュール名を代入する: '*' -> `folder1/file2`
  3. 代入結果が非相対パスのため、*baseUrl* を付与する: `projectRoot/folder1/file2.ts`
  4. ファイルが存在するため、ここで終了
 
- 'folder2/file3'
  1. パターン '*' に一致する
  2. 最初のマッピングにモジュール名を代入する: '*' -> `folder2/file3`
  3. 代入結果が非相対パスのため、*baseUrl* を付与する: `projectRoot/folder2/file3`
  4. ファイルが存在しないため、次のマッピングに移る
  5. 2 番目のマッピングにモジュール名を代入する: 'generated/*' -> `generated/folder2/file3`
  6. 代入結果が非相対パスのため、*baseUrl* を付与する: `projectRoot/generated/folder2/file3.ts`
  7. ファイルが存在するため、ここで終了


#### Virtual Directories with `rootDirs`
複数のディレクトリのソースファイルをひとつのディレクトリにまとめて出力することもあるでしょう。
これは複数のソースファイルのディレクトリを "仮想" ディレクトリのように見せかけることで実現しています。

'rootDirs' プロパティを使用し、コンパイラに "仮想" ディレクトリの *起点* を伝えます。
こうすることでコンパイラは相対パスで指定されたモジュールを "仮想" ディレクトリからの相対パスとして解決するようになります。

例として以下の構成のプロジェクトを見てみましょう。

```
 src
 └── views
     └── view1.ts ('./template1' をインポートしている)
     └── view2.ts

 generated
 └── templates
         └── views
             └── template1.ts ('./view2' をインポートしている)
```

`src/views` 内のファイルは UI コントロールに関するユーザコードであり、`generated/templates` 内のファイルはビルド時にテンプレートジェネレータにて自動生成される UI バインディング用のコードです。
また、ビルド時には `/src/views` と `/generated/templates/views` にあるファイルを同じ出力フォルダへコピーします。
そして、実行時にはビューとテンプレートが同じフォルダにあるものとしてインポートするため、この時の相対パスには `"./template"` を指定します。
>上記の例の話なら `"./template1"` じゃなかろうか

これらの関係性をコンパイラに伝えるには `"rootDirs"` を使用します。
`"rootDirs"` は実行時に同じフォルダにあるものとして扱う *ルートフォルダ* のリストを指定します。
上記の例の場合、`tsconfig.json` は以下のようになります。

```json:tsconfig.json
{
  "compilerOptions": {
    "rootDirs": [
      "src/views",
      "generated/templates/views"
    ]
  }
}
```
こうすることで、相対パスでモジュールをインポートした場合に `rootDirs` に指定した各フォルダ配下も検索対象となります。

`rootDirs` は非常に柔軟であり、ディレクトリの有無によらず、任意の数/名前のディレクトリを指定することが可能です。
これにより、条件付きインクルードやプロジェクト固有のローダープラグインといった、より高度なビルド方法や実行時機能を使用できるようになります。

ここでプログラムの国際化の例を考えてみましょう。
ビルドツールはロケール固有のコードを特殊なトークン (ここでは `#{locale}`) を含むパスに自動生成するものとします。
つまり、この時のモジュールの相対パスは `./#{locale}/messages` のようになります。
このツールを使用したとすると、対応しているロケールに従って `./zh/messages`、`./de/messages` といったモジュールが生成されます。

この時に生成されるモジュールは文字列の配列をエクスポートしているものとします。
例えば、`./zh/messages` であれば以下のような内容が出力されるとします。

```ts:./zh/messages.ts
export default [
    "您好吗",
    "很高兴认识你"
];
```

`rootDirs` を使用することで、(実際にはそのようなパスが存在しないにも関わらず) `./#{locale}/messages` を安全に解決することが可能です。
この時の `tsconfig.json` は以下のようになります。

```ts:tsconfig.json
{
  "compilerOptions": {
    "rootDirs": [
      "src/zh",
      "src/de",
      "src/#{locale}"
    ]
  }
}
```

こうすることで `import messages from './#{locale}/messages'` は `import messages from './zh/messages'` として解決されるため、ロケールを意識することなく開発を行うことができるようになります。
>`import messages from './messages'` としないと `src/zh/#{locale}/messages` を見に行ってしまうんではなかろうか


### Tracing module resolution
ここまで述べてきたように、モジュールを解決する際にカレントフォルダ以外のファイルも参照されるため、モジュールの解決に失敗した時の調査は難しくなるでしょう。
そのため、モジュール解決時の動作を出力するためのオプションとして `--traceResolution` が提供されています。

例として `typescript` モジュールを使用しているアプリケーションを見てみましょう。
ここで、`app.ts` は `import * as ts from "typescript"` と宣言しているものとします。

```
│   tsconfig.json
├───node_modules
│   └───typescript
│       └───lib
│               typescript.d.ts
└───src
        app.ts
```

`--traceResolution` オプションを指定してコンパイルを実行します。

```bash:コマンド
tsc --traceResolution
```

この時の出力結果は以下のようになります。

```
======== Resolving module 'typescript' from 'src/app.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module 'typescript' from 'node_modules' folder.
File 'src/node_modules/typescript.ts' does not exist.
File 'src/node_modules/typescript.tsx' does not exist.
File 'src/node_modules/typescript.d.ts' does not exist.
File 'src/node_modules/typescript/package.json' does not exist.
File 'node_modules/typescript.ts' does not exist.
File 'node_modules/typescript.tsx' does not exist.
File 'node_modules/typescript.d.ts' does not exist.
Found 'package.json' at 'node_modules/typescript/package.json'.
'package.json' has 'types' field './lib/typescript.d.ts' that references 'node_modules/typescript/lib/typescript.d.ts'.
File 'node_modules/typescript/lib/typescript.d.ts' exist - use it as a module resolution result.
======== Module name 'typescript' was successfully resolved to 'node_modules/typescript/lib/typescript.d.ts'. ========
```

#### Things to look out for

- インポートしているモジュールの名前と場所  
  ======== Resolving module **‘typescript’** from **‘src/app.ts’**. ========
- モジュール解決方式  
  Module resolution kind is not specified, using **‘NodeJs’**.
- npm パッケージからの types の読み込み  
  ‘package.json’ has **‘types’** field ‘./lib/typescript.d.ts’ that references ‘node_modules/typescript/lib/typescript.d.ts’.
- 最終結果  
  ======== Module name ‘typescript’ was **successfully resolved** to ‘node_modules/typescript/lib/typescript.d.ts’. ========


### Using `--noResolve`
デフォルトではコンパイル処理の開始前にすべてのモジュールの解決が行われます。
ここでモジュールの解決に成功したファイルがコンパイル対象として扱われます。

`--noResolve` オプションを指定することで、コマンドラインで指定されていないファイルをモジュール解決の対象に含めないようにすることができます。

例を見てみましょう。

```ts:app.ts
import * as A from "moduleA" // OK、 'moduleA' はコマンドラインで指定されている
import * as B from "moduleB" // Error TS2307: Cannot find module 'moduleB'.
```
```bash:コマンド
tsc app.ts moduleA.ts --noResolve
```
>イマイチ使いドコロが分からない。
>余分なファイルをコンパイルさせないことで、ビルド時間を短縮するとかかな?


### Common Questions
#### Why does a module in the exclude list still get picked up by the compiler?

`tsconfig.json` はフォルダを "プロジェクト" に変えます。
つまり、“exclude” や “files” を指定しなかった場合、`tsconfig.json` を含むフォルダは、そのサブフォルダも含めてすべてコンパイル対象となります。
そのため、もしも特定のファイルを除外したい場合は `“exclude”` を使用してください。
逆にコンパイル対象のファイルを指定したい場合は `"files"` を使用してください。

これは `tsconfig.json` の自動インクルード機構によるもので、これまでに述べてきたモジュール解決には影響しません。
そのため、コンパイラがインポート対象とみなしたファイルは `tsconfig.json` の設定によらず、コンパイル対象に含まれることになります。

コンパイル対象から除外するためには、そのファイル自身と、そのファイルを `import` や `/// <reference path="..." />` ディレクティブでインポートしている **すべての** ファイルを除外する必要があります。