Refine implementation

README.md

@@ -2,7 +2,10 @@
 
 # Kotlinx Serialization TypeScript Generator
 
-Create TypeScript interfaces from Kotlinx Serialization classes.
+[Kotlinx Serialization TypeScript Generator](https://github.com/adamko-dev/kotlinx-serialization-typescript-generator)
+creates TypeScript interfaces from
+[Kotlinx Serialization](https://github.com/Kotlin/kotlinx.serialization/)
+classes.
 
 ```kotlin
 @Serializable
@@ -39,23 +42,31 @@ The Kotlinx Serialization API should be used to generate TypeScript. The
 [`SerialDescriptor`s](https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.descriptors/-serial-descriptor/index.html)
 are flexible and comprehensive enough to allow for accurate TypeScript code, without any deviation.
 
+The aim is to create TypeScript interfaces that can accurately produce Kotlinx Serialization
+compatible JSON.
+
+The Kotlinx Serialization API should be used to generate TypeScript. The
+[`SerialDescriptor`s](https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.descriptors/-serial-descriptor/index.html)
+are flexible and comprehensive enough to allow for accurate TypeScript code, without any deviation.
+
 See [the docs](./docs) for working examples.
 
 ## Status
 
 This is a proof-of-concept.
 
-|                                       | Status                                                   | Notes                                                                                            |
-|---------------------------------------|----------------------------------------------------------|:-------------------------------------------------------------------------------------------------|
-| Kotlin multiplatform                  | ❓                                                        | The codebase is multiplatform, but only JVM has been tested                                      |
-| `@SerialName`                         | ✅/⚠                                                      | The serial name is directly converted and might produce invalid TypeScript                       |
-| Basic classes                         | ✅       [example](./docs/basic-classes.md)               |                                                                                                  |
-| Nullable and default-value properties | ✅       [example](./docs/default-values.md)              |                                                                                                  |
-| Value classes                         | ✅       [example](./docs/value-classes.md)               |                                                                                                  |
-| Enums                                 | ✅       [example](./docs/enums.md)                       |                                                                                                  |
-| Lists                                 | ✅       [example](./docs/lists.md)                       |                                                                                                  |
-| Maps                                  | ✅/⚠     [example](./docs/maps.md)                        | Maps with complex keys are converted to an ES6 Map, [see](./docs/maps.md#maps-with-complex-keys) |
-| Polymorphism - Sealed classes         | ✅/⚠     [example](./docs/polymorphism.md#sealed-classes) | Nested sealed classes are ignored, [see](./docs/polymorphism.md#nested-sealed-classes)           |
-| Polymorphism - Open classes           | ❌       [example](./docs/abstract-classes.md)            | Not implemented. Converted to `type MyClass = any`                                               |
-| `@JsonClassDiscriminator`             | ❌                                                        | Not implemented                                                                                  |
-| Edge cases - circular dependencies    | ✅       [example](./docs/edgecases.md)                   |                                                                                                  |
+|                                       | Status                                                          | Notes                                                                                                          |
+|---------------------------------------|-----------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------|
+| Kotlin multiplatform                  | ❓                                                               | The codebase is multiplatform, but only JVM has been tested                                                    |
+| `@SerialName`                         | ✅/⚠                                                             | The serial name is directly converted and might produce invalid TypeScript                                     |
+| Basic classes                         | ✅   [example](./docs/basic-classes.md)                          |                                                                                                                |
+| Nullable and default-value properties | ✅   [example](./docs/default-values.md)                         |                                                                                                                |
+| Value classes                         | ✅   [example](./docs/value-classes.md)                          |                                                                                                                |
+| Enums                                 | ✅   [example](./docs/enums.md)                                  |                                                                                                                |
+| Lists                                 | ✅   [example](./docs/lists.md)                                  |                                                                                                                |
+| Maps                                  | ✅/⚠ [example](./docs/maps.md)                                   | Maps with complex keys are converted to an ES6 Map, [see documentation](./docs/maps.md#maps-with-complex-keys) |
+| Polymorphism - Sealed classes         | ✅/⚠ [example](./docs/polymorphism.md#sealed-classes)            | Nested sealed classes are ignored, [see documentation](./docs/polymorphism.md#nested-sealed-classes)           |
+| Polymorphism - Open classes           | ❌   [example](./docs/abstract-classes.md)                       | Not implemented. Converted to `type MyClass = any`                                                             |
+| `@JsonClassDiscriminator`             | ❌                                                               | Not implemented                                                                                                |
+| JSON Content polymorphism             | ❌   [example](./docs/polymorphism.md#json-content-polymorphism) | Not implemented. Converted to `type MyClass = any`                                                             |
+| Edge cases - circular dependencies    | ✅   [example](./docs/edgecases.md)                              |                                                                                                                |

docs/code/example/example-generics-01.kt

@@ -8,7 +8,7 @@ import dev.adamko.kxstsgen.*
 import kotlinx.serialization.builtins.serializer
 
 @Serializable
-class Box<T>(
+class Box<T : Number>(
   val value: T,
 )
 

docs/code/example/example-json-polymorphic-01.kt

@@ -0,0 +1,31 @@
+// This file was automatically generated from polymorphism.md by Knit tool. Do not edit.
+@file:Suppress("PackageDirectoryMismatch", "unused")
+package dev.adamko.kxstsgen.example.exampleJsonPolymorphic01
+
+import kotlinx.serialization.*
+import dev.adamko.kxstsgen.*
+
+import kotlinx.serialization.json.*
+
+@Serializable
+abstract class Project {
+  abstract val name: String
+}
+
+@Serializable
+data class BasicProject(override val name: String) : Project()
+
+@Serializable
+data class OwnedProject(override val name: String, val owner: String) : Project()
+
+object ProjectSerializer : JsonContentPolymorphicSerializer<Project>(Project::class) {
+  override fun selectDeserializer(element: JsonElement) = when {
+    "owner" in element.jsonObject -> OwnedProject.serializer()
+    else                          -> BasicProject.serializer()
+  }
+}
+
+fun main() {
+  val tsGenerator = KxsTsGenerator()
+  println(tsGenerator.generate(ProjectSerializer))
+}

docs/code/example/example-list-objects-01.kt

@@ -0,0 +1,23 @@
+// This file was automatically generated from lists.md by Knit tool. Do not edit.
+@file:Suppress("PackageDirectoryMismatch", "unused")
+package dev.adamko.kxstsgen.example.exampleListObjects01
+
+import kotlinx.serialization.*
+import dev.adamko.kxstsgen.*
+
+@Serializable
+data class Colour(
+  val rgb: String
+)
+
+@Serializable
+data class MyLists(
+  val colours: List<Colour>,
+  val colourGroups: Set<List<Colour>>,
+  val colourGroupGroups: LinkedHashSet<List<List<Colour>>>,
+)
+
+fun main() {
+  val tsGenerator = KxsTsGenerator()
+  println(tsGenerator.generate(MyLists.serializer()))
+}

docs/code/example/example-list-objects-02.kt

@@ -0,0 +1,22 @@
+// This file was automatically generated from lists.md by Knit tool. Do not edit.
+@file:Suppress("PackageDirectoryMismatch", "unused")
+package dev.adamko.kxstsgen.example.exampleListObjects02
+
+import kotlinx.serialization.*
+import dev.adamko.kxstsgen.*
+
+@Serializable
+data class Colour(
+  val rgb: String
+)
+
+@Serializable
+data class MyLists(
+  val listOfMaps: List<Map<String, Int>>,
+  val listOfColourMaps: List<Map<String, Colour>>,
+)
+
+fun main() {
+  val tsGenerator = KxsTsGenerator()
+  println(tsGenerator.generate(MyLists.serializer()))
+}

docs/code/example/example-list-primitive-01.kt

@@ -8,8 +8,8 @@ import dev.adamko.kxstsgen.*
 @Serializable
 data class MyLists(
   val strings: List<String>,
-  val ints: List<Int>,
-  val longs: List<Long>,
+  val ints: Set<Int>,
+  val longs: Collection<Long>,
 )
 
 fun main() {

docs/code/example/example-list-primitive-02.kt

@@ -0,0 +1,23 @@
+// This file was automatically generated from lists.md by Knit tool. Do not edit.
+@file:Suppress("PackageDirectoryMismatch", "unused")
+package dev.adamko.kxstsgen.example.exampleListPrimitive02
+
+import kotlinx.serialization.*
+import dev.adamko.kxstsgen.*
+
+@Serializable
+data class Colour(
+  val rgb: String
+)
+
+@Serializable
+data class MyLists(
+  val colours: List<Colour>,
+  val colourGroups: List<List<Colour>>,
+  val colourGroupGroups: List<List<List<Colour>>>,
+)
+
+fun main() {
+  val tsGenerator = KxsTsGenerator()
+  println(tsGenerator.generate(MyLists.serializer()))
+}

docs/code/example/example-map-primitive-03.kt

@@ -6,11 +6,11 @@ import kotlinx.serialization.*
 import dev.adamko.kxstsgen.*
 
 @Serializable
-data class Config(
-  val properties: Map<String?, String?>
+class MapsWithLists(
+  val mapOfLists: Map<String, List<String>>
 )
 
 fun main() {
   val tsGenerator = KxsTsGenerator()
-  println(tsGenerator.generate(Config.serializer()))
+  println(tsGenerator.generate(MapsWithLists.serializer()))
 }

docs/code/example/example-map-primitive-04.kt

@@ -0,0 +1,20 @@
+// This file was automatically generated from maps.md by Knit tool. Do not edit.
+@file:Suppress("PackageDirectoryMismatch", "unused")
+package dev.adamko.kxstsgen.example.exampleMapPrimitive04
+
+import kotlinx.serialization.*
+import dev.adamko.kxstsgen.*
+
+@Serializable
+@JvmInline
+value class Data(val content: String)
+
+@Serializable
+class MyDataClass(
+  val mapOfLists: Map<String, Data>
+)
+
+fun main() {
+  val tsGenerator = KxsTsGenerator()
+  println(tsGenerator.generate(MyDataClass.serializer()))
+}

docs/code/example/example-map-primitive-05.kt

@@ -0,0 +1,16 @@
+// This file was automatically generated from maps.md by Knit tool. Do not edit.
+@file:Suppress("PackageDirectoryMismatch", "unused")
+package dev.adamko.kxstsgen.example.exampleMapPrimitive05
+
+import kotlinx.serialization.*
+import dev.adamko.kxstsgen.*
+
+@Serializable
+data class Config(
+  val properties: Map<String?, String?>
+)
+
+fun main() {
+  val tsGenerator = KxsTsGenerator()
+  println(tsGenerator.generate(Config.serializer()))
+}

docs/code/test/ListsTests.kt

@@ -25,4 +25,47 @@ class ListsTests {
           .normalize()
       )
   }
+
+  @Test
+  fun testExampleListObjects01() {
+    captureOutput("ExampleListObjects01") {
+      dev.adamko.kxstsgen.example.exampleListObjects01.main()
+    }.normalizeJoin()
+      .shouldBe(
+        // language=TypeScript
+        """
+          |export interface MyLists {
+          |  colours: Colour[];
+          |  colourGroups: Colour[][];
+          |  colourGroupGroups: Colour[][][];
+          |}
+          |
+          |export interface Colour {
+          |  rgb: string;
+          |}
+        """.trimMargin()
+          .normalize()
+      )
+  }
+
+  @Test
+  fun testExampleListObjects02() {
+    captureOutput("ExampleListObjects02") {
+      dev.adamko.kxstsgen.example.exampleListObjects02.main()
+    }.normalizeJoin()
+      .shouldBe(
+        // language=TypeScript
+        """
+          |export interface MyLists {
+          |  listOfMaps: { [key: string]: number }[];
+          |  listOfColourMaps: { [key: string]: Colour }[];
+          |}
+          |
+          |export interface Colour {
+          |  rgb: string;
+          |}
+        """.trimMargin()
+          .normalize()
+      )
+  }
 }

docs/code/test/MapsTests.kt

@@ -49,6 +49,40 @@ class MapsTests {
   fun testExampleMapPrimitive03() {
     captureOutput("ExampleMapPrimitive03") {
       dev.adamko.kxstsgen.example.exampleMapPrimitive03.main()
+    }.normalizeJoin()
+      .shouldBe(
+        // language=TypeScript
+        """
+          |export interface MapsWithLists {
+          |  mapOfLists: { [key: string]: string[] };
+          |}
+        """.trimMargin()
+          .normalize()
+      )
+  }
+
+  @Test
+  fun testExampleMapPrimitive04() {
+    captureOutput("ExampleMapPrimitive04") {
+      dev.adamko.kxstsgen.example.exampleMapPrimitive04.main()
+    }.normalizeJoin()
+      .shouldBe(
+        // language=TypeScript
+        """
+          |export interface MyDataClass {
+          |  mapOfLists: { [key: string]: Data };
+          |}
+          |
+          |export type Data = string;
+        """.trimMargin()
+          .normalize()
+      )
+  }
+
+  @Test
+  fun testExampleMapPrimitive05() {
+    captureOutput("ExampleMapPrimitive05") {
+      dev.adamko.kxstsgen.example.exampleMapPrimitive05.main()
     }.normalizeJoin()
       .shouldBe(
         // language=TypeScript

docs/code/test/PolymorphismTest.kt

@@ -206,4 +206,34 @@ class PolymorphismTest {
           .normalize()
       )
   }
+
+  @Test
+  fun testExampleGenerics01() {
+    captureOutput("ExampleGenerics01") {
+      dev.adamko.kxstsgen.example.exampleGenerics01.main()
+    }.normalizeJoin()
+      .shouldBe(
+        // language=TypeScript
+        """
+          |export interface Box {
+          |  value: number;
+          |}
+        """.trimMargin()
+          .normalize()
+      )
+  }
+
+  @Test
+  fun testExampleJsonPolymorphic01() {
+    captureOutput("ExampleJsonPolymorphic01") {
+      dev.adamko.kxstsgen.example.exampleJsonPolymorphic01.main()
+    }.normalizeJoin()
+      .shouldBe(
+        // language=TypeScript
+        """
+          |export type Project = any;
+        """.trimMargin()
+          .normalize()
+      )
+  }
 }