Jak utworzyć plik definicji „typowania” .d.ts z istniejącej biblioteki JavaScript?

Korzystam z wielu bibliotek, zarówno własnych, jak i zewnętrznych. Widzę, że katalog „typings” zawiera trochę Jquery i WinRT ... ale jak są tworzone?

Dostępnych jest kilka opcji, w zależności od biblioteki, o której mowa, w jaki sposób jest napisana i jakiego poziomu dokładności szukasz. Przyjrzyjmy się opcjom w przybliżeniu malejącym porządku pożądania.

Może już istnieje

Zawsze najpierw sprawdź ZdecydowanieTyped ( https://github.com/DefinitelyTyped/DefinitelyTyped ). Jest to repozytorium społeczności pełne dosłownie tysięcy plików .d.ts i jest bardzo prawdopodobne, że używasz już tego. Powinieneś także sprawdzić TypeSearch ( https://microsoft.github.io/TypeSearch/ ), która jest wyszukiwarką plików .d.ts opublikowanych przez NPM; to będzie miało nieco więcej definicji niż DefinentlyTyped. Kilka modułów dostarcza również własne definicje w ramach dystrybucji NPM, więc sprawdź, czy tak jest przed próbą napisania własnych.

Może nie potrzebujesz

TypeScript obsługuje teraz --allowJsflagę i uczyni więcej wniosków opartych na JS w plikach .js. Możesz spróbować dołączyć plik .js do kompilacji wraz z --allowJsustawieniem, aby sprawdzić, czy daje to wystarczająco dobre informacje o typie. TypeScript rozpozna w tych plikach klasy typu ES5 i komentarze JSDoc, ale może się potknąć, jeśli biblioteka zainicjuje się w dziwny sposób.

Rozpocznij z --allowJs

Jeśli --allowJsdałeś przyzwoite wyniki i chcesz sam napisać plik lepszej definicji, możesz połączyć go --allowJsz, --declarationaby zobaczyć „najlepsze odgadnięcie” TypeScript na temat typów bibliotek. To da ci dobry punkt wyjścia i może być tak dobry, jak ręcznie napisany plik, jeśli komentarze JSDoc są dobrze napisane, a kompilator był w stanie je znaleźć.

Rozpocznij z dts-gen

Jeśli --allowJsnie zadziałało, możesz użyć dts-gen ( https://github.com/Microsoft/dts-gen ), aby uzyskać punkt początkowy. To narzędzie używa kształtu środowiska wykonawczego obiektu do dokładnego wyliczenia wszystkich dostępnych właściwości. Na plus jest to zwykle bardzo dokładne, ale narzędzie nie obsługuje jeszcze skrobania komentarzy JSDoc w celu wypełnienia dodatkowych typów. Uruchamiasz to tak:

npm install -g dts-gen
dts-gen -m <your-module>

To wygeneruje your-module.d.tsw bieżącym folderze.

Naciśnij przycisk drzemki

Jeśli chcesz zrobić to wszystko później i przez jakiś czas nie używać typów, w TypeScript 2.0 możesz teraz pisać

declare module "foo";

co pozwoli ci importna "foo"moduł z typem any. Jeśli masz globalny dokument, z którym chcesz poradzić sobie później, po prostu napisz

declare const foo: any;

co da ci foozmienną.

Można użyć tsc --declaration fileName.tsjak Ryan opisuje, czy można określić declaration: truena podstawie compilerOptionsw swojej tsconfig.jsonzakładając już miał tsconfig.jsonpod swoim projektem.

Najlepszym sposobem na poradzenie sobie z tym (jeśli plik deklaracji nie jest dostępny w ZdecydowanieTyped ) jest pisanie deklaracji tylko dla rzeczy, których używasz, a nie dla całej biblioteki. To znacznie zmniejsza nakład pracy - a dodatkowo kompilator jest w stanie pomóc, narzekając na brakujące metody.

Jak mówi Ryan, kompilator tsc ma przełącznik, --declarationktóry generuje .d.tsplik z .tspliku. Zauważ też, że (z wyjątkiem błędów) TypeScript powinien być w stanie kompilować Javascript, więc możesz przekazać istniejący kod javascript do kompilatora tsc.

jak opisano w http://channel9.msdn.com/posts/Anders-Hejlsberg-Steve-Lucco-and-Luke-Hoban-Inside-TypeScript o 00:33:52 stworzyli narzędzie do konwersji metadanych WebIDL i WinRT na TypeScript d.ts

Oto niektóre PowerShell, który tworzy pojedynczy plik definicji TypeScript, bibliotekę zawierającą wiele *.jsplików z nowoczesnym JavaScript.

Najpierw zmień wszystkie rozszerzenia na .ts.

Get-ChildItem | foreach { Rename-Item $_ $_.Name.Replace(".js", ".ts") }

Po drugie, użyj kompilatora TypeScript do wygenerowania plików definicji. Będzie wiele błędów kompilatora, ale możemy je zignorować.

Get-ChildItem | foreach { tsc $_.Name  }

Na koniec połącz wszystkie *.d.tspliki w jeden index.d.ts, usuwając importinstrukcje i usuwając je defaultz każdej instrukcji eksportu.

Remove-Item index.d.ts; 

Get-ChildItem -Path *.d.ts -Exclude "Index.d.ts" | `
  foreach { Get-Content $_ } | `
  where { !$_.ToString().StartsWith("import") } | `
  foreach { $_.Replace("export default", "export") } | `
  foreach { Add-Content index.d.ts $_ }

Kończy się to jednym użytecznym index.d.tsplikiem, który zawiera wiele definicji.

Tworząc własną bibliotekę, możesz tworzyć *.d.tspliki za pomocą tsckomendy (TypeScript Compiler) w następujący sposób: (zakładając, że budujesz bibliotekę do dist/libfolderu)

tsc -d --declarationDir dist/lib --declarationMap --emitDeclarationOnly

• -d( --declaration): generuje *.d.tspliki
• --declarationDir dist/lib: Katalog wyjściowy dla wygenerowanych plików deklaracji.
• --declarationMap: Generuje sourcemap dla każdego odpowiedniego pliku „.d.ts”.
• --emitDeclarationOnly: Emituj tylko pliki deklaracji „.d.ts”. (brak skompilowanego JS)

(zobacz dokumentację wszystkich opcji kompilatora wiersza poleceń)

Lub na przykład w package.json:

"scripts": {
    "build:types": "tsc -d --declarationDir dist/lib --declarationMap --emitDeclarationOnly",
}

a następnie uruchom: yarn build:types(lub npm run build:types)

Poszukałbym istniejącego mapowania bibliotek JS innych firm, które obsługują Script # lub SharpKit. Użytkownicy tych kompilatorów krzyżowych C # do .js napotkają problem, z którym się teraz borykają, i mogą opublikować program open source do skanowania bibliotek innych firm i konwersji do szkieletowych klas C #. Jeśli tak, zhakuj program skanujący, aby wygenerować TypeScript zamiast C #.

W przeciwnym razie tłumaczenie publicznego interfejsu C # dla biblioteki innych firm na definicje TypeScript może być prostsze niż robienie tego samego przez odczytanie źródłowego JavaScript.

Moim szczególnym zainteresowaniem jest framework ExtJS RIA firmy Sencha i wiem, że opublikowano projekty generujące interpretację C # dla Script # lub SharpKit