Introduce PgRegistry; codecs own relations; type overhaul

[benjie]

First: the term "source" is overused, so we've renamed PgSource to PgResource. I'll try and refer to "resources" rather than "sources" from here on out. We've also renamed PgTypeCodec to simply PgCodec.

We want the schema to be exportable, which means the underlying "resources" need to be exportable. The resources relate to other resources, and sometimes these relations form circular dependencies, e.g. User.posts -> Post and Post.author -> User. When we try and export these we can't, because we can't define const User = ... without first defining Post, and we can't define const Post = ... without first defining User. How to solve?

Initially I solved this with a PgSourceBuilder. This was a precursor to a PgSource (now PgResource) - everything except the relationships - and then relationships could be to either a PgSource directly or to a PgSourceBuilder that would later "become" a PgSource (via PgSourceBuilder.get()). Code throughout the codebase had to say "if it's a PgSourceBuilder, .get() it, otherwise use it directly" and it was ugly. I didn't like it, and concluded that "relations" should be a separate thing (see #117).

From discussion with @jemgillam we realised that we could significantly simplify things by building first the codecs, then the resources, then the relations... But that accessing the relations would be painful, and more importantly the relations might not export along side everything else, which might cause the exported schema to be incomplete. Clearly not viable. We needed something that was interlinked with circular dependencies at runtime, but that was produced without circular dependencies at build time... We needed a registry!

The registry

The idea with the registry is simple: we take a list of codecConfigs, resourceConfigs, and relationshipConfigs (all without circular dependencies - a directed acyclic graph) and then we build from that a structure (the "registry") that contains the built codecs, resources and relationships which can link back to the central registry. So the "resources" don't actually "know" their relationships - they just know the "registry" which stores all the relationship data. And the registry itself is built via a factory function which we can export with the raw configs as input and no circular dependency issues.

graph TD
   PgCodecConfig
   PgResourceConfig
   PgRelationshipConfig
   PgRegistry
   PgCodec
   PgResource
   PgRelationship

   PgCodecConfig --> PgResourceConfig
   PgResourceConfig --> PgRelationshipConfig
   PgCodecConfig --> PgRelationshipConfig
   PgCodecConfig ---> PgRegistryConfig
   PgResourceConfig ---> PgRegistryConfig
   PgRelationshipConfig ---> PgRegistryConfig

   PgRegistryConfig -->|build| PgRegistry

   PgRegistry --> PgCodec
   PgCodec --> PgResource
   PgRegistry --> PgResource
   PgRegistry --> PgRelationship
   PgResource --> PgRegistry
   PgCodec --> PgRelationship
   PgResource --> PgRelationship

Loading

This also meant that we could maintain the types much better:

(Early screenshot, API has changed slightly.)

And also, the mixture of PgSource/PgSourceBuilder has been cleared up via the following rules:

• PgResourceOptions is generated during the "gather" phase, you don't deal with PgResource directly during gather (until the very end when the PgRegistry is built)
• PgResource is consumed during the "schema" phase, you don't deal with PgResourceOptions during the "schema" phase at all.

So no more hacky resolveSource()/sourceBuilder.get() nonsense!

Lots of breaking changes

• TypeScript v5 required, we use satisfies and const-generics
• PgSourceBuilder is no more (but it has effectively been replaced with PgResourceOptions)
• PgSource* -> PgResource*
• PgTypeCodec* -> PgCodec*
• PgTypeColumn* -> PgCodecAttribute*
• listOfType -> listOfCodec
• The generics on PgResource and PgCodec have changed significantly - the first generic is now a name (string) which allows us to build up the registry nicely
• Now that codecs own relationships, this has been reflected in the relationship inflectors; they no longer accept {resource, relationName}, instead accepting {registry, codec, relationName}. (Note: registry = resource.registry, codec = resource.codec.)
  • singleRelation
  • singleRelationBackwards
  • _manyRelation
  • manyRelationConnection
  • manyRelationList

Fixes #117