Feel the API
Ever got a feeling that the API of a library or an SDK is so convoluted that it might as well be easier to write your own?
Truth is, you will most likely waste your time and effort to create a worse version of what is already out there.
Just recently I stumbled upon such very situation. You see, in Multify translation works by deconstructing the whole HTML document, extracting pieces of text from it and then reassembling the document back together with the new text.
Back at the start of the project I picked jsdom as a go-to library for this. After all, it has tens of millions downloads on npm, would could go wrong?
It turned out to be the wrong tool for the job.
It is too “heavy” for what I need and this becomes a problem when more clients need to get more pages translated.
Luckily, with the help of Claude I identified two more options and conducted the benchmarks. The candidates were cheerio and htmlparser2.
Only… how do I pick the right one?
I already mentioned that I have ran the benchmarks. This concluded that htmlparser2 was the best option for my use case: it was lightweight and forgiving, and as fast as it can be.
But the API is a mess.
No, I don’t mean to insult the developers. In fact, they did a great job of optimizing it and keeping it lean.
However, coming over from jsdom where API mimics modern browsers, it was certainly a different beast. On top of that, many years of legacy did their thing.
It felt unwieldy and obscure. I wanted to drop it, even after I’ve conducted the experiments, wrote initial tests and everything looked as good as it ever could be.
Then it dawned upon me. I have played with this idea previously but never really got any real use out of it.
What if I asked Claude to write a comprehensive short guide, overlooking all of the main features and differences in the API?
You see, the problem wasn’t that I didn’t know how to write code. I didn’t know how to wrap my mind around it quick enough and combine it with existing jsdom API I’ve been using throughout my project.
Sure, I could have spent days or maybe even weeks “studying” the API. Where by studying what I really mean acclimating myself with it, building a new mental model that would cover both what I already know about jsdom, how it is being used in the project and the new things I didn’t know about htmlparser2: How do you extract text? How do you set attributes? How do you select elements?
And so I simply ordered Claude Code to draft the page in a newly created GitHub repository. And it did it almost flawlessly on the first try.
Behold: jsdom-to-htmlparser2.aleksei.dev
Of course, I had to point out some features and corrections, but the idea that I got an actually useful guide–from which I got new insights almost immediately–was pretty astonishing.
You see, the problem wasn’t that I didn’t know any of this stuff. I wanted to speed up my learning and make it more engaging for myself.
And carefully commanding AI to gain insights or do the grunt work can significantly speed up both your work and the process of gaining knee knowledge.
So this is a good case where AI didn’t help to write more code, in fact it didn’t write any. Instead, it helped me read the code. And helped to gain a deeper understanding – the feeling for the API.