Document Selector (Fixes #70)

site-in/customization/customize-selected-relations.md

@@ -0,0 +1,54 @@
+---
+title: Customize selected relations
+---
+
+
+You typically have many more relations in your database than you want to expose to application code.
+Maybe you're generating code for just a part of the system, not the whole thing.
+
+Typo has a mechanism by which you can choose which relations to generate code for.
+
+among the arguments to `generateFromDb` is `selector`, which by default picks all relations except those in the postgres schemas.
+
+```scala
+import typo.*
+
+generateFromDb(options, selector = Selector.ExcludePostgresInternal)
+```
+
+## `Selector`
+
+You can pick relations by expressing with `Selector` what you want:
+```scala mdoc:silent
+import typo.*
+
+val personAndPet = Selector.relationNames("person", "pet") // picks these regardless of schema
+val mySchema = Selector.schemas("myschema") // picks all relations in schema
+
+// heaviest syntax, but most flexible
+val custom: Selector = relName => relName.schema.exists(_.contains("foo")) && relName.name.contains("bar")
+```
+
+Selectors are also composable:
+
+```scala mdoc:silent
+// picks relations which are called `person` or `pet` AND are in the `myschema` schema
+personAndPet and mySchema
+
+// picks those who are *both* called `person` or `pet` OR are in the `myschema` schema. 
+// This will typically select more relations
+personAndPet or mySchema 
+```
+
+The and/or names follows boolean logic, and may actually be a bit counter-intuitive in this particular context. Suggestions welcome to improve naming
+
+## Transitive relations
+
+So in Typo we say that relations have dependencies, see [flow typing](type-safety/type-flow.md). 
+
+Say you have some [sql files](what-is/sql-is-king.md) and have chosen some relations, and some of those have dependencies on other relations.
+Typo can optionally generate code for these dependencies as well. 
+
+If you want that, you can  [customize](customization/overview.md) Typo and set the `keepDependencies` parameter to `true` to generate code for those dependencies as well. 
+
+`keepDependencies` is set to `false` by default. If it's left at `false`, you'll only see the [primary key types](type-safety/id-types.md) for those relations

site-in/other-features/faster-compilation.md

@@ -5,7 +5,14 @@ title: Focus on fast(er) compiles
 If you have a big database schema, Typo can easily produce tens to hundreds of thousands of lines of code.
 And it's all full of implicit type class instances.
 
-The following measures have been taken to compile code fast
+## Limit how much code is generated
+
+The main thing you can affect is to ask for less code to be generated. 
+
+This is done by [customizing selected relations](customization/customize-selected-relations.md).
+
+## The following measures have been taken to compile code fast 
+
 - work around auto-derivation which takes precedence over instances in companion objects. 
 For doobie it's the case the `Read`-instances, for example, are re-rederived instead of found on the companion object. 
 - inlined ~all implicits to save the resolving time

site-in/setup.md

@@ -62,13 +62,18 @@ val targetDir = location.resolve("myproject/src/main/scala/org/foo/generated")
 // where Typo will look for sql files
 val scriptsFolder = location.resolve("sql")
 
-generateFromDb(options, scriptsPaths = List(scriptsFolder))
+// you can use this to customize which relations you want to generate code for, see below
+val selector = Selector.ExcludePostgresInternal
+
+generateFromDb(options, selector = selector, scriptsPaths = List(scriptsFolder))
   .overwriteFolder(folder = targetDir)
 
 // add changed files to git, so you can keep them under control
 //scala.sys.process.Process(List("git", "add", targetDir.toString)).!!
 ```
 
+## `selector`
+You can customize which relations you generate code for, see [customize selected relations](customization/customize-selected-relations.md)
 ## sbt plugin
 
 It's natural to think an sbt plugin would be a good match for Typo. This will likely be added in the future.

site/sidebars.js

@@ -76,6 +76,7 @@ const sidebars = {
             collapsed: false,
             items: [
                 {type: "doc", id: "customization/overview"},
+                {type: "doc", id: "customization/customize-selected-relations"},
                 {type: "doc", id: "customization/customize-sql-files"},
                 {type: "doc", id: "customization/customize-naming"},
                 {type: "doc", id: "customization/customize-nullability"},