Multiple, independent, and ordered sortKey and orderBy directions

[airhorns]

The API for sortKey right now lets you sort by multiple keys but only in one direction for all of them, which is a bit limiting, especially if you want to let API consumers pass arbitrary sorts or lists of sorts to paginated connections. orderBy lets you sort by as many keys as you like with independent directions per key -- I think sortKey should support the same!

This changes the API for sortKey from this:

{
  order: "asc",
  key: ["created_at", "id"]
}

to this:

[
  {order: "asc", key: "created_at"},
  {order: "asc", key: "id"},
]

which is more expressive, allowing different orders per key, and keeps the key property of ordering the keys so we know which to sort by first. orderBy's object syntax kind of has that implicitly from object iteration order, but this makes it explicit which I think is better and less surprising.

The API is backwards compatible, if an object is passed to sortKey the old logic that applies the one order to all the keys will still run, and the new format only kicks in if an array is passed. 🎈

I considered using orderBy's same style of {[key: string]: Order} but I think this is more explicit. Relying on object insertion order to power super key API semantics like how things are sorted seems a little haphazard to me, and it means that the SQL output becomes super dependent on how an ordering thunk is implemented, not just it's output. To be honest I'd consider switching orderBy to be consistent and use the same explicitly ordered array of key/order pairs. An array of strings would also be good to support things like #321 and #313. If #418 means a big breaking change, it might be a good time to swap in that behaviour. Again, if an array were used, I think it'd be possible to make the API change backwards compatible way so people migrating to 3.0 didn't have to change their code just to make my API design OCD satisfied, but for new people integrating join-monster things would be that much better.

[ennoente]

Hey there,
I like the idea! Gonna check it out and test it.
We should definitely upgrade/migrate to graphql 15

[lorensr]

This is great! I think I'd deprecate the object syntax in the docs for now, and then in a later release, remove the code for it.

[airhorns]

Do you folks want to land a similar change for orderBy too for a 3.0 release?

[lorensr]

Yeah, would be good for the recommended APIs to match

[airhorns]

Ok. this is updated to change both sortKey and orderBy to look a bit similar. The new APIs for both use {column: string, direction: "asc" | "desc"}[] arrays to specify the sort / order verbosely, but both still accept the old style too. I think for orderBy the old style is still really handy for simple cases where you only want to order by one column, so I left the documentation for that around, establishing it as a shorthand instead of deprecated. For sortKey however I don't think it's quite the same. I have a couple test fails to chase down but it's fully working on Postgres!

[airhorns]

This sucker is good to go!

[alexbbt]

This looks good to me!

[lorensr]

Thanks again airhorns! Published in join-monster@3.0.0-alpha.2