✅ add more tests (#34)

Author: techouse

qs-kotlin/src/test/kotlin/io/github/techouse/qskotlin/unit/EncodeSpec.kt

@@ -20,7 +20,7 @@ import java.time.Instant
 import java.time.LocalDateTime
 import java.time.ZoneId
 import java.time.ZoneOffset
-import java.util.Locale
+import java.util.*
 
 class EncodeSpec :
     DescribeSpec({
@@ -112,7 +112,7 @@ class EncodeSpec :
                             EncodeOptions(
                                 encode = false,
                                 filter =
-                                    FunctionFilter { prefix: String, map: Any? ->
+                                    FunctionFilter { _: String, map: Any? ->
                                         // This should trigger the code path that accesses
                                         // properties of non-Map, non-Iterable objects
                                         val result = mutableMapOf<String, Any?>()
@@ -1184,7 +1184,7 @@ class EncodeSpec :
 
                         value is LocalDateTime -> {
                             prefix shouldBe "e[f]"
-                            value.atZone(java.time.ZoneOffset.UTC).toInstant().toEpochMilli()
+                            value.atZone(ZoneOffset.UTC).toInstant().toEpochMilli()
                         }
 
                         else -> value
@@ -2014,7 +2014,7 @@ class EncodeSpec :
 
             it("FunctionFilter branch inside recursion (prefix non-empty)") {
                 var count = 0
-                val filter = FunctionFilter { prefix, value ->
+                val filter = FunctionFilter { _, value ->
                     count += 1
                     // When prefix not empty return value unchanged; at root return original map
                     value

qs-kotlin/src/test/kotlin/io/github/techouse/qskotlin/unit/SentinelSpec.kt

@@ -0,0 +1,13 @@
+package io.github.techouse.qskotlin.unit
+
+import io.github.techouse.qskotlin.enums.Sentinel
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.shouldBe
+
+class SentinelSpec :
+    FunSpec({
+        test("sentinel encoded values are exposed") {
+            Sentinel.ISO.asQueryParam() shouldBe Sentinel.ISO.toString()
+            Sentinel.CHARSET.toEntry().key shouldBe Sentinel.PARAM_NAME
+        }
+    })

qs-kotlin/src/test/kotlin/io/github/techouse/qskotlin/unit/UtilsSpec.kt

@@ -3,6 +3,7 @@ package io.github.techouse.qskotlin.unit
 import io.github.techouse.qskotlin.enums.Format
 import io.github.techouse.qskotlin.fixtures.DummyEnum
 import io.github.techouse.qskotlin.internal.Utils
+import io.github.techouse.qskotlin.models.DecodeOptions
 import io.github.techouse.qskotlin.models.Undefined
 import io.kotest.core.spec.style.FunSpec
 import io.kotest.matchers.maps.shouldContainKey
@@ -129,6 +130,10 @@ class UtilsSpec :
                 Utils.encode(Undefined()) shouldBe ""
             }
 
+            test("falls back to defaults when charset or format null") {
+                Utils.encode("plain", null, null) shouldBe "plain"
+            }
+
             test("handles special characters") {
                 Utils.encode("~._-") shouldBe "~._-"
                 Utils.encode("!@#\$%^&*()") shouldBe "%21%40%23%24%25%5E%26%2A%28%29"
@@ -194,6 +199,10 @@ class UtilsSpec :
                 Utils.decode("foo%28bar%29", StandardCharsets.ISO_8859_1) shouldBe "foo(bar)"
             }
 
+            test("invalid percent sequence falls back to literal") {
+                Utils.decode("%E0") shouldBe "\uFFFD"
+            }
+
             test("decodes URL-encoded strings") {
                 Utils.decode("a+b") shouldBe "a b"
                 Utils.decode("name%2Eobj") shouldBe "name.obj"
@@ -202,6 +211,25 @@ class UtilsSpec :
             }
         }
 
+        context("Utils.compact") {
+            test("removes undefined entries and compacts nested lists") {
+                val inner = mutableListOf<Any?>(Undefined(), "value")
+                val root = mutableMapOf<String, Any?>("a" to Undefined(), "b" to inner)
+
+                val compacted = Utils.compact(root, allowSparseLists = false)
+                compacted shouldBe mutableMapOf<String, Any?>("b" to mutableListOf<Any?>("value"))
+            }
+
+            test("respects allowSparseLists and avoids cycles") {
+                val list = mutableListOf<Any?>(Undefined(), "v")
+                val root = mutableMapOf<String, Any?>("self" to list)
+                list += root // introduce cycle
+
+                val compacted = Utils.compact(root, allowSparseLists = true)
+                compacted["self"].shouldBeInstanceOf<MutableList<*>>()
+            }
+        }
+
         @Suppress("DEPRECATION")
         context("Utils.escape") {
             test("handles basic alphanumerics (remain unchanged)") {
@@ -368,6 +396,42 @@ class UtilsSpec :
         }
 
         context("Utils.merge") {
+            test("merges custom iterable target with iterable source producing list with wrapper") {
+                val target = BoxIterable(listOf("foo"))
+                val result = Utils.merge(target, listOf("bar"))
+
+                result.shouldBeInstanceOf<List<*>>()
+                result.size shouldBe 2
+                result[0] shouldBe target
+                result[1] shouldBe "bar"
+            }
+
+            test("merges custom iterable target with scalar source into list") {
+                val target = BoxIterable(listOf("foo"))
+                val result = Utils.merge(target, "bar")
+
+                result.shouldBeInstanceOf<List<*>>()
+                result.size shouldBe 2
+                result[0] shouldBe target
+                result[1] shouldBe "bar"
+            }
+
+            test("merges iterables of maps by index and merges entries") {
+                val target = listOf(mapOf("a" to 1))
+                val source = listOf(mapOf("b" to 2))
+
+                val result = Utils.merge(target, source)
+                result shouldBe listOf(mapOf("a" to 1, "b" to 2))
+            }
+
+            test("merges custom iterable of maps preserving merge semantics") {
+                val target = BoxIterable(listOf(mapOf("a" to 1)))
+                val source = listOf(mapOf("b" to 2))
+
+                val result = Utils.merge(target, source)
+                result shouldBe listOf(mapOf("a" to 1, "b" to 2))
+            }
+
             test("merges Map with List") {
                 Utils.merge(mapOf(0 to "a"), listOf(Undefined(), "b")) shouldBe
                     mapOf(0 to "a", "1" to "b")
@@ -584,6 +648,26 @@ class UtilsSpec :
                 map.shouldContainKey("foo")
                 map["foo"].shouldBeInstanceOf<Set<Map<String, String>>>()
             }
+
+            test("merge trims undefined placeholders when parseLists disabled") {
+                val result =
+                    Utils.merge(
+                        listOf(Undefined(), "keep"),
+                        emptyList<String>(),
+                        DecodeOptions(parseLists = false),
+                    )
+                result shouldBe mapOf<String, Any?>("1" to "keep")
+            }
+
+            test("merge scalar with iterable promotes to list without undefined") {
+                val result = Utils.merge("left", listOf("right", Undefined()))
+                result shouldBe listOf("left", "right")
+            }
+
+            test("merge iterable target with map source indexes existing elements") {
+                val result = Utils.merge(listOf("a", Undefined()), mapOf("b" to "c"))
+                result shouldBe mapOf<String, Any?>("0" to "a", "b" to "c")
+            }
         }
 
         context("Utils.combine") {
@@ -650,6 +734,10 @@ class UtilsSpec :
                 Utils.interpretNumericEntities("&#55357;&#56489;") shouldBe "💩"
             }
 
+            test("decodes single entity above BMP as surrogate pair") {
+                Utils.interpretNumericEntities("&#128169;") shouldBe "💩"
+            }
+
             test("entities can appear at string boundaries") {
                 Utils.interpretNumericEntities("&#65;BC") shouldBe "ABC"
                 Utils.interpretNumericEntities("ABC&#33;") shouldBe "ABC!"
@@ -694,12 +782,18 @@ class UtilsSpec :
             test("treats URI as primitive, honors skipNulls for empty string") {
                 Utils.isNonNullishPrimitive(URI("https://example.com")) shouldBe true
                 Utils.isNonNullishPrimitive("", skipNulls = true) shouldBe false
+                Utils.isNonNullishPrimitive(URI(""), skipNulls = true) shouldBe false
             }
         }
 
         context("Utils.isEmpty") {
             test("empty collections and maps") {
                 Utils.isEmpty(emptyMap<String, Any?>()) shouldBe true
+                Utils.isEmpty(emptyList<String>()) shouldBe true
             }
         }
     })
+
+private class BoxIterable<T>(private val items: List<T>) : Iterable<T> {
+    override fun iterator(): Iterator<T> = items.iterator()
+}

qs-kotlin/src/test/kotlin/io/github/techouse/qskotlin/unit/internal/DecoderInternalSpec.kt

@@ -0,0 +1,47 @@
+package io.github.techouse.qskotlin.unit.internal
+
+import io.github.techouse.qskotlin.internal.Decoder
+import io.github.techouse.qskotlin.models.DecodeOptions
+import io.kotest.assertions.throwables.shouldThrow
+import io.kotest.core.spec.style.DescribeSpec
+import io.kotest.matchers.shouldBe
+import java.nio.charset.StandardCharsets
+
+class DecoderInternalSpec :
+    DescribeSpec({
+        describe("Decoder.parseQueryStringValues") {
+            it("rejects non-positive parameter limits") {
+                shouldThrow<IllegalArgumentException> {
+                    Decoder.parseQueryStringValues("a=1", DecodeOptions(parameterLimit = 0))
+                }
+            }
+
+            it("throws when parameter limit exceeded and throwOnLimitExceeded=true") {
+                val options = DecodeOptions(parameterLimit = 1, throwOnLimitExceeded = true)
+                shouldThrow<IndexOutOfBoundsException> {
+                    Decoder.parseQueryStringValues("a=1&b=2", options)
+                }
+            }
+
+            it("splits comma-delimited lists respecting limits") {
+                val options = DecodeOptions(comma = true)
+                val result = Decoder.parseQueryStringValues("list=a,b", options)
+                result["list"] shouldBe listOf("a", "b")
+            }
+
+            it("respects charset sentinel and numeric entities") {
+                val options =
+                    DecodeOptions(
+                        interpretNumericEntities = true,
+                        charset = StandardCharsets.ISO_8859_1,
+                        charsetSentinel = true,
+                        ignoreQueryPrefix = true,
+                    )
+
+                val result =
+                    Decoder.parseQueryStringValues("?utf8=%26%2310003%3B&name=%26%2365%3B", options)
+                result.containsKey("name") shouldBe true
+                result["name"] shouldBe "A"
+            }
+        }
+    })

qs-kotlin/src/test/kotlin/io/github/techouse/qskotlin/unit/internal/EncoderInternalSpec.kt

@@ -0,0 +1,123 @@
+package io.github.techouse.qskotlin.unit.internal
+
+import io.github.techouse.qskotlin.enums.Format
+import io.github.techouse.qskotlin.enums.ListFormat
+import io.github.techouse.qskotlin.internal.Encoder
+import io.github.techouse.qskotlin.models.IterableFilter
+import io.kotest.core.spec.style.DescribeSpec
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.types.shouldBeInstanceOf
+import java.nio.charset.StandardCharsets
+import java.time.LocalDateTime
+
+class EncoderInternalSpec :
+    DescribeSpec({
+        describe("Encoder.encode internals") {
+            it("applies defaults when optional parameters are null") {
+                val calls = mutableListOf<String>()
+                val data = arrayOf("v1")
+                val result =
+                    Encoder.encode(
+                        data = data,
+                        undefined = false,
+                        sideChannel = mutableMapOf(),
+                        prefix = null,
+                        generateArrayPrefix = null,
+                        commaRoundTrip = null,
+                        encoder = { value, _, _ ->
+                            val text = value?.toString() ?: "<null>"
+                            calls += text
+                            "enc:$text"
+                        },
+                        format = Format.RFC3986,
+                        formatter = Format.RFC3986.formatter,
+                        charset = StandardCharsets.UTF_8,
+                        addQueryPrefix = true,
+                    )
+
+                result.shouldBeInstanceOf<String>()
+                result shouldBe "enc:?=enc:$data"
+                calls shouldBe listOf("?", data.toString())
+            }
+
+            it("encodes arrays using indices generator") {
+                val data = arrayOf("v0", "v1")
+                val result =
+                    Encoder.encode(
+                        data = data,
+                        undefined = false,
+                        sideChannel = mutableMapOf(),
+                        prefix = "arr",
+                        generateArrayPrefix = ListFormat.INDICES.generator,
+                        encoder = { value, _, _ -> value?.toString() ?: "" },
+                        format = Format.RFC3986,
+                        formatter = Format.RFC3986.formatter,
+                        charset = StandardCharsets.UTF_8,
+                    )
+
+                result.shouldBeInstanceOf<String>()
+                result.startsWith("arr=") shouldBe true
+            }
+
+            it("skips out-of-range array indices exposed by IterableFilter") {
+                val result =
+                    Encoder.encode(
+                        data = arrayOf("only"),
+                        undefined = false,
+                        sideChannel = mutableMapOf(),
+                        prefix = "arr",
+                        generateArrayPrefix = ListFormat.INDICES.generator,
+                        filter = IterableFilter(listOf(2)),
+                        encoder = { value, _, _ -> value?.toString() ?: "" },
+                        format = Format.RFC3986,
+                        formatter = Format.RFC3986.formatter,
+                        charset = StandardCharsets.UTF_8,
+                    )
+
+                result.shouldBeInstanceOf<String>()
+                result.startsWith("arr=") shouldBe true
+            }
+
+            it("handles unsupported object types by skipping values") {
+                val result =
+                    Encoder.encode(
+                        data = Plain("value"),
+                        undefined = false,
+                        sideChannel = mutableMapOf(),
+                        prefix = "plain",
+                        generateArrayPrefix = ListFormat.INDICES.generator,
+                        filter = IterableFilter(listOf("prop")),
+                        encoder = { value, _, _ -> value?.toString() ?: "" },
+                        format = Format.RFC3986,
+                        formatter = Format.RFC3986.formatter,
+                        charset = StandardCharsets.UTF_8,
+                    )
+
+                result.shouldBeInstanceOf<String>()
+                result shouldBe "plain=value"
+            }
+
+            it("serializes LocalDateTime values with custom serializer") {
+                val stamp = LocalDateTime.parse("2024-05-01T10:15:00")
+                val result =
+                    Encoder.encode(
+                        data = stamp,
+                        undefined = false,
+                        sideChannel = mutableMapOf(),
+                        prefix = "ts",
+                        serializeDate = { dt -> "X${dt.toLocalDate()}" },
+                        encoder = { value, _, _ -> value?.toString() ?: "" },
+                        format = Format.RFC3986,
+                        formatter = Format.RFC3986.formatter,
+                        charset = StandardCharsets.UTF_8,
+                    )
+
+                result.shouldBeInstanceOf<String>()
+                result shouldBe "ts=X2024-05-01"
+            }
+        }
+    })
+
+private class Plain(private val value: String) {
+    override fun toString(): String = value
+}