TypeScript - Definition Files

[00:00] Definition files are easily the most confusing thing in type script. For example, if I import lodash and I want to know what I can grab from lodash, I'll hit the auto-complete option here. Because I have a definition file, this index.d.ts, which you see popping up, it lets me know what I can import.

[00:25] That's coming from when I used typings, and I said typings install lodash, which gave me this directory typings, and installed it in browser, definitions lodash index.d.ts.

[00:45] This declared a module. Inside that module, it shows us all the different methods and objects I can import and use from it. It doesn't really matter what this index.d.ts is named. As long as type script finds it, then it'll include it as a definition file.

[01:03] Because this declares the modules like this one, or I'll just search declare module again. You can see that these declare modules are just re-aliasing that initial one. The only thing that matters one is the type script finds this module, lodash, so that it knows what it can export.

[01:20] If you compare that to something like reflect metadata, which we installed from NPM. This is in here, reflect metadata, this came with reflect metadata.d.ts. You can see that the module it has here, they hopefully left a comment that said it has no imports or exports, but you can use it to load the polyfill.

[01:42] This is just referencing a polyfill, meaning that you can use reflect.getmetadata without having to import anything. This is the scenario where the definition file is bundled in NPM for a polyfill. That means you don't have to import anything but the actual file itself, meaning you have to import this so it looks for that definition file and includes it.

[02:07] Then we have something like RxJS, which has bundled a bunch of definition files, clc.d.ts for AsyncSubject, behavior subject, and on and on and on. Those are all included in the NPM package for it.

[02:23] It's going to find all of those. If I import observable like this, and I try and grab stuff of it, I'll hit auto-complete. You can see it's finding observable in all these different definition files, and it's allowing you to import off any of them, but RxJS also has the ability to import individual methods.

[02:42] If you do RxJS, add operator map, which is a very common one, you navigate to it, you can see there's a map.d.ts with a module that's exposing observable and has that map that's adding that to the observable interface.

[03:00] Basically, it's finding this definition file and saying, "This definition of observable is allowing you to use map on it." There's all these different variations of definition files. Sometimes, in libraries like crypto, where it was actually reflect metadata that uses crypto under the hood. Crypto doesn't have a definition file in here.

[03:20] There's no d.ts. It's just going to access it under the hood and load it in the reflect library, but I never have to reference it, so it doesn't matter that there's not in the definition file if I'm never going to actually reference it in my code.

[03:32] Then lastly, just like the reflect metadata polyfill, when I use the promise, or if you try and use promise, it's going to say that because we're targeting ES 5 as our output instead of ES 6, promise isn't available in ES 5.

[03:47] There's actually a ES 5 library definition file, included with typescript that we're not looking at. Then, there's the ES 6 one that would have promise. Since we're going to be using promises as a polyfill and combining down to ES 5, we need to use the typings and I had typings install ES 6-shim.

[04:07] Now, that's available on browser ambient index, and you can see there's different things like iterator, and I'll just do a search for promise that aren't inside modules, it's just interface that's exposed through that definition file, so that when type script compiles, it won't complain about it.

[04:24] There's a bunch of different scenarios for definition files. There's lodash, which doesn't include its own definition file. In our scenario, we're actually using lodash from a CDN, so I didn't install it through NPM.

[04:36] I am loading it through a CDN, so it couldn't find a definition file anyway, but if I had a definition file like I do in here, then type script when complain about it being on a CDN, because it's found the definitions.

[04:48] Then, there are definition files that are bundled, all separated into different files for every single type or object inside a library, there are definition files that cover different polyfills. There are definition files that cover future features that you're not compiling out to.

[05:03] As you choose each library, or NPM install each library, you're going to have to check to see if it's included in node modules.

[05:09] When you try and use it, you'll see which errors are thrown, and you'll have to look at the typings and use typings to do things like search for the type of package you want. If you search for react, you'll see all the different things you could install, react, add-ons, perf. They could do typings, install, react, add-ons, perf, save, and ambient. It finds which one it needs.

[05:34] We'd have that react add-ons perf, and it's available for us to use. Just be aware sometimes, you have to hunt down definition files. Sometimes they're bundled, sometimes they're covering polyfills, sometimes there's none at all and you have to look for other solutions. It can be a painful process, but luckily typings has made it much nicer.