micahasowata/jason/v2

The month of February just started. I had just finished reading Let’s Go Further and I was looking to build something. Anything.

In Chapters 3 and 4 of the book, you build helper functions to handle JSON input and output. I liked the dev experience improvement that having those functions provided so I decided to make them into a stand alone module so that I could use them in my projects in the future.

On the 12th of February I created the jason repo to house that module. For the next 10 hours 26 minutes, according to Wakatime I worked on building it out.

I chose to use json-iter over the standard library’s encoding/json because it provides better performance but it had a worse error handling documentation by ways of docs, Github Issues and blog posts.

Since jason was meant properly format errors I had to find every possible kind of errors that the library was going to produce, based on some rules established this article by Alex Edwards.

Into the rabbit hole

I immediately setup the library in test mode and deliberately made the functions fail just to see the error messages that would be logged.

Armed with the error messages and Github code search, I dug into json-iter’s repo. I immediately realised that there weren’t a lot of sentinel errors instead the error messages where generated as strings on the fly. Literal "x" + {variable_name} + "y" sort of situation, so I had to use regexes to get important information from them.

Shoutout to ChatGPT for providing me with the regexes needed.

In that moment I realised that it is quite difficult to try to squeeze every inch of performance out of a product without giving up something even if it as “trivial” as error handling.

The v1

On the 12th I actually had a pre-release. But I wasn’t satisfied with the quality of work at all so I put more time into it and 6 days later on the 18th of February I released the v1 of jason.

I felt fulfilled. I still feel fulfilled anytime I look at the repo.

I immediately put it into use and it worked beautifully well. I loved it.

But like every piece of software, it always had room for improvement and for next 5 months I could conveniently over look them to focus on other projects but in late June I knew I had to work on improving it.

Why did it become a need? Two reasons:

  1. I was the only user so far despite my best efforts at “marketing” and I wanted to change that but to change it I needed to write something that I could confidently talk to entire strangers about
  2. I did not have any project to work on.

A v2

On July 2nd I created my first Reddit post.

I needed complete strangers to check out the library and criticise it. I needed as much criticism as possible and I actually got it.

Read the comments under the post to get the full gist. But if you can’t I would summarise.

  1. Write more idiomatic code, especially around error handling
  2. Don’t restrict output structure. Favor the any type over user defined types
  3. Move away from json-iter

Wow.

I was glad I got response but I was also nervous because of the amount of work necessary to implement the responses. But I asked for it, got it and now I have to live with it so I started work.

On the 3rd I made this commit. Work had started.

The process

First point of call was the core struct name.

In the v1 I called it Jason but at the time I started planning the v2 I had already become an avid user of Uber’s zap and the Chi router and I noticed that the core type for both of them described what the library did.

zap had the Logger type while chi had the Router type so I changed the core type name from Jason to Parser because it was more on the parser side of things.

Then I made a goal of zero dependencies no matter how much code I was going to write.

Using encoding/json would result in a slower overall performance but I didn’t mind for two reasons:

  1. When an engineer is looking to extract every morsel of performance they would discard helper libraries in favor of bare library APIs.
  2. json-iter no longer seems maintained. The last commit was 2 years ago. It has 200 issues and 60 open pull requests.

So off I went working entirely with the standard library. Making changes, moving methods and writing tests cases and in two days I was done.

The v2 was ready. Tested, linted and ready to publish.

So following the instructions from this article I published a v2.

How has it been faring?

If you go to jason’s repo you would notice that on the second-to-the-last or penultimate section you would find a note about aliasing the import path.

So far that is only known issue.

No performance tests were done because I would not trust the metrics that my laptop would generate. So if you are reading this and you want to check how much slower or faster the library has gotten you can. Check it. Generate a graph or table. Create an issue. It would not be ignored.

On the people side of things I got two more stars on Github. I don’t know whether they mean the stargazers have started using the library or they just want to support me but I am really grateful for the stars. They are really nice to look at.

What have I learnt from this process?

This is the first time I am building a v1 and v2 successfully and I feel grand about it. On the day I lauched and tested the v1 I felt like prime John Carmack and I still feel that way.

I think I would like more opportunities to feel that way so building jason has been a boost to start building projects no matter how daunting they might be initially.

Fun fact: This site is one of the results of the boost that building jason brought.

Thanks for readng about jason.

If you want to give it a star click here.