Working on a GraphQL Client Libary Based On Hiccup. Looking for early feedback

Hey all!

I am working on a graphql client based off hiccup-like data structures, calling it hql, for lack of a better name.

I think I have the “syntax” & transpiling to GraphQL queries are more/less completed. I think it is promising direction, given the library aims to be “closer to the metal” and tries stay true to how GraphQL queries look outside hiccup.

Still need to add support for cljs, as well as actual graphql over http clients.

Would appreciate any feedback or thoughts! :slightly_smiling_face:

1 Like

I took a look at the code. It’s really clean and the tests are nicely done. some thoughts:

  • do you really need spec.clj?
  • why this and not venia?

what do you mean by this?

Hey, thanks for taking the time to look over the code :slight_smile:

Those are great questions!

From a validation perspective, I do think so. I’d prefer to fail if the data doesn’t conform to what is expected. This would mainly manifest if a map was provided vs vectors, however, still is helpful.

Additionally, the runtime performance hit isn’t significant.

I had no idea venia existed. Tried to google “Clojure GraphQL Client” before I started on this, and it didn’t come up on my search results. Thanks for sending it along!

Most of the libraries I have come across only deal w/ parsing hiccup to graphql queries, leaving http client implementation up to the consumer of the library.

I would like a tighter integration, meaning that the hql library will provide a query function which performs “graphql over http”. Additionally, in order for the client API to be unified (and more Clojure-y), I am planning on the responses (either via queries, mutations or subscritpions) to communicate their results via clojure.core.async channels, which I haven’t seen much in the wild (though I may be prey to the search issue above).

It may be more pain than its worth to include clients which can handle queries/subscriptions in hql, but I’d like to try it out and see how it plays.

To be honest, I don’t really think the http thing is anything special. They are encoding something that everyone is doing already. The first question to ask is: do you need it?

What would be cool if you can provide a parser from GraphQL to hiccup and back.

Another thing would tight integration with a relational schema library for generating the graphs to then do actual sql generation.

Valid criticism & good question.

As far as the question of needing it, I think it depends. I have seen comments/issues raised on libraries both in clojure and out of it that critique either a “too much” approach or “too little”.

In this instance, while it may not be intrinsically needed, I would rather explore having a library/client which is homogeneous and can be extended/built upon, rather than leaving that as an exercise for a consumer of hql.

Those would be cool, and at the very least, a GraphQL → hiccup parser would be in scope for a project like this, albeit down the road.

I think you are a really great coder but I don’t think you understand WHY graphql is popular.

GraphQL spread because of Apollo and the way they do frontend caching, subscriptions and a bunch of stuff that is hard as hell, not to mention the sql transformations on the backend. That’s it. It’s not the specification itself or how you transform/transmit the query, it’s the underlying technology that makes it magic.

So to be perfectly honest, what you’ve done is pretty useless from a production standpoint when talking in terms of the graphql ecosystem. It may be a good tool to generate some pre-cached queries, but that’s about it.

Respectfully, that is quite the presumption, and not correct. There are many reasons for its popularity, some of which you have touched on some. I order to stay on topic here, I’ll not delve into my convictions on the technology.

I think this is getting off track. The fact is this library was put together in a couple days over a couple of weeks in order to tease out the hiccup syntax/idioms, not implement a full clj(s) framework. Getting feedback on the syntax/idioms was my main intention of this post, and what I am eager to collaborate on if anyone had feedback/other perspectives.

I have not claimed this is “production ready”, I have not claimed more than it is an early stage library. Even the whole http client/transport layer isn’t even implemented.

I don’t have a desire to continue our back and forth, as you’ve made you points clear. Therefore, I consider our exchange over.

look, I just think you’re being a bit disingenuous about wanting feedback. I’ve given you my feedback. You’re looking for praise.

You’re a great coder but I’m not that impressed with the library.

Not in the slightest, and is again very presumptuous. As I’ve said, I appreciate your input, and from my perspective you’ve made your points clear.

I appreciate the compliment, but that is not what this thread is about.

I know you’re not impressed, and again, that is not what I was looking for. I appreciate your bluntness, but there is no need for re-iteration on that point. You’ve made it very clear what features you’d expect out of a library/tool in the GraphQL ecosystem.

My earlier query still stands:

If you have feedback with respect to above, I am happy to hear you out! :slight_smile:

from the actual query, I would not use meta tags for mutations, subscriptions, etc as you want that to be explicit.

My issue is that there is no way to typecheck or prove that you have a correct query. So what are you going to do? Use spec on a relational model?

Also, it’s perfectly valid to describe a graph structure in json instead of graphql making the whole convention pretty useless.

Who are you interfacing with? would the consumer be at the ui side or the server side? These questions all go beyond the scope of what you’re asking for so feel free to ignore it. I’m not convinced by such a limited scope and if I’m not convinced I’m going to see this as just educational exercise, which is okay too.

1 Like

This is a great idea for a library! This is in fact something I’ve been toying about implementing at some point, but perhaps using a malli-like DSL instead.

Venia indeed is a great query library for GraphQL, what hql could stand to offer here is more compact representation and, if implemented properly, then also capability to produce arbitrary combination of mutations/queries/subscriptions all in one go.

Couple thoughts that come to mind looking at the library implementation (and roadmap):

  • aliasing syntax :&foo can easily get mixed up with implements interfaces part of the spec, I might try to model aliasing as a properties map instead
  • top level entities (subscription, mutation, etc.) should be keywords, not metadata, this makes the top-level entities composable with each other
  • sanitized input data? (did not read too hard into the code, but extremely important to have in a query library as part of the roadmap)
  • not sure about the websocket impl here, interested in rationale for this :slight_smile:

Also if you’re interested continuing this work more deeply, I would recommend thinking how the entire DSL should look like. There are two domains to think about: executable definitions and schema definitions/extensions. The former is something you definitely want to think about in its entirety beforehand. Depending a bit on the tightness of your scope, you may or may not want to model the entire GraphQL schema spec with hiccup representation (at least to park the ideas in your head).

Finally, I would scope out pretty printing unless you absolutely need it. :slight_smile: For example, if you’re matching against a production-grade formatter such as prettier, then you’ll have a lot of work ahead of you.

If you’re curious what kinds of graphql queries you can actually construct, I found this one to be pretty useful: prettier/tests/format/graphql at main · prettier/prettier · GitHub (also works as a fountain of information if you do end up implementing pretty formatting)

Hope this was useful :slight_smile:


Lots o’ good info here, thank you for taking the time!

From my current knowledge, websocket’s are a core piece of subscriptions, hence why I mentioned it. Not sure how much it is used in the wild.

Yeah, agree w/ you and @zcaudate1 on this.

The spec’s are something I was not implementing against (more-so example queries via the walkthrough examples on the GraphQL site), though is really helpful to craft an approach.

I think all in all, I have been a bit eager in posting this, which I think overall has been a good thing. It has made me realize there are a lot of pieces to have right before it can be usable in the GraphQL space, when writing any sort of DSL interface over another, something I thought would be more straightforward than laid out by @zcaudate1 and yourself.

I really appreciate the feedback on the syntax, as well as perspectives on what features would make a GraphQL library viable in the clj(s) ecosystem.

As a final thought, in posting this, I didn’t consider the overall scope, which is more than I can handle in the foreseeable future. Therefore, this can be chalked down to an education exercise, until I have done a deeper dive into the spec (have done superficial scans) and use cases in the wild beyond a hunch.

Agreed! Better interface using maps.

There has been a tension in me with respect to this. It can easily be seen as hiccup for hiccup’s sake.

Yeah, given the insight/perspective from you and @ilmoraunio, I think this is, and will be, an educational exercise. I don’t think i have the time to undertake a fully fledged GraphQL client impl, given I was ignorant of all the pieces which need to be in place for something like this to be viable in the ecosystem.

The type checker is not as difficult as you might expect depending on how you tackle the problem. It’s mainly a lot of tree-walking on a relation schema. If it’s about generating queries, then it’s pretty useful → say as an interface to Hasura.

The caching IS hard. I don’t recommend an end to end client.

In case someone is interested, I decided to take up the challenge of writing a malli-inspired DSL to represent GraphQL queries. Please have a look :slight_smile:


This topic was automatically closed 182 days after the last reply. New replies are no longer allowed.