Add small opt-in schema helpers

Author: adz

TASKS.md

@@ -17,11 +17,7 @@ Completed rename, parser, bridge, compatibility, JSON Schema, docs, and projecti
 
 - [x] **Task 29:** Split `src/CodecMapper/Library.fs` into explicit dependency-ordered files (`Core.fs`, `Schema.fs`, `Json.fs`, `JsonSchema.fs`, `Xml.fs`, `KeyValue.fs`, and `Yaml.fs`) and updated `CodecMapper.fsproj` to preserve the existing no-behavior-change compilation order.
 
-- [ ] **Task 31: Ergonomics without reflection**
-  - Keep the runtime DSL explicit and AOT/Fable-safe; do not introduce a second magic authoring path.
-  - Add small authoring helpers where they make the current DSL read smaller, such as compile aliases and more built-in validated/domain combinators.
-  - Prefer expanding safe static auto-resolution over making `fieldWith` implicit through runtime metadata.
-  - Keep `fieldWith` for true schema boundaries such as validated wrappers, imported contracts, and explicit child schemas.
+- [x] **Task 31:** Improved explicit authoring ergonomics without adding reflection or a competing magic DSL by shipping compile aliases plus opt-in validated helpers such as `Schema.nonEmptyString`, `Schema.trimmedString`, `Schema.positiveInt`, and `Schema.nonEmptyList`, with matching docs and regression coverage.
 
 - [x] **Task 32:** Added path-aware decode diagnostics across `Json`, `Xml`, `KeyValue`, and `Yaml`, including missing-field paths, collection indices/items, and `Schema.tryMap` validation context, with matching regression coverage in the unit test suite.
 

docs/GETTING_STARTED.md

@@ -280,6 +280,17 @@ let userIdSchema =
 
 Read `Schema.tryMap` as "decode the wire value first, then validate/refine it into a stronger domain type."
 
+For common opt-in boundary rules, `Schema` also exposes small validated helpers:
+
+```fsharp
+let userNameSchema = Schema.nonEmptyString
+let retryCountSchema = Schema.positiveInt
+let tagsSchema = Schema.nonEmptyList Schema.string
+let normalizedLabelSchema = Schema.trimmedString
+```
+
+These stay explicit authoring choices. They do not weaken the normal `Schema.string`, `Schema.int`, or `Schema.list` defaults.
+
 That schema can then be used inside larger records:
 
 ```fsharp
@@ -361,6 +372,7 @@ Still out of scope:
 - Prefer `Schema.field` when the type auto-resolves cleanly.
 - Use `Schema.fieldWith` when the nested or wrapped type has an explicit schema.
 - Use `Schema.tryMap` when decode needs validation.
+- Reach for `Schema.nonEmptyString`, `Schema.trimmedString`, `Schema.positiveInt`, and `Schema.nonEmptyList` when those boundary rules are part of the contract.
 - Keep schemas in one place so JSON and XML stay aligned.
 - Use [How To Export JSON Schema](HOW_TO_EXPORT_JSON_SCHEMA.md) when you need external schema documents.
 - Use [C# Attribute Bridge Design](CSHARP_ATTRIBUTE_BRIDGE.md) when you are importing existing C# contracts instead of authoring schemas directly.

src/CodecMapper/Schema.fs

@@ -138,6 +138,32 @@ module Schema =
             )
         )
 
+    ///
+    /// Empty strings are often accidental placeholders rather than meaningful
+    /// values. This helper keeps that validation explicit and reusable.
+    let nonEmptyString: Schema<string> =
+        string
+        |> tryMap
+            (fun value ->
+                if System.String.IsNullOrEmpty(value) then
+                    Error "string must not be empty"
+                else
+                    Ok value)
+            id
+
+    ///
+    /// Some contracts normalize surrounding whitespace at the boundary rather
+    /// than making every caller remember to trim before encode and after decode.
+    let trimmedString: Schema<string> =
+        string |> map (fun value -> value.Trim()) (fun value -> value.Trim())
+
+    ///
+    /// Positive identifiers and counters are a common wire-level constraint,
+    /// and `tryMap` keeps that rule opt-in rather than global.
+    let positiveInt: Schema<int> =
+        int
+        |> tryMap (fun value -> if value > 0 then Ok value else Error "int must be positive") id
+
     ///
     /// Narrow numeric types can safely reuse the integer codec as long as the
     /// schema enforces range checks on decode.
@@ -246,6 +272,18 @@ module Schema =
     /// Builds a schema for an F# list.
     let inline list (inner: Schema<'T>) : Schema<'T list> = create (List(inner :> ISchema))
 
+    ///
+    /// Some wire contracts require at least one item, but keeping that rule in
+    /// the schema is still clearer than scattering ad hoc list checks elsewhere.
+    let inline nonEmptyList (inner: Schema<'T>) : Schema<'T list> =
+        list inner
+        |> tryMap
+            (fun values ->
+                match values with
+                | [] -> Error "list must contain at least one item"
+                | _ -> Ok values)
+            id
+
     /// Builds a schema for an array.
     let inline array (inner: Schema<'T>) : Schema<'T[]> = create (Array(inner :> ISchema))
 

tests/CodecMapper.Tests/CustomizationTests.fs

@@ -42,3 +42,21 @@ let ``Smart-constructor wrapper rejects invalid decoded values`` () =
 
     expectFailure "XML decode error at $/id: Validation failed: UserId must be positive" (fun () ->
         Xml.deserialize xmlCodec "<account><id>0</id><name>Ada</name></account>")
+
+[<Fact>]
+let ``Opt-in validated helpers reject invalid scalar values`` () =
+    expectFailure "Validation failed: string must not be empty" (fun () ->
+        Json.deserialize (Json.compile Schema.nonEmptyString) "\"\"")
+
+    expectFailure "Validation failed: int must be positive" (fun () ->
+        Json.deserialize (Json.compile Schema.positiveInt) "0")
+
+    expectFailure "Validation failed: list must contain at least one item" (fun () ->
+        Json.deserialize (Json.compile (Schema.nonEmptyList Schema.int)) "[]")
+
+[<Fact>]
+let ``Trimmed string helper normalizes on encode and decode`` () =
+    let codec = Json.compile Schema.trimmedString
+
+    test <@ Json.deserialize codec "\"  Ada  \"" = "Ada" @>
+    test <@ Json.serialize codec "  Ada  " = "\"Ada\"" @>