DSL Builders

/**
 * Builds JsonObject with the given builderAction
 * @param builderAction Lambda with receiver for building object content
 * @return Constructed JsonObject
 */  
inline fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject

/**
 * DSL builder for JsonObject with methods to add key-value pairs
 */
class JsonObjectBuilder {
    /**
     * Add the given JSON element to resulting object using the given key
     * @param key Property name
     * @param element JsonElement value
     * @return Previous value associated with key, or null
     */
    fun put(key: String, element: JsonElement): JsonElement?
    
    /**
     * Add boolean value to resulting object using the given key
     * @param key Property name  
     * @param value Boolean value (null creates JsonNull)
     * @return Previous value associated with key, or null
     */
    fun put(key: String, value: Boolean?): JsonElement?
    
    /**
     * Add numeric value to resulting object using the given key
     * @param key Property name
     * @param value Number value (null creates JsonNull)
     * @return Previous value associated with key, or null
     */
    fun put(key: String, value: Number?): JsonElement?
    
    /**
     * Add string value to resulting object using the given key
     * @param key Property name
     * @param value String value (null creates JsonNull)
     * @return Previous value associated with key, or null
     */
    fun put(key: String, value: String?): JsonElement?
    
    /**
     * Add null value to resulting object using the given key
     * @param key Property name
     * @param value Must be null literal
     * @return Previous value associated with key, or null
     */
    fun put(key: String, value: Nothing?): JsonElement?
}

/**
 * Add nested JsonObject produced by builderAction to resulting object
 * @param key Property name
 * @param builderAction Lambda for building nested object
 * @return Previous value associated with key, or null
 */
fun JsonObjectBuilder.putJsonObject(key: String, builderAction: JsonObjectBuilder.() -> Unit): JsonElement?

/**
 * Add nested JsonArray produced by builderAction to resulting object
 * @param key Property name
 * @param builderAction Lambda for building nested array
 * @return Previous value associated with key, or null
 */
fun JsonObjectBuilder.putJsonArray(key: String, builderAction: JsonArrayBuilder.() -> Unit): JsonElement?

// Basic object construction
val userObject = buildJsonObject {
    put("id", 123)
    put("name", "Alice")
    put("active", true)
    put("email", null) // Creates JsonNull
}
// Result: {"id":123,"name":"Alice","active":true,"email":null}

// Nested objects and arrays
val complexObject = buildJsonObject {
    put("userId", 456)
    put("profile", buildJsonObject {
        put("firstName", "Bob")
        put("lastName", "Smith")
        put("age", 30)
    })
    put("permissions", buildJsonArray {
        add("read")
        add("write")
        add("admin")
    })
}

// Using put methods for different types
val apiResponse = buildJsonObject {
    put("success", true)
    put("timestamp", System.currentTimeMillis())
    put("message", "Operation completed")
    put("data", JsonPrimitive("custom element"))
}

// Nested with DSL extension functions
val settingsObject = buildJsonObject {
    put("version", "1.0")
    
    putJsonObject("database") {
        put("host", "localhost")
        put("port", 5432)
        put("ssl", true)
    }
    
    putJsonArray("features") {
        add("authentication")
        add("logging")
        add("metrics")
    }
}

/**
 * Builds JsonArray with the given builderAction
 * @param builderAction Lambda with receiver for building array content
 * @return Constructed JsonArray
 */
inline fun buildJsonArray(builderAction: JsonArrayBuilder.() -> Unit): JsonArray

/**
 * DSL builder for JsonArray with methods to add elements
 */
class JsonArrayBuilder {
    /**
     * Adds the given JSON element to resulting array
     * @param element JsonElement to add
     * @return Always true (similar to ArrayList specification)
     */
    fun add(element: JsonElement): Boolean
    
    /**
     * Adds the given boolean value to resulting array
     * @param value Boolean value (null creates JsonNull)
     * @return Always true
     */
    fun add(value: Boolean?): Boolean
    
    /**
     * Adds the given numeric value to resulting array
     * @param value Number value (null creates JsonNull)
     * @return Always true
     */
    fun add(value: Number?): Boolean
    
    /**
     * Adds the given string value to resulting array
     * @param value String value (null creates JsonNull)
     * @return Always true
     */
    fun add(value: String?): Boolean
    
    /**
     * Adds null value to resulting array
     * @param value Must be null literal
     * @return Always true
     */
    fun add(value: Nothing?): Boolean
    
    /**
     * Adds the given JSON elements to resulting array
     * @param elements Collection of JsonElements to add
     * @return true if array was changed
     */
    fun addAll(elements: Collection<JsonElement>): Boolean
    
    /**
     * Adds the given string values to resulting array
     * @param values Collection of strings to add
     * @return true if array was changed
     */
    fun addAll(values: Collection<String?>): Boolean
    
    /**
     * Adds the given boolean values to resulting array
     * @param values Collection of booleans to add
     * @return true if array was changed
     */
    fun addAll(values: Collection<Boolean?>): Boolean
    
    /**
     * Adds the given numeric values to resulting array
     * @param values Collection of numbers to add
     * @return true if array was changed
     */
    fun addAll(values: Collection<Number?>): Boolean
}

/**
 * Adds nested JsonObject produced by builderAction to resulting array
 * @param builderAction Lambda for building nested object
 * @return Always true
 */
fun JsonArrayBuilder.addJsonObject(builderAction: JsonObjectBuilder.() -> Unit): Boolean

/**
 * Adds nested JsonArray produced by builderAction to resulting array
 * @param builderAction Lambda for building nested array
 * @return Always true
 */
fun JsonArrayBuilder.addJsonArray(builderAction: JsonArrayBuilder.() -> Unit): Boolean

// Basic array construction
val numbersArray = buildJsonArray {
    add(1)
    add(2.5)
    add(3L)
    add(null) // Creates JsonNull
}
// Result: [1,2.5,3,null]

// Mixed type array
val mixedArray = buildJsonArray {
    add("string")
    add(42)
    add(true)
    add(JsonPrimitive("custom"))
}
// Result: ["string",42,true,"custom"]

// Nested structures
val complexArray = buildJsonArray {
    // Add simple values
    add("header")
    
    // Add nested object
    addJsonObject {
        put("id", 1)
        put("name", "Item 1")
    }
    
    // Add nested array
    addJsonArray {
        add("nested")
        add("values")
    }
    
    // Add another object
    addJsonObject {
        put("id", 2)
        put("active", false)
    }
}

// Using addAll for collections
val tags = listOf("kotlin", "json", "serialization")
val numbers = listOf(1, 2, 3, 4, 5)
val flags = listOf(true, false, true)

val collectionArray = buildJsonArray {
    add("Collections:")
    addAll(tags)       // Add all strings
    addAll(numbers)    // Add all numbers  
    addAll(flags)      // Add all booleans
}

// Building from existing data
data class User(val id: Int, val name: String)
val users = listOf(User(1, "Alice"), User(2, "Bob"))

val usersArray = buildJsonArray {
    for (user in users) {
        addJsonObject {
            put("id", user.id)
            put("name", user.name)
            put("active", true)
        }
    }
}

// Configuration file structure
val configJson = buildJsonObject {
    put("version", "2.1.0")
    put("environment", "production")
    
    putJsonObject("server") {
        put("host", "0.0.0.0")
        put("port", 8080)
        put("ssl", true)
        
        putJsonObject("limits") {
            put("maxConnections", 1000)
            put("timeout", 30000)
        }
    }
    
    putJsonObject("database") {
        put("driver", "postgresql")
        put("host", "db.example.com")  
        put("port", 5432)
        
        putJsonArray("replicas") {
            addJsonObject {
                put("host", "replica1.example.com")
                put("port", 5432)
                put("priority", 1)
            }
            addJsonObject {
                put("host", "replica2.example.com")
                put("port", 5432)
                put("priority", 2)
            }
        }
    }
    
    putJsonArray("features") {
        add("authentication")
        add("rate-limiting") 
        add("monitoring")
        
        addJsonObject {
            put("name", "custom-feature")
            put("enabled", true)
            putJsonObject("config") {
                put("param1", "value1")
                put("param2", 123)
            }
        }
    }
}

// API response format
fun buildApiResponse(success: Boolean, data: Any?, message: String? = null) = buildJsonObject {
    put("success", success)
    put("timestamp", System.currentTimeMillis())
    
    message?.let { put("message", it) }
    
    when (data) {
        is Collection<*> -> putJsonArray("data") {
            data.forEach { item ->
                when (item) {
                    is String -> add(item)
                    is Number -> add(item)
                    is Boolean -> add(item)
                    else -> add(item.toString())
                }
            }
        }
        is Map<*, *> -> putJsonObject("data") {
            data.forEach { (key, value) ->
                when (value) {
                    is String -> put(key.toString(), value)
                    is Number -> put(key.toString(), value)
                    is Boolean -> put(key.toString(), value)
                    else -> put(key.toString(), value.toString())
                }
            }
        }
        else -> put("data", data?.toString())
    }
}