Implement JS target (experimental)

README.md

@@ -9,7 +9,11 @@
 
 This library adds YAML support to [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization/).
 
-Currently, only Kotlin/JVM is supported. (Follow [this issue](https://github.com/charleskorn/kaml/issues/232) for a discussion of adding support for other targets.)
+Currently, only Kotlin/JVM is fully supported.
+
+Kotlin/JS support is considered highly experimental. It is not yet fully functional, and may be removed or modified at any time.
+
+(Follow [this issue](https://github.com/charleskorn/kaml/issues/232) for a discussion of adding support for other targets.)
 
 YAML version 1.2 is supported.
 

build.gradle.kts

@@ -29,6 +29,7 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 plugins {
     kotlin("multiplatform")
     kotlin("plugin.serialization")
+    id("io.kotest.multiplatform") version "5.6.2"
 }
 
 group = "com.charleskorn.kaml"
@@ -44,6 +45,19 @@ kotlin {
         withJava()
     }
 
+    js(IR) {
+        browser {
+            testTask {
+                // TODO: enable once the tests work with Kotlin/JS.
+                //  The main problem noticed so far is that the DescribeSpec isn't supported by Kotlin/JS.
+                //  See https://github.com/kotest/kotest/blob/71c1826e5b404359ad8efe7cd360a2db3af5436b/kotest-framework/kotest-framework-engine/src/commonMain/kotlin/io/kotest/engine/spec/interceptor/IgnoreNestedSpecStylesInterceptor.kt#L47
+                enabled = false
+            }
+        }
+        nodejs()
+        binaries.executable()
+    }
+
     sourceSets {
         all {
             languageSettings.optIn("kotlin.RequiresOptIn")
@@ -74,6 +88,13 @@ kotlin {
                 implementation("io.kotest:kotest-runner-junit5:5.6.2")
             }
         }
+
+        named("jsMain") {
+            dependencies {
+                implementation("it.krzeminski:snakeyaml-engine-kmp:2.7")
+                implementation("com.squareup.okio:okio:3.3.0")
+            }
+        }
     }
 }
 

buildSrc/src/main/kotlin/com/charleskorn/kaml/build/SpotlessConfiguration.kt

@@ -56,7 +56,7 @@ fun Project.configureSpotless() {
                     mapOf(
                         "dir" to ".",
                         "include" to listOf("**/*.md", "**/.gitignore", "**/*.yaml", "**/*.yml", "**/*.sh", "**/Dockerfile"),
-                        "exclude" to listOf(".gradle/**", ".gradle-cache/**", "build/**"),
+                        "exclude" to listOf(".gradle/**", ".gradle-cache/**", ".batect/**", "build/**"),
                     ),
                 ),
             )

src/commonMain/kotlin/com/charleskorn/kaml/YamlException.kt

@@ -29,7 +29,7 @@ public open class YamlException(
     public val line: Int = location.line
     public val column: Int = location.column
 
-    override fun toString(): String = "${this::class.qualifiedName} at ${path.toHumanReadableString()} on line $line, column $column: $message"
+    override fun toString(): String = "${this::class.simpleName} at ${path.toHumanReadableString()} on line $line, column $column: $message"
 }
 
 public class DuplicateKeyException(

src/commonTest/kotlin/com/charleskorn/kaml/YamlExceptionTest.kt

@@ -29,6 +29,6 @@ class YamlExceptionTest : FunSpec({
             .withListEntry(2, Location(123, 456))
         val exception = YamlException("Something went wrong", path)
 
-        exception.toString() shouldBe "com.charleskorn.kaml.YamlException at colours[2] on line 123, column 456: Something went wrong"
+        exception.toString() shouldBe "YamlException at colours[2] on line 123, column 456: Something went wrong"
     }
 })

src/commonTest/kotlin/com/charleskorn/kaml/YamlReadingTest.kt

@@ -2552,7 +2552,7 @@ private data class CustomSerializedValue(val thing: String)
 
 @OptIn(InternalSerializationApi::class, ExperimentalSerializationApi::class)
 private object LocationThrowingSerializer : KSerializer<Any> {
-    override val descriptor = buildSerialDescriptor(LocationThrowingSerializer::class.qualifiedName!!, SerialKind.CONTEXTUAL)
+    override val descriptor = buildSerialDescriptor(LocationThrowingSerializer::class.simpleName!!, SerialKind.CONTEXTUAL)
 
     override fun deserialize(decoder: Decoder): Any {
         val location = (decoder as YamlInput).getCurrentLocation()

src/jsMain/kotlin/com/charleskorn/kaml/Yaml.kt

@@ -0,0 +1,95 @@
+/*
+
+   Copyright 2018-2023 Charles Korn.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+*/
+
+package com.charleskorn.kaml
+
+import kotlinx.serialization.DeserializationStrategy
+import kotlinx.serialization.SerializationStrategy
+import kotlinx.serialization.StringFormat
+import kotlinx.serialization.modules.EmptySerializersModule
+import kotlinx.serialization.modules.SerializersModule
+import okio.Buffer
+import okio.ByteString.Companion.encodeUtf8
+import okio.Source
+import org.snakeyaml.engine.v2.api.StreamDataWriter
+
+public actual class Yaml(
+    override val serializersModule: SerializersModule = EmptySerializersModule(),
+    public actual val configuration: YamlConfiguration = YamlConfiguration(),
+) : StringFormat {
+    public actual fun <T> decodeFromYamlNode(
+        deserializer: DeserializationStrategy<T>,
+        node: YamlNode,
+    ): T {
+        val input = YamlInput.createFor(node, this, serializersModule, configuration, deserializer.descriptor)
+        return input.decodeSerializableValue(deserializer)
+    }
+
+    public actual companion object {
+        public actual val default: Yaml = Yaml() }
+
+    override fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T {
+        return decodeFromReader(deserializer, Buffer().write(string.encodeUtf8()))
+    }
+
+    private fun <T> decodeFromReader(deserializer: DeserializationStrategy<T>, source: Source): T {
+        val rootNode = parseToYamlNodeFromReader(source)
+
+        val input = YamlInput.createFor(rootNode, this, serializersModule, configuration, deserializer.descriptor)
+        return input.decodeSerializableValue(deserializer)
+    }
+
+    private fun parseToYamlNodeFromReader(source: Source): YamlNode {
+        val parser = YamlParser(source)
+        val reader = YamlNodeReader(parser, configuration.extensionDefinitionPrefix, configuration.allowAnchorsAndAliases)
+        val node = reader.read()
+        parser.ensureEndOfStreamReached()
+        return node
+    }
+
+    override fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String {
+        val writer = object : StreamDataWriter {
+            private var stringBuilder = StringBuilder()
+
+            override fun flush() { }
+
+            override fun write(str: String) {
+                stringBuilder.append(str)
+            }
+
+            override fun write(str: String, off: Int, len: Int) {
+                stringBuilder.append(str.drop(off).subSequence(0, len))
+            }
+
+            override fun toString(): String {
+                return stringBuilder.toString()
+            }
+        }
+
+        encodeToStreamDataWriter(serializer, value, writer)
+
+        return writer.toString().trimEnd()
+    }
+
+    @OptIn(ExperimentalStdlibApi::class)
+    private fun <T> encodeToStreamDataWriter(serializer: SerializationStrategy<T>, value: T, writer: StreamDataWriter) {
+        YamlOutput(writer, serializersModule, configuration).use { output ->
+            output.encodeSerializableValue(serializer, value)
+        }
+    }
+}

src/jsMain/kotlin/com/charleskorn/kaml/YamlNodeReader.kt

@@ -0,0 +1,210 @@
+/*
+
+   Copyright 2018-2023 Charles Korn.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+*/
+
+package com.charleskorn.kaml
+
+import org.snakeyaml.engine.v2.common.Anchor
+import org.snakeyaml.engine.v2.events.AliasEvent
+import org.snakeyaml.engine.v2.events.Event
+import org.snakeyaml.engine.v2.events.MappingStartEvent
+import org.snakeyaml.engine.v2.events.NodeEvent
+import org.snakeyaml.engine.v2.events.ScalarEvent
+import org.snakeyaml.engine.v2.events.SequenceStartEvent
+
+internal actual class YamlNodeReader(
+    private val parser: YamlParser,
+    private val extensionDefinitionPrefix: String? = null,
+    private val allowAnchorsAndAliases: Boolean = false,
+) {
+    private val aliases = mutableMapOf<Anchor, YamlNode>()
+
+    actual fun read(): YamlNode = readNode(YamlPath.root)
+
+    private fun readNode(path: YamlPath): YamlNode = readNodeAndAnchor(path).first
+
+    private fun readNodeAndAnchor(path: YamlPath): Pair<YamlNode, Anchor?> {
+        val event = parser.consumeEvent(path)
+        val node = readFromEvent(event, path)
+
+        if (event is NodeEvent) {
+            event.anchor?.let {
+                if (!allowAnchorsAndAliases) {
+                    throw ForbiddenAnchorOrAliasException("Parsing anchors and aliases is disabled.", path)
+                }
+
+                aliases.put(it, node.withPath(YamlPath.forAliasDefinition(it.value, event.location)))
+            }
+
+            return node to event.anchor
+        }
+
+        return node to null
+    }
+
+    private fun readFromEvent(event: Event, path: YamlPath): YamlNode = when (event) {
+        is ScalarEvent -> readScalarOrNull(event, path).maybeToTaggedNode(event.tag)
+        is SequenceStartEvent -> readSequence(path).maybeToTaggedNode(event.tag)
+        is MappingStartEvent -> readMapping(path).maybeToTaggedNode(event.tag)
+        is AliasEvent -> readAlias(event, path)
+        else -> throw MalformedYamlException("Unexpected ${event.eventId}", path.withError(event.location))
+    }
+
+    private fun readScalarOrNull(event: ScalarEvent, path: YamlPath): YamlNode {
+        if ((event.value == "null" || event.value == "" || event.value == "~") && event.plain) {
+            return YamlNull(path)
+        } else {
+            return YamlScalar(event.value, path)
+        }
+    }
+
+    private fun readSequence(path: YamlPath): YamlList {
+        val items = mutableListOf<YamlNode>()
+
+        while (true) {
+            val event = parser.peekEvent(path)
+
+            when (event.eventId) {
+                Event.ID.SequenceEnd -> {
+                    parser.consumeEventOfType(Event.ID.SequenceEnd, path)
+                    return YamlList(items, path)
+                }
+
+                else -> items += readNode(path.withListEntry(items.size, event.location))
+            }
+        }
+    }
+
+    private fun readMapping(path: YamlPath): YamlMap {
+        val items = mutableMapOf<YamlScalar, YamlNode>()
+
+        while (true) {
+            val event = parser.peekEvent(path)
+
+            when (event.eventId) {
+                Event.ID.MappingEnd -> {
+                    parser.consumeEventOfType(Event.ID.MappingEnd, path)
+                    return YamlMap(doMerges(items), path)
+                }
+
+                else -> {
+                    val keyLocation = parser.peekEvent(path).location
+                    val key = readMapKey(path)
+                    val keyNode = YamlScalar(key, path.withMapElementKey(key, keyLocation))
+
+                    val valueLocation = parser.peekEvent(keyNode.path).location
+                    val valuePath = if (isMerge(keyNode)) path.withMerge(valueLocation) else keyNode.path.withMapElementValue(valueLocation)
+                    val (value, anchor) = readNodeAndAnchor(valuePath)
+
+                    if (path == YamlPath.root && extensionDefinitionPrefix != null && key.startsWith(extensionDefinitionPrefix)) {
+                        if (anchor == null) {
+                            throw NoAnchorForExtensionException(key, extensionDefinitionPrefix, path.withError(event.location))
+                        }
+                    } else {
+                        items += (keyNode to value)
+                    }
+                }
+            }
+        }
+    }
+
+    private fun readMapKey(path: YamlPath): String {
+        val event = parser.peekEvent(path)
+
+        when (event.eventId) {
+            Event.ID.Scalar -> {
+                parser.consumeEventOfType(Event.ID.Scalar, path)
+                val scalarEvent = event as ScalarEvent
+                val isNullKey = (scalarEvent.value == "null" || scalarEvent.value == "~") && scalarEvent.plain
+
+                if (scalarEvent.tag != null || isNullKey) {
+                    throw nonScalarMapKeyException(path, event)
+                }
+
+                return scalarEvent.value
+            }
+            else -> throw nonScalarMapKeyException(path, event)
+        }
+    }
+
+    private fun nonScalarMapKeyException(path: YamlPath, event: Event) = MalformedYamlException("Property name must not be a list, map, null or tagged value. (To use 'null' as a property name, enclose it in quotes.)", path.withError(event.location))
+
+    private fun YamlNode.maybeToTaggedNode(tag: String?): YamlNode =
+        tag?.let { YamlTaggedNode(it, this) } ?: this
+
+    private fun doMerges(items: Map<YamlScalar, YamlNode>): Map<YamlScalar, YamlNode> {
+        val mergeEntries = items.entries.filter { (key, _) -> isMerge(key) }
+
+        when (mergeEntries.count()) {
+            0 -> return items
+            1 -> when (val mappingsToMerge = mergeEntries.single().value) {
+                is YamlList -> return doMerges(items, mappingsToMerge.items)
+                else -> return doMerges(items, listOf(mappingsToMerge))
+            }
+            else -> throw MalformedYamlException("Cannot perform multiple '<<' merges into a map. Instead, combine all merges into a single '<<' entry.", mergeEntries.second().key.path)
+        }
+    }
+
+    private fun isMerge(key: YamlNode): Boolean = key is YamlScalar && key.content == "<<"
+
+    private fun doMerges(original: Map<YamlScalar, YamlNode>, others: List<YamlNode>): Map<YamlScalar, YamlNode> {
+        val merged = mutableMapOf<YamlScalar, YamlNode>()
+
+        original
+            .filterNot { (key, _) -> isMerge(key) }
+            .forEach { (key, value) -> merged.put(key, value) }
+
+        others
+            .forEach { other ->
+                when (other) {
+                    is YamlNull -> throw MalformedYamlException("Cannot merge a null value into a map.", other.path)
+                    is YamlScalar -> throw MalformedYamlException("Cannot merge a scalar value into a map.", other.path)
+                    is YamlList -> throw MalformedYamlException("Cannot merge a list value into a map.", other.path)
+                    is YamlTaggedNode -> throw MalformedYamlException("Cannot merge a tagged value into a map.", other.path)
+                    is YamlMap ->
+                        other.entries.forEach { (key, value) ->
+                            val existingEntry = merged.entries.singleOrNull { it.key.equivalentContentTo(key) }
+
+                            if (existingEntry == null) {
+                                merged.put(key, value)
+                            }
+                        }
+                }
+            }
+
+        return merged
+    }
+
+    private fun readAlias(event: AliasEvent, path: YamlPath): YamlNode {
+        if (!allowAnchorsAndAliases) {
+            throw ForbiddenAnchorOrAliasException("Parsing anchors and aliases is disabled.", path)
+        }
+
+        val anchor = event.anchor!!
+
+        val resolvedNode = aliases.getOrElse(anchor) {
+            throw UnknownAnchorException(anchor.value, path.withError(event.location))
+        }
+
+        return resolvedNode.withPath(path.withAliasReference(anchor.value, event.location).withAliasDefinition(anchor.value, resolvedNode.location))
+    }
+
+    private fun <T> Iterable<T>.second(): T = this.drop(1).first()
+
+    private val Event.location: Location
+        get() = Location(startMark!!.line + 1, startMark!!.column + 1)
+}