CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-ktor--ktor-client-serialization-js

JavaScript platform-specific implementation for Ktor HTTP Client serialization plugin using Kotlinx Serialization

—

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

Ktor Client Serialization (JavaScript)

A deprecated JavaScript platform-specific implementation for Ktor HTTP Client serialization plugin that integrates with Kotlinx Serialization for JSON serialization and deserialization. This package provides automatic registration of the KotlinxSerializer for JavaScript environments.

⚠️ This package is deprecated since Ktor 2.0 in favor of the ContentNegotiation plugin.

Package Information

  • Package Name: io.ktor:ktor-client-serialization-js
  • Package Type: maven
  • Language: Kotlin (JavaScript target)
  • Installation: 
    implementation("io.ktor:ktor-client-serialization:3.2.0")

Core Imports

import io.ktor.client.plugins.kotlinx.serializer.KotlinxSerializer
import io.ktor.client.plugins.json.*
import kotlinx.serialization.json.Json

Basic Usage

import io.ktor.client.*
import io.ktor.client.plugins.json.*
import io.ktor.client.plugins.kotlinx.serializer.*
import kotlinx.serialization.*
import kotlinx.serialization.json.*

// The serializer is automatically registered on JavaScript platform
// through the SerializerInitializer

// Create HTTP client with JSON plugin (deprecated)
@Suppress("DEPRECATION_ERROR")
val client = HttpClient {
    install(JsonPlugin) {
        serializer = KotlinxSerializer()
    }
}

// Or use custom Json configuration
@Suppress("DEPRECATION_ERROR")
val customClient = HttpClient {
    install(JsonPlugin) {
        serializer = KotlinxSerializer(Json {
            isLenient = true
            ignoreUnknownKeys = true
        })
    }
}

Architecture

The package consists of three main components:

  • KotlinxSerializer: The core serializer implementation that handles JSON serialization/deserialization using Kotlinx Serialization
  • Platform Initializers: JavaScript and WebAssembly-specific initializers that automatically register the serializer
  • Type System Integration: Automatic serializer detection for various Kotlin data types including collections, maps, and custom serializable classes

Capabilities

JSON Serialization

Core JSON serialization functionality using Kotlinx Serialization for type-safe conversion between Kotlin objects and JSON.

@Deprecated("Please use ContentNegotiation plugin and its converters")
class KotlinxSerializer(
    private val json: Json = DefaultJson
) : JsonSerializer {
    
    /**
     * Convert data object to OutgoingContent with specified content type
     */
    fun write(data: Any, contentType: ContentType): OutgoingContent
    
    /**
     * Convert data object to OutgoingContent with default JSON content type
     */
    fun write(data: Any): OutgoingContent
    
    /**
     * Read content from response using type information
     */
    fun read(type: TypeInfo, body: Input): Any
    
    companion object {
        /**
         * Default Json configuration for KotlinxSerializer
         */
        val DefaultJson: Json
    }
}

Usage Examples:

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

// Serialization is handled automatically by the HTTP client
val response = client.post<User>("https://api.example.com/users") {
    body = User("Alice", 30)
}

Automatic Platform Registration

JavaScript and WebAssembly platform-specific automatic serializer registration.

/**
 * Platform initializer that automatically registers KotlinxSerializer
 * Available on both JavaScript and WebAssembly platforms with identical implementation
 */
@InternalAPI
object SerializerInitializer {
    /**
     * Eager initialization property that triggers serializer registration
     */
    @EagerInitialization
    val initializer: SerializerInitializer
}

The initializer automatically adds KotlinxSerializer() to the platform-specific serializers store during module initialization. Both JavaScript and WebAssembly platforms use identical implementations.

Supported Data Types

The serializer supports various Kotlin data types with automatic serializer detection:

// Supported types (handled automatically):
// - JsonElement: Direct serialization
// - List<*>: ListSerializer with element type detection
// - Array<*>: Array serialization with fallback to String serializer
// - Set<*>: SetSerializer with element type detection  
// - Map<*, *>: MapSerializer with key/value type detection
// - Custom @Serializable classes: Via reflection and SerializersModule
// - Nullable types: Automatic nullable serializer wrapping

Error Handling:

  • Throws error for collections with mixed element types
  • Provides descriptive error messages with serializer information
  • Falls back to String serializer for unknown/empty collections

Default JSON Configuration

Pre-configured JSON settings optimized for HTTP client usage:

/**
 * Default Json configuration for KotlinxSerializer
 */
val DefaultJson: Json = Json {
    isLenient = false
    ignoreUnknownKeys = false
    allowSpecialFloatingPointValues = true
    useArrayPolymorphism = false
}

Migration

This package is deprecated in favor of the ContentNegotiation plugin. To migrate:

// Old (deprecated)
@Suppress("DEPRECATION_ERROR")
val client = HttpClient {
    install(JsonPlugin) {
        serializer = KotlinxSerializer()
    }
}

// New (recommended)
val client = HttpClient {
    install(ContentNegotiation) {
        json(Json {
            isLenient = true
            ignoreUnknownKeys = true
        })
    }
}

For detailed migration instructions, see: https://ktor.io/docs/migration-to-20x.html#serialization-client

Platform Availability

  • Primary Target: JavaScript (browser and Node.js environments)
  • Secondary Target: WebAssembly with JavaScript interop
  • Registration: Automatic via @EagerInitialization during module loading
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-serialization@3.2.x?classifier=js
Publish Source
CLI
Badge
tessl/maven-io-ktor--ktor-client-serialization-js badge