CtrlK
BlogDocsLog inGet started
Tessl Logo

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

Kotlin multiplatform reflectionless serialization library core module for JavaScript platform

—

Pending
Overview
Eval results
Files

builtins.mddocs/

Built-in Serializers

Complete reference for all built-in serializers provided by kotlinx.serialization-core-js for standard Kotlin types.

Primitive Type Serializers

Companion Object Serializers

All primitive types provide serializers through their companion objects.

val Char.Companion.serializer: KSerializer<Char>
val Byte.Companion.serializer: KSerializer<Byte>
val Short.Companion.serializer: KSerializer<Short>
val Int.Companion.serializer: KSerializer<Int>
val Long.Companion.serializer: KSerializer<Long>
val Float.Companion.serializer: KSerializer<Float>
val Double.Companion.serializer: KSerializer<Double>
val Boolean.Companion.serializer: KSerializer<Boolean>
val String.Companion.serializer: KSerializer<String>
val Unit.serializer: KSerializer<Unit>

{ .api }

Usage:

// Access primitive serializers
const charSerializer = Char.serializer();
const byteSerializer = Byte.serializer();
const shortSerializer = Short.serializer();
const intSerializer = Int.serializer();
const longSerializer = Long.serializer();
const floatSerializer = Float.serializer();
const doubleSerializer = Double.serializer();
const booleanSerializer = Boolean.serializer();
const stringSerializer = String.serializer();
const unitSerializer = Unit.serializer();

// Use with any format
const json = format.encodeToString(Int.serializer(), 42);
const number = format.decodeFromString(Int.serializer(), json);

Unsigned Type Serializers

Serializers for unsigned integer types.

val UByte.Companion.serializer: KSerializer<UByte>
val UShort.Companion.serializer: KSerializer<UShort>
val UInt.Companion.serializer: KSerializer<UInt>
val ULong.Companion.serializer: KSerializer<ULong>

{ .api }

Usage:

// Unsigned type serializers
const ubyteSerializer = UByte.serializer();
const ushortSerializer = UShort.serializer();
const uintSerializer = UInt.serializer();
const ulongSerializer = ULong.serializer();

// Example usage
const value = 42u;
const serialized = format.encodeToString(UInt.serializer(), value);

Nullable Serializers

.nullable Property

Any serializer can be made nullable using the .nullable property.

val KSerializer<T>.nullable: KSerializer<T?>

{ .api }

Usage:

// Create nullable serializers
const nullableString = String.serializer().nullable;
const nullableInt = Int.serializer().nullable;
const nullableUser = User.serializer().nullable;

// Serialize nullable values
const json1 = format.encodeToString(nullableString, "hello");  // "hello"
const json2 = format.encodeToString(nullableString, null);    // null

// Deserialize nullable values
const str1 = format.decodeFromString(nullableString, '"hello"'); // "hello"
const str2 = format.decodeFromString(nullableString, 'null');    // null

Collection Serializers

List Serializer

Factory function for creating List serializers.

fun <T> ListSerializer(elementSerializer: KSerializer<T>): KSerializer<List<T>>

{ .api }

Usage:

// Create list serializers
const stringListSerializer = ListSerializer(String.serializer());
const intListSerializer = ListSerializer(Int.serializer());
const userListSerializer = ListSerializer(User.serializer());

// Nested collections
const nestedListSerializer = ListSerializer(ListSerializer(String.serializer()));

// Usage
const names = ["Alice", "Bob", "Charlie"];
const json = format.encodeToString(stringListSerializer, names);
// Output: ["Alice","Bob","Charlie"]

const deserializedNames = format.decodeFromString(stringListSerializer, json);

Set Serializer

Factory function for creating Set serializers.

fun <T> SetSerializer(elementSerializer: KSerializer<T>): KSerializer<Set<T>>

{ .api }

Usage:

// Create set serializers
const stringSetSerializer = SetSerializer(String.serializer());
const intSetSerializer = SetSerializer(Int.serializer());

// Usage
const uniqueNumbers = new Set([1, 2, 3, 3, 4]); // Set with 4 unique elements
const json = format.encodeToString(intSetSerializer, uniqueNumbers);
const deserializedSet = format.decodeFromString(intSetSerializer, json);

Map Serializer

Factory function for creating Map serializers.

fun <K, V> MapSerializer(
    keySerializer: KSerializer<K>, 
    valueSerializer: KSerializer<V>
): KSerializer<Map<K, V>>

{ .api }

Usage:

// Create map serializers
const stringIntMapSerializer = MapSerializer(String.serializer(), Int.serializer());
const intUserMapSerializer = MapSerializer(Int.serializer(), User.serializer());

// Complex maps
const mapOfListsSerializer = MapSerializer(
  String.serializer(), 
  ListSerializer(Int.serializer())
);

// Usage
const scores = new Map([
  ["Alice", 95],
  ["Bob", 87],
  ["Charlie", 92]
]);

const json = format.encodeToString(stringIntMapSerializer, scores);
const deserializedScores = format.decodeFromString(stringIntMapSerializer, json);

Pair and Triple Serializers

Pair Serializer

Factory function for creating Pair serializers.

fun <A, B> PairSerializer(
    aSerializer: KSerializer<A>, 
    bSerializer: KSerializer<B>
): KSerializer<Pair<A, B>>

{ .api }

Usage:

// Create pair serializer
const stringIntPairSerializer = PairSerializer(String.serializer(), Int.serializer());

// Usage
const coordinate = new Pair("x", 10);
const json = format.encodeToString(stringIntPairSerializer, coordinate);
const deserializedCoordinate = format.decodeFromString(stringIntPairSerializer, json);

MapEntry Serializer

Factory function for creating Map.Entry serializers.

fun <K, V> MapEntrySerializer(
    keySerializer: KSerializer<K>, 
    valueSerializer: KSerializer<V>
): KSerializer<Map.Entry<K, V>>

{ .api }

Usage:

// Create map entry serializer
const stringIntEntrySerializer = MapEntrySerializer(String.serializer(), Int.serializer());

// Usage with map entries
const map = new Map([["key", 42]]);
const entry = map.entries().next().value;
const json = format.encodeToString(stringIntEntrySerializer, entry);

Triple Serializer

Factory function for creating Triple serializers.

fun <A, B, C> TripleSerializer(
    aSerializer: KSerializer<A>, 
    bSerializer: KSerializer<B>, 
    cSerializer: KSerializer<C>
): KSerializer<Triple<A, B, C>>

{ .api }

Usage:

// Create triple serializer
const stringIntBoolTripleSerializer = TripleSerializer(
  String.serializer(), 
  Int.serializer(), 
  Boolean.serializer()
);

// Usage
const coordinate3D = new Triple("point", 10, true);
const json = format.encodeToString(stringIntBoolTripleSerializer, coordinate3D);

Array Serializers

Reference Array Serializer

Factory functions for creating Array serializers (Experimental).

@ExperimentalSerializationApi
inline fun <reified T, reified E : T> ArraySerializer(
    elementSerializer: KSerializer<E>
): KSerializer<Array<T>>

@ExperimentalSerializationApi
fun <T> ArraySerializer(
    kClass: KClass<T>, 
    elementSerializer: KSerializer<T>
): KSerializer<Array<T>>

{ .api }

Usage:

// Create array serializers
const stringArraySerializer = ArraySerializer(String.serializer());
const userArraySerializer = ArraySerializer(User::class, User.serializer());

// Usage
const names = ["Alice", "Bob", "Charlie"];
const json = format.encodeToString(stringArraySerializer, names);
const deserializedArray = format.decodeFromString(stringArraySerializer, json);

Primitive Array Serializers

Specialized serializers for primitive arrays.

fun CharArraySerializer(): KSerializer<CharArray>
fun ByteArraySerializer(): KSerializer<ByteArray>
fun ShortArraySerializer(): KSerializer<ShortArray>
fun IntArraySerializer(): KSerializer<IntArray>
fun LongArraySerializer(): KSerializer<LongArray>
fun FloatArraySerializer(): KSerializer<FloatArray>
fun DoubleArraySerializer(): KSerializer<DoubleArray>
fun BooleanArraySerializer(): KSerializer<BooleanArray>

{ .api }

Usage:

// Primitive array serializers
const charArraySer = CharArraySerializer();
const byteArraySer = ByteArraySerializer();
const shortArraySer = ShortArraySerializer();
const intArraySer = IntArraySerializer();
const longArraySer = LongArraySerializer();
const floatArraySer = FloatArraySerializer();
const doubleArraySer = DoubleArraySerializer();
const booleanArraySer = BooleanArraySerializer();

// Usage examples
const numbers = new Int32Array([1, 2, 3, 4, 5]);
const json = format.encodeToString(intArraySer, numbers);
const deserializedNumbers = format.decodeFromString(intArraySer, json);

const bytes = new Uint8Array([65, 66, 67]); // "ABC" in ASCII
const byteJson = format.encodeToString(byteArraySer, bytes);

Unsigned Array Serializers

Serializers for unsigned primitive arrays (Experimental).

@ExperimentalSerializationApi
fun UByteArraySerializer(): KSerializer<UByteArray>

@ExperimentalSerializationApi
fun UShortArraySerializer(): KSerializer<UShortArray>

@ExperimentalSerializationApi
fun UIntArraySerializer(): KSerializer<UIntArray>

@ExperimentalSerializationApi
fun ULongArraySerializer(): KSerializer<ULongArray>

{ .api }

Usage:

// Unsigned array serializers (experimental)
const ubyteArraySer = UByteArraySerializer();
const ushortArraySer = UShortArraySerializer();
const uintArraySer = UIntArraySerializer();
const ulongArraySer = ULongArraySerializer();

// Usage
const unsignedInts = new Uint32Array([1u, 2u, 3u]);
const json = format.encodeToString(uintArraySer, unsignedInts);

Time and Duration Serializers

Duration Serializer

Serializer for kotlin.time.Duration.

val Duration.Companion.serializer: KSerializer<Duration>

{ .api }

Usage:

const durationSerializer = Duration.serializer();

// Usage with durations
const duration = Duration.ofSeconds(30);
const json = format.encodeToString(durationSerializer, duration);
const deserializedDuration = format.decodeFromString(durationSerializer, json);

// In serializable classes
@Serializable
class Task {
  name;
  timeout; // Duration type, automatically uses Duration.serializer()
  
  constructor(name, timeout) {
    this.name = name;
    this.timeout = timeout;
  }
}

Instant Serializer

Serializer for kotlinx.datetime.Instant (Experimental).

@ExperimentalSerializationApi
val Instant.Companion.serializer: KSerializer<Instant>

{ .api }

Usage:

const instantSerializer = Instant.serializer();

// Usage with instants
const now = Instant.now();
const json = format.encodeToString(instantSerializer, now);
const deserializedInstant = format.decodeFromString(instantSerializer, json);

Instant Component Serializer

Alternative serializer that represents Instant as epoch components (Experimental).

@ExperimentalSerializationApi
object InstantComponentSerializer : KSerializer<Instant>

{ .api }

Usage:

// Use component-based instant serialization
@Serializable
class Event {
  name;
  
  @Serializable(InstantComponentSerializer::class)
  timestamp; // Serialized as {epochSeconds: 1234567890, nanosecondsOfSecond: 123456789}
  
  constructor(name, timestamp) {
    this.name = name;
    this.timestamp = timestamp;
  }
}

UUID Serializer

Uuid Serializer

Serializer for UUID values (Experimental).

@ExperimentalSerializationApi
val Uuid.Companion.serializer: KSerializer<Uuid>

{ .api }

Usage:

const uuidSerializer = Uuid.serializer();

// Usage with UUIDs
const id = Uuid.random();
const json = format.encodeToString(uuidSerializer, id);
const deserializedUuid = format.decodeFromString(uuidSerializer, json);

// In data classes
@Serializable
class Document {
  @Serializable(Uuid.serializer()::class)
  id; // UUID
  
  title;
  
  constructor(id, title) {
    this.id = id;
    this.title = title;
  }
}

JavaScript-Specific Serializers

Long as String Serializer

Special serializer for Long values that serializes them as strings to avoid JavaScript precision issues.

object LongAsStringSerializer : KSerializer<Long>

{ .api }

Usage:

// Use for JavaScript interoperability
@Serializable
class Transaction {
  @Serializable(LongAsStringSerializer::class)
  amount; // Serialized as "1234567890123456789" instead of number
  
  description;
  
  constructor(amount, description) {
    this.amount = amount;
    this.description = description;
  }
}

// Direct usage
const longValue = 9007199254740991L; // Larger than MAX_SAFE_INTEGER
const json = format.encodeToString(LongAsStringSerializer, longValue);
// Output: "9007199254740991"

const deserializedLong = format.decodeFromString(LongAsStringSerializer, json);

Nothing Serializer

NothingSerializer

Serializer for the Nothing type that always throws (Experimental).

@ExperimentalSerializationApi
fun NothingSerializer(): KSerializer<Nothing>

{ .api }

Usage:

const nothingSerializer = NothingSerializer();

// This will always throw SerializationException
try {
  format.encodeToString(nothingSerializer, /* any value */);
} catch (e) {
  console.log("Nothing cannot be serialized:", e.message);
}

// Useful for sealed class exhaustiveness
@Serializable
sealed class Result<T> {
  @Serializable
  static class Success<T> extends Result<T> {
    constructor(value) {
      super();
      this.value = value;
    }
  }
  
  @Serializable  
  static class Error extends Result {
    constructor(message) {
      super();
      this.message = message;
    }
  }
  
  // This ensures all cases are covered in pattern matching
  static neverCase() {
    return NothingSerializer();
  }
}

Custom Collection Types

Creating Custom Collection Serializers

// Custom collection serializer example
class ImmutableListSerializer {
  constructor(elementSerializer) {
    this.elementSerializer = elementSerializer;
    this.descriptor = ListSerializer(elementSerializer).descriptor;
  }
  
  serialize(encoder, value) {
    // Convert ImmutableList to regular array for serialization
    const array = value.toArray();
    const listSerializer = ListSerializer(this.elementSerializer);
    listSerializer.serialize(encoder, array);
  }
  
  deserialize(decoder) {
    // Deserialize as array then convert to ImmutableList
    const listSerializer = ListSerializer(this.elementSerializer);
    const array = listSerializer.deserialize(decoder);
    return ImmutableList.from(array);
  }
}

// Usage
const immutableStringListSerializer = new ImmutableListSerializer(String.serializer());

@Serializable
class DataContainer {
  @Serializable(ImmutableListSerializer<String>::class)
  items;
  
  constructor(items) {
    this.items = items;
  }
}

Serializer Registration

Using Built-in Serializers in Modules

// Register built-in serializers in modules
const module = SerializersModule {
  // Contextual serializers for special handling
  contextual(Long::class, LongAsStringSerializer)
  contextual(Instant::class, InstantComponentSerializer)
  
  // Custom serializers for third-party types
  contextual(BigDecimal::class, BigDecimalStringSerializer)
};

// Use with format
const format = Json {
  serializersModule = module
};

@Serializable  
class FinancialRecord {
  @Contextual
  amount; // Uses LongAsStringSerializer from module
  
  @Contextual
  timestamp; // Uses InstantComponentSerializer from module
  
  constructor(amount, timestamp) {
    this.amount = amount;
    this.timestamp = timestamp;
  }
}

Type-Safe Generic Serializers

Generic Factory Functions

// Type-safe generic serializer factories
function createListSerializer<T>(elementSerializer: KSerializer<T>): KSerializer<Array<T>> {
  return ListSerializer(elementSerializer);
}

function createMapSerializer<K, V>(
  keySerializer: KSerializer<K>, 
  valueSerializer: KSerializer<V>
): KSerializer<Map<K, V>> {
  return MapSerializer(keySerializer, valueSerializer);
}

// Usage with full type safety
const userListSerializer: KSerializer<Array<User>> = createListSerializer(User.serializer());
const stringIntMapSerializer: KSerializer<Map<string, number>> = createMapSerializer(
  String.serializer(), 
  Int.serializer()
);

The built-in serializers provide comprehensive support for all standard Kotlin types and collections, enabling seamless serialization of complex data structures while maintaining type safety and JavaScript interoperability.

Install with Tessl CLI

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

docs

annotations.md

builtins.md

descriptors.md

encoding.md

index.md

modules.md

serializers.md

tile.json