api: add buildAndCompile helpers

Author: adz

README.md

@@ -39,15 +39,13 @@ let addressSchema =
     |> field "city" _.City
     |> build
 
-let personSchema =
+let codec =
     define<Person>
     |> construct makePerson
     |> field "id" _.Id
     |> field "name" _.Name
     |> fieldWith "home" _.Home addressSchema
-    |> build
-
-let codec = Json.compile personSchema
+    |> Json.buildAndCompile
 let person =
     {
         Id = 42
@@ -76,13 +74,13 @@ That schema reads almost like the data constructor:
 
 The result is not hidden serializer behavior. It is the contract itself, written in normal F#.
 
-If you want the compile step to read a bit smaller in samples, the format modules also expose `Json.codec`, `Xml.codec`, `Yaml.codec`, and `KeyValue.codec` as direct aliases for `compile`.
+If the schema only exists inline at the end of the authoring pipeline, `Json.buildAndCompile`, `Xml.buildAndCompile`, `Yaml.buildAndCompile`, and `KeyValue.buildAndCompile` make that terminal step easier to scan. Keep `Json.compile personSchema` when the named schema is reused.
 
 ## Why use it
 
 - The schema mirrors the data, so changes to the wire contract are visible in one place.
 - Encode and decode come from the same definition, so drift is harder to introduce accidentally.
-- `Json.compile` / `Json.codec` and `Xml.compile` / `Xml.codec` reuse the same schema instead of making you maintain separate mappings.
+- `Json.compile` and `Xml.compile` reuse the same schema instead of making you maintain separate mappings.
 - Domain refinement stays explicit through `Schema.map` and `Schema.tryMap` instead of being buried in serializer settings.
 - Versioned message and config contracts stay deliberate because the wire shape is authored directly.
 

docs/GETTING_STARTED.md

@@ -31,15 +31,26 @@ define<'T>
 |> build
 ```
 
-Compile explicitly and reuse the resulting codec:
+When the schema is named and reused, compile explicitly and keep the resulting codec:
 
 ```fsharp
 let codec = Json.compile personSchema
 let json = Json.serialize codec person
 let roundTripped = Json.deserialize codec json
 ```
 
-The format modules also expose `Json.codec`, `Xml.codec`, `Yaml.codec`, and `KeyValue.codec` as direct aliases for the corresponding `compile` functions. This tutorial uses the shorter `*.codec` form in the small examples to reduce noise, but the separate `compile` step is still the important performance habit: compile once, keep the codec, and reuse it.
+When the schema only exists to feed one inline pipeline, end the authoring flow with the format-specific `buildAndCompile` helper:
+
+```fsharp
+let codec =
+    define<Person>
+    |> construct makePerson
+    |> field "id" _.Id
+    |> field "name" _.Name
+    |> Json.buildAndCompile
+```
+
+Use `buildAndCompile` to make inline examples easier to scan. Use `Json.compile personSchema` when the schema itself is named, linked from other schemas, or reused across multiple codecs.
 
 ## How to read a schema
 
@@ -61,14 +72,12 @@ open CodecMapper.Schema
 type Person = { Id: int; Name: string }
 let makePerson id name = { Id = id; Name = name }
 
-let personSchema =
+let jsonCodec =
     define<Person>
     |> construct makePerson
     |> field "id" _.Id
     |> field "name" _.Name
-    |> build
-
-let jsonCodec = Json.codec personSchema
+    |> Json.buildAndCompile
 
 let person = { Id = 1; Name = "Ada" }
 let json = Json.serialize jsonCodec person
@@ -86,7 +95,7 @@ Output:
   Name = "Ada" }
 ```
 
-This tutorial keeps using the shorter `Json.codec` spelling in the small snippets:
+This tutorial uses `Json.buildAndCompile` for the small inline snippets:
 
 ```fsharp
 open CodecMapper
@@ -95,17 +104,15 @@ open CodecMapper.Schema
 type Person = { Id: int; Name: string }
 let makePerson id name = { Id = id; Name = name }
 
-let personSchema =
+let jsonCodec =
     define<Person>
     |> construct makePerson
     |> field "id" _.Id
     |> field "name" _.Name
-    |> build
-
-let jsonCodec = Json.codec personSchema
+    |> Json.buildAndCompile
 ```
 
-In longer-lived application code, prefer keeping the explicit `Json.compile personSchema` shape when you want to emphasize that the codec should be created once and reused.
+When you keep the schema in a named value, prefer the explicit `Json.compile personSchema` shape so the reuse boundary stays obvious.
 
 ## Starting from C#
 

docs/HOW_TO_MODEL_A_BASIC_RECORD.md

@@ -9,14 +9,12 @@ open CodecMapper.Schema
 type Person = { Id: int; Name: string }
 let makePerson id name = { Id = id; Name = name }
 
-let personSchema =
+let codec =
     define<Person>
     |> construct makePerson
     |> field "id" _.Id
     |> field "name" _.Name
-    |> build
-
-let codec = Json.codec personSchema
+    |> Json.buildAndCompile
 ```
 
-This is the smallest authored schema shape: define the record target, provide the constructor, then map each field explicitly.
+This is the smallest authored schema shape: define the record target, provide the constructor, then map each field explicitly and finish with `Json.buildAndCompile`.

src/CodecMapper/Json.fs

@@ -1378,8 +1378,14 @@ module Json =
         }
 
     ///
-    /// `codec` is the shorter authoring alias for `compile`, so examples can
-    /// stay explicit about the compile step without repeating the longer name.
+    /// Inline schema pipelines read more clearly when the final `build` and
+    /// JSON compile step collapse into one terminal pipeline stage.
+    let inline buildAndCompile (builder: Builder<'T, 'T>) : Codec<'T> =
+        builder |> Schema.build |> compile
+
+    ///
+    /// `codec` remains as the shorter schema-to-codec alias for callers that
+    /// prefer the direct `compile schema` shape without the longer name.
     let codec (schema: Schema<'T>) : Codec<'T> = compile schema
 
     /// Serializes a value to JSON using a previously compiled codec.

src/CodecMapper/KeyValue.fs

@@ -304,8 +304,14 @@ module KeyValue =
     let compile (schema: Schema<'T>) : Codec<'T> = compileUsing Options.defaults schema
 
     ///
-    /// `codec` keeps the default-key-path compile step explicit while giving
-    /// config examples the same shorter shape as the JSON and XML helpers.
+    /// Inline schema pipelines read more clearly when the final `build` and
+    /// key/value compile step collapse into one terminal pipeline stage.
+    let inline buildAndCompile (builder: Builder<'T, 'T>) : Codec<'T> =
+        builder |> Schema.build |> compile
+
+    ///
+    /// `codec` remains as the shorter schema-to-codec alias for callers that
+    /// prefer the direct compile step under the default options.
     let codec (schema: Schema<'T>) : Codec<'T> = compile schema
 
     /// Serializes a value to a flat key/value map using a previously compiled codec.

src/CodecMapper/Xml.fs

@@ -719,8 +719,14 @@ module Xml =
         }
 
     ///
-    /// `codec` mirrors `Json.codec` so multi-format examples can keep the same
-    /// explicit compile step while using a shorter, copy-paste-friendly name.
+    /// Inline schema pipelines read more clearly when the final `build` and
+    /// XML compile step collapse into one terminal pipeline stage.
+    let inline buildAndCompile (builder: Builder<'T, 'T>) : Codec<'T> =
+        builder |> Schema.build |> compile
+
+    ///
+    /// `codec` mirrors `Json.codec` for callers that still prefer the direct
+    /// schema-to-codec alias over the longer `compile` name.
     let codec (schema: Schema<'T>) : Codec<'T> = compile schema
 
     /// Serializes a value to XML using the schema-derived root element name.

src/CodecMapper/Yaml.fs

@@ -380,8 +380,14 @@ module Yaml =
         }
 
     ///
-    /// `codec` mirrors the other format modules so config-oriented examples
-    /// can keep the compile step explicit without extra visual noise.
+    /// Inline schema pipelines read more clearly when the final `build` and
+    /// YAML compile step collapse into one terminal pipeline stage.
+    let inline buildAndCompile (builder: Builder<'T, 'T>) : Codec<'T> =
+        builder |> Schema.build |> compile
+
+    ///
+    /// `codec` mirrors the other format modules for callers that still prefer
+    /// the shorter schema-to-codec alias over the longer `compile` name.
     let codec (schema: Schema<'T>) : Codec<'T> = compile schema
 
     /// Serializes a value to YAML using a previously compiled codec.

tests/CodecMapper.Tests/SchemaDslTests.fs

@@ -89,8 +89,17 @@ let ``Round-trip list of strings JSON`` () =
     test <@ decoded = value @>
 
 [<Fact>]
-let ``Codec aliases mirror compile helpers across formats`` () =
-    let personSchema =
+let ``buildAndCompile composes build and compile across formats`` () =
+    let person = {
+        Id = 7
+        Name = "Alias"
+        Home = {
+            Street = "Codec Street"
+            City = "Adelaide"
+        }
+    }
+
+    let jsonCodec =
         Schema.define<Person>
         |> Schema.construct makePerson
         |> Schema.field "id" _.Id
@@ -103,26 +112,62 @@ let ``Codec aliases mirror compile helpers across formats`` () =
              |> Schema.field "street" _.Street
              |> Schema.field "city" _.City
              |> Schema.build)
-        |> Schema.build
+        |> Json.buildAndCompile
 
-    let person = {
-        Id = 7
-        Name = "Alias"
-        Home = {
-            Street = "Codec Street"
-            City = "Adelaide"
-        }
-    }
+    let xmlCodec =
+        Schema.define<Person>
+        |> Schema.construct makePerson
+        |> Schema.field "id" _.Id
+        |> Schema.field "name" _.Name
+        |> Schema.fieldWith
+            "home"
+            _.Home
+            (Schema.define<Address>
+             |> Schema.construct makeAddress
+             |> Schema.field "street" _.Street
+             |> Schema.field "city" _.City
+             |> Schema.build)
+        |> Xml.buildAndCompile
 
-    let json = Json.serialize (Json.codec personSchema) person
-    let xml = Xml.serialize (Xml.codec personSchema) person
-    let yaml = Yaml.serialize (Yaml.codec personSchema) person
-    let keyValue = KeyValue.serialize (KeyValue.codec personSchema) person
+    let yamlCodec =
+        Schema.define<Person>
+        |> Schema.construct makePerson
+        |> Schema.field "id" _.Id
+        |> Schema.field "name" _.Name
+        |> Schema.fieldWith
+            "home"
+            _.Home
+            (Schema.define<Address>
+             |> Schema.construct makeAddress
+             |> Schema.field "street" _.Street
+             |> Schema.field "city" _.City
+             |> Schema.build)
+        |> Yaml.buildAndCompile
+
+    let keyValueCodec =
+        Schema.define<Person>
+        |> Schema.construct makePerson
+        |> Schema.field "id" _.Id
+        |> Schema.field "name" _.Name
+        |> Schema.fieldWith
+            "home"
+            _.Home
+            (Schema.define<Address>
+             |> Schema.construct makeAddress
+             |> Schema.field "street" _.Street
+             |> Schema.field "city" _.City
+             |> Schema.build)
+        |> KeyValue.buildAndCompile
+
+    let json = Json.serialize jsonCodec person
+    let xml = Xml.serialize xmlCodec person
+    let yaml = Yaml.serialize yamlCodec person
+    let keyValue = KeyValue.serialize keyValueCodec person
 
-    test <@ Json.deserialize (Json.codec personSchema) json = person @>
-    test <@ Xml.deserialize (Xml.codec personSchema) xml = person @>
-    test <@ Yaml.deserialize (Yaml.codec personSchema) yaml = person @>
-    test <@ KeyValue.deserialize (KeyValue.codec personSchema) keyValue = person @>
+    test <@ Json.deserialize jsonCodec json = person @>
+    test <@ Xml.deserialize xmlCodec xml = person @>
+    test <@ Yaml.deserialize yamlCodec yaml = person @>
+    test <@ KeyValue.deserialize keyValueCodec keyValue = person @>
 
 [<Fact>]
 let ``Round-trip mapped type (PersonId) JSON`` () =