Prerender functions (#102)

* Added prerender method

* added prerenderAround function

* Review fixes

Author: Lanayx

src/Oxpecker.ViewEngine/Builder.fs

@@ -106,9 +106,86 @@ module Builder =
         interface HtmlElement with
             member this.Render sb = this.Render sb
 
+    /// Node with a prerendered prefix and suffix around its children
+    type PrerenderedNode(prefix: string, suffix: string) =
+        let mutable children: CustomQueue<HtmlElement> = Unchecked.defaultof<_>
+        member this.Children = children.AsEnumerable()
+        member this.AddChild(element: HtmlElement) = children.Enqueue(element)
+        member this.Render(sb: StringBuilder) =
+            sb.Append(prefix) |> ignore
+            RenderHelpers.renderChildren sb children
+            sb.Append(suffix) |> ignore
+        interface HtmlContainer with
+            member this.Render sb = this.Render sb
+            member this.AddChild element = this.AddChild element
+
+    /// Placeholder that records where the dynamic part of a template begins
+    type internal HoleMarker() =
+        let mutable buffer: StringBuilder | null = null
+        let mutable position = -1
+        let mutable count = 0
+        member this.Position = position
+        /// Forgets renders that happened while the template was being built
+        member this.Reset() =
+            buffer <- null
+            position <- -1
+            count <- 0
+        /// True only when the hole was rendered exactly once, into this very buffer
+        member this.WasRenderedOnceInto(sb: StringBuilder) =
+            count = 1 && obj.ReferenceEquals(buffer, sb)
+        member this.Render(sb: StringBuilder) =
+            buffer <- sb
+            position <- sb.Length
+            count <- count + 1
+        interface HtmlElement with
+            member this.Render sb = this.Render sb
+
     /// Create text node that will NOT be HTML-escaped
     let inline raw text = RawTextNode text
 
+    /// <summary>
+    /// Renders an element together with all its children into a static HTML snapshot.
+    /// Use it to render static parts of a view once, instead of re-rendering them on every request.
+    /// </summary>
+    /// <remarks>
+    /// The snapshot is taken eagerly, at the moment of the call. Children or attributes added
+    /// to the original element afterwards will not be reflected in the returned node.
+    /// </remarks>
+    let prerender (view: #HtmlElement) =
+        let sb = StringBuilderPool.Get()
+        try
+            view.Render sb
+            RawTextNode(sb.ToString())
+        finally
+            StringBuilderPool.Return(sb)
+
+    /// <summary>
+    /// Renders the static part of a template with a hole in it once, and returns a factory
+    /// creating nodes that fill the hole. Use it for layouts, where only a small part of the
+    /// markup changes between renders.
+    /// </summary>
+    /// <param name="template">
+    /// Function that receives the hole and places it inside the markup. It has to use the hole exactly once.
+    /// </param>
+    /// <remarks>
+    /// The static part is rendered eagerly, at the moment of the call, exactly like <c>prerender</c> does.
+    /// </remarks>
+    let prerenderAround (template: HtmlElement -> #HtmlElement) =
+        let hole = HoleMarker()
+        let view = template hole
+        let sb = StringBuilderPool.Get()
+        let prefix, suffix =
+            try
+                // the template may have rendered the hole into a buffer of its own while being built
+                hole.Reset()
+                view.Render sb
+                if not(hole.WasRenderedOnceInto sb) then
+                    invalidArg (nameof template) "Template has to render the provided hole exactly once"
+                sb.ToString(0, hole.Position), sb.ToString(hole.Position, sb.Length - hole.Position)
+            finally
+                StringBuilderPool.Return(sb)
+        fun () -> PrerenderedNode(prefix, suffix)
+
     type HtmlContainerFun = HtmlContainer -> unit
 
     // builder methods

src/Oxpecker.ViewEngine/Oxpecker.ViewEngine.fsproj

@@ -22,9 +22,9 @@
         <PackageReadmeFile>README.md</PackageReadmeFile>
         <IncludeSymbols>true</IncludeSymbols>
         <SymbolPackageFormat>snupkg</SymbolPackageFormat>
-        <Version>2.0.1</Version>
-        <PackageVersion>2.0.1</PackageVersion>
-        <PackageReleaseNotes>Included documentation file in the package</PackageReleaseNotes>
+        <Version>2.1.0</Version>
+        <PackageVersion>2.1.0</PackageVersion>
+        <PackageReleaseNotes>Added prerender and prerenderAround functions</PackageReleaseNotes>
     </PropertyGroup>
     <ItemGroup>
         <PackageReference Include="FSharp.Core" Version="10.0.100" />

src/Oxpecker.ViewEngine/README.md

@@ -44,6 +44,7 @@ let mainView (model: Person) =
 - [Attributes](#attributes)
 - [Event handlers](#event-handlers)
 - [Html escaping](#html-escaping)
+- [Prerendering](#prerendering)
 - [Rendering](#rendering)
 - [ARIA](#aria)
 - [Fragments](#fragments)
@@ -63,7 +64,7 @@ let mainView (model: Person) =
         abstract member AddChild: HtmlElement -> unit
     ...
 ```
-There are 5 types of HTML elements available: `RegularNode`, `VoidNode` (only attributes), `FragmentNode` (only children), `RegularTextNode`(escaped text), `RawTextNode`(unescaped text).
+There are 7 types of HTML elements available: `RegularNode`, `VoidNode` (only attributes), `FragmentNode` (only children), `RegularTextNode`(escaped text), `RawTextNode`(unescaped text), `IntNode`(integer), `PrerenderedNode`(prerendered markup around children).
 
 All HTML tags inherit from `RegularNode` or `VoidNode` and you can easily create your own tag:
 
@@ -140,6 +141,55 @@ div(){
 }
 ```
 
+### Prerendering
+
+Views are object trees that are walked (and their text and attributes escaped) on every render. When a part of your view is static, `prerender` lets you pay that cost once: it renders an element **together with all its children** into a snapshot that is appended as a plain string on every subsequent render.
+
+```fsharp
+// rendered once, when the module is initialized
+let pageHeader =
+    prerender(
+        header() {
+            h1() { "My site" }
+            nav() { a(href = "/") { "Home" } }
+        }
+    )
+
+let page (model: Model) =
+    html() {
+        body() {
+            pageHeader // appended as a plain string on every request
+            main() { model.Content }
+        }
+    }
+```
+
+`prerender` returns a `RawTextNode` holding already-escaped HTML, so the snapshot is not escaped again when embedded.
+
+Note that the snapshot is taken **eagerly**, at the moment of the call: children or attributes added to the original element afterwards won't be reflected in the returned node.
+
+When only a small part of the markup changes between renders, `prerenderAround` lets you prerender everything around it. It takes a function that places the provided _hole_ inside your markup, renders the static part once, and gives you back a factory that is used like any other tag:
+
+```fsharp
+let layout =
+    prerenderAround(fun content ->
+        html() {
+            body() {
+                header() { h1() { "My site" } }
+                main() { content }
+                footer() { "(c) 2026" }
+            }
+        })
+
+let page (model: Model) =
+    layout() {
+        h2() { model.Title }
+        p() { model.Text }
+    }
+```
+
+Everything outside the hole is rendered once, so every `page` call only appends two prerendered strings around its own children. The hole has to be used exactly once, otherwise `prerenderAround` raises an `ArgumentException`.
+
 ### Rendering
 
 There are several functions to render `HtmlElement` (after opening Oxpecker.ViewEngine namespace):

tests/Oxpecker.ViewEngine.Tests/Render.Tests.fs

@@ -163,3 +163,187 @@ let ``Render to text writer`` () =
         |> Encoding.UTF8.GetString
         |> shouldEqual $"""<!DOCTYPE html>{Environment.NewLine}<html><div id="1"></div></html>"""
     }
+
+[<Fact>]
+let ``Prerender renders the same as the original element`` () =
+    let view =
+        div(id = "1") {
+            span(class' = "a") { "Hello" }
+            br()
+        }
+    let expected = view |> Render.toString
+    prerender view |> Render.toString |> shouldEqual expected
+
+[<Fact>]
+let ``Prerender includes all children`` () =
+    let result =
+        html() {
+            div(id = "1") { 1 }
+            div(id = "2") {
+                div(id = "3", class' = "test")
+                br()
+                ul() { yield! [ li() { "one" }; li() { "two" } ] }
+            }
+        }
+        |> prerender
+    result
+    |> Render.toString
+    |> shouldEqual
+        """<html><div id="1">1</div><div id="2"><div id="3" class="test"></div><br><ul><li>one</li><li>two</li></ul></div></html>"""
+
+[<Fact>]
+let ``Prerendered node is not escaped again when embedded`` () =
+    let prerendered =
+        p(id = "<br>") {
+            raw "<hr>"
+            span() { "<hr>" }
+        }
+        |> prerender
+    let result = div() { prerendered }
+    result
+    |> Render.toString
+    |> shouldEqual """<div><p id="&lt;br&gt;"><hr><span>&lt;hr&gt;</span></p></div>"""
+
+[<Fact>]
+let ``Prerendered node is embedded without a wrapper`` () =
+    let header = h1() { "My site" } |> prerender
+    let result = html() { body() { header } }
+    result
+    |> Render.toString
+    |> shouldEqual """<html><body><h1>My site</h1></body></html>"""
+
+[<Fact>]
+let ``Prerender of a fragment renders children only`` () =
+    let result =
+        Fragment() {
+            span() { "one" }
+            span() { "two" }
+        }
+        |> prerender
+    result |> Render.toString |> shouldEqual """<span>one</span><span>two</span>"""
+
+[<Fact>]
+let ``Prerender takes an eager snapshot`` () =
+    let view = div() { span() { "early" } }
+    let prerendered = prerender view
+    view.AddChild(span() { "late" })
+    prerendered
+    |> Render.toString
+    |> shouldEqual """<div><span>early</span></div>"""
+    view
+    |> Render.toString
+    |> shouldEqual """<div><span>early</span><span>late</span></div>"""
+
+[<Fact>]
+let ``Double render of a prerendered node works`` () =
+    let prerendered = prerender(span(id = "test1") { "test2" })
+    let result1 = prerendered |> Render.toString
+    let result2 = prerendered |> Render.toString
+    result1 |> shouldEqual """<span id="test1">test2</span>"""
+    result2 |> shouldEqual """<span id="test1">test2</span>"""
+
+[<Fact>]
+let ``Prerendered template renders the same as the original view`` () =
+    let layout =
+        prerenderAround(fun content ->
+            html() {
+                body() {
+                    h1() { "My site" }
+                    main() { content }
+                }
+            })
+    let expected =
+        html() {
+            body() {
+                h1() { "My site" }
+                main() { p() { "Dynamic" } }
+            }
+        }
+        |> Render.toString
+    layout() { p() { "Dynamic" } } |> Render.toString |> shouldEqual expected
+
+[<Fact>]
+let ``Prerendered template accepts several children`` () =
+    let layout = prerenderAround(fun content -> div(id = "wrap") { content })
+    layout() {
+        span() { "one" }
+        span() { "two" }
+    }
+    |> Render.toString
+    |> shouldEqual """<div id="wrap"><span>one</span><span>two</span></div>"""
+
+[<Fact>]
+let ``Prerendered template can be filled more than once`` () =
+    let layout = prerenderAround(fun content -> div() { content })
+    let first = layout() { "one" }
+    let second = layout() { "two" }
+    first |> Render.toString |> shouldEqual """<div>one</div>"""
+    second |> Render.toString |> shouldEqual """<div>two</div>"""
+
+[<Fact>]
+let ``Prerendered template with an unfilled hole`` () =
+    let layout = prerenderAround(fun content -> div() { content })
+    layout() |> Render.toString |> shouldEqual """<div></div>"""
+
+[<Fact>]
+let ``Prerendered template still escapes the hole content`` () =
+    let layout = prerenderAround(fun content -> p(id = "<br>") { content })
+    layout() { "<hr>" }
+    |> Render.toString
+    |> shouldEqual """<p id="&lt;br&gt;">&lt;hr&gt;</p>"""
+
+[<Fact>]
+let ``Prerendered template with an empty prefix and suffix`` () =
+    let layout = prerenderAround(fun content -> Fragment() { content })
+    layout() { span() { "only" } }
+    |> Render.toString
+    |> shouldEqual """<span>only</span>"""
+
+[<Fact>]
+let ``Prerendered template hole accepts a for loop`` () =
+    let layout = prerenderAround(fun content -> ul() { content })
+    layout() {
+        for i in 1..3 do
+            li() { i }
+    }
+    |> Render.toString
+    |> shouldEqual """<ul><li>1</li><li>2</li><li>3</li></ul>"""
+
+[<Fact>]
+let ``Prerendered templates can be nested`` () =
+    let outer = prerenderAround(fun content -> html() { body() { content } })
+    let inner = prerenderAround(fun content -> main(class' = "c") { content })
+    outer() { inner() { p() { "text" } } }
+    |> Render.toString
+    |> shouldEqual """<html><body><main class="c"><p>text</p></main></body></html>"""
+
+[<Fact>]
+let ``Prerendered template requires the hole to be used`` () =
+    Assert.Throws<ArgumentException>(fun () -> prerenderAround(fun _ -> div() { "no hole" }) |> ignore)
+    |> ignore
+
+[<Fact>]
+let ``Prerendered template rejects a hole used twice`` () =
+    Assert.Throws<ArgumentException>(fun () ->
+        prerenderAround(fun content ->
+            div() {
+                content
+                content
+            })
+        |> ignore)
+    |> ignore
+
+[<Fact>]
+let ``Prerendered template rejects a hole rendered into another buffer`` () =
+    Assert.Throws<ArgumentException>(fun () -> prerenderAround(fun content -> div() { prerender content }) |> ignore)
+    |> ignore
+
+[<Fact>]
+let ``Prerendered template allows the hole to be rendered elsewhere first`` () =
+    let layout =
+        prerenderAround(fun content ->
+            let _ = Render.toString content
+            div() { content })
+    layout() { "dynamic" }
+    |> Render.toString
+    |> shouldEqual """<div>dynamic</div>"""