CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-json-js

Kotlin multiplatform JSON serialization library with JavaScript-specific dynamic object conversion capabilities

—

Pending
Overview
Eval results
Files

builder-dsl.mddocs/

JSON Builder DSL

Fluent DSL for constructing JSON objects and arrays with type-safe builder functions. The builder DSL provides an intuitive way to create JsonElement structures programmatically.

Capabilities

Object Builder

Create JSON objects using a fluent builder DSL.

/**
 * Builds a JsonObject using a type-safe DSL
 * @param builderAction Lambda with receiver for building the object
 * @return Constructed JsonObject
 */
fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject

/**
 * Builder interface for constructing JSON objects
 */
interface JsonObjectBuilder {
    /**
     * Add a JsonElement value
     */
    fun put(key: String, value: JsonElement)
    
    /**
     * Add a string value (null creates JsonNull)
     */
    fun put(key: String, value: String?)
    
    /**
     * Add a number value (null creates JsonNull)
     */
    fun put(key: String, value: Number?)
    
    /**
     * Add a boolean value (null creates JsonNull)
     */
    fun put(key: String, value: Boolean?)
    
    /**
     * Add a nested JSON object
     */
    fun putJsonObject(key: String, builderAction: JsonObjectBuilder.() -> Unit)
    
    /**
     * Add a nested JSON array
     */
    fun putJsonArray(key: String, builderAction: JsonArrayBuilder.() -> Unit)
}

Usage Examples:

// Simple object construction
val userObject = buildJsonObject {
    put("id", 123)
    put("name", "Alice")
    put("email", "alice@example.com")
    put("isActive", true)
    put("lastLogin", null as String?) // Creates JsonNull
}

// Nested object construction
val profileObject = buildJsonObject {
    put("userId", 456)
    
    putJsonObject("personal") {
        put("firstName", "Bob")
        put("lastName", "Smith")
        put("age", 30)
    }
    
    putJsonObject("contact") {
        put("email", "bob@example.com")
        put("phone", "555-1234")
        put("address", null as String?)
    }
    
    putJsonArray("roles") {
        add("user")
        add("admin")
        add("moderator")
    }
}

// Dynamic object construction
fun createApiResponse(success: Boolean, message: String, data: Map<String, Any>? = null) = buildJsonObject {
    put("success", success)
    put("message", message)
    put("timestamp", System.currentTimeMillis())
    
    if (data != null) {
        putJsonObject("data") {
            data.forEach { (key, value) ->
                when (value) {
                    is String -> put(key, value)
                    is Number -> put(key, value)
                    is Boolean -> put(key, value)
                    else -> put(key, value.toString())
                }
            }
        }
    }
}

Array Builder

Create JSON arrays using a fluent builder DSL.

/**
 * Builds a JsonArray using a type-safe DSL
 * @param builderAction Lambda with receiver for building the array
 * @return Constructed JsonArray
 */
fun buildJsonArray(builderAction: JsonArrayBuilder.() -> Unit): JsonArray

/**
 * Builder interface for constructing JSON arrays
 */
interface JsonArrayBuilder {
    /**
     * Add a JsonElement value
     */
    fun add(value: JsonElement)
    
    /**
     * Add a string value (null creates JsonNull)
     */
    fun add(value: String?)
    
    /**
     * Add a number value (null creates JsonNull)
     */
    fun add(value: Number?)
    
    /**
     * Add a boolean value (null creates JsonNull)
     */
    fun add(value: Boolean?)
    
    /**
     * Add a nested JSON object
     */
    fun addJsonObject(builderAction: JsonObjectBuilder.() -> Unit)
    
    /**
     * Add a nested JSON array
     */
    fun addJsonArray(builderAction: JsonArrayBuilder.() -> Unit)
}

Usage Examples:

// Simple array construction
val numbersArray = buildJsonArray {
    add(1)
    add(2)
    add(3)
    add(null as Int?) // Creates JsonNull
}

val mixedArray = buildJsonArray {
    add("hello")
    add(42)
    add(true)
    add(3.14)
}

// Nested array construction
val complexArray = buildJsonArray {
    // Add primitive values
    add("item1")
    add("item2")
    
    // Add nested object
    addJsonObject {
        put("type", "object")
        put("value", 123)
    }
    
    // Add nested array
    addJsonArray {
        add("nested1")
        add("nested2")
        add("nested3")
    }
}

// Array of objects
val usersArray = buildJsonArray {
    addJsonObject {
        put("id", 1)
        put("name", "Alice")
        put("role", "admin")
    }
    
    addJsonObject {
        put("id", 2)
        put("name", "Bob")
        put("role", "user")
    }
    
    addJsonObject {
        put("id", 3)
        put("name", "Charlie")
        put("role", "moderator")
    }
}

Complex Nested Structures

Build complex nested JSON structures combining objects and arrays.

Usage Examples:

// E-commerce product catalog example
val catalogJson = buildJsonObject {
    put("catalogId", "electronics-2024")
    put("version", "1.2")
    put("lastUpdated", "2024-01-15T10:30:00Z")
    
    putJsonArray("categories") {
        addJsonObject {
            put("id", "smartphones")
            put("name", "Smartphones")
            
            putJsonArray("products") {
                addJsonObject {
                    put("sku", "PHONE-001")
                    put("name", "SuperPhone Pro")
                    put("price", 999.99)
                    put("inStock", true)
                    
                    putJsonArray("features") {
                        add("5G connectivity")
                        add("Wireless charging")
                        add("Triple camera")
                    }
                    
                    putJsonObject("specifications") {
                        put("screenSize", "6.7 inches")
                        put("storage", "256 GB")
                        put("ram", "12 GB")
                        put("batteryLife", "24 hours")
                    }
                }
                
                addJsonObject {
                    put("sku", "PHONE-002")
                    put("name", "BasicPhone")
                    put("price", 299.99)
                    put("inStock", false)
                    
                    putJsonArray("features") {
                        add("Long battery life")
                        add("Durable design")
                    }
                }
            }
        }
        
        addJsonObject {
            put("id", "laptops")
            put("name", "Laptops")
            
            putJsonArray("products") {
                addJsonObject {
                    put("sku", "LAPTOP-001")
                    put("name", "WorkBook Pro")
                    put("price", 1599.99)
                    put("inStock", true)
                }
            }
        }
    }
    
    putJsonObject("metadata") {
        put("totalCategories", 2)
        put("totalProducts", 3)
        putJsonArray("supportedCurrencies") {
            add("USD")
            add("EUR") 
            add("GBP")
        }
    }
}

Dynamic Construction Patterns

Common patterns for building JSON structures dynamically.

Usage Examples:

// Build object from map data
fun mapToJsonObject(data: Map<String, Any?>) = buildJsonObject {
    data.forEach { (key, value) ->
        when (value) {
            null -> put(key, null as String?)
            is String -> put(key, value)
            is Number -> put(key, value)
            is Boolean -> put(key, value)
            is List<*> -> putJsonArray(key) {
                value.forEach { item ->
                    when (item) {
                        is String -> add(item)
                        is Number -> add(item)
                        is Boolean -> add(item)
                        else -> add(item.toString())
                    }
                }
            }
            is Map<*, *> -> putJsonObject(key) {
                @Suppress("UNCHECKED_CAST")
                val stringMap = value as Map<String, Any?>
                stringMap.forEach { (k, v) ->
                    put(k, v?.toString())
                }
            }
            else -> put(key, value.toString())
        }
    }
}

// Build array from collection
fun <T> collectionToJsonArray(items: Collection<T>, transform: JsonArrayBuilder.(T) -> Unit) = buildJsonArray {
    items.forEach { item ->
        transform(item)
    }
}

// Usage
val dataMap = mapOf(
    "name" to "Alice",
    "age" to 30,
    "tags" to listOf("kotlin", "developer", "tech")
)

val jsonFromMap = mapToJsonObject(dataMap)

val users = listOf("Alice", "Bob", "Charlie")
val usersJson = collectionToJsonArray(users) { name ->
    addJsonObject {
        put("name", name)
        put("id", name.hashCode())
    }
}

Conditional Building

Build JSON structures with conditional logic.

Usage Examples:

// Conditional properties
fun createUserJson(
    name: String,
    email: String,
    age: Int? = null,
    isAdmin: Boolean = false,
    preferences: Map<String, String> = emptyMap()
) = buildJsonObject {
    put("name", name)
    put("email", email)
    
    // Conditional properties
    if (age != null && age > 0) {
        put("age", age)
    }
    
    if (isAdmin) {
        put("role", "admin")
        putJsonArray("permissions") {
            add("read")
            add("write")
            add("delete")
            add("admin")
        }
    }
    
    // Conditional nested object
    if (preferences.isNotEmpty()) {
        putJsonObject("preferences") {
            preferences.forEach { (key, value) ->
                put(key, value)
            }
        }
    }
}

// Usage
val adminUser = createUserJson(
    name = "Admin User",
    email = "admin@example.com", 
    age = 35,
    isAdmin = true,
    preferences = mapOf("theme" to "dark", "language" to "en")
)

val basicUser = createUserJson(
    name = "Basic User",
    email = "user@example.com"
)

Integration with Json Class

Use builder DSL results with Json serialization methods.

Usage Examples:

val json = Json { prettyPrint = true }

// Build and serialize
val dataObject = buildJsonObject {
    put("status", "success")
    put("timestamp", System.currentTimeMillis())
    
    putJsonArray("items") {
        add("item1")
        add("item2")
        add("item3")
    }
}

// Convert to string
val jsonString = json.encodeToString(JsonElement.serializer(), dataObject)
println(jsonString)

// Use in serialization workflows
@Serializable
data class Response(val data: JsonElement, val metadata: String)

val response = Response(
    data = buildJsonObject {
        put("result", "processed")
        put("count", 42)
    },
    metadata = "Generated response"
)

val responseString = json.encodeToString(response)

Install with Tessl CLI

npx tessl i tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-json-js

docs

builder-dsl.md

configuration.md

core-operations.md

custom-serializers.md

dynamic-conversion.md

index.md

json-annotations.md

json-element.md

tile.json