There are however gems like this in the source:
https://github.com/gajus/slonik/blob/master/src/routines/exe...
You can spend an hour trying to reason about the control flow of that triple try/catch alone. Bonus points if that function can recursively call itself (not sure what retryTransaction can get up to).
There may be an explanation for this horrifying code, but it should probably be right above in the form of:
/*
* The following code is not for the weak minded.
*
* Great care needs to be taken with it, for even the smallest mistake
* risks summoning the gods of old to end all life on earth
* in the most terrible way imaginable.
*
* There is however no other way because a, b, and c.
*/
But at least afterwards a newcomer can fix a bug without endangering the multiverse.
Maybe a one liner comment would help, but exaggerating as if the code is some horrifying monstrosity is not helpful IMO. It just smells of elitism and makes the code seem more unapproachable than it really is.
Another nice thing about slonik is that it is built on top of https://github.com/brianc/node-postgres. One gets all the benefit of node-pg with the nicer dev experience of slonik.
I'm trying to decide between this, or writing my own helpers around https://github.com/felixfbecker/node-sql-template-strings.
Also, have you found anything the solves typechecking of embedded expressions inside the SQL template?
For example, Webstorm will help you autocomplete your SQL, but you can still type:
sql`SELECT * FROM foo WHERE barInt = ${bazStr}`
You may want to look at something like https://github.com/adelsz/pgtyped. The downside is that dynamic queries are more challenging.
We have been looking at moving over to pgtyped, but it will be a hard transition because we do a fair amount of building up queries at runtime.
Slonik does have a wonderfully smaller API surface and I sure do like writing SQL manually and getting to take advantage of various lower level benefits (ex. postgres JSON operations) without too much fuss/work arounds, but TypeORM also lets you drop to raw (but parametrized) SQL fairly quickly, and it's query builder is actually pretty good...
[0]: https://typeorm.io/
[1] https://github.com/felixfbecker/node-sql-template-strings
Ideally the system would require you to use the tag and prohibit a plain ol string.