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
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Kotlinx Serialization JSON for JavaScript

Kotlinx Serialization JSON for JavaScript is the JavaScript platform implementation of Kotlin's multiplatform JSON serialization library. It provides comprehensive JSON serialization and deserialization capabilities with JavaScript-specific features for seamless interoperability with native JavaScript objects.

Package Information

  • Package Name: kotlinx-serialization-json-js
  • Package Type: maven
  • Language: Kotlin
  • Installation: implementation("org.jetbrains.kotlinx:kotlinx-serialization-json-js:1.9.0")

Core Imports

import kotlinx.serialization.json.*
import kotlinx.serialization.*

For JavaScript-specific dynamic conversion:

import kotlinx.serialization.json.Json
// Dynamic functions are extension functions on Json

For JSON annotations and builders:

import kotlinx.serialization.json.JsonNames
import kotlinx.serialization.json.JsonClassDiscriminator  
import kotlinx.serialization.json.JsonIgnoreUnknownKeys
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.buildJsonArray

For JsonElement tree manipulation:

import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.JsonNull
// Extension properties for type conversion
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonArray
import kotlinx.serialization.json.jsonPrimitive

Basic Usage

@Serializable
data class User(val name: String, val age: Int, val isActive: Boolean)

// Create Json instance
val json = Json { 
    ignoreUnknownKeys = true
    prettyPrint = true
}

// Serialize to JSON string
val user = User("Alice", 25, true)
val jsonString = json.encodeToString(user)
// {"name":"Alice","age":25,"isActive":true}

// Deserialize from JSON string  
val parsedUser = json.decodeFromString<User>(jsonString)

// JavaScript-specific: Convert to/from dynamic objects
val dynamicObject = json.encodeToDynamic(user)
val userFromDynamic = json.decodeFromDynamic<User>(dynamicObject)

Architecture

Kotlinx Serialization JSON is built around several key components:

  • Json Class: Primary entry point providing serialization/deserialization methods and configuration
  • JsonElement API: Tree-based JSON representation for programmatic manipulation
  • Configuration System: Extensive customization options for encoding/decoding behavior
  • JavaScript Integration: Dynamic object conversion for seamless JS interop
  • Custom Serializers: Base classes for implementing custom serialization logic
  • Type Safety: Full Kotlin type safety with generic type preservation

Capabilities

Core JSON Operations

Primary JSON serialization and deserialization functionality with comprehensive configuration options.

object Json {
    companion object {
        val Default: Json
    }
}

fun Json(builderAction: JsonBuilder.() -> Unit = {}): Json
fun Json(from: Json, builderAction: JsonBuilder.() -> Unit): Json

// String serialization
fun <T> Json.encodeToString(serializer: SerializationStrategy<T>, value: T): String
inline fun <reified T> Json.encodeToString(value: T): String
fun <T> Json.decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T  
inline fun <reified T> Json.decodeFromString(string: String): T

// JsonElement serialization
fun <T> Json.encodeToJsonElement(serializer: SerializationStrategy<T>, value: T): JsonElement
inline fun <reified T> Json.encodeToJsonElement(value: T): JsonElement
fun <T> Json.decodeFromJsonElement(deserializer: DeserializationStrategy<T>, element: JsonElement): T
inline fun <reified T> Json.decodeFromJsonElement(element: JsonElement): T
fun Json.parseToJsonElement(string: String): JsonElement

Core JSON Operations

JavaScript Dynamic Conversion

JavaScript-specific functionality for converting between Kotlin objects and native JavaScript objects with full type safety.

@ExperimentalSerializationApi
fun <T> Json.encodeToDynamic(serializer: SerializationStrategy<T>, value: T): dynamic
@ExperimentalSerializationApi  
inline fun <reified T> Json.encodeToDynamic(value: T): dynamic
@ExperimentalSerializationApi
fun <T> Json.decodeFromDynamic(deserializer: DeserializationStrategy<T>, dynamic: dynamic): T
@ExperimentalSerializationApi
inline fun <reified T> Json.decodeFromDynamic(dynamic: dynamic): T

JavaScript Dynamic Conversion

JsonElement Tree API

Programmatic JSON tree manipulation with a rich hierarchy of JsonElement types for building and accessing JSON structures.

sealed class JsonElement
abstract class JsonPrimitive : JsonElement {
    abstract val content: String
    val isString: Boolean
    val contentOrNull: String?
}
class JsonObject(val content: Map<String, JsonElement>) : JsonElement, Map<String, JsonElement>
class JsonArray(val content: List<JsonElement>) : JsonElement, List<JsonElement>  
object JsonNull : JsonPrimitive()

fun JsonPrimitive(value: Boolean?): JsonPrimitive
fun JsonPrimitive(value: Number?): JsonPrimitive
fun JsonPrimitive(value: String?): JsonPrimitive

JsonElement Tree API

JSON Builder DSL

Fluent DSL for constructing JSON objects and arrays with type-safe builder functions.

fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject
fun buildJsonArray(builderAction: JsonArrayBuilder.() -> Unit): JsonArray

interface JsonObjectBuilder {
    fun put(key: String, value: JsonElement)
    fun put(key: String, value: String?)
    fun put(key: String, value: Number?)
    fun put(key: String, value: Boolean?)
    fun putJsonObject(key: String, builderAction: JsonObjectBuilder.() -> Unit)
    fun putJsonArray(key: String, builderAction: JsonArrayBuilder.() -> Unit)
}

JSON Builder DSL

Configuration and Customization

Comprehensive configuration system for customizing JSON encoding/decoding behavior, naming strategies, and polymorphism handling.

class JsonBuilder {
    var encodeDefaults: Boolean
    var explicitNulls: Boolean
    var ignoreUnknownKeys: Boolean
    var coerceInputValues: Boolean
    var prettyPrint: Boolean
    var prettyPrintIndent: String
    var isLenient: Boolean
    var allowSpecialFloatingPointValues: Boolean
    var allowStructuredMapKeys: Boolean
    var allowTrailingComma: Boolean
    var allowComments: Boolean
    var useAlternativeNames: Boolean
    var namingStrategy: JsonNamingStrategy?
    var decodeEnumsCaseInsensitive: Boolean
    var classDiscriminator: String
    var classDiscriminatorMode: ClassDiscriminatorMode
    var useArrayPolymorphism: Boolean
}

interface JsonNamingStrategy {
    fun serialNameForJson(descriptor: SerialDescriptor, elementIndex: Int, serialName: String): String
    
    companion object {
        val SnakeCase: JsonNamingStrategy
        val KebabCase: JsonNamingStrategy
    }
}

Configuration and Customization

Custom Serializers

Base classes and interfaces for implementing custom JSON serialization logic with transformation and polymorphic capabilities.

abstract class JsonTransformingSerializer<T>(private val tSerializer: KSerializer<T>) : KSerializer<T> {
    protected open fun transformSerialize(element: JsonElement): JsonElement = element
    protected open fun transformDeserialize(element: JsonElement): JsonElement = element
}

abstract class JsonContentPolymorphicSerializer<T : Any>(private val baseClass: KClass<T>) : AbstractPolymorphicSerializer<T>() {
    protected abstract fun selectDeserializer(element: JsonElement): DeserializationStrategy<T>
}

interface JsonEncoder : Encoder, CompositeEncoder {
    val json: Json
    fun encodeJsonElement(element: JsonElement)
}

interface JsonDecoder : Decoder, CompositeDecoder {
    val json: Json  
    fun decodeJsonElement(): JsonElement
}

Custom Serializers

JSON Annotations

JSON-specific annotations for controlling serialization behavior, providing alternative names, class discriminators, and selective ignoring of unknown properties.

/**
 * Allows multiple alternative names for a single property during JSON deserialization
 */
@ExperimentalSerializationApi
annotation class JsonNames(vararg val names: String)

/**
 * Specifies a custom key for class discriminator values in polymorphic serialization
 */
@ExperimentalSerializationApi  
annotation class JsonClassDiscriminator(val discriminator: String)

/**
 * Allows specific classes to ignore unknown properties during deserialization
 */
@ExperimentalSerializationApi
annotation class JsonIgnoreUnknownKeys

JSON Annotations

Types

enum class ClassDiscriminatorMode {
    NONE, POLYMORPHIC, ALL_JSON_OBJECTS
}

class JsonEncodingException(message: String) : SerializationException(message)
class JsonDecodingException(message: String) : SerializationException(message)
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlinx/kotlinx-serialization-json-js@1.9.x
Publish Source
CLI
Badge
tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-json-js badge