rename TsType to TsTypeAlias, and update docs in tsElements.kt

Author: aSemy

modules/kxs-ts-gen-core/src/commonMain/kotlin/dev.adamko.kxstsgen/KxsTsSourceCodeGenerator.kt

@@ -16,25 +16,19 @@ abstract class KxsTsSourceCodeGenerator(
       is TsDeclaration.TsEnum      -> generateEnum(element)
       is TsDeclaration.TsInterface -> generateInterface(element)
       is TsDeclaration.TsNamespace -> generateNamespace(element)
-      is TsDeclaration.TsType      -> generateType(element)
+      is TsDeclaration.TsTypeAlias -> generateType(element)
     }
   }
 
   abstract fun generateEnum(enum: TsDeclaration.TsEnum): String
   abstract fun generateInterface(element: TsDeclaration.TsInterface): String
   abstract fun generateNamespace(namespace: TsDeclaration.TsNamespace): String
-  abstract fun generateType(element: TsDeclaration.TsType): String
+  abstract fun generateType(element: TsDeclaration.TsTypeAlias): String
 
-  abstract fun generateMapTypeReference(
-//    requestorId: TsElementId?,
-    tsMap: TsLiteral.TsMap,
-  ): String
+  abstract fun generateMapTypeReference(tsMap: TsLiteral.TsMap): String
 
   abstract fun generatePrimitive(primitive: TsLiteral.Primitive): String
-  abstract fun generateTypeReference(
-//    rootId: TsElementId?,
-    typeRef: TsTypeRef,
-  ): String
+  abstract fun generateTypeReference(typeRef: TsTypeRef): String
 
   open class Default(
     config: KxsTsConfig,
@@ -118,6 +112,8 @@ abstract class KxsTsSourceCodeGenerator(
       }
     }
 
+
+    // note: this isn't used because at present poly-open descriptors are converted to 'any'
     private fun generatePolyOpen(
       element: TsDeclaration.TsInterface,
       polymorphism: TsPolymorphism.Open,
@@ -144,7 +140,7 @@ abstract class KxsTsSourceCodeGenerator(
         subInterfaces,
       )
 
-      val subInterfaceTypeUnion = TsDeclaration.TsType(
+      val subInterfaceTypeUnion = TsDeclaration.TsTypeAlias(
         element.id,
         subInterfaceRefs
       )
@@ -154,6 +150,14 @@ abstract class KxsTsSourceCodeGenerator(
       }
     }
 
+    /**
+     * Generate a 'sealed class' equivalent.
+     *
+     * * type union of all subclasses
+     * * a namespace with contains
+     *   * a 'Type' enum
+     *   * subclasses, each with an additional 'Type' property that has a literal 'Type' enum value
+     */
     private fun generatePolyClosed(
       element: TsDeclaration.TsInterface,
       polymorphism: TsPolymorphism.Sealed,
@@ -189,7 +193,7 @@ abstract class KxsTsSourceCodeGenerator(
         subclass.copy(properties = setOf(typeProp) + subclass.properties)
       }
 
-      val subInterfaceTypeUnion = TsDeclaration.TsType(
+      val subInterfaceTypeUnion = TsDeclaration.TsTypeAlias(
         element.id,
         subInterfaceRefs.keys
       )
@@ -208,7 +212,7 @@ abstract class KxsTsSourceCodeGenerator(
     }
 
 
-    override fun generateType(element: TsDeclaration.TsType): String {
+    override fun generateType(element: TsDeclaration.TsTypeAlias): String {
       val aliases =
         element.typeRefs
           .map { generateTypeReference(it) }

modules/kxs-ts-gen-core/src/commonMain/kotlin/dev.adamko.kxstsgen/TsElementConverter.kt

@@ -75,7 +75,7 @@ fun interface TsElementConverter {
         PolymorphicKind.OPEN   -> {
           val resultId = context.elementId(descriptor)
           val fieldTypeRef = TsTypeRef.Literal(TsLiteral.Primitive.TsAny, false)
-          TsDeclaration.TsType(resultId, fieldTypeRef)
+          TsDeclaration.TsTypeAlias(resultId, fieldTypeRef)
         }
       }
     }
@@ -117,7 +117,7 @@ fun interface TsElementConverter {
       val resultId = context.elementId(structDescriptor)
       val fieldDescriptor = structDescriptor.elementDescriptors.first()
       val fieldTypeRef = context.typeRef(fieldDescriptor)
-      return TsDeclaration.TsType(resultId, fieldTypeRef)
+      return TsDeclaration.TsTypeAlias(resultId, fieldTypeRef)
     }
 
 

modules/kxs-ts-gen-core/src/commonMain/kotlin/dev.adamko.kxstsgen/tsElements.kt

@@ -1,8 +1,18 @@
 package dev.adamko.kxstsgen
 
+import dev.adamko.kxstsgen.TsProperty.Optional
+import dev.adamko.kxstsgen.TsProperty.Required
 import kotlin.jvm.JvmInline
+import kotlinx.serialization.descriptors.SerialDescriptor
 
 
+/**
+ * A unique identifier for a [TsElement].
+ *
+ * This is usually generated from [SerialDescriptor.serialName].
+ */
+// Note: A value class probably isn't the best choice here. The manual String manipulation is
+// restrictive and clunky, and makes nested references very difficult to decipher.
 @JvmInline
 value class TsElementId(private val id: String) {
   val namespace: String
@@ -13,14 +23,25 @@ value class TsElementId(private val id: String) {
   override fun toString(): String = id
 }
 
-
+/**
+ * Some TypeScript source code element. Either a [TsLiteral] or a [TsDeclaration].
+ */
 sealed interface TsElement
 
 
+/**
+ * Declarations are named elements that developers create in TypeScript source code.
+ *
+ * For example, an [interface][TsDeclaration.TsInterface] is declared. In contrast, the interface
+ * may have a [string][TsLiteral.Primitive.TsString] property, which is represented as a
+ * [TsLiteral].
+ */
 sealed interface TsDeclaration : TsElement {
   val id: TsElementId
 
-  data class TsType(
+
+  /** A named reference to one or more other types. */
+  data class TsTypeAlias(
     override val id: TsElementId,
     val typeRefs: Set<TsTypeRef>,
   ) : TsDeclaration {
@@ -50,6 +71,7 @@ sealed interface TsDeclaration : TsElement {
 }
 
 
+/** Literal built-in TypeScript elements. */
 sealed interface TsLiteral : TsElement {
 
   sealed interface Primitive : TsLiteral {
@@ -61,17 +83,23 @@ sealed interface TsLiteral : TsElement {
     object TsObject : Primitive
 
     object TsAny : Primitive
+
+    // the remaining primitives are defined, but unused
     object TsNever : Primitive
     object TsNull : Primitive
     object TsUndefined : Primitive
     object TsUnknown : Primitive
     object TsVoid : Primitive
   }
 
+
+  /** A list with elements of type [valueTypeRef]. */
   data class TsList(
     val valueTypeRef: TsTypeRef,
   ) : TsLiteral
 
+
+  /** A key-value map. */
   data class TsMap(
     val keyTypeRef: TsTypeRef,
     val valueTypeRef: TsTypeRef,
@@ -87,11 +115,19 @@ sealed interface TsLiteral : TsElement {
 }
 
 
+/**
+ * A reference to some [TsElement]. The reference may be [nullable].
+ *
+ * A reference does not require the target to be generated.
+ * This helps prevent circular dependencies causing a lock.
+ */
 sealed interface TsTypeRef {
   val nullable: Boolean
 
+
   data class Literal(val element: TsLiteral, override val nullable: Boolean) : TsTypeRef
 
+
   data class Declaration(
     val id: TsElementId,
     val parent: Declaration?,
@@ -101,40 +137,49 @@ sealed interface TsTypeRef {
 }
 
 
-// source: kxs
+/**
+ * A property within an [interface][TsDeclaration.TsInterface]
+ *
+ *  In  property may be [Required] or [Optional]. See the TypeScript docs:
+ *  ['Optional Properties'](https://www.typescriptlang.org/docs/handbook/2/objects.html#optional-properties)
+ */
 sealed interface TsProperty {
   val name: String
   val typeRef: TsTypeRef
 
+
   data class Required(
     override val name: String,
     override val typeRef: TsTypeRef,
   ) : TsProperty
 
+
   data class Optional(
     override val name: String,
     override val typeRef: TsTypeRef,
   ) : TsProperty
 }
 
 
+/**
+ * Meta-data about the polymorphism of a [TsDeclaration.TsInterface].
+ */
 sealed interface TsPolymorphism {
 
+  /** The name of the field used to discriminate between [subclasses]. */
   val discriminatorName: String
   val subclasses: Set<TsDeclaration.TsInterface>
 
+
   data class Sealed(
     override val discriminatorName: String,
     override val subclasses: Set<TsDeclaration.TsInterface>,
   ) : TsPolymorphism
 
+
+  /** Note: [Open] is not implemented correctly */
   data class Open(
     override val discriminatorName: String,
     override val subclasses: Set<TsDeclaration.TsInterface>,
   ) : TsPolymorphism
-
-//  object None : TsPolymorphism {
-//    override val discriminatorName: Nothing = error("not implemented")
-//    override val subclasses: Nothing = error("not implemented")
-//  }
 }