or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

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

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-serialization@3.2.x?classifier=js

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-serialization-js@3.2.0

index.mddocs/

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