Better typing for TILs

Author: Mopolo

resources/views/pages/til/index.twig

@@ -16,7 +16,7 @@
 
                 <ul class="ps-2">
                     {% for til in entries %}
-                        <li class="pb-1"><a href="{{ til.url }}" class="cursor-pointer hover:underline">{{ til.title }}</a></li>
+                        <li class="pb-1"><a href="{{ til.url }}" class="cursor-pointer hover:underline">{{ til.frontMatter.title }}</a></li>
                     {% endfor %}
                 </ul>
             </div>

resources/views/pages/til/show.twig

@@ -6,7 +6,7 @@
         <h2 class="text-2xl font-semibold {{ colors.textLightBg }}">
             <a href="{{ urls.til.href }}" class="font-black underline">TIL</a>
             <span class="block pt-2 md:inline md:pt-0">
-                {{ til.title }}
+                {{ til.frontMatter.title }}
             </span>
         </h2>
     </div>
@@ -17,11 +17,11 @@
         </div>
     </div>
 
-    {% if til.sources %}
+    {% if til.frontMatter.sources %}
         <div class="mt-4 md:mt-14 mb-5 text-gray-600 dark:text-gray-400">
             <div class="mb-2 border-b-2 border-gray-500">
                 <h4 class="text-sm">
-                    {% if til.sources|length == 1 %}
+                    {% if til.frontMatter.sources|length == 1 %}
                         Source
                     {% else %}
                         Sources
@@ -30,7 +30,7 @@
             </div>
 
             <div class="flex flex-col text-sm">
-                {% for source in til.sources %}
+                {% for source in til.frontMatter.sources %}
                     <a href="{{ source }}" class="hover:underline">{{ source }}</a>
                 {% endfor %}
             </div>

src/Til/Entry.php

@@ -7,11 +7,9 @@
 final readonly class Entry
 {
     public function __construct(
-        public string $category,
-        public string $title,
+        public FrontMatter $frontMatter,
         public string $content,
         public string $slug,
         public string $url,
-        public array $sources,
     ) {}
 }

src/Til/FrontMatter.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mopolo\Cv\Til;
+
+final readonly class FrontMatter
+{
+    public function __construct(
+        public string $category,
+        public string $title,
+        /** @var array<string>|null */
+        public ?array $sources = null,
+    ) {
+    }
+}

src/Til/Renderer.php

@@ -4,6 +4,8 @@
 
 namespace Mopolo\Cv\Til;
 
+use CuyZ\Valinor\Mapper\Source\Source;
+use CuyZ\Valinor\MapperBuilder;
 use Exception;
 use League\CommonMark\Environment\Environment;
 use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
@@ -49,7 +51,7 @@ public function renderList(): array
         foreach ($finder as $file) {
             $entry = $this->renderFile($file);
 
-            $tils[$entry->category][] = $entry;
+            $tils[$entry->frontMatter->category][] = $entry;
         }
 
         return $tils;
@@ -91,33 +93,19 @@ public function render(string $path, string $content): Entry
             throw new Exception('Missing front matter in ' . $path);
         }
 
-        $frontMatter = $result->getFrontMatter();
+        $rawFrontMatter = $result->getFrontMatter();
 
-        if (!is_array($frontMatter)) {
-            throw new Exception('Invalid front matter in ' . $path);
+        if (!is_array($rawFrontMatter)) {
+            throw new Exception("Front matter is not an array");
         }
 
-        $category = $frontMatter['category'] ?? throw new Exception('Missing category in ' . $path);
-
-        if (!is_string($category)) {
-            throw new Exception('Invalid category in ' . $path);
-        }
-
-        $title = $frontMatter['title'] ?? throw new Exception('Missing title in ' . $path);
-
-        if (!is_string($title)) {
-            throw new Exception('Invalid title in ' . $path);
-        }
-
-        $sources = $frontMatter['sources'] ?? [];
+        $frontMatter = (new MapperBuilder())->mapper()->map(FrontMatter::class, Source::array($rawFrontMatter));
 
         return new Entry(
-            $category,
-            $title,
+            $frontMatter,
             $result->getContent(),
             $slug,
             $this->url($slug),
-            $sources,
         );
     }