Generate typescript definitions from content model

WORKSPACE

@@ -46,6 +46,7 @@ maven_install(
         "com.fasterxml.jackson.core:jackson-databind:2.10.0",
         "com.fasterxml.jackson.module:jackson-module-afterburner:2.10.0",
         "com.jayway.jsonpath:json-path:2.4.0",
+        "cz.habarta.typescript-generator:typescript-generator-core:2.26.723",
         "io.confluent:kafka-avro-serializer:5.5.1",
         "io.confluent:kafka-schema-registry-client:5.5.1",
         "io.confluent:kafka-schema-registry:5.5.1",

backend/lib/mapping/BUILD

@@ -1,4 +1,4 @@
-load("@rules_java//java:defs.bzl", "java_library")
+load("@rules_java//java:defs.bzl", "java_binary", "java_library")
 load("//tools/build:junit5.bzl", "junit5")
 
 lib_deps = [
@@ -19,6 +19,16 @@ java_library(
     deps = lib_deps,
 )
 
+java_binary(
+    name = "ts-generator",
+    srcs = glob(["src/ts-generator/**/*.java"]),
+    main_class = "co.airy.ts_generator.Main",
+    deps = [
+        ":mapping",
+        "@maven//:cz_habarta_typescript_generator_typescript_generator_core",
+    ],
+)
+
 [
     junit5(
         file = file,

backend/lib/mapping/README.md

@@ -0,0 +1,24 @@
+# Mapping library
+
+This library is responsible for mapping source ingestion message content strings to a payload structure
+that can be sent via network APIs.
+
+## Motivation
+
+We have learned that the safest way of handling ingestion message data from `n` sources with up to `m` 
+content schemata each is to keep the data "as is" and map the content to a usable schema dynamically.
+
+This gives us the ability to address mapping bugs by fixing code (cheap) rather than fixing
+streaming data (expensive).
+
+## Typescript definitions
+
+To allow web clients an easy way of mapping this payload structure, we provide automatically generated Typescript
+definitions using [this Typescript generator](https://github.com/vojtechhabarta/typescript-generator).
+
+The following command puts the generated definitions in `frontend/components/src/content.ts` and has to be run
+after every change to the content model in `backend/lib/mapping/src/main/java/co/airy/mapping/model/`:
+
+```shell script
+bazel run //backend/lib/mapping:ts-generator
+```

backend/lib/mapping/src/main/java/co/airy/mapping/model/Content.java

@@ -4,8 +4,8 @@
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
 
 @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type")
-@JsonSubTypes(
+@JsonSubTypes({
         @JsonSubTypes.Type(value = Text.class, name = "text")
-)
+})
 public abstract class Content {
 }

backend/lib/mapping/src/ts-generator/java/co/airy/ts_generator/Main.java

@@ -0,0 +1,35 @@
+package co.airy.ts_generator;
+
+import cz.habarta.typescript.generator.Input;
+import cz.habarta.typescript.generator.JsonLibrary;
+import cz.habarta.typescript.generator.Output;
+import cz.habarta.typescript.generator.Settings;
+import cz.habarta.typescript.generator.TypeScriptFileType;
+import cz.habarta.typescript.generator.TypeScriptGenerator;
+import cz.habarta.typescript.generator.TypeScriptOutputKind;
+
+import java.io.File;
+import java.util.List;
+
+public class Main {
+    public static void main(String[] args) {
+        final Settings settings = new Settings();
+
+        settings.outputKind = TypeScriptOutputKind.module; // Needed to generate `export` statements
+        settings.outputFileType = TypeScriptFileType.implementationFile;
+        settings.jsonLibrary = JsonLibrary.jackson2;
+        settings.setExcludeFilter(List.of("java.io.Serializable"), List.of("**.**Builder"));
+
+        final TypeScriptGenerator generator = new TypeScriptGenerator(settings);
+
+        final Input.Parameters parameters = new Input.Parameters();
+
+        parameters.debug = false;
+        parameters.classNamePatterns = List.of("co.airy.mapping.model.**");
+
+        final File output = new File(System.getenv().get("BUILD_WORKSPACE_DIRECTORY") + "/frontend/components/src/content.ts");
+        settings.validateFileName(output);
+
+        generator.generateTypeScript(Input.from(parameters), Output.to(output));
+    }
+}

docs/docs/api/http.md

@@ -214,7 +214,9 @@ This is a [paginated](#pagination) endpoint.
   "last_message": {
     id: "{UUID}",
     content: {
-      text: "{String}"
+      text: "{String}",
+      type: "text"
+      // Determines the schema of the content 
     },
     // typed source message model
     state: "{String}",
@@ -318,7 +320,9 @@ This is a [paginated](#pagination) endpoint and messages are sorted from oldest
     {
       id: "{UUID}",
       content: {
-        text: "{String}"
+        text: "{String}",
+        type: "text"
+        // Determines the schema of the content
       },
       // typed source message model
       state: "{String}",
@@ -361,7 +365,9 @@ Sends a message to a conversation and returns a payload.
 {
   id: "{UUID}",
   content: {
-    text: "{String}"
+    text: "{String}",
+    type: "text"
+    // Determines the schema of the content
   },
   // typed source message model
   state: "{String}",

docs/docs/api/websocket.md

@@ -31,7 +31,9 @@ Incoming payloads notify connected clients that a message was created or updated
   message: {
     id: "{UUID}",
     content: {
-      text: "{String}"
+      text: "{String}",
+      type: "text"
+      // Determines the schema of the content
     },
     // typed source message model
     state: "{String}",

docs/docs/glossary.md

@@ -91,7 +91,8 @@ Identifies the participant that sent the message. Interpretation is based on the
 
 - `channelId` uuid
 
-- `content` string
+- `content` string  Immutable string version of the ingested content. APIs dynamically parse and map it to a schema
+                    using the mapping library. [Read more]()
 
 - `offset` long sequence number of message within a conversation
 

frontend/components/src/content.ts

@@ -0,0 +1,14 @@
+/* tslint:disable */
+/* eslint-disable */
+// Generated using typescript-generator version 2.26.723 on 2020-11-06 17:30:31.
+
+export interface Content {
+  type: "text";
+}
+
+export interface Text extends Content {
+  type: "text";
+  text: string;
+}
+
+export type ContentUnion = Text;

frontend/components/src/index.ts

@@ -3,3 +3,6 @@ export * from "./components/cta";
 export * from "./components/general";
 export * from "./components/inputs";
 export * from "./components/loaders";
+
+// export the content model
+export * from "./content";