This PR provides an annotation that allows marking properties that have default values as required in the TypeScript code.

The primary use case we have for this is for Read DTOs that have default values that are guaranteed to always be present by the time they reach the TypeScript code.

This is safe to use as long as encodeDefaults = true is set in the server's Json config. Otherwise all properties with default values should be considered optional.

Hello, it would be great to have this package on maven.

In my case I'm stuck on Maven since am using cloud functions and they require maven pom.xml unless you want to build and upload a jar. All my dependencies including kotlinx.serialization are maven except this packages.

To help emulate Kotlin's strong typing, use 'brand typing' to specify primitives and value classes. Otherwise TypeScript doesn't discriminate between UInt and Long

Builtin primitives should be handled

type Byte = number & { __kotlin_byte__ : void};

Value classes too

package my.package

@Serializable
@JvmInline
value class UserCount(private val count: UInt)

Something like this...

type UInt = number & { __kotlin_uint__ : void};

type UserCount = UInt & { __my_package__usercount__ : void};

Adding some docs to demo how @Required can be used to make properties required.

cc @nschulzke https://github.com/adamko-dev/kotlinx-serialization-typescript-generator/pull/47

• Create GitHub workflows for running tests
• add an option for enabling/disabling the TS compile tests
• fix TS compile assertions
• misc version bumps
• disable Kotest JS tests (blocked by https://github.com/kotest/kotest/issues/3141)
• bump to jvm11, kotlin-level 1.7
• enable test-fixtures in knit tests, and re-organise source sets

• version bump Kotlin 1.6.20
• jdk decrease to 1.8 (wider compatibility)
• set up version catalogue and platform
• Knit test improvements
• fix sealed class enums
• map types: allow overriding, and consider existing overrides
• fix tuple deserialization
• indexed types: allow for number keys
• disable unused 'descriptor extractor' reflection code
• enable Kotlin/JS

PrototypeKey is a primitive, so it's a valid value for an indexed type key.

export interface Dictionary {
  protos: Map<PrototypeKey, PrototypeName>; // actual
  protos: { [key: PrototypeKey]: { [key: string]: PrototypeKey } }; // expected
}

export type PrototypeKey = string;

https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#labeled-tuple-elements

Should be very easy to do, and the TS is much more clear.

fixes #24

Also fixes an issue where nullable keys in maps should be converted to Map<>, not an indexed type. Update docs and tests for this case.

Currently the Knit tests only do a string comparison. But that doesn't mean the expected string is correct TypeScript...

1. add the Gradle Node plugin, download TypeScript
2. download TypeScript npx task
3. in the tests, try compiling the generated TypeScript using a command line arg npx tsc (somehow? I'm not sure about this...)
4. Check there's no errors (again, I'm not sure)

• make the Tuples API a little nicer by returning an iterator to the constructor, so there's no need for fetching elements by index.
• extract descriptors from sealed subclasses properties (they were previously ignored)
• create a specific 'TypeUnion' declaration, so the type aliases are more distinct and the brand typing only works on type aliases

If a client already has some standard type aliases, then I want to re-use those type aliases in my generated code.

@Serializable
data class Position(
  val x: Double,
  val y: Double,
)

// provided by library
export type double = number

// I want generated code to use 'double'
export interface Position {
  x: double;
  y: double;
}

If I hack around a bit, I can come up with something that works. But it's not pretty, or intuitive

fun main() {
  val tsGenerator = KxsTsGenerator()

  val libraryDoubleTypeRef = TsTypeRef.Declaration(TsElementId("Double"), null, false)

  tsGenerator.descriptorElements += Double.serializer().descriptor to setOf(
    TsDeclaration.TsTypeAlias(
      TsElementId("Double"),
      TsTypeRef.Declaration(TsElementId("double"), null, false),
    )
  )

  tsGenerator.descriptorTypeRef += mapOf(
    Double.serializer().descriptor to libraryDoubleTypeRef
  )

  println(tsGenerator.generate(Position.serializer()))
}

@Serializable
data class Position(
  val x: Double,
  val y: Double,
)

This produces the correct output...

export interface Position {
  x: Double;
  y: Double;
}

export type Double = double;

Good luck figuring that out if you're new to KXS, and didn't happen to build this library...

Potential solutions

Users should be able to set overrides for SerialDescriptors, similar to the existing serializerDescriptors and descriptorElements in KxsTsGenerator. For example

val gen = KxsTsGenerator()

gen.addOverride(
  Double.serializer().descriptor to existingTypeAlias("double"),
)

Double and Int are both converted directly to number. This is confusing on the TypeScript side.

@Serializable
data class Position(
  val x: Double,
  val y: Double,
  val level: Int,
)

// generated
export interface Position {
  x: number;
  y: number;
  level: number; // level looks the same as x and y, but if I produce a JSON message with 1.5, KXS will error
}

Unsigned numbers (because they are value classes) are converted to type aliases, e.g.

export interface Score {
  goals: UInt;
}

export type UInt = number;

In TypeScript this isn't safe (UInt can accept any numeric value, despite its name) - but it gives a good indication, and can be enhanced with brand typing (#7).

Can the other numeric primitives be exported as type aliases?

export type Byte = number
export type Short = number
export type Int = number
export type Long = number
export type Float = number
export type Double = number

Ideally the test should work on all platforms, but getting the tests working on JVM and JS would be a good first step

Requires some way of capturing log output on all platforms (e.g. https://github.com/kotest/kotest/issues/2914)

This has a large scope. SerialDescriptors are not at all generic. It is probably impossible to get this information from KSX.

1. Generic fields

class WrapperClass(
  val type: List<String>
)

1. Generic classes

class WrapperClass<T>(
  val type: T
)

3. Generic constraints

interface MyInterface
class WrapperClass<T: MyInterface>(
  val type: T
)

4. Inheritance plus generics

interface MyInterface<T>
class WrapperClass<T>(
  val type: T
) : MyInterface<T>

4. Wildcards

class SomeClass(
  val type: List<*>
)  

The plugin will scan for all classes with @Serializable. It will convert each to a TypeScript definition.

Nice extras

1. kxs-ts-gen is configurable

2. Add a @TsExport annotation so only specific types are generated

3. Allow @TsExport to be added to const strings, and the raw value will be exported (inspired by https://github.com/ntrrgc/ts-generator/issues/24)

   @TsExport
   const val customConfig: String = """
   object ApiConstants {
       const SOME_VAL_1 = 1234
       const SOME_VAL_2 = "hello world"
   }
   """
   

   kxs-ts-gen will produce

   object ApiConstants {
       const SOME_VAL_1 = 1234
       const SOME_VAL_2 = "hello world"
   }
   

   Or maybe directly convert a const

   object ApiConstants {
     @TsExport
     const val SOME_VAL_1 = 1234
     @TsExport
     const val SOME_VAL_2 = "hello world"
   }
   

   kxs-ts-gen will produce

   object ApiConstants {
       const SOME_VAL_1 = 1234
       const SOME_VAL_2 = "hello world"
   }
   

4. Grab KDoc, and convert it to JSDoc

5. Grab annotations and convert them https://github.com/ntrrgc/ts-generator/issues/23

~~Use KSP to create a plugin.~~ KSP is unsuitable, it can only view and can't run code, use https://github.com/ronmamo/reflections or https://github.com/classgraph/classgraph instead?