Jamaica real time feedback into the behavior of your distributed systems and observing changes exceptions errors in real time allows you to not only experiment with confidence, but respond instantly to get things working again. Youre hey, how's it going today? I want to talk to you about JSDoCs. It's sort of like typescript, but without all of the typescript tooling. So if you use typescript and you love it, maybe JS docs won't be for you. But if you have either heard of typescript and have not tried it yet, or you're curious, or you tried it and you didn't like it, we're going to look at JS Docs and maybe it's going to be something that youre interested in. Before we get into that, two things I want to share with you. One, I have a really awesome dog, super cute, his name is Nugget. He's going to be in the presentation today. And two, I actually really like JavaScript, so let's see how those two things combine. First of all, there's nugget. I told you he was cute. I hope I delivered. He actually has an instagram. So side note, I do these presentations halfway as a way to get him more followers, so make sure to check him out later. And yeah, like I said, I like JavaScript. I think there's a lot of cool things about it. For example, it runs everywhere. I think this is probably the number one feature that I like about JavaScript is that I can take the same JavaScript code and run it in the browser on the server, in an embedded device in freaking space. For NASA it's doing all of those things, which is really cool. Also, it only requires very minimal tooling. I mean, you really just need a browser to get started writing JavaScript. You can open up the console and start playing around, and if you're on a computer you probably have some sort of browser already available. It also has a really huge community, which has a lot of benefits in terms of providing more tooling or frameworks or libraries, or if you need help debugging something. Just having a rich community allows for all of these other resources around the actual programming language. But JavaScript has its quirks and its flaws and things that I don't think are quite so cool. For example, when I'm working in my editor, I really like having those little red squigglies that tell me when I'm doing something wrong. And JavaScript is a loosely typed language, which means it doesn't give us quite as many hints of when those red squigglies should be there, as it could be. This makes it a little bit more difficult if you want to refactor a code base, because you might introduce some bugs or errors that could otherwise be caught by a more strongly typed language, such as typescript, which we'll look at in a moment. Part of these errors youre can also have introduced with type mismatches, meaning if you have a function that expects an input like a string, and you pass it a number, JavaScript is not going to help you with that. And then you can introduce a bug to your code that could otherwise have been caught. In addition to introducing these bugs, there's also scenarios where you make chances to your code base, which could happen both internally or from external code bases. So if you're working with a libraries, maybe they publish new changes and you upgraded and you didn't catch some of those changes that they made, you're not going to see those errors that could have been caught. And again, this is where typescript comes in. These are the things that make typescript super cool. It's a strongly typed language, so because everything is typed, the language processor knows what to expect of certain types, which means it can help you catch things like typos or errors. Like if you have an object that you're trying to access a method and you accidentally misspell it, typescript is going to give you that little red squiggly and say hey, that's not a property on this object. In addition to helping you catch those errors, it can improve the developer experience by providing intellisense or autocomplete. So again, if you're accessing properties on an object, you can enter the object, the variable name, hit that period, and then vs code could throw up a little prompt that says, oh, do you want all of these properties that are available? It can really help you learn the API of a system, which makes it easier or better for onboarding and collaboration, because people don't have to be as entirely familiar with a code base before they can start contributing to it. Typescript also has some features that work really well for CI CD. You can set up your system such that if you introduce an error that could be caught by this strong typing language, meaning you have like a type mismatch, you can actually set up your delivery pipeline such that if those errors exist, you don't actually push them to production, and it kind of sends a warning or sends you an email that something's not right. And finally, having typescript or strong types available in the JavaScript project makes maintenance a lot easier, because not only is it safer that youre not going to introduce errors, it can help you catch or get familiar with a code base that maybe you haven't touched in like six months. And the other thing is, having these strong types can actually be really cool because there's some tooling around typescript or strongly typed languages that serve well for documentation, in that they can automatically generate documentation for you. All right, so I've been talking about all the cool things I like about typescript, but there's still some things that I don't like as well, particularly around the tooling. I really love that when I write javascript, I can take it and copy and paste it to all of those different environments that I talked about, and it's just going to work because that's the underlying language. That's not the case for typescript. You have to have a transpolation step that takes your typescript code and then converts it to javascript, which is the language that browsers understand. There's also the learning curve that if I am a lead developer and I want to bring on junior developers, there's probably more people that are familiar with javascript today than there are typescript, which means to introduce them to a typescript code base, there's going to be a little bit of friction to get them up to speed with learning the typescript ways. I also think that typescript is more complex than JavaScript because it introduces a lot of noise by having the type definitions embedded into the code base, and it adds a sort of complexity that never really got over. Also, typescript doesn't work everywhere. Like I said, you can't copy and paste typescript from your code base into the browser to debug things or to put them in other systems or runtimes. And this sort of pros and cons list of JavaScript on its own, or typescript as a superset of JavaScript had me kind of thinking like why not try and take the best of both and sort of combine it? And we can do that thanks to vs code. So we're going to look at JS Doc today, but the only tool that we're going to begin with is vs code. It's an editor that I think most JavaScript developers today are using. Hopefully, if you're already using it, then you've already gotten started on the path that I'm going to recommend. And vs code is really cool because it actually has the typescript language engine sort of powering its features like intellisense or autocomplete. When you see those auto suggestions in vs code, that's actually the typescript language saying or analyzing your code and giving you those prompts. So what that looks like is if you have a variable such as my object here that has a property of hello, when you try and access the properties on my object vs code is going to prompt you hey, do you want to use the hello property? Here it is. It's a type of string, and that's super handy to know, especially if you have an object with, I don't know, tens or dozens or hundreds of properties on it. But there's one issue the intellisense doesn't go so far to help catch when you have errors such as type errors. So if we have a function here called yell that expects a string and returns a string, you could accidentally introduce an error if you pass a number to that function. So if we pass the number two to yell. So the first step on my journey of getting this type checking sort of strongly typed in JavaScript path is to just enable typescript checking more strict checking on individual files. So you can do that at the file level by putting this comment at the top of the file that is the at symbol with PS check. And once you do that, you can see already more little red squigglies are going to appear in your code. For example, if we have that object with a property of hello and we try and reassign that property, typescript is going to say hold on, that property is supposed to be a string, and now you're trying to convert it to a number, and you can configure it such that hello can be one or the other, but by default it's going to assume that you have introduced a bug to your code. That's super handy. So how do we sort of get that feature where we can say, well actually that wasn't an error, we want to be able to use a string or a number in that case, and this is where JS doc comes in. JSDocs is a markup language used to annotate JavaScript, where we use the comments in JavaScript to add the type annotations to our code. So it's not any different than JavaScript, it actually works within JavaScript, and because it works within the comment system, you can copy and paste it to different code bases, and it's not going to actually do anything, but it can be used by typescript to understand the types of your project. The official typescript team actually enabling using JSDoCs so here's sort of the example of JSDocs. We have a variable called age, and we have a comment right above it where we say the type of this variable is either a string or a number, which means that we assign it to the number one. It's totally fine when we assign it to a string of two. That's fine when we try to reassign it to a boolean of false. Then we get the little red squiggly, because that's not the type that age is supposed to be. We can also see how we can add type definitions to our functions with this documentation block where we define the first parameter, which is a string and has the name str, and this function returns a string. So the function yell now can be passed a number. But if you pass that number to the function, you're going to get a little red squiggly that says hey, you're trying to use a number, but this function only accepts a string. It's very handy to catch those errors that we talked about before. So once you start enabling JSDocs or typescript checking on a file by file level, you may find that it gets kind of tedious to add the comment at the top of every single file. That is a nice way to incrementally start introducing it. But eventually, if you're on a JavaScript project, you probably want to start enabling it for the entire project, and you can do that a number of ways. Number one, in vs code if you just want to enable it for yourself, your instance of vs code, I'd recommend going into the settings and checking the box js ts Chevron implicit project config check js, turn that sucker on and it's going to start checking all of your JavaScript or using the typescript checker on all of your JavaScript files without having to use those comments. Option number two is great if you actually want to enable this for yourself or for your team, or your team that's using vs code, at least you can add a file to your project called tsconfig JSOn and put in the compiler options to check js and set that to true. And this is again handy if youre are working on a team, or if you want to do it for yourself as well. This is the option that I actually prefer. Now JSDocs has some native types built in string number boolean array promise basically any of the primitives that you're going to find in typescript. But then most JavaScript projects are not built using just these primitives, you usually have complex types such as objects, and you want to be able to define those. Now typescript has that support built in, and so does JS docs with the typedef little tool. So you can create a new type definition which is a type of object and his name is dog, and that object can expect to have properties of breed, which is a string age which is a number and name, which is an optional string. And we can use that in our code by creating a variable and assigning it the type of dog. And we can say in this case we have a variable called my dog, which is an object that is the breed of chihuini, age of four, and name is nugget. And this is also a good example here where you can define your types in one file and actually import them to another file. In fact, you can even combine typescript and js docs by using, let's say a types D ts file and define youre types in there and import them into a JavaScript file using this syntax. So as I mentioned, jsdocs, I'm not going to dig into too much of the syntax today. I think there's a lot of documentation out there, and I have an article that I wrote that I'll link to for actually learning the syntax, but I want to walk through the different processes or phases of including it into a project. So we talked about into files into an entire project, and then I feel like the next phase is as part of a CI CD pipeline. This is going to be a little bit different because up until now we haven't used any other tooling additional besides vs code. So we've done everything that's already built in. We haven't had to NPM install anything, we haven't had to run any sort of other process in our terminal or anything like that. That changes with CI CD, because in a CI CD pipeline it's not going to have the typescript language engine built in, so we have to provide that for it. To do that we can NPM install and save as a dependency or a dev dependency the typescript compiler. Once we do that, we can also go to a package JSON file. We can add a script that I like to call TS, and we can see that the dev dependencies include typescript. Now, because we are now using the typescript compiler, we probably want to start adding more configuration options to our TS config file. One is we want to tell it which files to actually check. So our index file, for example, and we want to pass two new configuration options to it. One is to allow JS, even though we had checked JS before, but now we want to allow it for the compiler, and we also want to turn on the noemit flag. Now by default the typescript compiler is going to take typescript source code and convert it to or output JavaScript. We are going to be starting with JavaScript, so we don't actually have to output anything, unless you did want to do some transforms. I don't like to do that. So once we have this typescript compiler in place, we can actually open up our terminal and run that TS command. And if we have errors in our code base we're going to be able to, or it's going to tell us where those errors are, what file, what line, what column, things like that. And this is again particularly helpful if you want to build a pipeline. You can put this as a step in the pipeline that is required before deploying your code. And if this step runs into one of these errors, it's not going to go to the next step, which could be to again deploy your code super handy to avoid type checking errors in production. So now that we've introduced that type checking into our CI CD pipeline, we can actually take it a step further and include it into generating types for our libraries. Now this is going to be something that is unique to library authors like myself, but again, this is kind of as we are going the next incremental step that I see. So I want to be able to generate type definitions to provide to my library's consumers. We can do that once again by going back to that ts config file. And now instead of turning on that no emit rule, we actually want the typescript compiler to emit those type definition files. However, we only want those type definition files. So we're going to set declaration to true for the type declarations. We're going to set emit declaration only to true so that it doesn't actually output any javascript. Because again, I'm already writing javascript, I don't need typescript to turn it into more javascript, and I'm going to define a folder where I want those type definitions to exist. And with that I can go back to my package Json file and I can tell package Json where my type definition files exist, in this case in the disk folder, so that when I publish my package and people are going to be consuming it, they can grab the type definitions for my library from the disk folder. So that is essentially the roadmap that I've followed through my journey and I've felt that it works just fine. I've started as just enabling type checking on individual files and then on the entire project, and then figured out how to incorporate it into a CitV pipeline and then generate type definitions for the libraries that I'm publishing, and it's been really awesome. I like this approach because you can do it incrementally and you don't have to rewrite your whole code base all at once. You can just kind of fix bugs as they arise. So a couple of closing points that I want to make is that in this case you don't have to pick well, with this approach you don't have to pick either typescript or JS docs. I really like this because it is an incremental adoption strategy. If youre starting from JavaScript, you can just start adding these type annotations with JSDocs to your JavaScript files, and eventually you can start introducing more and more typescript if you like that. In fact, you can do a little bit of both. You can start with JavaScript and then slowly incorporate more typescript. And then eventually, if you like the typescript syntax better, you can transition into typescript. I personally find that JS docs works better for adding more descriptions to things like objects or methods, because I don't know if typescript has a syntax for adding extended definitions to what an object property is, for example, or what a type property is. However, typescript is certainly kind of the underlying engine that's powering all of this, and therefore it's going to be better at some other things. For example, typecasting in typescript is just way better. And if you don't know what typecasting is, I don't think I need to get into it now. But if you go down this route, you are going to find that as well. There are some things that the typescript team is not going to support that is part of JSDOCs, or things that typescript has that they are not going to implement if you're using the JSDOCs syntax. That said, I haven't had any problem yet having large JavaScript projects that are using JSDOCs and using typescript to do the type checking on it. Either way, you're probably still going to push some errors to production typescript JSDocs. They're not going to help you catch every single but, and they both can get extremely complicated. It is a wonderful way to waste a whole bunch of time on things that are not going to add any value to the actual user, but is going to take hours and hours and hours of your day. So either way, it's fun, I guess, and it helps me catch a lot of errors that I would otherwise not have caught. So I hope that you found that this talk interesting, and I hope that you practice some of these things and it can help you catch some otherwise or some errors that would otherwise have gotten through. So that's all I've got for you today. If you want to learn more, I do have a blog post that I wrote about this that basically outlines in more detail this process. It's Austin gil.com typescript theeasyway and if you have any questions, I would love to connect with you. I'm looking to do these talks that I can talk to more people in the community. So if you like the talk, if you hated it, if you have corrections that you want me to make, reach out to me on Twitter. I'd love to chat with you about this or anything else related to web development. And don't forget my dog is really cute. If you like the pictures of Nugget and you want more, head to instagram.com at nuggetthemighty. So I hope you enjoy this talk and I will catch you out on the Internet.