setting up typescript integration - depends on a new release of types…

…cript generator
yupiik · Aug 19, 2022 · 11f347a · 11f347a
1 parent a46fec8
commit 11f347a
Show file tree

Hide file tree

Showing 253 changed files with 1,198 additions and 1 deletion.
diff --git a/bundlebee-java/pom.xml b/bundlebee-java/pom.xml
@@ -29,6 +29,10 @@
   <artifactId>bundlebee-java</artifactId>
   <name>Kubernetes Java Descriptors :: Bundlebee</name>
 
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
+
   <dependencies>
     <!-- provided because we let the consumer import the API/impl he wants when needed -->
     <dependency>

diff --git a/documentation/src/main/minisite/content/getting-started.adoc b/documentation/src/main/minisite/content/getting-started.adoc
@@ -279,3 +279,9 @@ To ensure you target the right descriptor for your cluster, it is recommended to
 Typically, if you target Kubernetes 1.24.3, you will use the module `kubernetes-java-1.24.3`.
 
 You can check on the xref:kubernetes-java-bindings.adoc[binding list] page the one you need.
+
+== NPM support
+
+We provide an experimental support for typescript applications/scripts.
+It is mainly about providing the model as `.d.ts`.
+For more information, read about xref:npm.adoc[NPM bundles] documentation.
diff --git a/documentation/src/main/minisite/content/npm.adoc b/documentation/src/main/minisite/content/npm.adoc
@@ -0,0 +1,125 @@
+= NPM support
+
+IMPORTANT: this support is experimental for now, if validated we would envision to release the bundles on npm registry and therefore this documentation would be outdated.
+
+== Features
+
+From the build, we generate `.d.ts` enabling you to get typescript build validation and completion in your preferred IDE to write script.
+
+== How to use
+
+For now, the declaration files are only pushed to Maven central repository and not yet to npm registry.
+Therefore to set it up, you must download the files from your build.
+Here is how to do it:
+
+[source,java]
+.package.json
+----
+{
+    "devDependencies": { // <1>
+        "typescript": "^4.7.4",
+        "ts-node": "^10.9.1"
+    },
+    "scripts": { // <2>
+        "postinstall": "node build/kubernetes-descriptors.install.mjs"
+    }
+}
+----
+<.> We import typescript to ensure we have the syntax validation and the completion in the editors,
+<.> We execute after the installation - could be before - a script which will download and setup the `kubernetes-descriptors` dependency.
+
+`kubernetes-descriptors.install.mjs` will simply download the `d.ts` and `package.json` file in the right version from central:
+
+[source,js]
+.kubernetes-descriptors.install.mjs
+----
+import { copyFileSync, mkdirSync } from 'fs';
+
+// VARIABLES
+const KUBERNETES_VERSION = process.env.KUBERNETES_VERSION || '1.24.3';
+const KUBERNETES_DESCRIPTOR_VERSION = process.env.KUBERNETES_DESCRIPTOR_VERSION || '1.0-SNAPSHOT';
+const REPOSITORY = process.env.MAVEN_CENTRAL || 'https://repo.maven.apache.org/maven2';
+const TARGET = process.env.OUTPUT || 'node_modules/kubernetes-descriptors';
+
+// START OF THE SCRIPT
+const baseUrl = `${REPOSITORY}/io/yupiik/kubernetes/kubernetes-java-${KUBERNETES_VERSION}/${KUBERNETES_DESCRIPTOR_VERSION}/kubernetes-java-${KUBERNETES_VERSION}-${KUBERNETES_DESCRIPTOR_VERSION}-`;
+const declarationTs = `${baseUrl}d.ts`;
+const packageJson = `${baseUrl}package.json`;
+
+async function download(url, target) {
+    const response = await fetch(url);
+    if (response.status != 200) {
+        throw new Error(`Invalid download: HTTP ${response.status}`);
+    }
+    const out = fs.createWriteStream(target);
+    await new Promise((resolve, reject) => {
+        res.body.pipe(out);
+        res.body.on('error', reject);
+        fileStream.on('finish', resolve);
+    });
+}
+
+mkdirSync(TARGET, { recursive: true });
+
+const dTsName = declarationTs.substring(declarationTs.lastIndexOf('/') + 1);
+download(declarationTs, `${TARGET}/${dTsName.substring(0, dTsName.length - KUBERNETES_DESCRIPTOR_VERSION.length - '--d.ts'.length)}.d.ts`);
+download(packageJson, `${TARGET}/package.json`);
+----
+
+Now just execute `npm i` and you will be set up.
+
+To start generating kubernetes descriptors, just create a script `index.ts` you will execute with `npm run generate`.
+To do it we first add this script in our `package.json`:
+
+[source,json]
+.package.json
+----
+{
+    "scripts": {
+        "postinstall": "node build/kubernetes-descriptors.install.mjs",
+        "generate": "npx ts-node index.ts" <1>
+    },
+    // ... as before
+}
+----
+<.> The new command we add to generate the descriptors.
+
+And the script itself will import the model to modelize the descriptors and will serialize the model as JSON:
+
+[source,js]
+.index.ts
+----
+import { writeFileSync, mkdirSync } from 'fs';
+import { io } from 'kubernetes-descriptors'; // <1>
+import v1 = io.yupiik.kubernetes.bindings.v1_9_8.v1; // <2>
+
+const deployment = <v1.Deployment>{ // <3>
+    apiVersion: 'v1',
+    kind: 'Deployment',
+    spec: {
+        template: {
+            metadata: {
+                name: 'my-deployment',
+            },
+            spec: {
+                containers: [
+                    {
+                        name: 'hello-world',
+                        image: 'hello-world',
+                    },
+                ],
+            },
+        },
+    },
+};
+
+// <4>
+const target = 'dist/';
+const bundlebeeDescriptors = `${target}/bundlebee/kubernetes`;
+mkdirSync(bundlebeeDescriptors, { recursive: true });
+writeFileSync(`${bundlebeeDescriptors}/deployment.json`, JSON.stringify(deployment, null, 2));
+----
+<.> Import the root namespace of the descriptors,
+<.> Alias (to be shorter) the actual namespace we target (the version in general),
+<.> Create a model matching the expected type (here `Deployment`), this is what gives us completion and validation,
+<.> Just export the model writing the model (`deployment`) as JSON (thanks `JSON.stringify`) on the filesystem.
diff --git a/generator/src/main/java/io/yupiik/kubernetes/generator/GenerateBindings.java b/generator/src/main/java/io/yupiik/kubernetes/generator/GenerateBindings.java
@@ -182,6 +182,10 @@ private String generate(final JsonReaderFactory readerFactory, final Path path,
                 "\n" +
                 "  <artifactId>" + artifactId + "</artifactId>\n" +
                 "  <name>Kubernetes Java Descriptors :: Versions :: " + k8sApiVersion + "</name>\n" +
+                "\n" +
+                "  <properties>\n" +
+                "    <typescript-generator.skip>false</typescript-generator.skip>\n" +
+                "  </properties>\n" +
                 "</project>\n" +
                 "\n");
 

diff --git a/pom.xml b/pom.xml
@@ -34,6 +34,8 @@
 
     <yupiik-uship.version>1.0.8</yupiik-uship.version>
 
+    <typescript-generator.skip>true</typescript-generator.skip>
+
     <bundlebee.kubernetes.schemas.url>https://github.com/yupiik/bundlebee/archive/refs/heads/gh-pages.zip</bundlebee.kubernetes.schemas.url>
     <bundlebee.kubernetes.schemas.base>generated/kubernetes/jsonschema</bundlebee.kubernetes.schemas.base>
     <bundlebee.schema.extension>.jsonschema.raw.json</bundlebee.schema.extension>
@@ -176,6 +178,71 @@
           <autoReleaseAfterClose>true</autoReleaseAfterClose>
         </configuration>
       </plugin>
+      <plugin>
+        <groupId>cz.habarta.typescript-generator</groupId>
+        <artifactId>typescript-generator-maven-plugin</artifactId>
+        <version>2.36-SNAPSHOT</version>
+        <executions>
+          <execution>
+            <id>generate</id>
+            <phase>process-classes</phase>
+            <goals>
+              <goal>generate</goal>
+            </goals>
+          </execution>
+        </executions>
+        <configuration>
+          <skip>${typescript-generator.skip}</skip>
+          <outputKind>module</outputKind>
+          <outputFileType>declarationFile</outputFileType>
+          <outputFile>${project.build.directory}/typescript/${project.artifactId}.d.ts</outputFile>
+          <jsonLibrary>jsonb</jsonLibrary>
+          <mapPackagesToNamespaces>true</mapPackagesToNamespaces>
+          <sortTypeDeclarations>true</sortTypeDeclarations>
+          <generateNpmPackageJson>true</generateNpmPackageJson>
+          <npmName>@yupiik/${project.artifactId}</npmName>
+          <stringQuotes>singleQuotes</stringQuotes>
+          <classPatterns>
+            <classPattern>io.yupiik.kubernetes.bindings.**</classPattern>
+          </classPatterns>
+          <excludeClassPatterns>
+            <excludeClassPattern>**.Exportable</excludeClassPattern>
+            <excludeClassPattern>**.JsonStrings</excludeClassPattern>
+            <excludeClassPattern>**.Validable</excludeClassPattern>
+            <excludeClassPattern>**.ValidationException</excludeClassPattern>
+            <excludeClassPattern>**.ValidationException$ValidationError</excludeClassPattern>
+          </excludeClassPatterns>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>build-helper-maven-plugin</artifactId>
+        <version>3.3.0</version>
+        <executions>
+          <execution>
+            <id>attach-artifacts</id>
+            <phase>package</phase>
+            <goals>
+              <goal>attach-artifact</goal>
+            </goals>
+            <configuration>
+              <skipAttach>${typescript-generator.skip}</skipAttach>
+              <artifacts>
+                <artifact>
+                  <file>${project.build.directory}/typescript/${project.artifactId}.d.ts</file>
+                  <type>ts</type>
+                  <classifier>d</classifier>
+                </artifact>
+                <artifact>
+                  <file>${project.build.directory}/typescript/package.json</file>
+                  <type>json</type>
+                  <classifier>package</classifier>
+                </artifact>
+              </artifacts>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
       <plugin><!--  mvn ossindex:audit -->
         <groupId>org.sonatype.ossindex.maven</groupId>
         <artifactId>ossindex-maven-plugin</artifactId>

diff --git a/versions/kubernetes-java-1.10.0/pom.xml b/versions/kubernetes-java-1.10.0/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.0</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.0</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.1/pom.xml b/versions/kubernetes-java-1.10.1/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.1</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.1</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.10/pom.xml b/versions/kubernetes-java-1.10.10/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.10</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.10</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.11/pom.xml b/versions/kubernetes-java-1.10.11/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.11</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.11</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.12/pom.xml b/versions/kubernetes-java-1.10.12/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.12</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.12</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.13/pom.xml b/versions/kubernetes-java-1.10.13/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.13</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.13</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.2/pom.xml b/versions/kubernetes-java-1.10.2/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.2</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.2</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.3/pom.xml b/versions/kubernetes-java-1.10.3/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.3</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.3</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.4/pom.xml b/versions/kubernetes-java-1.10.4/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.4</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.4</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.5/pom.xml b/versions/kubernetes-java-1.10.5/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.5</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.5</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.6/pom.xml b/versions/kubernetes-java-1.10.6/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.6</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.6</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.7/pom.xml b/versions/kubernetes-java-1.10.7/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.7</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.7</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.8/pom.xml b/versions/kubernetes-java-1.10.8/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.8</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.8</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.10.9/pom.xml b/versions/kubernetes-java-1.10.9/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.10.9</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.10.9</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.11.0/pom.xml b/versions/kubernetes-java-1.11.0/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.11.0</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.11.0</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>
 
diff --git a/versions/kubernetes-java-1.11.1/pom.xml b/versions/kubernetes-java-1.11.1/pom.xml
@@ -28,5 +28,9 @@
 
   <artifactId>kubernetes-java-1.11.1</artifactId>
   <name>Kubernetes Java Descriptors :: Versions :: 1.11.1</name>
+
+  <properties>
+    <typescript-generator.skip>false</typescript-generator.skip>
+  </properties>
 </project>