The Sajari JS SDK allows developers to quickly and easily query the Sajari API from web browsers. It enables the use of javascript to deliver search operations and can be used to build anything from search interfaces for your site search to recommendations widgets for websites and webapps.

We rebuilt our existing JavaScript SDK in TypeScript. TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. It eliminates whole classes of bugs and significantly improves the development process.

The trouble with search APIs

Interacting with search APIs can be very overwhelming, especially when you start tapping into the more complex and dynamic functionality available. While this allows experts to finely tune their systems, it has proved to be a large barrier to user adoption and understanding. Some of the more well known open source solutions have spawned an ecosystem of query builders to give users a simplified interface to their APIs.

With the full rewrite came the opportunity to streamline our SDK, simplifying the search endpoints but also removing functionality that was now unnecessary (managing user info, creating, destroying, and updating records). The previous SDK began life as a CommonJS module, which has now been superseded by JavaScript bundlers that can take advantage of static code analysis and modern optimizations like dead code elimination (i.e. tree shaking).

The experience that comes with having our code used in numerous internal and external projects, as well as run on thousands of sites has heavily influenced how we design APIs and reinforced the need to keep things simple. Using the feedback and insights we’ve gained we’ve completely transformed the experience for developers.

Rebuilding for a pure search experience

This release is a complete rewrite of the last version. It re-focuses the JS SDK as a core building block in the Sajari ecosystem. We want to make it as simple as possible for developers to get started, so we identified all the key needs of our users and stripped away everything that wasn’t necessary for searching. The interface has been intentionally kept small, simple, and non-opinionated, allowing it to fit into any kind of project.

At Sajari we use Go for all of our backend code & services. Go’s strong, static typing is a huge boon for us, allowing us to quickly & safely iterate at scale. TypeScript brings many of the benefits of Go to JavaScript without the usual sacrifices of ad-hoc type systems. This is a huge win for us and we don’t see any reason to write vanilla JavaScript again!

TypeScript allowed us to strongly define the shape of the API upfront. From there we could develop and refine without worrying over implementation details. This was a welcome change from traditional JavaScript. We could put our mind at ease that the compiler would guarantee the API types we’d defined upfront, leaving us free to focus on more important things. One of the numerous upsides is that we can never break API compatibility by accident though changing an implementation detail.

With the cleanup of old unneeded functionality we were able to get rid of all the external dependencies. For a visual comparison of the difference, here’s the dependency graph from the old & new versions using NPM’s handy lscommand.

Old 😞

New 😁

Summary

The advantage of doing a rewrite was two fold:

1. We got to remove all the old APIs and functionality that isn’t needed in a web search client, bringing the size down a cool order of magnitude from 40k to 4k while simultaneously simplifying the interface. Since this library is used in all of our integrations and interfaces all savings are multiplied.
2. Upgrade to TypeScript & ES modules. This enabled us to generate documentation with types without needing to hand annotate docstrings for every function and value, as well as be confident that we’re avoiding a whole class of possible bugs.

Where to next?

Our JS SDK was the first on a list of SDKs that we’re updating and improving in order to help developers and end users get the most out of Sajari. We upgraded the language that it was written in, removed old functionality, improved the API, and cut the size down by 90%.

Next up: our React SDK!

‍