Issue-110: Add TaskExtras.InvokeIf

closes #110
SemVer:Minor

Author: doomchild

README.md

@@ -157,6 +157,29 @@ Task.FromException<int>(new ArgumentException())
   ))
 ```
 
+#### InvokeIf
+
+`InvokeIf` can be used to conditionally invoke a function. This is most useful for side effects.
+
+```c#
+Task.FromResult(someUrl)
+  .Then(httpClient.GetAsync)
+  .IfFulfilled(TaskExtras.InvokeIf(
+    httpResponse => !httpResponse.IsSuccessStatusCode,
+    httpResponse => _logger.LogWarning("Got '{StatusCode}' response from server", httpResponse.StatusCode)
+  );
+```
+
+However, it can be used with `.Then` as well:
+
+```c#
+Task.FromResult(4)
+  .Then(InvokeIf(
+    value => value % 2 == 0,
+    value => value + 1
+  );
+```
+
 [bluebird]: http://bluebirdjs.com/docs/getting-started.html
 [MONADS.md]: ./MONADS.md
 [nuget.org]: https://www.nuget.org/packages/RLC.TaskChaining/

src/TaskExtras.cs

@@ -131,6 +131,138 @@ Func<Exception, Task<T>> resolutionSupplier
 		? resolutionSupplier(value)
 		: Task.FromException<T>(value);
 
+  /// <summary>
+  /// Invokes <paramref name="action"/> if <paramref name="predicate"/> succeeds.
+  /// </summary>
+  /// <example>This is useful for conditionally executing a side effect.
+  /// <code>
+  /// Task.FromResult(someUrl)
+  ///   .Then(httpClient.GetAsync)
+  ///   .IfFulfilled(InvokeIf(
+  ///     httpResponse => !httpResponse.IsSuccessStatusCode,
+  ///     response => _logger.LogWarning("Got '{StatusCode}' response from server", response.StatusCode)
+  ///   );
+  /// </code>
+  /// </example>
+  /// <param name="predicate">A predicate to evaluate with the <see cref="Task{T}"/>'s value.</param>
+  /// <param name="action">The function to invoke if <paramref name="predicate"/> returns <code>true</code>.</param>
+  /// <typeparam name="T">The type passed into <code>InvokeIf</code>.</typeparam>
+  /// <returns>A function that conditionally invokes another function.</returns>
+  public static Func<T, Task<T>> InvokeIf<T>(
+    Predicate<T> predicate,
+    Action<T> action
+  )
+  {
+    return value =>
+    {
+      if (predicate(value))
+      {
+        action(value);
+      }
+
+      return Task.FromResult(value);
+    };
+  }
+
+  /// <summary>
+  /// Invokes <paramref name="func"/> if <paramref name="predicate"/> succeeds.
+  /// </summary>
+  /// <example>This is useful for conditionally executing a side effect.
+  /// <code>
+  /// Task.FromResult(someUrl)
+  ///   .Then(httpClient.GetAsync)
+  ///   .IfFulfilled(InvokeIf(
+  ///     httpResponse => !httpResponse.IsSuccessStatusCode,
+  ///     response => _logger.LogWarning("Got '{StatusCode}' response from server", response.StatusCode)
+  ///   );
+  /// </code>
+  /// </example>
+  /// <param name="predicate">A predicate to evaluate with the <see cref="Task{T}"/>'s value.</param>
+  /// <param name="func">The function to invoke if <paramref name="predicate"/> returns <code>true</code>.</param>
+  /// <typeparam name="T">The type passed into <code>InvokeIf</code>.</typeparam>
+  /// <returns>A function that conditionally invokes another function.</returns>
+  public static Func<T, Task<T>> InvokeIf<T>(
+    Predicate<T> predicate,
+    Func<T, T> func
+  )
+  {
+    return value =>
+    {
+      if (predicate(value))
+      {
+        return Task.FromResult(func(value));
+      }
+
+      return Task.FromResult(value);
+    };
+  }
+
+  /// <summary>
+  /// Invokes <paramref name="func"/> if <paramref name="predicate"/> succeeds.
+  /// </summary>
+  /// <example>This is useful for conditionally executing a side effect.
+  /// <code>
+  /// Task.FromResult(someUrl)
+  ///   .Then(httpClient.GetAsync)
+  ///   .IfFulfilled(InvokeIf(
+  ///     httpResponse => !httpResponse.IsSuccessStatusCode,
+  ///     response => _logger.LogWarning("Got '{StatusCode}' response from server", response.StatusCode)
+  ///   );
+  /// </code>
+  /// </example>
+  /// <param name="predicate">A predicate to evaluate with the <see cref="Task{T}"/>'s value.</param>
+  /// <param name="func">The function to invoke if <paramref name="predicate"/> returns <code>true</code>.</param>
+  /// <typeparam name="T">The type passed into <code>InvokeIf</code>.</typeparam>
+  /// <returns>A function that conditionally invokes another function.</returns>
+  public static Func<T, Task<T>> InvokeIf<T>(
+    Predicate<T> predicate,
+    Func<T, Task<T>> func
+  )
+  {
+    return value =>
+    {
+      if (predicate(value))
+      {
+        return func(value);
+      }
+
+      return Task.FromResult(value);
+    };
+  }
+
+  /// <summary>
+  /// Invokes <paramref name="func"/> if <paramref name="predicate"/> succeeds.
+  /// </summary>
+  /// <example>This is useful for conditionally executing a side effect.
+  /// <code>
+  /// Task.FromResult(someUrl)
+  ///   .Then(httpClient.GetAsync)
+  ///   .IfFulfilled(InvokeIf(
+  ///     httpResponse => !httpResponse.IsSuccessStatusCode,
+  ///     response => _logger.LogWarning("Got '{StatusCode}' response from server", response.StatusCode)
+  ///   );
+  /// </code>
+  /// </example>
+  /// <param name="predicate">A predicate to evaluate with the <see cref="Task{T}"/>'s value.</param>
+  /// <param name="func">The function to invoke if <paramref name="predicate"/> returns <code>true</code>.</param>
+  /// <typeparam name="T">The type passed into <code>InvokeIf</code>.</typeparam>
+  /// <returns>A function that conditionally invokes another function.</returns>
+  public static Func<T, Task<T>> InvokeIf<T>(
+    Predicate<T> predicate,
+    Func<T, Task> func
+  )
+  {
+    return value =>
+    {
+      if (predicate(value))
+      {
+        return Task.FromResult(value).Then(func).Then(_ => value);
+      }
+
+      return Task.FromResult(value);
+    };
+  }
+
 	/// <summary>
   /// A function that executes the <paramref name="supplier"/> after <paramref name="deferTime"/> has elapsed.
   /// </summary>

tests/unit/InvokeIf/WithAction.cs

@@ -0,0 +1,37 @@
+using System;
+using System.Threading.Tasks;
+using RLC.TaskChaining;
+using Xunit;
+
+namespace RLC.TaskChainingTests.InvokeIf;
+
+public class WithAction
+{
+  [Fact]
+  public async Task ItShouldInvokeIfPredicateSucceeds()
+  {
+    int actualValue = 0;
+    int expectedValue = 5;
+    Predicate<int> predicate = value => value % 2 == 0;
+    Action<int> action = _ => { actualValue = 5; };
+
+    await Task.FromResult(4)
+      .Then(TaskExtras.InvokeIf(predicate, action));
+    
+    Assert.Equal(expectedValue, actualValue);
+  }
+  
+  [Fact]
+  public async Task ItShouldNotInvokeIfPredicateFails()
+  {
+    int actualValue = 0;
+    int expectedValue = 5;
+    Predicate<int> predicate = value => value % 2 == 0;
+    Action<int> action = _ => { actualValue = 5; };
+
+    await Task.FromResult(3)
+      .Then(TaskExtras.InvokeIf(predicate, action));
+    
+    Assert.NotEqual(expectedValue, actualValue);
+  }
+}

tests/unit/InvokeIf/WithFullTaskFunc.cs

@@ -0,0 +1,35 @@
+using System;
+using System.Threading.Tasks;
+using RLC.TaskChaining;
+using Xunit;
+
+namespace RLC.TaskChainingTests.InvokeIf;
+
+public class WithFullTaskFunc
+{
+  [Fact]
+  public async Task ItShouldInvokeIfPredicateSucceeds()
+  {
+    int expectedValue = 5;
+    Predicate<int> predicate = value => value % 2 == 0;
+    Func<int, Task<int>> func = _ => Task.FromResult(5);
+
+    int actualValue = await Task.FromResult(4)
+      .Then(TaskExtras.InvokeIf(predicate, func));
+    
+    Assert.Equal(expectedValue, actualValue);
+  }
+  
+  [Fact]
+  public async Task ItShouldNotInvokeIfPredicateFails()
+  {
+    int expectedValue = 3;
+    Predicate<int> predicate = value => value % 2 == 0;
+    Func<int, Task<int>> func = _ => Task.FromResult(5);
+
+    int actualValue = await Task.FromResult(3)
+      .Then(TaskExtras.InvokeIf(predicate, func));
+    
+    Assert.Equal(expectedValue, actualValue);
+  }
+}

tests/unit/InvokeIf/WithRawTaskFunc.cs

@@ -0,0 +1,45 @@
+using System;
+using System.Threading.Tasks;
+using RLC.TaskChaining;
+using Xunit;
+
+namespace RLC.TaskChainingTests.InvokeIf;
+
+public class WithRawTaskFunc
+{
+  [Fact]
+  public async Task ItShouldInvokeIfPredicateSucceeds()
+  {
+    int actualValue = 0;
+    int expectedValue = 5;
+    Predicate<int> predicate = value => value % 2 == 0;
+    Func<int, Task> func = value =>
+    {
+      actualValue = 5;
+      return Task.CompletedTask;
+    };
+
+    await Task.FromResult(4)
+      .Then(TaskExtras.InvokeIf(predicate, func));
+    
+    Assert.Equal(expectedValue, actualValue);
+  }
+  
+  [Fact]
+  public async Task ItShouldNotInvokeIfPredicateFails()
+  {
+    int actualValue = 0;
+    int expectedValue = 5;
+    Predicate<int> predicate = value => value % 2 == 0;
+    Func<int, Task> func = value =>
+    {
+      actualValue = 5;
+      return Task.CompletedTask;
+    };
+
+    await Task.FromResult(3)
+      .Then(TaskExtras.InvokeIf(predicate, func));
+    
+    Assert.NotEqual(expectedValue, actualValue);
+  }
+}

tests/unit/InvokeIf/WithTFunc.cs

@@ -0,0 +1,35 @@
+using System;
+using System.Threading.Tasks;
+using RLC.TaskChaining;
+using Xunit;
+
+namespace RLC.TaskChainingTests.InvokeIf;
+
+public class WithTFunc
+{
+  [Fact]
+  public async Task ItShouldInvokeIfPredicateSucceeds()
+  {
+    int expectedValue = 5;
+    Predicate<int> predicate = value => value % 2 == 0;
+    Func<int, int> func = _ => 5;
+
+    int actualValue = await Task.FromResult(4)
+      .Then(TaskExtras.InvokeIf(predicate, func));
+    
+    Assert.Equal(expectedValue, actualValue);
+  }
+  
+  [Fact]
+  public async Task ItShouldNotInvokeIfPredicateFails()
+  {
+    int expectedValue = 3;
+    Predicate<int> predicate = value => value % 2 == 0;
+    Func<int, int> func = _ => 5;
+
+    int actualValue = await Task.FromResult(3)
+      .Then(TaskExtras.InvokeIf(predicate, func));
+    
+    Assert.Equal(expectedValue, actualValue);
+  }
+}