1. Qu'est-ce que c'est et pourquoi l'utiliser ?

kotlinx-datetime est la bibliothèque officielle de JetBrains pour manipuler les dates et heures dans l'écosystème Kotlin. Sa principale force est la multiplateforme : le même code fonctionne sur JVM, JS (navigateur et Node.js), Native (iOS, macOS, Windows, Linux) et Wasm. Fini les wrappers spécifiques à chaque plateforme ou l'utilisation de bibliothèques différentes selon l'environnement.

Pourquoi en avez-vous besoin ? La bibliothèque standard Kotlin/JVM utilise java.time, qui n'est pas disponible sur les autres plateformes. Pour Kotlin/Native et Kotlin/JS, les développeurs devaient soit utiliser des API natives (NSDate, Date), soit intégrer des bibliothèques tierces. kotlinx-datetime résout ce problème en offrant une API unifiée, basée sur la norme ISO-8601. Elle inclut des classes pour représenter les instants (Instant), les dates sans heure (LocalDate), les heures sans date (LocalTime), les dates avec heure (LocalDateTime), les fuseaux horaires (TimeZone) et les périodes (DateTimePeriod).

Cette bibliothèque est idéale pour les projets utilisant Kotlin Multiplatform (KMP), les applications serveur avec Ktor, les applications Android (en remplacement de java.time), et même pour les scripts et utilitaires en console. Légère, sans dépendances externes et activement maintenue par la communauté, elle est un choix de premier ordre.

2. Installation

La bibliothèque est disponible sur Maven Central. Pour l'ajouter à votre projet, il suffit d'ajouter la dépendance dans le fichier build.gradle.kts (ou build.gradle). Voici le code exact pour Gradle Kotlin DSL.

// build.gradle.kts
repositories {
    mavenCentral()
}

dependencies {
    // Bibliothèque principale
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")

    // Pour un projet multiplateforme, ajoutez dans commonMain :
    // commonMain.dependencies {
    //     implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
    // }
}

Important : La version 0.6.1 est la dernière version stable au moment de la rédaction de cet article. Vérifiez la version la plus récente sur les releases GitHub. Pour Gradle Groovy DSL, la commande est similaire, mais sans les guillemets autour des chaînes.

Si vous utilisez Maven, ajoutez ceci dans votre pom.xml :

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime</artifactId>
    <version>0.6.1</version>
</dependency>

Pour un projet Gradle Kotlin DSL multiplateforme (KMP), ajoutez dans commonMain :

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
        }
    }
}

3. Démarrage rapide

Un exemple minimal : créer l'instant présent, le formater et l'afficher dans la console.

import kotlinx.datetime.*

fun main() {
    // Obtenir l'instant présent en UTC
    val now: Instant = Clock.System.now()
    println("Instant présent en UTC : $now")

    // Convertir en date et heure locales (en utilisant le fuseau horaire système)
    val localDateTime: LocalDateTime = now.toLocalDa