Fixed JsonElement null handling in Function.ChangeValueType without unwrapping Nullable types

Fixed deep copy tags and attributes in `CaseValue` copy constructor
Changed `Date.Tomorrow` and `Date.Yesterday` from static readonly to computed properties
Fixed off-by-one in `HasOverlapping` skipping first element in `DatePeriod` and `HourPeriod` extensions
Fixed period creation for open-ended date ranges in `PeriodValue` constructor
Fixed period-matching in `CasePayrollValue` modulo operator to prevent `IndexOutOfRangeException`
Updated `IPayrunRuntime` for async payrun job support
Payrun function: added preview job
Updated readme

Author: Jani Giannoudis

Client.Scripting.Tests/PayrollEngine.Client.Scripting.Tests.csproj

@@ -8,7 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
     <PackageReference Include="xunit.v3" Version="3.2.2" />
   </ItemGroup>
 

Client.Scripting/ActionReflector.cs

@@ -40,6 +40,7 @@ public static (Assembly Assembly, List<ActionInfo> Actions) LoadFrom(string asse
     /// <returns>List of action infos.</returns>
     public static List<ActionInfo> LoadFrom(Assembly assembly)
     {
+        ArgumentNullException.ThrowIfNull(assembly);
         if (assembly == null)
         {
             throw new ArgumentNullException(nameof(assembly));

Client.Scripting/Cache.cs

@@ -81,6 +81,12 @@ protected List<DateTime> GetConsolidatedPeriodStarts(PayrunFunction function, Co
             return null;
         }
 
+        // noRetro queries bypass the cache (cache contains retro entries)
+        if (query.NoRetro)
+        {
+            return null;
+        }
+
         // mismatching job status
         if (query.JobStatus != JobStatus)
         {

Client.Scripting/CasePayrollValue.cs

@@ -143,6 +143,10 @@ public CasePayrollValue(string caseFieldName, IEnumerable<PeriodValue> periodVal
     public bool HasPeriods => HasValue;
 
     /// <summary>Total payroll value, summary of period values</summary>
+    /// <remarks>The reference comparison (value != PeriodValues.First()) is intentional:
+    /// it uses the first element as the seed and only accumulates distinct subsequent entries.
+    /// This is required for cancellation mode "Previous" where split periods produce
+    /// multiple entries with equal values that must not be double-counted.</remarks>
     public PayrollValue TotalValue()
     {
         // no values
@@ -205,14 +209,25 @@ public static implicit operator DateTime(CasePayrollValue payrollValue) =>
 
     #region Binary operators
 
+    /// <summary>Find the best matching period value for a given left period.
+    /// First tries exact match; falls back to containment (right period contains left period).
+    /// Required when TimeType differs, e.g. CalendarPeriod (trimmed) vs. Period (open-ended, End=MaxValue).</summary>
+    private static PeriodValue FindMatchingPeriodValue(ReadOnlyCollection<PeriodValue> periodValues, DatePeriod leftPeriod)
+    {
+        var match = periodValues.FirstOrDefault(x => Equals(x.Period, leftPeriod));
+        if (match != null) return match;
+        return periodValues.FirstOrDefault(x =>
+            x.Period.Start <= leftPeriod.Start && x.Period.End >= leftPeriod.End);
+    }
+
     /// <summary>Addition of two case values</summary>
     public static PayrollValue operator +(CasePayrollValue left, CasePayrollValue right)
     {
         var result = Empty;
         foreach (var leftValue in left.PeriodValues)
         {
             // find matching period
-            var rightValue = right.PeriodValues.FirstOrDefault(x => Equals(x.Period, leftValue.Period));
+            var rightValue = FindMatchingPeriodValue(right.PeriodValues, leftValue.Period);
             if (rightValue == null)
             {
                 continue;
@@ -254,7 +269,7 @@ public static implicit operator DateTime(CasePayrollValue payrollValue) =>
         // find matching period
         foreach (var leftValue in left.PeriodValues)
         {
-            var rightValue = right.PeriodValues.FirstOrDefault(x => Equals(x.Period, leftValue.Period));
+            var rightValue = FindMatchingPeriodValue(right.PeriodValues, leftValue.Period);
             if (rightValue == null)
             {
                 continue;
@@ -296,7 +311,7 @@ public static implicit operator DateTime(CasePayrollValue payrollValue) =>
         // find matching period
         foreach (var leftValue in left.PeriodValues)
         {
-            var rightValue = right.PeriodValues.FirstOrDefault(x => Equals(x.Period, leftValue.Period));
+            var rightValue = FindMatchingPeriodValue(right.PeriodValues, leftValue.Period);
             if (rightValue == null)
             {
                 continue;
@@ -338,7 +353,7 @@ public static implicit operator DateTime(CasePayrollValue payrollValue) =>
         // find matching period
         foreach (var leftValue in left.PeriodValues)
         {
-            var rightValue = right.PeriodValues.FirstOrDefault(x => Equals(x.Period, leftValue.Period));
+            var rightValue = FindMatchingPeriodValue(right.PeriodValues, leftValue.Period);
             if (rightValue == null)
             {
                 continue;
@@ -374,12 +389,19 @@ public static implicit operator DateTime(CasePayrollValue payrollValue) =>
     }
 
     /// <summary>Remainder of two case values</summary>
+    /// <remarks>Fixed: uses period-matching like other binary operators
+    /// to prevent IndexOutOfRangeException when collections differ in size.</remarks>
     public static PayrollValue operator %(CasePayrollValue left, CasePayrollValue right)
     {
         var result = Empty;
-        for (var i = 0; i < left.PeriodValues.Count; i++)
+        foreach (var leftValue in left.PeriodValues)
         {
-            var periodResult = left.PeriodValues[i] % right.PeriodValues[i];
+            var rightValue = FindMatchingPeriodValue(right.PeriodValues, leftValue.Period);
+            if (rightValue == null)
+            {
+                continue;
+            }
+            var periodResult = leftValue % rightValue;
             result = AddToResult(result, periodResult);
         }
         return result;

Client.Scripting/CaseValue.cs

@@ -40,6 +40,7 @@ public CaseValue()
 
     /// <summary>Initializes a new instance from a copy</summary>
     /// <param name="copySource">The copy source</param>
+    /// <remarks>Deep copies Tags and Attributes to prevent shared-reference mutations.</remarks>
     public CaseValue(CaseValue copySource)
     {
         CaseFieldName = copySource.CaseFieldName;
@@ -48,8 +49,9 @@ public CaseValue(CaseValue copySource)
         End = copySource.End;
         Value = copySource.Value;
         CancellationDate = copySource.CancellationDate;
-        Tags = copySource.Tags;
-        Attributes = copySource.Attributes;
+        // deep copy mutable collections
+        Tags = copySource.Tags != null ? [..copySource.Tags] : null;
+        Attributes = copySource.Attributes != null ? new Dictionary<string, object>(copySource.Attributes) : null;
     }
 
     /// <summary>Initializes a new instance</summary>
@@ -101,9 +103,10 @@ public bool Equals(CaseValue compare)
             End == compare.End &&
             Value == compare.Value &&
             CancellationDate == compare.CancellationDate &&
-            (Tags?.SequenceEqual(compare.Tags) ?? compare.Tags != null) &&
+            // null-safe: both null → equal, one null → not equal
+            (Tags?.SequenceEqual(compare.Tags) ?? compare.Tags == null) &&
             // ReSharper disable once UsageOfDefaultStructEquality
-            (Attributes?.SequenceEqual(compare.Attributes) ?? compare.Attributes != null);
+            (Attributes?.SequenceEqual(compare.Attributes) ?? compare.Attributes == null);
     }
 
     /// <summary>Returns a <see cref="string" /> that represents this instance</summary>

Client.Scripting/Date.cs

@@ -36,10 +36,12 @@ public static class Date
     public static DateTime Today => Now.Date;
 
     /// <summary>Gets a time instant that is set to the next day</summary>
-    public static readonly DateTime Tomorrow = Today.AddDays(1);
+    /// <remarks>Computed property (not static readonly) so the value updates with Today.</remarks>
+    public static DateTime Tomorrow => Today.AddDays(1);
 
     /// <summary>Gets a time instant that is set to the previous day</summary>
-    public static readonly DateTime Yesterday = Today.AddDays(-1);
+    /// <remarks>Computed property (not static readonly) so the value updates with Today.</remarks>
+    public static DateTime Yesterday => Today.AddDays(-1);
 
     /// <summary>Get the year start date in UTC</summary>
     public static DateTime YearStart(int year) =>

Client.Scripting/Extensions.cs

@@ -587,8 +587,8 @@ public DateTime SubtractYears(int years) =>
 
         /// <summary>Format a compact date (removes empty time parts)</summary>
         /// <returns>The formatted period start date</returns>
-        public string ToCompactString() => moment.IsMidnight() ? 
-            moment.ToShortDateString() : 
+        public string ToCompactString() => moment.IsMidnight() ?
+            moment.ToShortDateString() :
             $"{moment.ToShortDateString()} {moment.ToShortTimeString()}";
 
         /// <summary>Format a period start date (removes empty time parts), using the current culture</summary>
@@ -597,8 +597,8 @@ public string ToCompactString() => moment.IsMidnight() ?
 
         /// <summary>Format a period end date (removed empty time parts, and round last moment values), using the current culture</summary>
         /// <returns>The formatted period end date</returns>
-        public string ToPeriodEndString() => moment.IsMidnight() || moment.IsLastMomentOfDay() ? 
-            moment.ToShortDateString() : 
+        public string ToPeriodEndString() => moment.IsMidnight() || moment.IsLastMomentOfDay() ?
+            moment.ToShortDateString() :
             $"{moment.ToShortDateString()} {moment.ToShortTimeString()}";
 
         /// <summary>Test if the date is in UTC</summary>
@@ -775,7 +775,7 @@ public bool IsFirstDayOfMonth(Month month) =>
         /// <summary>Test if a specific day is the last day of the month</summary>
         /// <param name="ignoreLeapYear">Ignore the leap year day</param>
         /// <returns>True if the test day is the last day of the month</returns>
-        public bool IsLastDayOfMonth(bool ignoreLeapYear = false) => 
+        public bool IsLastDayOfMonth(bool ignoreLeapYear = false) =>
             moment.IsLastDayOfMonth(moment.Month(), ignoreLeapYear);
 
         /// <summary>Test if a specific day is the last day of the month</summary>
@@ -1152,8 +1152,15 @@ public object GetValue(string key, object defaultValue = null)
         /// <param name="key">The value key</param>
         /// <param name="defaultValue">The default value</param>
         /// <returns>The dictionary value</returns>
-        public T GetValue<T>(string key, T defaultValue = default) =>
-            (T)Convert.ChangeType(dictionary.GetValue(key, (object)defaultValue), typeof(T));
+        public T GetValue<T>(string key, T defaultValue = default)
+        {
+            var value = dictionary.GetValue(key);
+            if (value == null)
+            {
+                return defaultValue;
+            }
+            return (T)value;
+        }
     }
 
     /// <summary>Get value from a string/JSON-string dictionary</summary>
@@ -1319,7 +1326,7 @@ public List<DatePeriod> Split(List<DateTime> splitMoments)
                     splitPeriods.Add(new(last.End.NextTick(), period.End));
                 }
             }
-            return splitPeriods;
+            return splitPeriods.Any() ? splitPeriods : [period];
         }
 
         /// <summary>Get period days</summary>
@@ -1460,10 +1467,11 @@ public TimeSpan TotalDuration()
 
         /// <summary>Test if any period is overlapping another period</summary>
         /// <returns>True, if the period is overlapping this period</returns>
+        /// <remarks>Fixed: outer loop starts at 0 to include the first element in comparisons.</remarks>
         public bool HasOverlapping()
         {
             var periodList = datePeriods.ToList();
-            for (var current = 1; current < periodList.Count; current++)
+            for (var current = 0; current < periodList.Count; current++)
             {
                 for (var remain = current + 1; remain < periodList.Count; remain++)
                 {
@@ -1568,7 +1576,7 @@ public bool IsWithin(decimal test) =>
         /// <summary>Test if a specific time period is within the period, including open periods</summary>
         /// <param name="testPeriod">The period to test</param>
         /// <returns>True, if the test period is within this period</returns>
-        public bool IsWithin(HourPeriod testPeriod) => 
+        public bool IsWithin(HourPeriod testPeriod) =>
             period.IsWithin(testPeriod.Start) && period.IsWithin(testPeriod.End);
 
         /// <summary>Test if a specific time moment is within or before the period, including open periods</summary>
@@ -1626,10 +1634,11 @@ public TimeSpan TotalDuration()
 
         /// <summary>Test if any period is overlapping another period</summary>
         /// <returns>True, if the period is overlapping this period</returns>
+        /// <remarks>Fixed: outer loop starts at 0 to include the first element in comparisons.</remarks>
         public bool HasOverlapping()
         {
             var periodList = timePeriods.ToList();
-            for (var current = 1; current < periodList.Count; current++)
+            for (var current = 0; current < periodList.Count; current++)
             {
                 for (var remain = current + 1; remain < periodList.Count; remain++)
                 {
@@ -2203,7 +2212,7 @@ valueType is ValueType.Date or
 
         /// <summary>Test if value type is a number</summary>
         /// <returns>True for number value types</returns>
-        public bool IsNumber() => 
+        public bool IsNumber() =>
             valueType.IsInteger() || valueType.IsDecimal();
 
         /// <summary>Test if value type is an integer</summary>
@@ -2376,7 +2385,7 @@ public static CaseValue TupleToCaseValue(this Tuple<string, DateTime, Tuple<Date
     /// <summary>Convert tuple values to case values</summary>
     /// <param name="values">The tuple values</param>
     /// <returns>The case period values</returns>
-    public static List<CaseValue> TupleToCaseValues(this List<Tuple<string, DateTime, 
+    public static List<CaseValue> TupleToCaseValues(this List<Tuple<string, DateTime,
         Tuple<DateTime?, DateTime?>, object, DateTime?, List<string>, Dictionary<string, object>>> values)
     {
         var caseValues = new List<CaseValue>();
@@ -2386,7 +2395,7 @@ public static List<CaseValue> TupleToCaseValues(this List<Tuple<string, DateTime
             {
                 if (value != null)
                 {
-                    caseValues.Add(new(value.Item1, value.Item2, value.Item3.Item1, 
+                    caseValues.Add(new(value.Item1, value.Item2, value.Item3.Item1,
                         value.Item3.Item2, new(value.Item4), value.Item5, value.Item6, value.Item7));
                 }
             }
@@ -2401,19 +2410,23 @@ public static CasePayrollValueDictionary TupleToCaseValuesDictionary(this Dictio
         List<Tuple<DateTime, DateTime?, DateTime?, object>>> values)
     {
         var caseValues = new Dictionary<string, CasePayrollValue>();
-        foreach (var value in values)
+        if (values != null)
         {
-            var periodValues = value.Value.Select(x => new PeriodValue(x.Item2, x.Item3, x.Item4));
-            caseValues.Add(value.Key, new(value.Key, periodValues));
+            foreach (var value in values)
+            {
+                var periodValues = value.Value.Select(x => new PeriodValue(x.Item2, x.Item3, x.Item4));
+                caseValues.Add(value.Key, new(value.Key, periodValues));
+            }
         }
         return new(caseValues);
     }
 
     /// <summary>Convert tuple values to a collector result</summary>
     /// <param name="values">The tuple values</param>
     /// <returns>The collector results</returns>
-    public static List<CollectorResult> TupleToCollectorResults(this List<Tuple<string, 
+    public static List<CollectorResult> TupleToCollectorResults(this List<Tuple<string,
         Tuple<DateTime, DateTime>, decimal, List<string>, Dictionary<string, object>>> values) =>
+        values == null ? new() :
     [
         ..values.Select(x => new CollectorResult
         {
@@ -2431,6 +2444,7 @@ public static List<CollectorResult> TupleToCollectorResults(this List<Tuple<stri
     /// <returns>The collector custom results</returns>
     public static List<CollectorCustomResult> TupleToCollectorCustomResults(
         this List<Tuple<string, string, Tuple<DateTime, DateTime>, decimal, List<string>, Dictionary<string, object>>> values) =>
+        values == null ? new() :
     [
         ..values.Select(x => new CollectorCustomResult
         {
@@ -2449,6 +2463,7 @@ public static List<CollectorCustomResult> TupleToCollectorCustomResults(
     /// <returns>The wage type results</returns>
     public static List<WageTypeResult> TupleToWageTypeResults
         (this List<Tuple<decimal, string, Tuple<DateTime, DateTime>, decimal, List<string>, Dictionary<string, object>>> values) =>
+        values == null ? new() :
     [
         ..values.Select(x => new WageTypeResult
         {
@@ -2467,6 +2482,7 @@ public static List<WageTypeResult> TupleToWageTypeResults
     /// <returns>The wage type custom results</returns>
     public static List<WageTypeCustomResult> TupleToWageTypeCustomResults(
         this List<Tuple<decimal, string, string, Tuple<DateTime, DateTime>, decimal, List<string>, Dictionary<string, object>>> values) =>
+        values == null ? new() :
     [
         ..values.Select(x => new WageTypeCustomResult
         {
@@ -2486,6 +2502,7 @@ public static List<WageTypeCustomResult> TupleToWageTypeCustomResults(
     /// <returns>The lookup brackets</returns>
     public static List<LookupRangeBracket> TupleToLookupRangeBracketList(
         List<Tuple<string, string, decimal, decimal, decimal?>> brackets) =>
+        brackets == null ? new() :
     [
         ..brackets.Select(x => new LookupRangeBracket
         {