From 6000efa109de55bac2055fd3bba39de3a7a248dd Mon Sep 17 00:00:00 2001
From: Jamie Pollock <jamie.pollock@rhythmagency.com>
Date: Mon, 22 Jan 2024 11:00:26 -0500
Subject: [PATCH] feat (Links): adds further null checks and docs

Updates all methods to accept a nullable source. This is handled within the methods now.

Updates all the docs to note this will be an empty collection or default if the source parameter is null.
---
 .../Links/MapperContextLinkExtensions.cs      | 30 +++++++++++++++----
 .../Links/MapperContextLinksExtensions.cs     | 19 +++++++++---
 .../Links/UmbracoMapperLinkExtensions.cs      | 30 +++++++++++++++----
 .../Links/UmbracoMapperLinksExtensions.cs     | 19 +++++++++---
 4 files changed, 78 insertions(+), 20 deletions(-)

diff --git a/src/Rhythm.Drop.Umbraco.Mapping/Links/MapperContextLinkExtensions.cs b/src/Rhythm.Drop.Umbraco.Mapping/Links/MapperContextLinkExtensions.cs
index 710ed29..b4d0b47 100644
--- a/src/Rhythm.Drop.Umbraco.Mapping/Links/MapperContextLinkExtensions.cs
+++ b/src/Rhythm.Drop.Umbraco.Mapping/Links/MapperContextLinkExtensions.cs
@@ -16,7 +16,10 @@ public static class MapperContextLinkExtensions
     /// <typeparam name="TLink">The type of the link.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="block">The block to map.</param>
-    /// <returns>A <typeparamref name="TLink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TLink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="block"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TLink? MapLink<TLink>(this MapperContext mapperContext, IBlockReference<IPublishedElement, IPublishedElement>? block) where TLink : class, ILink
     {
         if (block is null)
@@ -32,7 +35,10 @@ public static class MapperContextLinkExtensions
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="block">The block to map.</param>
-    /// <returns>A <see cref="ILink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="ILink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="block"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static ILink? MapLink(this MapperContext mapperContext, IBlockReference<IPublishedElement, IPublishedElement>? block)
     {
         return mapperContext.MapLink<ILink>(block);
@@ -44,7 +50,10 @@ public static class MapperContextLinkExtensions
     /// <typeparam name="TLink">The type of the link.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="element">The element to map.</param>
-    /// <returns>A <typeparamref name="TLink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TLink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="element"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TLink? MapLink<TLink>(this MapperContext mapperContext, IPublishedElement? element) where TLink : class, ILink
     {
         if (element is null)
@@ -60,7 +69,10 @@ public static class MapperContextLinkExtensions
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="element">The element to map.</param>
-    /// <returns>A <see cref="ILink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="ILink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="element"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static ILink? MapLink(this MapperContext mapperContext, IPublishedElement? element)
     {
         return mapperContext.MapLink<ILink>(element);
@@ -72,7 +84,10 @@ public static class MapperContextLinkExtensions
     /// <typeparam name="TLink">The type of the link.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="list">The list to map.</param>
-    /// <returns>A <typeparamref name="TLink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TLink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="list"/> or its first item are <see langword="null"/>.</para>
+    /// </returns>
     public static TLink? MapLink<TLink>(this MapperContext mapperContext, BlockListModel? list) where TLink : class, ILink
     {
         if (list is null)
@@ -88,7 +103,10 @@ public static class MapperContextLinkExtensions
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="list">The list to map.</param>
-    /// <returns>A <see cref="ILink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="ILink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="list"/> or its first item are <see langword="null"/>.</para>
+    /// </returns>
     public static ILink? MapLink(this MapperContext mapperContext, BlockListModel? list)
     {
         return mapperContext.MapLink<ILink>(list);
diff --git a/src/Rhythm.Drop.Umbraco.Mapping/Links/MapperContextLinksExtensions.cs b/src/Rhythm.Drop.Umbraco.Mapping/Links/MapperContextLinksExtensions.cs
index c120434..a4d7b77 100644
--- a/src/Rhythm.Drop.Umbraco.Mapping/Links/MapperContextLinksExtensions.cs
+++ b/src/Rhythm.Drop.Umbraco.Mapping/Links/MapperContextLinksExtensions.cs
@@ -15,9 +15,17 @@ public static class MapperContextLinksExtensions
     /// <typeparam name="TLink">The type of the link.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="list">The list to map.</param>
-    /// <returns>An array of <typeparamref name="TLink"/>.</returns>
-    public static TLink[] MapLinks<TLink>(this MapperContext mapperContext, BlockListModel list) where TLink : class, ILink
+    /// <returns>
+    /// <para>An array of <typeparamref name="TLink"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="list"/> is <see langword="null"/>.</para>
+    /// </returns>
+    public static TLink[] MapLinks<TLink>(this MapperContext mapperContext, BlockListModel? list) where TLink : class, ILink
     {
+        if (list is null)
+        {
+            return [];
+        }
+
         var links = new List<TLink>();
         foreach (var block in list)
         {
@@ -38,8 +46,11 @@ public static TLink[] MapLinks<TLink>(this MapperContext mapperContext, BlockLis
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="list">The list to map.</param>
-    /// <returns>An array of <see cref="ILink"/>.</returns>
-    public static ILink[] MapLinks(this MapperContext mapperContext, BlockListModel list)
+    /// <returns>
+    /// <para>An array of <see cref="ILink"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="list"/> is <see langword="null"/>.</para>
+    /// </returns>
+    public static ILink[] MapLinks(this MapperContext mapperContext, BlockListModel? list)
     {
         return mapperContext.MapLinks<ILink>(list);
     }
diff --git a/src/Rhythm.Drop.Umbraco.Mapping/Links/UmbracoMapperLinkExtensions.cs b/src/Rhythm.Drop.Umbraco.Mapping/Links/UmbracoMapperLinkExtensions.cs
index 71dcb49..597831e 100644
--- a/src/Rhythm.Drop.Umbraco.Mapping/Links/UmbracoMapperLinkExtensions.cs
+++ b/src/Rhythm.Drop.Umbraco.Mapping/Links/UmbracoMapperLinkExtensions.cs
@@ -19,7 +19,10 @@ public static class UmbracoMapperLinkExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="block">The block to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <typeparamref name="TLink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TLink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="block"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TLink? MapLink<TLink>(this IUmbracoMapper mapper, IBlockReference<IPublishedElement, IPublishedElement>? block, Action<MapperContext>? configureContext = default) where TLink : class, ILink
     {
         if (block is null)
@@ -36,7 +39,10 @@ public static class UmbracoMapperLinkExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="block">The block to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <see cref="ILink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="ILink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="block"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static ILink? MapLink(this IUmbracoMapper mapper, IBlockReference<IPublishedElement, IPublishedElement>? block, Action<MapperContext>? configureContext = default)
     {
         return mapper.MapLink<ILink>(block, configureContext);
@@ -49,7 +55,10 @@ public static class UmbracoMapperLinkExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="element">The element to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <typeparamref name="TLink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TLink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="element"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TLink? MapLink<TLink>(this IUmbracoMapper mapper, IPublishedElement? element, Action<MapperContext>? configureContext = default) where TLink : class, ILink
     {
         if (element is null)
@@ -66,7 +75,10 @@ public static class UmbracoMapperLinkExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="element">The element to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <see cref="ILink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="ILink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="element"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static ILink? MapLink(this IUmbracoMapper mapper, IPublishedElement? element, Action<MapperContext>? configureContext = default)
     {
         return mapper.MapLink<ILink>(element, configureContext);
@@ -79,7 +91,10 @@ public static class UmbracoMapperLinkExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="list">The list to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <typeparamref name="TLink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TLink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="list"/> or its first item are <see langword="null"/>.</para>
+    /// </returns>
     public static TLink? MapLink<TLink>(this IUmbracoMapper mapper, BlockListModel? list, Action<MapperContext>? configureContext = default) where TLink : class, ILink
     {
         if (list is null)
@@ -96,7 +111,10 @@ public static class UmbracoMapperLinkExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="list">The list to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <see cref="ILink"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="ILink"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="list"/> or its first item are <see langword="null"/>.</para>
+    /// </returns>
     public static ILink? MapLink(this IUmbracoMapper mapper, BlockListModel? list, Action<MapperContext>? configureContext = default)
     {
         return mapper.MapLink<ILink>(list, configureContext);
diff --git a/src/Rhythm.Drop.Umbraco.Mapping/Links/UmbracoMapperLinksExtensions.cs b/src/Rhythm.Drop.Umbraco.Mapping/Links/UmbracoMapperLinksExtensions.cs
index 43ea434..cb0de43 100644
--- a/src/Rhythm.Drop.Umbraco.Mapping/Links/UmbracoMapperLinksExtensions.cs
+++ b/src/Rhythm.Drop.Umbraco.Mapping/Links/UmbracoMapperLinksExtensions.cs
@@ -18,9 +18,17 @@ public static class UmbracoMapperLinksExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="list">The list to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>An array of <typeparamref name="TLink"/>.</returns>
-    public static TLink[] MapLinks<TLink>(this IUmbracoMapper mapper, BlockListModel list, Action<MapperContext>? configureContext = default) where TLink : class, ILink
+    /// <returns>
+    /// <para>An array of <typeparamref name="TLink"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="list"/> is <see langword="null"/>.</para>
+    /// </returns>
+    public static TLink[] MapLinks<TLink>(this IUmbracoMapper mapper, BlockListModel? list, Action<MapperContext>? configureContext = default) where TLink : class, ILink
     {
+        if (list is null)
+        {
+            return [];
+        }
+
         var links = new List<TLink>();
         foreach (var block in list)
         {
@@ -42,8 +50,11 @@ public static TLink[] MapLinks<TLink>(this IUmbracoMapper mapper, BlockListModel
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="list">The list to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>An array of <see cref="ILink"/>.</returns>
-    public static ILink[] MapLinks(this IUmbracoMapper mapper, BlockListModel list, Action<MapperContext>? configureContext = default)
+    /// <returns>
+    /// <para>An array of <see cref="ILink"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="list"/> is <see langword="null"/>.</para>
+    /// </returns>
+    public static ILink[] MapLinks(this IUmbracoMapper mapper, BlockListModel? list, Action<MapperContext>? configureContext = default)
     {
         return mapper.MapLinks<ILink>(list, configureContext);
     }