Merge pull request #3044 from DataDog/typo/flags-resolveMap-api

feat: resolve map of primitives

Co-authored-by: typotter <[email protected]>

Author: dd-mergequeue[bot]

detekt_custom_safe_calls.yml

@@ -1152,8 +1152,8 @@ datadog:
       - "org.json.JSONArray.length()"
       - "org.json.JSONArray.toJsonArray()"
       - "org.json.JSONObject.constructor()"
-      - "org.json.JSONObject.optString(kotlin.String?, kotlin.String?)"
       - "org.json.JSONObject.keys()"
+      - "org.json.JSONObject.optString(kotlin.String?, kotlin.String?)"
       - "org.json.JSONObject.toJsonObject()"
       # endregion
       # region Opentelemetry

features/dd-sdk-android-flags/api/apiSurface

@@ -7,6 +7,7 @@ interface com.datadog.android.flags.FlagsClient
   fun resolveDoubleValue(String, Double): Double
   fun resolveIntValue(String, Int): Int
   fun resolveStructureValue(String, org.json.JSONObject): org.json.JSONObject
+  fun resolveStructureValue(String, Map<String, Any?>): Map<String, Any?>
   fun <T: Any> resolve(String, T): com.datadog.android.flags.model.ResolutionDetails<T>
   val state: StateObservable
   class Builder

features/dd-sdk-android-flags/api/dd-sdk-android-flags.api

@@ -17,6 +17,7 @@ public abstract interface class com/datadog/android/flags/FlagsClient {
 	public abstract fun resolveDoubleValue (Ljava/lang/String;D)D
 	public abstract fun resolveIntValue (Ljava/lang/String;I)I
 	public abstract fun resolveStringValue (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String;
+	public abstract fun resolveStructureValue (Ljava/lang/String;Ljava/util/Map;)Ljava/util/Map;
 	public abstract fun resolveStructureValue (Ljava/lang/String;Lorg/json/JSONObject;)Lorg/json/JSONObject;
 	public abstract fun setEvaluationContext (Lcom/datadog/android/flags/model/EvaluationContext;)V
 }

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/FlagsClient.kt

@@ -108,14 +108,30 @@ interface FlagsClient {
     fun resolveIntValue(flagKey: String, defaultValue: Int): Int
 
     /**
-     * Resolves a structured flag value as a JSON object.
+     * Resolves a structured flag value as a [JSONObject].
      *
      * @param flagKey The unique identifier of the flag to resolve.
      * @param defaultValue The value to return if the flag cannot be retrieved or parsed.
      * @return The JSON object value of the flag, or the default value if unavailable.
      */
     fun resolveStructureValue(flagKey: String, defaultValue: JSONObject): JSONObject
 
+    /**
+     * Resolves a structured flag value as a Map.
+     *
+     * The returned Map contains only primitives (String, Int, Long, Double, Boolean),
+     * null values, nested Maps, and Lists. All nested structures are recursively
+     * converted.
+     *
+     * This method is useful for integrations that prefer working with Kotlin collections
+     * over JSON types.
+     *
+     * @param flagKey The unique identifier of the flag to resolve.
+     * @param defaultValue The map to return if the flag cannot be retrieved or parsed.
+     * @return The map value of the flag, or the default value if unavailable.
+     */
+    fun resolveStructureValue(flagKey: String, defaultValue: Map<String, Any?>): Map<String, Any?>
+
     /**
      * Resolves a flag value with detailed resolution information.
      *

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/DatadogFlagsClient.kt

@@ -128,6 +128,23 @@ internal class DatadogFlagsClient(
     override fun resolveStructureValue(flagKey: String, defaultValue: JSONObject): JSONObject =
         resolveValue(flagKey, defaultValue)
 
+    /**
+     * Resolves a structured flag value as a Map (overload).
+     *
+     * The returned Map contains no JSON types - all nested structures are recursively
+     * converted to Maps and Lists with only primitives, null, and nested collections.
+     *
+     * If the flag cannot be found or an error occurs, the default value is returned.
+     *
+     * @param flagKey The name of the flag to query. Cannot be null.
+     * @param defaultValue The map to return if the flag cannot be found or resolved.
+     * @return The map value of the flag, or the default value if unavailable.
+     */
+    override fun resolveStructureValue(flagKey: String, defaultValue: Map<String, Any?>): Map<String, Any?> {
+        val result = resolveValue(flagKey, defaultValue)
+        return result
+    }
+
     /**
      * Resolves a flag value with detailed resolution information.
      *

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/FlagValueConverter.kt

@@ -55,8 +55,16 @@ internal object FlagValueConverter {
                 String::class -> variationValue as T
                 Int::class -> variationValue.toIntOrNull() as? T
                 Double::class -> variationValue.toDoubleOrNull() as? T
+                Map::class -> variationValue.toMap() as? T
                 JSONObject::class -> JSONObject(variationValue) as? T
-                else -> null
+                else -> {
+                    // Check if targetType is a Map implementation
+                    if (Map::class.java.isAssignableFrom(targetType.java)) {
+                        variationValue.toMap() as? T
+                    } else {
+                        null
+                    }
+                }
             }
 
             result ?: throw IllegalArgumentException("Failed to parse value '$variationValue'")
@@ -78,7 +86,15 @@ internal object FlagValueConverter {
             variationType == VariationType.NUMBER.value || variationType == VariationType.FLOAT.value ||
                 variationType == VariationType.INTEGER.value
         JSONObject::class -> variationType == VariationType.OBJECT.value
-        else -> false
+        Map::class -> variationType == VariationType.OBJECT.value
+        else -> {
+            // Check if targetType is a Map implementation (e.g., LinkedHashMap, HashMap, etc.)
+            if (Map::class.java.isAssignableFrom(targetType.java)) {
+                variationType == VariationType.OBJECT.value
+            } else {
+                false
+            }
+        }
     }
 
     fun getTypeName(targetType: KClass<*>): String = when (targetType) {
@@ -87,6 +103,7 @@ internal object FlagValueConverter {
         Int::class -> "Int"
         Double::class -> "Double"
         JSONObject::class -> "JSONObject"
+        Map::class -> "Map"
         else -> targetType.simpleName ?: "Unknown"
     }
 }

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/JsonExtensions.kt

@@ -0,0 +1,163 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2016-Present Datadog, Inc.
+ */
+
+package com.datadog.android.flags.internal
+
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+/**
+ * Parses a JSON string and converts it to a Map with no JSON types.
+ *
+ * The returned Map contains only primitives (String, Int, Long, Double, Boolean),
+ * null, nested Maps, and nested Lists. Nested JSONObjects and JSONArrays are
+ * recursively converted.
+ *
+ * @return A map with primitive types, null, nested Maps, and nested Lists
+ * @throws JSONException if the string is not valid JSON
+ */
+internal fun String.toMap(): Map<String, Any?> {
+    // Safe: Input validation happens at call site; JSONException is expected to propagate
+    @Suppress("UnsafeThirdPartyFunctionCall")
+    val jsonObject = JSONObject(this)
+    return jsonObject.toMap()
+}
+
+/**
+ * Recursively converts a [JSONObject] to a [Map] with no JSON types.
+ *
+ * Nested JSONObjects and JSONArrays are recursively converted to Maps and Lists.
+ * The returned Map contains only primitives (String, Int, Long, Double, Boolean),
+ * null, nested Maps, and nested Lists.
+ *
+ * JSONObject.NULL values are converted to null.
+ *
+ * @return A map with primitive types, null, nested Maps, and nested Lists
+ */
+internal fun JSONObject.toMap(): Map<String, Any?> {
+    val result = mutableMapOf<String, Any?>()
+    val keys = this.keys()
+
+    // Safe: Standard iterator pattern - hasNext() checks state, next() is safe after hasNext() returns true
+    @Suppress("UnsafeThirdPartyFunctionCall")
+    while (keys.hasNext()) {
+        @Suppress("UnsafeThirdPartyFunctionCall")
+        val key = keys.next()
+        // Safe: Key exists because it came from keys() iterator
+        @Suppress("UnsafeThirdPartyFunctionCall")
+        result[key] = convertJsonValue(this.get(key))
+    }
+
+    return result
+}
+
+/**
+ * Recursively converts a [JSONArray] to a [List] with no JSON types.
+ *
+ * Nested JSONObjects and JSONArrays are recursively converted to Maps and Lists.
+ * The returned List contains only primitives (String, Int, Long, Double, Boolean),
+ * null, nested Maps, and nested Lists.
+ *
+ * JSONObject.NULL values are converted to null.
+ *
+ * @return A list with primitive types, null, nested Maps, and nested Lists
+ */
+internal fun JSONArray.toList(): List<Any?> {
+    val result = mutableListOf<Any?>()
+
+    // Safe: Iterating within bounds (0 until length)
+    @Suppress("UnsafeThirdPartyFunctionCall")
+    for (i in 0 until this.length()) {
+        // Safe: Index is within bounds (0 until length)
+        @Suppress("UnsafeThirdPartyFunctionCall")
+        result.add(convertJsonValue(this.get(i)))
+    }
+
+    return result
+}
+
+/**
+ * Converts a Map to a JSONObject, recursively converting nested Maps and Lists.
+ *
+ * Nested Maps and Lists are recursively converted to JSONObjects and JSONArrays.
+ * Null values are converted to JSONObject.NULL.
+ *
+ * @return A JSONObject with all nested structures converted
+ */
+internal fun Map<String, Any?>.toJSONObject(): JSONObject {
+    val jsonObject = JSONObject()
+
+    forEach { (key, value) ->
+        // Safe: convertToJsonValue ensures valid types (primitives, JSONObject.NULL, JSONObject, JSONArray)
+        @Suppress("UnsafeThirdPartyFunctionCall")
+        jsonObject.put(key, convertToJsonValue(value))
+    }
+
+    return jsonObject
+}
+
+/**
+ * Converts a List to a JSONArray, recursively converting nested Maps and Lists.
+ *
+ * Nested Maps and Lists are recursively converted to JSONObjects and JSONArrays.
+ * Null values are converted to JSONObject.NULL.
+ *
+ * @return A JSONArray with all nested structures converted
+ */
+internal fun List<*>.toJSONArray(): JSONArray {
+    val jsonArray = JSONArray()
+
+    forEach { value ->
+        // Safe: convertToJsonValue ensures valid types (primitives, JSONObject.NULL, JSONObject, JSONArray)
+        @Suppress("UnsafeThirdPartyFunctionCall")
+        jsonArray.put(convertToJsonValue(value))
+    }
+
+    return jsonArray
+}
+
+/**
+ * Converts a Kotlin value to a JSON-compatible value.
+ *
+ * Recursively handles nested structures:
+ * - Map<*, *> → JSONObject (non-String keys converted via toString())
+ * - List<*> → JSONArray
+ * - null → JSONObject.NULL
+ * - Primitives → unchanged
+ *
+ * @param value The Kotlin value to convert
+ * @return The JSON-compatible value
+ */
+private fun convertToJsonValue(value: Any?): Any = when (value) {
+    null -> JSONObject.NULL
+    is Map<*, *> -> {
+        // Convert keys to String (supports non-String keys via toString())
+        val stringMap = value.entries.associate { (k, v) -> k.toString() to v }
+        stringMap.toJSONObject()
+    }
+    is List<*> -> value.toJSONArray()
+    else -> value // Primitives: String, Int, Long, Double, Boolean
+}
+
+/**
+ * Converts a JSON value (from JSONObject.get or JSONArray.get) to a plain Kotlin type.
+ *
+ * Recursively handles nested structures:
+ * - JSONObject → Map<String, Any?>
+ * - JSONArray → List<Any?>
+ * - Primitives → String, Int, Long, Double, Boolean
+ * - JSONObject.NULL → null
+ *
+ * @param value The value from JSONObject or JSONArray
+ * @return The converted value with no JSON types
+ */
+private fun convertJsonValue(value: Any?): Any? = when (value) {
+    JSONObject.NULL -> null
+    is JSONObject -> value.toMap()
+    is JSONArray -> value.toList()
+    else -> value // Primitives: String, Int, Long, Double, Boolean, or null
+}

features/dd-sdk-android-flags/src/main/kotlin/com/datadog/android/flags/internal/NoOpFlagsClient.kt

@@ -123,6 +123,17 @@ internal class NoOpFlagsClient(
         return defaultValue
     }
 
+    /**
+     * Returns the provided default value without any flag evaluation.
+     * @param flagKey Ignored flag key.
+     * @param defaultValue The map to return.
+     * @return The provided default value.
+     */
+    override fun resolveStructureValue(flagKey: String, defaultValue: Map<String, Any?>): Map<String, Any?> {
+        logOperation("resolveStructureValue for flag '$flagKey'", InternalLogger.Level.WARN)
+        return defaultValue
+    }
+
     /**
      * Logs an operation call on this NoOpFlagsClient using the policy-aware logging function.
      * This ensures visibility in both debug builds (MAINTAINER) and production (USER, if verbosity allows).

features/dd-sdk-android-flags/src/test/kotlin/com/datadog/android/flags/NoOpFlagsClientTest.kt

@@ -467,4 +467,24 @@ internal class NoOpFlagsClientTest {
     }
 
     // endregion
+
+    // region resolveStructureValue() - Map overload
+
+    @Test
+    fun `M return default map W resolveStructureValue() {map default}`(forge: Forge) {
+        // Given
+        val fakeFlagKey = forge.anAlphabeticalString()
+        val fakeDefaultValue = mapOf(
+            "key1" to forge.anAlphabeticalString(),
+            "key2" to forge.anInt()
+        )
+
+        // When
+        val result = testedClient.resolveStructureValue(fakeFlagKey, fakeDefaultValue)
+
+        // Then
+        assertThat(result).isEqualTo(fakeDefaultValue)
+    }
+
+    // endregion
 }