WIP: docs for usertypes feature.

Author: rspeele

doc/Language/MissingFeatures.md

@@ -36,7 +36,6 @@ work on this project [a long time](https://www.youtube.com/watch?v=izQB2-Kmiic):
 * Interpreted in-memory implementation of each DB backend, for easy unit testing
 * Linq-ish query builder using the type provider's database model
 * Statically typed (w/ schema) JSON/XML access
-* Custom data types (e.g. Postgres range types)
 
 ## In my nightmares
 

doc/Language/UserTypes/README.md

@@ -0,0 +1,47 @@
+# UserTypes
+
+The UserTypes feature allows you to bring custom .NET data types into RZSQL by pointing the type provider at your own assemblies.
+
+This allows you to:
+
+1. Model your domain better, getting columns typed as `EmailAddress` instead of `string`, `UserId` instead of `Guid`, and so on.
+2. Make query result row types implement your interfaces. All your queries against the `User` table can return rows implementing an `IUser` interface you define, so you can write consumer code that works on all of them.
+3. Remap built-in types to other storage formats. For example, RZSQL's default handling for DateTime in SQLite is to store an ISO8601 string. If you prefer to store it as an integer Unix time, you can do that with a UserType mapping.
+4. Store and retrieve data from backend-specific column types RZSQL doesn't natively support, like Postgres `point` or TSQL `geography`.
+
+## The layout
+
+This is how a solution with UserTypes might look:
+
+![](SolutionLayout.gv.svg)
+
+The user types you wish to use MUST be in a separate assembly from your SQL queries, and must build first.
+
+The type provider cannot "see" types defined in the same assembly it's trying to compile. They don't exist yet!
+
+Referencing Rezoom.SQL.Annotations is optional. This is a lightweight package that only defines attribute classes.
+Those attributes give you more control over how your custom-mapped UserTypes are translated to SQL.
+
+## Mapping your own primitive types
+
+STUB
+
+## Mapping externally owned primitive types
+
+STUB
+
+## Row interfaces
+
+STUB
+
+## Mapping to vendor-specific database column types
+
+STUB
+
+## Annotation attributes reference
+
+STUB
+
+## Pitfalls to know about
+
+STUB

doc/Language/UserTypes/SolutionLayout.gv

@@ -0,0 +1,47 @@
+// dot -Tsvg -O SolutionLayout.gv
+digraph "Solution Layout" {
+  rankdir=BT
+  node[shape=plaintext,fontname=Consolas]
+
+  rzsql[label=<
+    <table border="3" cellborder="1" cellspacing="0" cellpadding="14" bgcolor="lightblue">
+      <tr><td cellpadding="2">NuGet</td></tr>
+      <tr><td><b>Rezoom.SQL.Provider</b></td></tr>
+    </table>
+  >]
+
+  annot[label=<
+    <table border="3" cellborder="1" cellspacing="0" cellpadding="14" bgcolor="lightblue">
+      <tr><td cellpadding="2">NuGet</td></tr>
+      <tr><td><b>Rezoom.SQL.Annotations</b></td></tr>
+    </table>
+  >]
+
+  { rank=same; rzsql; annot; }
+
+  utl[label=<
+    <table border="3" cellborder="1" cellspacing="0" cellpadding="14">
+      <tr><td><b>YourProject.UserTypes.fsproj</b></td></tr>
+      <tr><td align="left">type IUser = abstract member Id : UserId...</td></tr>
+      <tr><td align="left">type UserId = UserId of int</td></tr>
+      <tr><td align="left">[&lt;SQLTypeLength(254)&gt;]<br align="left"/>type EmailAddress = EmailAddress of string</td></tr>
+      <tr><td align="left">type System.TimeOnly with member this.ToPrimitive() = this.ToString(&quot;o&quot;)...</td></tr>
+    </table>
+  >]
+
+  tpu[label=<
+    <table border="3" cellborder="1" cellspacing="0" cellpadding="14">
+      <tr><td colspan="2"><b>YourProject.SQLQueries.fsproj</b></td></tr>
+      <tr><td>rzsql.json</td><td align="left">{ &quot;UserTypes&quot;: [&quot;YourProject.UserTypes&quot;] }</td></tr>
+      <tr><td>V1.model.sql</td><td align="left">create table Users(Id UserId primary key, Email EmailAddress, ...)</td></tr>
+      <tr><td rowspan="3">Query.fs</td><td align="left">type MyQuery = SQL&lt;&quot;select&lt;IUser&gt; * from Users where Id = @id&quot;&gt;</td></tr>
+      <tr><td align="left">let rows = MyQuery.Command(id = UserId 123).Execute(connection)</td></tr>
+      <tr><td align="left">let user = rows.[0] :&gt; IUser</td></tr>
+
+    </table>
+  >]
+
+  tpu -> utl
+  tpu -> rzsql
+  utl -> annot
+}