Building APIs From Documentation

Photo by Magda Ehlers from Pexels

As continuation to my obsession on Optional, I decided to implement the thing in TypeScript! Pretty straight-forward, since Java has pretty good documentation on the thing, and OpenJDK's implementation is open-source.

And in the process, I learned a lot. For example, the Java documentation states that no two empties are expected to be the same instance, but OpenJDK implements it that way anyways. I also learned about wildcard types in Java, and TypeScript's sort-of-close equivalent unknown. I learned how to build APIs using Generics. I also learned that --strictNullChecks in TypeScript forces you to handle null and undefined cases whenever it can detect it, and may omit the need for Optional entirely.

Got to work with Github Actions again, although it has not sunk in yet. Need to do it more to be able to write build yamls from memory. Also got to evaluate Deno as well. I like the module system, feels more like how ECMAScript envisioned it. Too bad TypeScript isn't a browser language, would have made for a good cross-platform way to build stuff. Still waiting for Microsoft, or someone else, to build a fully-native TypeScript engine or for Deno to morph into that.

Reimplementing APIs with just the docs and a rough guide is sort of like working with a jigsaw puzzle. You get the pieces, the expected dimensions, the box art, and that's it. From there, you're on your own. Once you're done, you pack it up, send it to someone else to pick apart while you move on to another.

Now on to the next interesting thing that I can port to TypeScript! 🤓

PS: My port of Optional to TypeScript isn't a direct port from Java. I actually ported it to JavaScript first, but then realized that Optional wasn't just about null-checks. It was also about guaranteeing the type and identity of the value througout the API, whether it was extracted, mapped, or defaulted. Hence I proceeded to TypeScript right after I finished a rough JavaScript implementation.