🎨 standardize exception handling and improve culture-invariant string formatting

QsNet.Tests/DecodeOptionsTests.cs

@@ -121,7 +121,7 @@ public void DecodeKey_ShouldThrow_When_DecodeDotInKeysTrue_And_AllowDotsFalse()
         };
 
         Action act = () => options.DecodeKey("a%2Eb", Encoding.UTF8);
-        act.Should().Throw<ArgumentException>()
+        act.Should().Throw<InvalidOperationException>()
             .Where(e => e.Message.Contains("decodeDotInKeys", StringComparison.OrdinalIgnoreCase)
                         && e.Message.Contains("allowDots", StringComparison.OrdinalIgnoreCase));
     }

QsNet.Tests/DecodeTests.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections;
 using System.Collections.Generic;
+using System.Linq;
 using System.Text;
 using System.Text.RegularExpressions;
 using System.Web;
@@ -272,7 +273,7 @@ public void Should_Throw_When_Comma_List_Limit_Exceeded()
 
         action
             .Should()
-            .Throw<IndexOutOfRangeException>()
+            .Throw<InvalidOperationException>()
             .WithMessage("List limit exceeded. Only 3 elements allowed in a list.");
     }
 
@@ -2277,7 +2278,7 @@ public void Decode_StrictDepth_ThrowsExceptionForMultipleNestedObjectsWithStrict
         var options = new DecodeOptions { Depth = 1, StrictDepth = true };
 
         Action act = () => Qs.Decode("a[b][c][d][e][f][g][h][i]=j", options);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -2286,7 +2287,7 @@ public void Decode_StrictDepth_ThrowsExceptionForMultipleNestedListsWithStrictDe
         var options = new DecodeOptions { Depth = 3, StrictDepth = true };
 
         Action act = () => Qs.Decode("a[0][1][2][3][4]=b", options);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -2295,7 +2296,7 @@ public void Decode_StrictDepth_ThrowsExceptionForNestedMapsAndListsWithStrictDep
         var options = new DecodeOptions { Depth = 3, StrictDepth = true };
 
         Action act = () => Qs.Decode("a[b][c][0][d][e]=f", options);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -2304,7 +2305,7 @@ public void Decode_StrictDepth_ThrowsExceptionForDifferentTypesOfValuesWithStric
         var options = new DecodeOptions { Depth = 3, StrictDepth = true };
 
         Action act = () => Qs.Decode("a[b][c][d][e]=true&a[b][c][d][f]=42", options);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -2405,7 +2406,7 @@ public void Decode_ParameterLimit_ThrowsErrorWhenParameterLimitExceeded()
         var options = new DecodeOptions { ParameterLimit = 3, ThrowOnLimitExceeded = true };
 
         Action act = () => Qs.Decode("a=1&b=2&c=3&d=4&e=5&f=6", options);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -2483,7 +2484,7 @@ public void Decode_ListLimit_ThrowsErrorWhenListLimitExceeded()
         var options = new DecodeOptions { ListLimit = 3, ThrowOnLimitExceeded = true };
 
         Action act = () => Qs.Decode("a[]=1&a[]=2&a[]=3&a[]=4", options);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -2530,7 +2531,7 @@ public void Decode_ListLimit_HandlesNegativeListLimitCorrectly()
         var options = new DecodeOptions { ListLimit = -1, ThrowOnLimitExceeded = true };
 
         Action act = () => Qs.Decode("a[]=1&a[]=2", options);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -2539,7 +2540,7 @@ public void Decode_ListLimit_AppliesListLimitToNestedLists()
         var options = new DecodeOptions { ListLimit = 3, ThrowOnLimitExceeded = true };
 
         Action act = () => Qs.Decode("a[0][]=1&a[0][]=2&a[0][]=3&a[0][]=4", options);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -4127,10 +4128,50 @@ public void Decode_NonGeneric_Hashtable_Is_Normalised()
         decoded.Should().Equal(new Dictionary<string, object?> { ["x"] = 1, ["2"] = "y" });
     }
 
+    [Fact]
+    public void Decode_CommaSplit_NoTruncationWhenSumExceedsLimit_AndThrowOff()
+    {
+        var opts = new DecodeOptions
+        {
+            Comma = true,
+            ListLimit = 3,
+            ThrowOnLimitExceeded = false,
+            ParseLists = true,
+            Duplicates = Duplicates.Combine
+        };
+
+        var result = Qs.Decode("a=1,2&a=3,4,5", opts);
+
+        var dict = Assert.IsType<Dictionary<string, object?>>(result);
+        var list = Assert.IsType<List<object?>>(dict["a"]);
+        // With ThrowOnLimitExceeded = false, no truncation occurs; full concatenation is allowed
+        list.Select(x => x?.ToString()).Should().Equal("1", "2", "3", "4", "5");
+    }
+
+    [Fact]
+    public void Decode_BracketSingle_CommaSplit_YieldsNestedList()
+    {
+        var opts = new DecodeOptions { Comma = true };
+
+        // Control: unbracketed key
+        var res = Qs.Decode("a=1,2,3", opts);
+        var dict1 = Assert.IsType<Dictionary<string, object?>>(res);
+        var list1 = Assert.IsType<List<object?>>(dict1["a"]);
+        list1.Select(x => x?.ToString()).Should().Equal("1", "2", "3");
+
+        // Bracketed single occurrence yields a nested list: [["1","2","3"]]
+        var res2 = Qs.Decode("a[]=1,2,3", opts);
+        var dict2 = Assert.IsType<Dictionary<string, object?>>(res2);
+        var outer = Assert.IsType<List<object?>>(dict2["a"]);
+        outer.Should().HaveCount(1);
+        var inner = Assert.IsType<List<object?>>(outer[0]);
+        inner.Select(x => x?.ToString()).Should().Equal("1", "2", "3");
+    }
+
     #region Encoded dot behavior in keys (%2E / %2e)
 
     [Fact]
-    public void EncodedDot_TopLevel_AllowDotsTrue_DecodeDotInKeysTrue_PlainDotSplits_EncodedDotDoesNotSplit()
+    public void EncodedDot_TopLevel_AllowDotsTrue_DecodeDotInKeysTrue_PlainAndEncodedDotSplit()
     {
         var opt = new DecodeOptions { AllowDots = true, DecodeDotInKeys = true };
 
@@ -4157,7 +4198,7 @@ public void EncodedDot_TopLevel_AllowDotsTrue_DecodeDotInKeysTrue_PlainDotSplits
     }
 
     [Fact]
-    public void EncodedDot_TopLevel_AllowDotsTrue_DecodeDotInKeysFalse_EncodedDotRemainsPercentSequence()
+    public void EncodedDot_TopLevel_AllowDotsTrue_DecodeDotInKeysFalse_EncodedDotAlsoSplits()
     {
         var opt = new DecodeOptions { AllowDots = true, DecodeDotInKeys = false };
 
@@ -4181,7 +4222,7 @@ public void EncodedDot_AllowDotsFalse_DecodeDotInKeysTrue_IsInvalid()
     {
         var opt = new DecodeOptions { AllowDots = false, DecodeDotInKeys = true };
         Action act = () => Qs.Decode("a%2Eb=c", opt);
-        act.Should().Throw<ArgumentException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -4205,7 +4246,7 @@ public void EncodedDot_BracketSegment_MapsToDot_WhenDecodeDotInKeysTrue()
     }
 
     [Fact]
-    public void EncodedDot_BracketSegment_RemainsPercentSequence_WhenDecodeDotInKeysFalse()
+    public void EncodedDot_BracketSegment_DecodesToDot_WhenDecodeDotInKeysFalse()
     {
         var opt = new DecodeOptions { AllowDots = true, DecodeDotInKeys = false };
 
@@ -4349,8 +4390,9 @@ public void MixedCase_EncodedBrackets_EncodedDot_AllowDotsFalse_DecodeDotInKeysT
     {
         var opt = new DecodeOptions { AllowDots = false, DecodeDotInKeys = true };
         Action act = () => Qs.Decode("a%5Bb%5D%5Bc%5D%2Ed=x", opt);
-        act.Should().Throw<ArgumentException>()
-            .WithMessage("*decodeDotInKeys*allowDots*");
+        act.Should().Throw<InvalidOperationException>()
+            .WithMessage("*DecodeDotInKeys*AllowDots*")
+            .WithMessage("*DecodeDotInKeys=true*AllowDots=true*");
     }
 
     [Fact]
@@ -4646,7 +4688,7 @@ public void StrictDepthOverflow_RaisesForWellFormed()
     {
         var act = () =>
             InternalDecoder.SplitKeyIntoSegments("a[b][c][d]", false, 1, true);
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -4681,4 +4723,46 @@ public void LeadingDot_EncodedBracket_AllowDotsTrue_DecodeDotInKeysTrue()
     }
 
     #endregion
+
+    #region Decode comma limit
+
+    [Fact]
+    public void Decode_CommaSplit_AllowedWhenSumEqualsLimit()
+    {
+        var opts = new DecodeOptions
+        {
+            Comma = true,
+            ListLimit = 5,
+            ThrowOnLimitExceeded = true,
+            ParseLists = true,
+            Duplicates = Duplicates.Combine
+        };
+
+        // Existing N=2 from first part, incoming M=3; N+M = 5 == limit → allowed
+        var result = Assert.IsType<Dictionary<string, object?>>(Qs.Decode("a=1,2&a=3,4,5", opts));
+        result.Should().ContainKey("a");
+
+        var list = Assert.IsType<List<object?>>(result["a"]);
+        list.Should().HaveCount(5);
+        list.Select(x => x?.ToString()).Should().Equal("1", "2", "3", "4", "5");
+    }
+
+    [Fact]
+    public void Decode_CommaSplit_ThrowsWhenSumExceedsLimitAndThrowOn()
+    {
+        var opts = new DecodeOptions
+        {
+            Comma = true,
+            ListLimit = 5,
+            ThrowOnLimitExceeded = true,
+            ParseLists = true,
+            Duplicates = Duplicates.Combine
+        };
+
+        // Existing N=2, incoming M=4; N+M = 6 > limit and ThrowOnLimitExceeded = true → throws
+        Action act = () => Qs.Decode("a=1,2&a=3,4,5,6", opts);
+        act.Should().Throw<InvalidOperationException>();
+    }
+
+    #endregion
 }

QsNet.Tests/EncodeTests.cs

@@ -1790,13 +1790,13 @@ public void Encode_DoesNotCrashWhenParsingCircularReferences()
 
         Action act1 = () =>
             Qs.Encode(new Dictionary<string, object?> { { "foo[bar]", "baz" }, { "foo[baz]", a } });
-        act1.Should().Throw<IndexOutOfRangeException>();
+        act1.Should().Throw<InvalidOperationException>();
 
         var circular = new Dictionary<string, object?> { { "a", "value" } };
         circular["a"] = circular;
 
         Action act2 = () => Qs.Encode(circular);
-        act2.Should().Throw<IndexOutOfRangeException>();
+        act2.Should().Throw<InvalidOperationException>();
 
         var arr = new List<object?> { "a" };
         Action act3 = () =>
@@ -3405,7 +3405,7 @@ public void Encode_ThrowsOnSelfReferentialMap()
         a["self"] = a;
 
         var act = () => Qs.Encode(new Dictionary<string, object?> { { "a", a } });
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]
@@ -3415,7 +3415,7 @@ public void Encode_ThrowsOnSelfReferentialList()
         l.Add(l);
 
         var act = () => Qs.Encode(new Dictionary<string, object?> { { "l", l } });
-        act.Should().Throw<IndexOutOfRangeException>();
+        act.Should().Throw<InvalidOperationException>();
     }
 
     [Fact]

QsNet.Tests/Fixtures/DummyEnum.cs

@@ -5,6 +5,7 @@ internal enum DummyEnum
     // ReSharper disable InconsistentNaming
     LOREM,
     IPSUM,
+
     DOLOR
     // ReSharper restore InconsistentNaming
 }

QsNet.Tests/UtilsTests.cs

@@ -1285,8 +1285,8 @@ public void InterpretNumericEntities_MalformedOrUnsupportedPatternsRemainUnchang
         Utils.InterpretNumericEntities("&#;").Should().Be("&#;");
         // Missing terminating semicolon
         Utils.InterpretNumericEntities("&#12").Should().Be("&#12");
-        // Hex form not supported by this decoder
-        Utils.InterpretNumericEntities("A").Should().Be("A");
+        // Hex form is supported by this decoder
+        Utils.InterpretNumericEntities("A").Should().Be("A");
         // Space inside
         Utils.InterpretNumericEntities("&# 12;").Should().Be("&# 12;");
         // Negative / non-digit after '#'
@@ -1302,6 +1302,62 @@ public void InterpretNumericEntities_OutOfRangeCodePointsRemainUnchanged()
         Utils.InterpretNumericEntities("�").Should().Be("�");
     }
 
+    [Fact]
+    public void InterpretNumericEntities_DecodesSingleHexEntity()
+    {
+        Utils.InterpretNumericEntities("A").Should().Be("A"); // uppercase hex digits
+        Utils.InterpretNumericEntities("m").Should().Be("m"); // lowercase hex digits
+    }
+
+    [Fact]
+    public void InterpretNumericEntities_DecodesSingleHexEntity_UppercaseX()
+    {
+        Utils.InterpretNumericEntities("A").Should().Be("A");
+    }
+
+    [Fact]
+    public void InterpretNumericEntities_AcceptsMaxValidHexAndRejectsBeyond()
+    {
+        // U+10FFFF is valid
+        Utils.InterpretNumericEntities("").Should().Be(char.ConvertFromUtf32(0x10FFFF));
+        // One above max should remain unchanged
+        Utils.InterpretNumericEntities("�").Should().Be("�");
+    }
+
+    [Fact]
+    public void InterpretNumericEntities_EmptyHexDigitsRemainUnchanged()
+    {
+        Utils.InterpretNumericEntities("&#x;").Should().Be("&#x;");
+        Utils.InterpretNumericEntities("&#X;").Should().Be("&#X;");
+    }
+
+    [Fact]
+    public void InterpretNumericEntities_DecodesMultipleHexEntities()
+    {
+        Utils.InterpretNumericEntities("Hi!").Should().Be("Hi!");
+    }
+
+    [Fact]
+    public void InterpretNumericEntities_DecodesHexSurrogatePair()
+    {
+        // U+1F4A9 (💩) as surrogate halves: 0xD83D, 0xDCA9
+        Utils.InterpretNumericEntities("��").Should().Be("💩");
+    }
+
+    [Fact]
+    public void InterpretNumericEntities_MixedDecimalAndHexEntities()
+    {
+        Utils.InterpretNumericEntities("A = A and B").Should().Be("A = A and B");
+    }
+
+    [Fact]
+    public void InterpretNumericEntities_InvalidHexEntitiesRemainUnchanged()
+    {
+        Utils.InterpretNumericEntities("&#xZZ;").Should().Be("&#xZZ;"); // non-hex digits
+        Utils.InterpretNumericEntities("&#x1G;").Should().Be("&#x1G;"); // invalid hex digit
+        Utils.InterpretNumericEntities("&#x41").Should().Be("&#x41"); // missing semicolon
+    }
+
     [Fact]
     public void Apply_OnScalarAndList()
     {
@@ -1567,4 +1623,24 @@ public void ToStringKeyDeepNonRecursive_Converts_Nested_Lists_And_Dicts()
 
         outTopList[2].Should().Be(4);
     }
+
+    [Fact]
+    public void EnsureAstralCharactersAtSegmentLimitMinus1OrSegmentLimitEncodeAs4ByteSequences()
+    {
+        const int SegmentLimit = 1024;
+        // Ensure astral characters at SegmentLimit-1/SegmentLimit encode as 4-byte sequences
+        var s = new string('a', SegmentLimit - 1) + "\U0001F600" + "b";
+        var encoded = Utils.Encode(s, Encoding.UTF8, Format.Rfc3986);
+        Assert.Contains("%F0%9F%98%80", encoded);
+    }
+
+    [Fact]
+    public void EnsureAstralCharactersAtSegmentLimitEncodeAs4ByteSequences()
+    {
+        const int SegmentLimit = 1024;
+        // Astral character starts exactly at the chunk boundary (index == SegmentLimit)
+        var s = new string('a', SegmentLimit) + "\U0001F600" + "b";
+        var encoded = Utils.Encode(s, Encoding.UTF8, Format.Rfc3986);
+        Assert.Contains("%F0%9F%98%80", encoded);
+    }
 }