JS plain objects 컴파일러 플러그인

JavaScript(JS) plain objects 컴파일러 플러그인(js-plain-objects)을 사용하면 일반(plain) JS 객체를 타입 세이프한 방식으로 만들고 복사할 수 있어요.

여기에서 plain JS 객체에 대한 정보와 Kotlin/JS 프로젝트에 js-plain-objects 컴파일러 플러그인을 사용하는 방법을 확인할 수 있어요.

js-plain-objects 플러그인은 새 K2 Kotlin 컴파일러에서만 동작해요.

Plain JS 객체

plain 객체는 데이터 프로퍼티를 포함하고 객체 리터럴({})로 생성되는 단순한 JS 객체예요. 많은 JS API가 설정이나 데이터 교환을 위해 Plain JS 객체를 받거나 반환해요.

js-plain-objects 플러그인을 사용하면 객체의 형태를 설명하기 위해 Kotlin external interface를 선언하고 @JsPlainObject로 어노테이션을 붙여요. 그러면 컴파일러가 Kotlin 타입 안전성을 유지하면서 그런 객체를 만들고 복사하는 편리한 함수들을 생성해 줘요.

플러그인 활성화하기

다음 Kotlin DSL에서 보여 주듯이 js-plain-objects 플러그인을 프로젝트의 Gradle 구성 파일에 추가해요:

// build.gradle.kts
plugins {
    kotlin("multiplatform") version "2.4.20"
    kotlin("plugin.js-plain-objects") version "2.4.20"
}

kotlin {
    js {
        browser() // or nodejs()
    }
}

// build.gradle
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.20'
    id 'org.jetbrains.kotlin.plugin.js-plain-objects' version '2.4.20'
}

kotlin {
    js {
        browser() // or nodejs()
    }
}

Plain 객체 타입 선언하기

js-plain-objects 플러그인을 활성화한 뒤에는 plain 객체 타입을 선언할 수 있어요. external interface에 @JsPlainObject 어노테이션을 붙이면 돼요. 예를 들어:

@JsPlainObject
external interface User {
    val name: String
    val age: Int
    // You can use nullable types to declare a property as optional
    val email: String?
}

플러그인이 이런 인터페이스를 처리하면 객체를 만들고 복사하는 두 가지 헬퍼 함수가 있는 companion object를 생성해요:

@JsPlainObject
external interface User {
    val name: String
    val age: Int
    val email: String?

    // Generated by the plugin
    @JsExport.Ignore
    companion object {
        inline operator fun invoke(name: String, age: Int, email: String? = NOTHING): User =
            js("({ name: name, age: age, email: email })")

        inline fun copy(source: User, name: String = NOTHING, age: Int = NOTHING, email: String? = NOTHING): User =
            js("Object.assign({}, source, { name: name, age: age, email: email })")
    }
}

앞선 예제에서:

name과 age는 nullability 표시 없이 선언됐으므로 필수예요.
email은 nullable로 선언됐으므로 선택 사항이고 생성 시 생략할 수 있어요.
invoke 연산자는 제공된 프로퍼티로 새 plain JS 객체를 만들어요.
copy 함수는 source를 얕게 복사(shallow copy)하고 지정된 프로퍼티를 덮어써서 새 객체를 만들어요.
companion은 @JsExport.Ignore로 표시되어 이 헬퍼들이 JS export로 새어 나가지 않도록 해요.

Plain 객체 사용하기

생성된 헬퍼를 사용해서 객체를 만들고 복사해요:

fun main() {
    val user = User(name = "Name", age = 10)
    val copy = User.copy(user, age = 11, email = "[email protected]")

    println(JSON.stringify(user))
    // { "name": "Name", "age": 10 }
    println(JSON.stringify(copy))
    // { "name": "Name", "age": 11, "email": "[email protected]" }
}

이 Kotlin 코드는 JavaScript로 컴파일돼요:

function main () {
    var user = { name: "Name", age: 10 };
    var copy = Object.assign({}, user, { age: 11, email: "[email protected]" });

    println(JSON.stringify(user));
    // { "name": "Name", "age": 10 }
    println(JSON.stringify(copy));
    // { "name": "Name", "age": 11, "email": "[email protected]" }
}

이 방식으로 만들어진 모든 JavaScript 객체는 안전해요. 잘못된 프로퍼티 이름이나 값 타입을 사용하면 컴파일 타임 에러를 만나게 돼요. 이 방식은 생성된 코드가 단순한 객체 리터럴과 Object.assign 호출로 인라인되기 때문에 비용이 0이에요(zero-cost).

다음 단계

Use JavaScript code from Kotlin과 dynamic type 문서에서 JavaScript와의 인터옵에 대해 더 자세히 알아보세요.