Table Of Content

Dr. Axel Rauschmayer Tackling TypeScript Upgrading from JavaScript 2 Tackling TypeScript Dr. Axel Rauschmayer 2020 Copyright©2020byDr. AxelRauschmayer Allrightsreserved. Thisbookoranyportionthereofmaynotbereproducedorusedin anymannerwhatsoeverwithouttheexpresswrittenpermissionofthepublisherexcept fortheuseofbriefquotationsinabookrevieworscholarlyjournal. exploringjs.com Contents I Preliminaries 7 1 Aboutthisbook 9 1.1 Whereisthehomepageofthisbook? . . . . . . . . . . . . . . . . . . . . 9 1.2 Whatisinthisbook? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3 WhatdoIgetformymoney? . . . . . . . . . . . . . . . . . . . . . . . . 9 1.4 HowcanIpreviewthecontent? . . . . . . . . . . . . . . . . . . . . . . . 10 1.5 HowdoIreporterrors?. . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.6 Whatdothenoteswithiconsmean?. . . . . . . . . . . . . . . . . . . . . 10 1.7 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2 WhyTypeScript? 13 2.1 ThebenefitsofusingTypeScript . . . . . . . . . . . . . . . . . . . . . . . 13 2.2 ThedownsidesofusingTypeScript . . . . . . . . . . . . . . . . . . . . . 15 2.3 TypeScriptmyths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3 FreeresourcesonTypeScript 17 II GettingstartedwithTypeScript 19 4 HowdoesTypeScriptwork? Thebird’seyeview 21 4.1 ThestructureofTypeScriptprojects . . . . . . . . . . . . . . . . . . . . . 21 4.2 ProgrammingTypeScriptviaanintegrateddevelopmentenvironment(IDE) 22 4.3 OtherfilesproducedbytheTypeScriptcompiler . . . . . . . . . . . . . . 23 4.4 UsingtheTypeScriptcompilerforplainJavaScriptfiles . . . . . . . . . . 24 5 TryingoutTypeScript 25 5.1 TheTypeScriptPlayground . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.2 TSNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 6 Notationusedinthisbook 27 6.1 Testassertions(dynamic) . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 6.2 Typeassertions(static) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 7 TheessentialsofTypeScript 29 7.1 Whatyou’lllearn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 7.2 Specifyingthecomprehensivenessoftypechecking . . . . . . . . . . . . 30 3 4 CONTENTS 7.3 TypesinTypeScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.4 Typeannotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.5 Typeinference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 7.6 Specifyingtypesviatypeexpressions . . . . . . . . . . . . . . . . . . . . 32 7.7 Thetwolanguagelevels: dynamicvs.static. . . . . . . . . . . . . . . . . 33 7.8 Typealiases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 7.9 TypingArrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 7.10 Functiontypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 7.11 Uniontypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 7.12 Optionalvs.defaultvaluevs.undefined|T . . . . . . . . . . . . . . . . . 38 7.13 Typingobjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 7.14 Typevariablesandgenerictypes. . . . . . . . . . . . . . . . . . . . . . . 41 7.15 Example: atype-parameterizedclass . . . . . . . . . . . . . . . . . . . . 42 7.16 Conclusion: understandingtheinitialexample . . . . . . . . . . . . . . . 44 8 CreatingCommonJS-basednpmpackagesviaTypeScript 45 8.1 Requiredknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 8.2 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 8.3 Therepositoryts-demo-npm-cjs. . . . . . . . . . . . . . . . . . . . . . . 46 8.4 .gitignore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 8.5 .npmignore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 8.6 package.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 8.7 tsconfig.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 8.8 TypeScriptcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 9 CreatingwebappsviaTypeScriptandwebpack 51 9.1 Requiredknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 9.2 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 9.3 Therepositoryts-demo-webpack. . . . . . . . . . . . . . . . . . . . . . . 52 9.4 package.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 9.5 webpack.config.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 9.6 tsconfig.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 9.7 index.html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 9.8 main.ts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 9.9 Installing,buildingandrunningthewebapp . . . . . . . . . . . . . . . . 56 9.10 Usingwebpackwithoutaloader: webpack-no-loader.config.js . . . . 57 10 StrategiesformigratingtoTypeScript 59 10.1 Threestrategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 10.2 Strategy: mixedJavaScript/TypeScriptcodebases . . . . . . . . . . . . . 60 10.3 Strategy: addingtypeinformationtoplainJavaScriptfiles. . . . . . . . . 60 10.4 Strategy: migratinglargeprojectsbysnapshottestingtheTypeScripterrors 61 10.5 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 III Diggingdeeper 63 11 WhatisatypeinTypeScript? Twoperspectives 65 11.1 Threequestionsforeachperspective . . . . . . . . . . . . . . . . . . . . 65 CONTENTS 5 11.2 Perspective1: typesaresetsofvalues . . . . . . . . . . . . . . . . . . . . 66 11.3 Perspective2: typecompatibilityrelationships . . . . . . . . . . . . . . . 66 11.4 Nominaltypesystemsvs.structuraltypesystems . . . . . . . . . . . . . 67 11.5 Furtherreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 12 TypeScriptenums: Howdotheywork? Whatcantheybeusedfor? 69 12.1 Thebasics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 12.2 Specifyingenummembervalues(advanced) . . . . . . . . . . . . . . . . 72 12.3 Downsidesofnumericenums . . . . . . . . . . . . . . . . . . . . . . . . 75 12.4 Usecasesforenums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 12.5 Enumsatruntime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 12.6 constenums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 12.7 Enumsatcompiletime . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 12.8 Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 13 AlternativestoenumsinTypeScript 87 13.1 Unionsofsingletonvalues . . . . . . . . . . . . . . . . . . . . . . . . . . 87 13.2 Discriminatedunions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 13.3 Objectliteralsasenums. . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 13.4 Enumpattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 13.5 Summaryofenumsandenumalternatives . . . . . . . . . . . . . . . . . 101 13.6 Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 14 Addingspecialvaluestotypes 103 14.1 Addingspecialvaluesinband . . . . . . . . . . . . . . . . . . . . . . . . 103 14.2 Addingspecialvaluesoutofband . . . . . . . . . . . . . . . . . . . . . . 105 15 Typingobjects 109 15.1 Rolesplayedbyobjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 15.2 Typesforobjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 15.3 Objectvs.objectinTypeScript . . . . . . . . . . . . . . . . . . . . . . . 110 15.4 Objecttypeliteralsandinterfaces . . . . . . . . . . . . . . . . . . . . . . 113 15.5 Typeinference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 15.6 Otherfeaturesofinterfaces . . . . . . . . . . . . . . . . . . . . . . . . . . 123 15.7 JavaScript’sprototypechainsandTypeScript’stypes . . . . . . . . . . . . 125 15.8 Sourcesofthischapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 16 ClassdefinitionsinTypeScript 127 16.1 Cheatsheet: classesinplainJavaScript . . . . . . . . . . . . . . . . . . . 127 16.2 Non-publicdataslotsinTypeScript . . . . . . . . . . . . . . . . . . . . . 133 16.3 Privateconstructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 16.4 Initializinginstanceproperties . . . . . . . . . . . . . . . . . . . . . . . . 137 16.5 Abstractclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 17 Class-relatedtypes 143 17.1 Thetwoprototypechainsofclasses . . . . . . . . . . . . . . . . . . . . . 143 17.2 Interfacesforinstancesofclasses . . . . . . . . . . . . . . . . . . . . . . 144 17.3 Interfacesforclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 17.4 Classesastypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 6 CONTENTS 17.5 Furtherreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 18 Typesforclassesasvalues 151 18.1 Typesforspecificclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 18.2 Thetypeoperatortypeof. . . . . . . . . . . . . . . . . . . . . . . . . . . 152 18.3 Agenerictypeforclasses: Class<T> . . . . . . . . . . . . . . . . . . . . . 153 19 TypingArrays 157 19.1 RolesofArrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 19.2 WaysoftypingArrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 19.3 Pitfall: typeinferencedoesn’talwaysgetArraytypesright . . . . . . . . 159 19.4 Pitfall: TypeScriptassumesindicesareneveroutofbounds . . . . . . . . 162 20 Typingfunctions 163 20.1 Definingstaticallytypedfunctions . . . . . . . . . . . . . . . . . . . . . 164 20.2 Typesforfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 20.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 20.4 Overloading(advanced) . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 20.5 Assignability(advanced) . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 20.6 Furtherreadingandsourcesofthischapter . . . . . . . . . . . . . . . . . 176 IV Dealingwithambiguoustypes 177 21 Thetoptypesanyandunknown 179 21.1 TypeScript’stwotoptypes . . . . . . . . . . . . . . . . . . . . . . . . . . 179 21.2 Thetoptypeany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 21.3 Thetoptypeunknown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 22 Typeassertions(relatedtocasting) 183 22.1 Typeassertions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 22.2 Constructsrelatedtotypeassertions. . . . . . . . . . . . . . . . . . . . . 185 23 Typeguardsandassertionfunctions 187 23.1 Whenarestatictypestoogeneral? . . . . . . . . . . . . . . . . . . . . . . 188 23.2 Narrowingviabuilt-intypeguards . . . . . . . . . . . . . . . . . . . . . 190 23.3 User-definedtypeguards. . . . . . . . . . . . . . . . . . . . . . . . . . . 195 23.4 Assertionfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 23.5 Quickreference: user-definedtypeguardsandassertionfunctions . . . . 199 23.6 Alternativestoassertionfunctions . . . . . . . . . . . . . . . . . . . . . . 200 23.7 @hqoss/guards: librarywithtypeguards . . . . . . . . . . . . . . . . . . 202 24 Validatingexternaldata 203 24.1 JSONschema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 24.2 ApproachesfordatavalidationinTypeScript . . . . . . . . . . . . . . . . 205 24.3 Example: validatingdataviathelibraryZod . . . . . . . . . . . . . . . . 206 24.4 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Part I Preliminaries 7