API Reporting Docs with API Extractor

[00:00:00]
>> We need to go into each package JSON, And add one more NPM script, just kick it out to scripting API report. So do it two data types. By the way, if you wanted to automate this, a great tool to look at is Jq. It allows For csli manipulation and querying of JSON values, and this would be a great thing where you could like read the file, alter the JSON, write the file back out.

[00:00:37]
Jq would be great for this. But we only have four, so I do this. All right, so now each package will look to script D to do something called API report. And what is that thing? Well surprise, I have a script for you. So we're gonna bring that into our scripts packages folder, right alongside with everything that operates on a per package basis.

[00:01:02]
Of course not forgetting the chmod to make sure that we can actually execute this thing. One last step. Your API report for each package will be placed in a folder called etc. It must exist before you run the tool. So let's create it. Just like that, go to every package and create an etc folder.

[00:01:36]
And there it is. Now it's time to run it. Learner run. API report. What's happening here? I know my problem. So on the fly, I decided to move this base config file from the root of the project into the packages folder. So now I'm reaching too far down In these little thin API extractor configs we'll just have to fix those real quick.

[00:02:11]
No regrets. I still still like where it lives. It's things that live there have a very clear purpose. They're sort of baselines that apply broadly to all contents of that folder. Okay and utils save. Let's try this again. This looks much more promising. All right, supposedly everything has completed.

[00:02:49]
Let's look at what happened. In the etc folder of each package, I have a mark down file. And this describes my public API surface. If I were to view this file directly, here is what it would look like. So it would say, here's my API report donated this file.

[00:03:08]
And then here we go. This is public. The deferred is also public. It's telling me that these things are undocumented. I could make this an error if I wanted to, if I really wanted to make sure Things are documented. I could say hard fail if you find that.

[00:03:26]
And then let's see anything else that's interesting here public public, no package documentation comment for this package. Let's see, I actually enriched one of these packages so that it would look more like What I would hope ducks would look like in the real world, Come on close group, There we go.

[00:04:05]
Sorry. It's not gonna show up. The docs are not gonna show up here. This is just the API report. Here's an example of something interesting. I have a beta annotation here, and it's just a js doc comment, this beta thing. Just a js comment, right? Just like you'd say at Prem, something like that.

[00:04:29]
And And the idea here is that in my roll ups for this, for this package, which are these things that were created here Types. This is tricky because I think I actually have a module here that's called types. I bet it just got overwritten. Yep, I think it did, which is fine.

[00:04:50]
So this is the public API surface. Note that there are not typed cards here. In fact, there should be Yep, here. They are. It's telling me I excluded some things from this release. They're not here they were stripped away. But if we look at beta, here they are.

[00:05:10]
So it would just be a simple matter of a consumer that wishes to try this beta stuff out. They just need to simply say, look when you're looking at the type information for at slac slash types Here's the declaration file, you should look for it. Don't go to this one, which is the default.

[00:05:27]
Just go to this one here. I'm telling you to go and look at the beta, and then all the stuff will start showing up in their autocomplete. It's it's a low overhead but deliberate act. Then the consumer has to take if they want to use this pre release thing.

[00:05:42]
And then it's all there, right, and there's the beta tag. And then private. This is where you start to see everything even. I don't know if I have an example here, but sometimes we mark things as internal which just means. This is not gonna be public ever. So there you go.

[00:06:03]
These are the roll ups. And you would simply go into your package JSON and say types. Don't just go and look at this index that DTS. You're gonna say types, right? Go look at one of the roll ups, the public one by default. And finally in that temp folder, I know I already had these here.

[00:06:27]
Let me delete this just cuz there's no proof that I actually made that pop up. It was already there and is identical content [LAUGH] We should see that pop up again. temp, still building, then the last one popped up. So here you go. This is information. Think of it as API docs in JSON form.

[00:06:54]
So if you wanted to build your own API doc site, You could build a little, little view app on top of this or something. And it's extremely low level and a very stable API. So if you look at Doc, stop Microsoft comm. This is where. There's just all of this stuff, like everything that Microsoft makes with a public API of some sort.

[00:07:25]
Right guides and all this stuff here. It's all powered by what I showed you today. You should look- you should consider that When wondering like, is this contract going to change like crazy? It would hurt if it changed a lot. Microsoft would be harming themselves to do that.

[00:07:49]
So, but you can consume this and then you can do whatever you want, right? You could diff this like what was just added what was removed. Show me how this has evolved over time. So this is API extractor. One last thing I want to make sure I show you, let me stage all this.

[00:08:13]
Okay, so the script that we're running this API report thing, this dash dash local Argument means I am running a local build. And I'm telling you what the API surface should be. However, you could run this in, in ci, for example, and let me make a change. Let me alter the API surface in some way.

[00:08:41]
Let's say I take in, what is this taken? It takes a number or a date. So let's, I mean, theoretically, no reason why I can't do this. But it's an alteration to the API. Now if I do this, I think it will yell at me. Oops Sorry. That command that I just copied to my clipboard is intended for.

[00:09:07]
per package invocation. Now little work.Okay.So we're getting a lot of feedback about some small things and our ducks. This export ID symbol. I haven't said Is it public private beta alpha. It's telling me Look, you got it. You gotta tell me something. To missing a release tag. I think it defaults to public but you can change that.

[00:09:44]
And where did it really get upset with me?. Completed with warnings anything else in here?. It should give me a much nicer error message than what I'm seeing here, says it completed successfully. I'll tell you what's going on though. So this is this date function, right? So what's happened is, each package has its own little temp folder and this is sort of what it It read from the code.

[00:10:33]
I know what I did wrong here. Yarn build. And so we have to build because type information is the input for this API extraction. So it was sort of like reading the previous build. Now what I should see here we go date or number And then this is the meaningful thing.

[00:10:57]
I have changed a public API signature for this project. Please copy this file utils right copy this into the etc folder. If it's in the etc folder that's like I'm giving it a thumbs up. But it found differences. So I have this turned on, such that people have to run this and generate that report as part of a pull request.

[00:11:20]
So I would get a code change that would look like I now accept numbers in this function. And here's the human readable report for how this affects the public API surface. If that reports not up to date, this will fail. And there will be a GitHub check that will say thumbs down.

[00:11:38]
The API report is not up to date. So it really helps surface these changes in a way where meaningful discussions can happen. And it's just, it makes it so that never again will you ship something and say, Crap, I didn't realise we export it that or I didn't realise that.

[00:11:56]
That we were using the type of this argument for this internal thing as part of a public API surface. That happens all the time. Now it's in your face. Now it's part of your code review, and you can see what's happening and make good decisions.