0
# kotlinx.serialization-core-js
1
2
A powerful Kotlin multiplatform serialization library compiled for JavaScript that provides comprehensive type-safe serialization and deserialization capabilities for JavaScript/TypeScript applications.
3
4
## Package Information
5
6
**Maven Package:** `org.jetbrains.kotlinx:kotlinx-serialization-core-js`
7
**Platform:** Kotlin/JS
8
**Language Support:** JavaScript, TypeScript
9
**API Level:** Kotlin Serialization 1.6+
10
11
### Installation
12
13
For Kotlin/JS projects, add to your `build.gradle.kts`:
14
15
```kotlin
16
dependencies {
17
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0")
18
}
19
```
20
21
Or for Gradle with Groovy:
22
23
```gradle
24
dependencies {
25
implementation 'org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0'
26
}
27
```
28
29
### Core Imports
30
31
```kotlin
32
// Core serialization APIs
33
import kotlinx.serialization.*
34
import kotlinx.serialization.builtins.*
35
import kotlinx.serialization.descriptors.*
36
import kotlinx.serialization.encoding.*
37
import kotlinx.serialization.modules.*
38
39
```
40
41
## Basic Usage
42
43
### Simple Data Class Serialization
44
45
```kotlin
46
// Define a serializable data class
47
@Serializable
48
data class User(val name: String, val age: Int, val email: String)
49
50
// Create an instance
51
val user = User("John Doe", 30, "john@example.com")
52
53
// Get the serializer (requires a format like JSON)
54
val serializer = User.serializer()
55
56
// Usage with a format implementation (e.g., kotlinx-serialization-json):
57
// val json = Json.encodeToString(serializer, user)
58
// val deserializedUser = Json.decodeFromString(serializer, json)
59
```
60
61
### Custom Property Names
62
63
```kotlin
64
@Serializable
65
data class ApiResponse(
66
@SerialName("user_id") val userId: Int,
67
@SerialName("full_name") val fullName: String
68
)
69
```
70
71
### Optional and Required Fields
72
73
```kotlin
74
@Serializable
75
data class Profile(
76
@Required val username: String, // Must be present during deserialization
77
val bio: String = "", // Optional with default value
78
@Transient val temporaryData: String? = null // Excluded from serialization
79
)
80
```
81
82
## Architecture
83
84
The kotlinx.serialization-core-js library is built around several key architectural components:
85
86
### Core Interfaces
87
88
```typescript
89
interface KSerializer<T> extends SerializationStrategy<T>, DeserializationStrategy<T> {
90
readonly descriptor: SerialDescriptor;
91
}
92
93
interface SerializationStrategy<T> {
94
serialize(encoder: Encoder, value: T): void;
95
}
96
97
interface DeserializationStrategy<T> {
98
deserialize(decoder: Decoder): T;
99
}
100
```
101
102
### Descriptor System
103
104
Every serializable type has an associated `SerialDescriptor` that describes its structure:
105
106
- **Serial Name**: Identifies the type in serialized form
107
- **Kind**: Categorizes the type (primitive, class, list, map, etc.)
108
- **Elements**: For structured types, describes each property/element
109
- **Annotations**: Metadata attached to the type or its elements
110
111
### Format Independence
112
113
The library separates serialization logic from format-specific encoding:
114
115
1. **Serializers** define *what* to serialize
116
2. **Encoders/Decoders** define *how* to represent data in specific formats
117
3. **Formats** coordinate between serializers and encoders/decoders
118
119
This architecture enables the same serializable classes to work with JSON, ProtoBuf, CBOR, and other formats.
120
121
## Capabilities
122
123
### Annotations
124
125
Comprehensive annotation system for controlling serialization behavior:
126
127
```kotlin
128
@Serializable // Mark classes as serializable
129
@SerialName("custom") // Override property/class names
130
@Required // Require fields during deserialization
131
@Transient // Exclude fields from serialization
132
@Contextual // Use contextual serializer lookup
133
@Polymorphic // Enable polymorphic serialization
134
```
135
136
**→ [Complete Annotations Reference](./annotations.md)**
137
138
### Core Serializers
139
140
Built-in and factory serializers for all standard types:
141
142
```kotlin
143
// Retrieve serializers
144
serializer<String>() // For reified types
145
String.serializer() // Via companion object
146
ListSerializer(Int.serializer()) // Collection serializers
147
```
148
149
**→ [Serializers API Reference](./serializers.md)**
150
151
### Type Descriptors
152
153
Introspect and describe serializable type structure:
154
155
```kotlin
156
val descriptor = User.serializer().descriptor
157
println(descriptor.serialName) // "User"
158
println(descriptor.kind) // StructureKind.CLASS
159
println(descriptor.elementsCount) // 3
160
```
161
162
**→ [Descriptors API Reference](./descriptors.md)**
163
164
### Encoding/Decoding
165
166
Low-level APIs for format implementors:
167
168
```kotlin
169
interface Encoder {
170
fun encodeString(value: String)
171
fun encodeInt(value: Int)
172
fun beginStructure(descriptor: SerialDescriptor): CompositeEncoder
173
}
174
```
175
176
**→ [Encoding/Decoding Reference](./encoding.md)**
177
178
### Built-in Type Support
179
180
Comprehensive serializers for Kotlin standard library types:
181
182
```kotlin
183
// Primitives and standard types
184
String.serializer()
185
Int.serializer()
186
Duration.serializer()
187
188
// Collections
189
ListSerializer(String.serializer())
190
MapSerializer(String.serializer(), Int.serializer())
191
192
// Arrays
193
IntArraySerializer()
194
ArraySerializer(String.serializer())
195
```
196
197
**→ [Built-in Serializers Reference](./builtins.md)**
198
199
### Runtime Configuration
200
201
Flexible module system for contextual and polymorphic serialization:
202
203
```kotlin
204
val module = SerializersModule {
205
contextual(LocalDateTime::class, LocalDateTimeSerializer)
206
polymorphic(Animal::class) {
207
subclass(Cat::class)
208
subclass(Dog::class)
209
}
210
}
211
```
212
213
**→ [Modules and Configuration](./modules.md)**
214
215
## JavaScript Integration
216
217
### Long Value Handling
218
219
For JavaScript compatibility, use `LongAsStringSerializer` to avoid precision issues:
220
221
```typescript
222
@Serializable
223
class TransactionRecord {
224
@Serializable(LongAsStringSerializer::class)
225
amount: string; // Serialized as string to preserve precision
226
227
constructor(amount: string) {
228
this.amount = amount;
229
}
230
}
231
```
232
233
### TypeScript Type Definitions
234
235
The library provides comprehensive TypeScript definitions:
236
237
```typescript
238
// Serializer functions are typed
239
const userSerializer: KSerializer<User> = User.serializer();
240
241
// Generic serializers maintain type safety
242
const listSerializer: KSerializer<Array<string>> = ListSerializer(String.serializer());
243
244
// Format operations are fully typed
245
const users: Array<User> = format.decodeFromString(listSerializer, jsonString);
246
```
247
248
### Platform-Specific Considerations
249
250
- Enum classes require `@Serializable` annotation on JavaScript
251
- Interface detection uses JavaScript-specific metadata
252
- Type lookup leverages JavaScript's dynamic features
253
- All primitive arrays and reference arrays are supported
254
255
## Error Handling
256
257
The library provides specific exception types for different error conditions:
258
259
```typescript
260
try {
261
const result = format.decodeFromString(serializer, invalidJson);
262
} catch (e) {
263
if (e instanceof SerializationException) {
264
console.log("Serialization error:", e.message);
265
} else if (e instanceof MissingFieldException) {
266
console.log("Missing required field:", e.missingFields);
267
}
268
}
269
```
270
271
## Format Integration
272
273
While kotlinx.serialization-core-js provides the serialization framework, it's designed to work with format-specific libraries:
274
275
```typescript
276
// JSON format (separate library)
277
import { Json } from 'kotlinx-serialization-json-js';
278
279
const json = Json.Default;
280
const serialized = json.encodeToString(User.serializer(), user);
281
const deserialized = json.decodeFromString(User.serializer(), serialized);
282
283
// Other formats follow similar patterns
284
import { ProtoBuf } from 'kotlinx-serialization-protobuf-js';
285
import { Cbor } from 'kotlinx-serialization-cbor-js';
286
```
287
288
This modular approach allows you to include only the formats your application needs while sharing the same serializable class definitions across all formats.