✨ add support for sparse Lists in DecodeOptions and update compact utility method

Author: techouse

qs-kotlin/src/main/kotlin/io/github/techouse/qskotlin/internal/Utils.kt

@@ -476,13 +476,18 @@ internal object Utils {
      * intact.
      *
      * @param root The root of the Map or List structure to compact.
+     * @param allowSparseLists If true, allows sparse Lists (i.e., Lists with Undefined values). If
+     *   false, removes all Undefined values from Lists.
      * @return The compacted Map or List structure.
      */
-    fun compact(root: MutableMap<String, Any?>): MutableMap<String, Any?> {
+    fun compact(
+        root: MutableMap<String, Any?>,
+        allowSparseLists: Boolean = false,
+    ): MutableMap<String, Any?> {
         val stack = ArrayDeque<Any>()
         stack.add(root)
 
-        // Identity-based visited set: avoids infinite loops on cycles
+        // Identity-based visited set to prevent cycles
         val visited: MutableSet<Any> = Collections.newSetFromMap(IdentityHashMap())
 
         visited.add(root)
@@ -518,7 +523,7 @@ internal object Utils {
                     val it = list.listIterator()
                     while (it.hasNext()) {
                         when (val v = it.next()) {
-                            is Undefined -> it.remove()
+                            is Undefined -> if (allowSparseLists) it.set(null) else it.remove()
 
                             is MutableMap<*, *> -> {
                                 if (visited.add(v)) {

qs-kotlin/src/main/kotlin/io/github/techouse/qskotlin/models/DecodeOptions.kt

@@ -34,6 +34,9 @@ data class DecodeOptions(
     /** Set to `true` to allow empty List values inside Maps in the encoded input. */
     val allowEmptyLists: Boolean = false,
 
+    /** Set to `true` to allow sparse Lists in the encoded input. */
+    val allowSparseLists: Boolean = false,
+
     /**
      * QS will limit specifying indices in a List to a maximum index of `20`. Any List members with
      * an index of greater than `20` will instead be converted to a Map with the index as the key.

qs-kotlin/src/main/kotlin/io/github/techouse/qskotlin/qs.kt

@@ -69,7 +69,7 @@ fun decode(input: Any?, options: DecodeOptions? = null): Map<String, Any?> {
         }
     }
 
-    return Utils.compact(obj)
+    return Utils.compact(obj, options.allowSparseLists)
 }
 
 /**

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

@@ -366,7 +366,7 @@ class QsParserSpec :
             }
 
             it("should parse sparse arrays") {
-                val optionsAllowSparse = DecodeOptions(allowSparse = true)
+                val optionsAllowSparse = DecodeOptions(allowSparseLists = true)
 
                 decode("a[4]=1&a[1]=2", optionsAllowSparse) shouldBe
                     mapOf("a" to listOf(null, "2", null, null, "1"))
@@ -510,11 +510,11 @@ class QsParserSpec :
             }
 
             it("should use number decoder") {
-                val numberDecoder: io.github.techouse.qskotlin.models.Decoder = { value, _ ->
+                val numberDecoder: Decoder = { value, _ ->
                     try {
                         val intValue = value?.toInt()
                         "[$intValue]"
-                    } catch (e: NumberFormatException) {
+                    } catch (_: NumberFormatException) {
                         value
                     }
                 }
@@ -665,10 +665,8 @@ class QsParserSpec :
             }
 
             it("should allow for decoding keys and values") {
-                val keyValueDecoder: io.github.techouse.qskotlin.models.Decoder = { content, _ ->
-                    // Note: Kotlin implementation doesn't distinguish between key and value
-                    // decoding
-                    // This is a simplified version
+                val keyValueDecoder: Decoder = { content, _ ->
+                    // Note: Kotlin implementation doesn't distinguish between key and value decoding
                     content?.lowercase()
                 }
                 val options = DecodeOptions(decoder = keyValueDecoder)