X(Twitter)での共有Blueskyでの共有はてなブックマークでの共有

d.ts ファイルを単一ファイルにするモチベーション

TypeScript の issue には、d.ts ファイルを single にする propsal が上がっているが、5 年たった今でも機能実現に至っておらず、これを実現しようとするツールが独自に発展している。

なんで単一ファイルにまとめたいんだっけ？ってなったので、メモとして残しておく。
検証 repo はこちら
tyankatsu0105/sandbox-rollup-dts

メリット

ts ファイルのフラットな形に倣うことができる

ts ファイルを単一のファイルに変換するツールに倣って、d.ts ファイルも単一にして、統一性をもたらすことができる。
例えばこう。

.
└── dist
    ├── index.d.ts
    ├── index.es.js #ejs
    └── index.js # commonjs

ファイルサイズの削減

d.ts ファイルを一つにまとめるのと、ディレクトリ構造を保ったまま出力するのとではファイルサイズが変わってくるので、配信する際のスピード向上につながる。

.
├── api-extractor
│   └── dist
│       ├── api-extractor.d.ts # 5,667 バイト
│       ├── index.es.js
│       ├── index.js
│       └── tsdoc-metadata.json
├── rollup
│   └── dist
│       ├── index.es.js
│       ├── index.js
│       └── src # 7,882 バイト
│           ├── index.d.ts
│           ├── libs
│           │   ├── fn1.d.ts
│           │   ├── fn10.d.ts
│           │   ├── fn100.d.ts
│           │   ├── fn11.d.ts
│           │   ├── fn12.d.ts
│           │   ├── fn13.d.ts
│           │   ├── fn14.d.ts
│           │   ├── fn15.d.ts
│           │   ├── fn16.d.ts
│           │   ├── fn17.d.ts
│           │   ├── fn18.d.ts
│           │   ├── fn19.d.ts
│           │   ├── fn2.d.ts
│           │   ├── fn20.d.ts
│           │   ├── fn21.d.ts
│           │   ├── fn22.d.ts
│           │   ├── fn23.d.ts
│           │   ├── fn24.d.ts
│           │   ├── fn25.d.ts
│           │   ├── fn26.d.ts
│           │   ├── fn27.d.ts
│           │   ├── fn28.d.ts
│           │   ├── fn29.d.ts
│           │   ├── fn3.d.ts
│           │   ├── fn30.d.ts
│           │   ├── fn31.d.ts
│           │   ├── fn32.d.ts
│           │   ├── fn33.d.ts
│           │   ├── fn34.d.ts
│           │   ├── fn35.d.ts
│           │   ├── fn36.d.ts
│           │   ├── fn37.d.ts
│           │   ├── fn38.d.ts
│           │   ├── fn39.d.ts
│           │   ├── fn4.d.ts
│           │   ├── fn40.d.ts
│           │   ├── fn41.d.ts
│           │   ├── fn42.d.ts
│           │   ├── fn43.d.ts
│           │   ├── fn44.d.ts
│           │   ├── fn45.d.ts
│           │   ├── fn46.d.ts
│           │   ├── fn47.d.ts
│           │   ├── fn48.d.ts
│           │   ├── fn49.d.ts
│           │   ├── fn5.d.ts
│           │   ├── fn50.d.ts
│           │   ├── fn51.d.ts
│           │   ├── fn52.d.ts
│           │   ├── fn53.d.ts
│           │   ├── fn54.d.ts
│           │   ├── fn55.d.ts
│           │   ├── fn56.d.ts
│           │   ├── fn57.d.ts
│           │   ├── fn58.d.ts
│           │   ├── fn59.d.ts
│           │   ├── fn6.d.ts
│           │   ├── fn60.d.ts
│           │   ├── fn61.d.ts
│           │   ├── fn62.d.ts
│           │   ├── fn63.d.ts
│           │   ├── fn64.d.ts
│           │   ├── fn65.d.ts
│           │   ├── fn66.d.ts
│           │   ├── fn67.d.ts
│           │   ├── fn68.d.ts
│           │   ├── fn69.d.ts
│           │   ├── fn7.d.ts
│           │   ├── fn70.d.ts
│           │   ├── fn71.d.ts
│           │   ├── fn72.d.ts
│           │   ├── fn73.d.ts
│           │   ├── fn74.d.ts
│           │   ├── fn75.d.ts
│           │   ├── fn76.d.ts
│           │   ├── fn77.d.ts
│           │   ├── fn78.d.ts
│           │   ├── fn79.d.ts
│           │   ├── fn8.d.ts
│           │   ├── fn80.d.ts
│           │   ├── fn81.d.ts
│           │   ├── fn82.d.ts
│           │   ├── fn83.d.ts
│           │   ├── fn84.d.ts
│           │   ├── fn85.d.ts
│           │   ├── fn86.d.ts
│           │   ├── fn87.d.ts
│           │   ├── fn88.d.ts
│           │   ├── fn89.d.ts
│           │   ├── fn9.d.ts
│           │   ├── fn90.d.ts
│           │   ├── fn91.d.ts
│           │   ├── fn92.d.ts
│           │   ├── fn93.d.ts
│           │   ├── fn94.d.ts
│           │   ├── fn95.d.ts
│           │   ├── fn96.d.ts
│           │   ├── fn97.d.ts
│           │   ├── fn98.d.ts
│           │   ├── fn99.d.ts
│           │   ├── index.d.ts
│           │   └── user.d.ts
│           └── shared
│               ├── const.d.ts
│               ├── helpers
│               │   ├── const.d.ts
│               │   └── index.d.ts
│               └── index.d.ts
└── rollup-plugin-dts
    └── dist
        ├── index.d.ts # 5,326 バイト
        ├── index.es.js
        └── index.js

デメリット

元ファイルのディレクトリ構造が不明になる

実装ファイルが圧縮されていたり、トランスパイルされたあとで元の実装の確認が困難な場合、型定義ファイルのディレクトリを参考にしながら、GitHub の repo などを確認することが困難になる。
型定義ファイルを読み物とする場合、単一ファイルにすることはそぐわない。

一つのファイルサイズが膨れる

すべての型定義をひとつにまとめるので、一つのファイルサイズが膨れる。そうすると型定義ファイルのプレビューに時間がかかる。

結論

ライブラリ配信者としてはファイルサイズ削減するのはいいことだし、コンパイル後はすべてのファイルがフラットになることできれいな dist 構造を保つことができる。
しかし一つのファイルにすることは型定義を読みづらくするとは思う。
ただ、これは慣れの問題かなと思うので、api-extractor まずは入れるでもいいかもしれない。