TypeScript Handbook を読む (15. Namespaces and Modules)

[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 (今ココ)
1. [Module Resolution](http://qiita.com/murank/items/5f11466474d49498bbd5)
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)


# Namespaces and Modules
[原文](https://www.typescriptlang.org/docs/handbook/namespaces-and-modules.html)

## Using Namespaces
名前空間は単なる名前付きオブジェクトであり、複数ファイルにまたがる名前空間を `--outFile` で連結することが可能です。
名前空間は Web アプリーションを構築する際に `<script>` を使用して依存ファイルを読み込む場合に使用すると良いでしょう。

ただし、特に大規模なアプリケーションにおいて、コンポーネント間の依存関係を識別することは難しくなります。


## Using Modules
モジュールは名前空間と同じように実装と宣言を含んでいますが、モジュールはそれ自身の依存関係を *宣言* している点が異なります。

このことは小規模なアプリケーションでは必ずしも最適とは限りませんが、アプリケーションが大規模であれば、長期間にわたるモジュール性やメンテナンス性において、充分コストに見合った利益が得られます。

モジュールは ECMAScript 2015 から言語規格にも組み込まれており、新しいプロジェクトではコードを体系化するための手法として推奨します。


## Pitfalls of Namespaces and Modules
### `/// <reference>`-ing a module
よくある間違いのひとつとして、モジュールファイルを参照するために `import` 構文ではなく、`/// <reference ... />` を使用してしまうことが挙げられます。

なぜこれが間違いなのか理解するために、まずコンパイラがどのようにインポートパス (例: `import x from "...";` や `import x = require("...");` の `...` 部分) に基づいてモジュールの型情報を読み込むか見てみましょう。

コンパイラは指定されたパスに対し、`.ts`、`.tsx` ファイルが存在するか確認した上で、適切なパスに `.d.ts` ファイルが存在するか確認します。
もしも該当するファイルが存在しなかった場合、*アンビエントモジュール宣言* が検索されます。

```ts:myModules.d.ts
// .d.ts ファイル、またはモジュールではない .ts ファイルでの宣言
declare module "SomeModule" {
    export function fn(): string;
}
```
```ts:myOtherModule.ts
/// <reference path="myModules.d.ts" />
import * as m from "SomeModule";
```

参照タグを使用することで、アンビエントモジュールを宣言しているファイルを指定することが可能です。
>`SomeModule.ts`、`SomeModule.d.ts` を探しに行ってしまうため、参照タグで正しいパスを指定してるということかな?

### Needless Namespacing
名前空間からモジュールを使用するようにプログラムを変更する場合、次のようなコードを書いてしまうかもしれません。

```ts:shapes.ts
export namespace Shapes {
    export class Triangle { /* ... */ }
    export class Square { /* ... */ }
}
```
`Shapes` で `Triangle`、`Square` をラップしていますが、これは何の意味もない上に、利用者の混乱を招いてしまいます。

```ts:shapeConsumer.ts
import * as shapes from "./shapes";
let t = new shapes.Shapes.Triangle(); // shapes.Shapes だって?
```

モジュールの利用者は読み込んだモジュールの名前を指定することが可能なため、エクスポートするシンボルをわざわざ名前空間でラップする必要はありません。

モジュールにおいて名前空間を使用するべきでない理由を繰り返すと、名前空間は名前の衝突を避けるために用いられるものですが、そもそもモジュールはインポート時に名前を指定するため、さらにレイヤーを増やす必要性はまったくないということです。

それを踏まえた正しいコードは以下のとおりです。

```ts:shapes.ts
export class Triangle { /* ... */ }
export class Square { /* ... */ }
```
```ts:shapeConsumer.ts
import * as shapes from "./shapes";
let t = new shapes.Triangle();
```

### Trade-offs of Modules
JS ファイルとモジュールに 1 対 1 の関係があるように、TypeScript でもモジュールファイルと出力される JS ファイルに 1 対 1 の関係があります。
つまり、使用するモジュールローダーによっては、複数のモジュールファイルを連結できないということです。
例えば、`commonjs` や `umd` を使用する場合には `outFile` オプションを使用することはできませんが、TypeScript 1.8 以降であれば `amd` や `system` を使用することで `outFile` オプションを使用できます。
>まあ実際には [webpack](https://webpack.js.org/) とかで連結するからいいんですけどね