ajarc

Ajar

Ajar is an O(1) fetch client for APIs that implement the OpenAPI specification. It consumes a generic interface generated by openapi-typescript-codegen and returns a fully typed, deeply nested object that maps to fetch calls.

const client = Ajar<paths>()

client.feeds.get()
client.user["500"].comments.post()
client.user["500"].posts["3"].get()

Because it is implemented almost entirely using TypeScript's extensive type system, Ajar is largely capable of 'dissolving' during code compilation. In your app's bundle, all that remains is a lightweight¹ core library that does not grow over time.

Currently, Ajar only implements a small subset of the OpenAPI specification², however it should be more than enough for almost every project.

How it works

Ajar makes use of JavaScript proxies to create an infinitely nested object, and each entry exposes a number of methods. This roughly maps to:

type AjarObject = {
    [key: string]: AjarObject
    get: () => {}
    post: () => {}
    ...
}

This object is then artificially restricted to a set of known paths using the type system. This approach is advantageous because it means there is no runtime growth.

Project status

Ajar is not currently usable. Almost all typing work has been completed, however the actual client is still a stub.

• 🟦 Extract response from paths
• 🟦 Generate basic chain type from a path
• 🟦 Generate a complete chained type from the paths type
• 🟨 Basic proxy
• 🟦 Support parameters in the chained type
• 🟨 Create basic fetch client inside the proxy callback
• 🟦 Type response
• ⭐ Regression tests

Credits

This project was heavily inspired by the hono client which pioneered our usage of proxies.

---

It all started with a message:

In the SolidJS discord, BTW ;)

Footnotes

1. When the core JavaScript is complete I'll have concrete numbers, however I'm positive it will not exceed 1kb. In addition, an optimization push will be made before every release ↩

2. Look: at the end of the day, Ajar was made to solve my problems. I hope it solves yours as well, but I can tell you right now that I've already spent enough time wrangling with typescript to last a lifetime (and I'm pretty young, for the record). I don't want to prematurely squander even more time solving edge cases people (or more likely, corporations) might encounter. I try to live my life in the now. I'm happy to accept PRs (and even issues I guess, though I might ask for a "donation") that help push Ajar closer to compliance, just know it's not a goal. ↩