Clean up dead draft version of usertypes doc that was inlined in rzsql.json doc.

Author: rspeele

doc/Configuration/Json.md

@@ -119,103 +119,23 @@ _default: `[]`_
 
 This optional setting allows you to bring your own types into RZSQL's type system.
 
-I like to use a lot of little wrapper types in my domain layer.
-
-Instead of `string`, I might have an `EmailAddress` type. Instead of passing around `int` IDs, I like to have `UserId` and `GroupId` and `CompanyId` and so on.
-
-This allows validation rules to live in the type's constructor, it makes methods self-documenting,
-and it creates a compiler error if I accidentally call `service.AddUser(userId, companyId)` when that method is supposed to take `(companyId, userId)`.
-
-By default though, RZSQL only understands the handful of built-in SQL primitives described in [Language/Data Types](../Language/DataTypes.md).
-
-If we put our user type definitions in a separate assembly, reference that assembly from the project where our SQL
-model+queries live, and add the assembly name to the `"usertypes"` list in rzsql.json, Rezoom SQL can use any user type that wraps a supported underlying primitive.
-
 Reference the assembly full name in rzsql.json like so:
 
 ```javascript
   "usertypes": ["MyProduct.MyCustomTypesAssembly"]
 ```
 
-You must also reference the MyProduct.MyCustomTypesAssembly project from your F# project where you're using Rezoom.SQL.Provider.
-
-The type provider will search the listed assemblies for user types with mappings to primitive types.
-
-A "primitive type" means any of the .NET types listed in the table at the top of [Language/Data Types](../Language/DataTypes.md).
-
-A user type is:
-
-* Any F# single-case union that wraps a primitive type, such as `type UserId = UserId of Guid`. `[<Struct>]` unions are also supported.
-* Or, any type `T` for which we find a class with static `ToPrimitive` and `FromPrimitive` methods mapping `T` to and from a primitive type.
-* Or, any type `T` for which we find F#-style extension methods `member this.ToPrimitive()` and `static member FromPrimitive(x)` mapping `T` to and from a primitive type.
-
-In the latter two cases, it should be noted that `T` does not HAVE to be a type that you own.
-
-For example, you can write ToPrimitive and FromPrimitive extension methods for `System.TimeOnly` in your UserTypes assembly, and then use `TimeOnly` in your SQL schema.
-
-User-type code:
-
-```fsharp
-// simple DU
-type UserId = UserId of System.Guid
-
-// custom mapping for a type defined elsewhere
-module TimeOnlyMapping =
-    type System.TimeOnly with
-        member this.ToPrimitive() =
-            this.ToString("o")
-        static member FromPrimitive(s : string) =
-            System.TimeOnly.ParseExact(s, "o")
-```
-
-SQL schema:
-
-```sql
-create table Employees
-( Id UserId primary key
-, Name string(80)
-, ShiftStarts TimeOnly
-, ShiftEnds TimeOnly
-);
-```
-
-The actual SQL that runs on your database will treat ShiftStarts and ShiftEnds as if you'd written `string`.
-
-Selecting from this table will give you a `TimeOnly` property in your result set rows from the type provider.
-
-Comparing to a parameter will cause that parameter to get a `TimeOnly` type inferred:
-
-
-```fsharp
-type MyQuery = SQL<"""
-select * from Employees where ShiftStarts = @t
-""">
-
-let usage =
-    MyQuery.Command(t = TimeOnly(0, 0, 0))
-```
-
-### Caveats and limitations
-
-It is not supported to define a custom primitive that is backed by multiple columns. ToPrimitive and FromPrimitive must convert to a single primitive object! There are no plans to add multi-column primitives in the future.
-
-It is not supported to define custom primitive mappings for a generic type. You cannot have `Id<User>` and `Id<Company>`. All custom-mapped types must be simple non-generic types.
-
-When implementing ToPrimitive you should not return a null, and when implementing FromPrimitive you do not need to handle nulls.
-You are defining the mapping for a non-null object. The mapping for a null / None object is always assumed to be null / None and cannot be overridden.
+Your F# project using the type provider must also reference the MyProduct.MyCustomTypesAssembly project.
 
-The ToPrimitive and FromPrimitive methods for any single UserType must be defined in the same class. You can't have
-`ToPrimitive(x : Foo) : int` in one class and `FromPrimitive(x : int) : Foo` in another class and have it work -- the
-assembly search will not detect `Foo` as a mapped UserType.
+Read [the full UserTypes feature documentation here](../Language/UserTypes/README.md).
 
-You must be aware of the underlying representation for usertypes when writing your SQL. For example, your custom type
-may override comparison operators, but SQL doesn't know about that, and indeed doesn't know about your custom type at
-all. It is erased to the underlying primitive at F# compile-time.
+You can reference multiple assemblies in this list. For example, you could have your primitive mappings in one assembly
+and your row interfaces in another.
 
-If you write `where ShiftStarts < @t and ShiftEnds > @t`, that comparison will be done on the underlying *string
-representation*! With the above example ToPrimitive and FromPrimitive methods using the "o" format string this will
-actually work fine, but a different representation might not hold up so well. So choose your underlying representation
-carefully and be mindful of how your queries are actually working.
+It is also supported to reference a path to a .dll file for the assembly. Paths will be resolved relative to the folder
+containing rzsql.json. However, it is generally better to use a project reference and just name the project, without
+path elements or the ".dll" extension. Otherwise you'll have issues where, for example, you're pointing at the path to
+the DLL under "debug", and your build breaks or pulls an outdated assembly when you're building in "release" mode.
 
 ---
 <!-- nav-bottom -->

doc/Language/UserTypes/README.md

@@ -33,7 +33,7 @@ Your UserTypes MUST be in a separate assembly from your SQL queries, and must bu
 The type provider cannot "see" types defined in the same assembly it's trying to compile. They don't exist yet!
 
 The fsproj where you're using Rezoom.SQL.Provider must have a project reference to your UserType project(s). It must
-**also** name those projects in [rzsql.json's](../../Configuration/Json.md) `"UserTypes"` list. This tells the type
+**also** name those projects in [rzsql.json's](../../Configuration/Json.md) `"usertypes"` list. This tells the type
 provider to search the listed assemblies at design-time to find your custom types.
 
 Referencing Rezoom.SQL.Annotations is optional. This is a lightweight package that only defines attributes.

doc/Language/UserTypes/SolutionLayout.gv

@@ -32,7 +32,7 @@ digraph "Solution Layout" {
   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>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(myGuid)).Plan()</td></tr>