Documentation recommendation

For starters: love what you’ve done here. Definitely fills a need, so I want this lib to be successful.

But I think the README is structured poorly, to the point of being alienating to a potential new user.

This is the first bit of code in the readme:

const rows = await select(list.id, list.createdAt)
  .from(list)
  .where(list.createdAt.gt(now().minus(`2 days`)).or(list.value.eq(0)))
  .limit(10);

What’s “list” and where does it come from? It just appears in your sample code. How do you import the module?

After reading the full readme the picture becomes clear(ish) but you should start the Readme with the “Schema” section so its clear how to define a Mammoth class (and how you provide static type information to Typescript) before talking about operations you can make using that class.

This lib deserves more attention than it’s getting currently! Keep up the good work! I ended up here after you got a shoutout here: https://news.ycombinator.com/item?id=22739121 so I expect many people are discovering this at the moment.

PS Shouldn’t “list” be capitalized in most of the sample code?

[martijndeh]

Thank you! I appreciate the advice and I agree it causes confusion. I have spent too little effort on getting the docs and any other getting started content in shape which makes it really hard to start using this library. I’ll clear this up in the coming days!

I think this library is nearing feature parity with e.g. knexjs (but postgres only). I’m working on subqueries right now and CTEs are next. But everything is type-safe which is awesome of course! 😉

[martijndeh]

Still nothing about how to import the module. On a related note: for some reason a bunch of functions (uuid, createTable) aren’t being exported in the module. I looked at your code and couldn’t figure out why this was happening…it’s pretty odd.

I clarified the install procedure. The changes are available under a beta tag in npm. So to install you have to run npm i @ff00ff/mammoth@1.0.0-beta.9. Does this fix the issue for you?

You may want to consider generating the db object with code generation, it would let you do things like inferred relation types (including recursive relations) and a better .select API like the one used in mst-gql where you just “dot together” all the fields you want. Can’t be done with just type inference sadly since it requires a custom getter defined for each property.

The thing I wanted to avoid with mammoth is having to need a build step or watch running. If we ever add a build step, considering one of the other goals is trying to stick to SQL as close as possible (because that’s what we all know, and that knowledge is reusable across projects), it probably makes most sense to generate types for raw queries and define your schema using, again, raw SQL (in for example migrations). So I don’t think this project will ever get a build step.

You should write up a blog post complaining about the dangers of non-type safe database access without static type guarantees, yadda yadda, then tell people about this lib.

Yea this is coming. 😃

Is the CLI implemented? Documentation? If you’re still working on it you may want to look at the code for Prisma’s CLI, which supports Postgres introspection. You may be able to use some of their code to convert a SQL schema to a structured representation in Javascript-land.

The CLI needs some love. There is an initial version but I’m rewriting the automatic migration generator. It used to have a custom query parser, but now I’m switching to the actual postgres query parser. I’ll have a look at Prisma! I did check TypeORM, but I noticed they’re actually using the local typeorm models and the schema of the database to diff changes. I think it makes more sense to diff the migrations and the local table files.

---

Thanks for the feedback. Feel free to improve the readme by creating a pull request. 😉 I’m also going to set up a documentation site to include some of the use cases you’re mentioning.