or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

annotations.md builtins.md descriptors.md encoding.md index.md modules.md serializers.md

tile.json

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

Kotlin multiplatform reflectionless serialization library core module for JavaScript platform

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/org.jetbrains.kotlinx/kotlinx-serialization-core-js@1.9.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-core-js@1.9.0

kotlinx.serialization-core-js

A powerful Kotlin multiplatform serialization library compiled for JavaScript that provides comprehensive type-safe serialization and deserialization capabilities for JavaScript/TypeScript applications.

Package Information

Maven Package: org.jetbrains.kotlinx:kotlinx-serialization-core-js
Platform: Kotlin/JS
Language Support: JavaScript, TypeScript
API Level: Kotlin Serialization 1.6+

Installation

For Kotlin/JS projects, add to your build.gradle.kts:

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0")
}

Or for Gradle with Groovy:

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0'
}

Core Imports

// Core serialization APIs
import kotlinx.serialization.*
import kotlinx.serialization.builtins.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
import kotlinx.serialization.modules.*

Basic Usage

Simple Data Class Serialization

// Define a serializable data class
@Serializable
data class User(val name: String, val age: Int, val email: String)

// Create an instance
val user = User("John Doe", 30, "john@example.com")

// Get the serializer (requires a format like JSON)
val serializer = User.serializer()

// Usage with a format implementation (e.g., kotlinx-serialization-json):
// val json = Json.encodeToString(serializer, user)
// val deserializedUser = Json.decodeFromString(serializer, json)

Custom Property Names

@Serializable
data class ApiResponse(
    @SerialName("user_id") val userId: Int,
    @SerialName("full_name") val fullName: String
)

Optional and Required Fields

@Serializable
data class Profile(
    @Required val username: String, // Must be present during deserialization
    val bio: String = "", // Optional with default value
    @Transient val temporaryData: String? = null // Excluded from serialization
)

Architecture

The kotlinx.serialization-core-js library is built around several key architectural components:

Core Interfaces

interface KSerializer<T> extends SerializationStrategy<T>, DeserializationStrategy<T> {
  readonly descriptor: SerialDescriptor;
}

interface SerializationStrategy<T> {
  serialize(encoder: Encoder, value: T): void;
}

interface DeserializationStrategy<T> {
  deserialize(decoder: Decoder): T;
}

Descriptor System

Every serializable type has an associated SerialDescriptor that describes its structure:

Serial Name: Identifies the type in serialized form
Kind: Categorizes the type (primitive, class, list, map, etc.)
Elements: For structured types, describes each property/element
Annotations: Metadata attached to the type or its elements

Format Independence

The library separates serialization logic from format-specific encoding:

Serializers define what to serialize
Encoders/Decoders define how to represent data in specific formats
Formats coordinate between serializers and encoders/decoders

This architecture enables the same serializable classes to work with JSON, ProtoBuf, CBOR, and other formats.

Capabilities

Annotations

Comprehensive annotation system for controlling serialization behavior:

@Serializable          // Mark classes as serializable
@SerialName("custom")   // Override property/class names  
@Required              // Require fields during deserialization
@Transient             // Exclude fields from serialization
@Contextual            // Use contextual serializer lookup
@Polymorphic           // Enable polymorphic serialization

→ Complete Annotations Reference

Core Serializers

Built-in and factory serializers for all standard types:

// Retrieve serializers
serializer<String>()           // For reified types
String.serializer()            // Via companion object
ListSerializer(Int.serializer()) // Collection serializers

→ Serializers API Reference

Type Descriptors

Introspect and describe serializable type structure:

val descriptor = User.serializer().descriptor
println(descriptor.serialName)    // "User"  
println(descriptor.kind)          // StructureKind.CLASS
println(descriptor.elementsCount) // 3

→ Descriptors API Reference

Encoding/Decoding

Low-level APIs for format implementors:

interface Encoder {
  fun encodeString(value: String)
  fun encodeInt(value: Int) 
  fun beginStructure(descriptor: SerialDescriptor): CompositeEncoder
}

→ Encoding/Decoding Reference

Built-in Type Support

Comprehensive serializers for Kotlin standard library types:

// Primitives and standard types
String.serializer()
Int.serializer() 
Duration.serializer()

// Collections  
ListSerializer(String.serializer())
MapSerializer(String.serializer(), Int.serializer())

// Arrays
IntArraySerializer()
ArraySerializer(String.serializer())

→ Built-in Serializers Reference

Runtime Configuration

Flexible module system for contextual and polymorphic serialization:

val module = SerializersModule {
  contextual(LocalDateTime::class, LocalDateTimeSerializer)
  polymorphic(Animal::class) {
    subclass(Cat::class)
    subclass(Dog::class)  
  }
}

→ Modules and Configuration

JavaScript Integration

Long Value Handling

For JavaScript compatibility, use LongAsStringSerializer to avoid precision issues:

@Serializable
class TransactionRecord {
  @Serializable(LongAsStringSerializer::class)
  amount: string; // Serialized as string to preserve precision
  
  constructor(amount: string) {
    this.amount = amount;
  }
}

TypeScript Type Definitions

The library provides comprehensive TypeScript definitions:

// Serializer functions are typed
const userSerializer: KSerializer<User> = User.serializer();

// Generic serializers maintain type safety  
const listSerializer: KSerializer<Array<string>> = ListSerializer(String.serializer());

// Format operations are fully typed
const users: Array<User> = format.decodeFromString(listSerializer, jsonString);

Platform-Specific Considerations

Enum classes require @Serializable annotation on JavaScript
Interface detection uses JavaScript-specific metadata
Type lookup leverages JavaScript's dynamic features
All primitive arrays and reference arrays are supported

Error Handling

The library provides specific exception types for different error conditions:

try {
  const result = format.decodeFromString(serializer, invalidJson);
} catch (e) {
  if (e instanceof SerializationException) {
    console.log("Serialization error:", e.message);
  } else if (e instanceof MissingFieldException) {
    console.log("Missing required field:", e.missingFields);
  }
}

Format Integration

While kotlinx.serialization-core-js provides the serialization framework, it's designed to work with format-specific libraries:

// JSON format (separate library)
import { Json } from 'kotlinx-serialization-json-js';

const json = Json.Default;
const serialized = json.encodeToString(User.serializer(), user);
const deserialized = json.decodeFromString(User.serializer(), serialized);

// Other formats follow similar patterns
import { ProtoBuf } from 'kotlinx-serialization-protobuf-js';
import { Cbor } from 'kotlinx-serialization-cbor-js';

This modular approach allows you to include only the formats your application needs while sharing the same serializable class definitions across all formats.