[fei4960.4.examples] Migrate examples (#611)

## Summary:
This migrates the various test examples from Khan/render-gateway and adds the infrastructure to run them (i.e. `babel-watch`).

Issue: FEI-4960

## Test plan:
`yarn typecheck`
`yarn build`
`yarn build:types`
`yarn --cwd packages/wonder-stuff-render-environment-jsdom example jsdom-simple`
`yarn --cwd packages/wonder-stuff-render-server example simple`
`yarn --cwd packages/wonder-stuff-render-server example error`
`yarn --cwd packages/wonder-stuff-render-server example logging`

Author: somewhatabstract

Reviewers: somewhatabstract, jeresig

Required Reviewers:

Approved By: jeresig

Checks: ✅ codecov/project, ✅ Test (macos-latest, 16.x), ✅ CodeQL, ✅ Lint, typecheck, and coverage check (ubuntu-latest, 16.x), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ✅ gerald, ✅ Analyze (javascript), ⏭  dependabot

Pull Request URL: #611

.changeset/flat-pumas-unite.md

@@ -0,0 +1,2 @@
+---
+---

.codecov.yml

@@ -22,5 +22,6 @@ ignore:
   - "build-settings/*.js"
   - "utils/*.js"
   - "packages/**/dist/index.js"
-  - "packages/**/types.js"
-  - "packages/**/*.flowtest.js "
+  - "packages/**/types/**/*.ts"
+  - "packages/**/examples/**/*.ts"
+  - "packages/**/*.flowtest.js"

config/jest/test.config.js

@@ -32,6 +32,8 @@ module.exports = {
         "!packages/**/node_modules/",
         "!packages/**/.babelrc.js",
         "!packages/eslint-config-khan/**",
+        "!packages/**/examples/**/*.ts",
+        "!packages/**/types/**/*.ts",
     ],
     // Only output log messages on test failure. From:
     // https://github.com/facebook/jest/issues/4156#issuecomment-490764080

package.json

@@ -40,6 +40,7 @@
     "@typescript-eslint/eslint-plugin": "^5.57.0",
     "@typescript-eslint/parser": "^5.57.0",
     "babel-jest": "29.5.0",
+    "babel-watch": "^7.7.2",
     "eslint": "^8.37.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-import-resolver-typescript": "^3.5.4",

packages/wonder-stuff-core/tsconfig.json

@@ -4,5 +4,7 @@
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src",
-  }
+  },
+  "references": [
+  ]
 }

packages/wonder-stuff-i18n/tsconfig.json

@@ -4,5 +4,7 @@
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src",
-  }
+  },
+  "references": [
+  ]
 }

packages/wonder-stuff-render-environment-jsdom/examples/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+Each folder in this location must contain a file named `run.ts` that is
+responsible for executing the given example. To execute an example, you can
+run the following command from the root folder, where `<EXAMPLE>` is the name
+of the example folder.
+
+```shell
+yarn example <EXAMPLE>
+```

packages/wonder-stuff-render-environment-jsdom/examples/jsdom-simple/render.ts

@@ -0,0 +1,10 @@
+// @ts-expect-error This is what we want and I don't get why TS doesn't like it
+window["__jsdom_env_register"](() => {
+    // This is where we can return our result.
+    return Promise.resolve({
+        // @ts-expect-error We know that this does exist off window.
+        body: `You asked us to render ${window._API.url}`,
+        status: 200,
+        headers: {},
+    });
+});

packages/wonder-stuff-render-environment-jsdom/examples/jsdom-simple/run.ts

@@ -0,0 +1,50 @@
+/**
+ * This is a simple JSDOM-based server.
+ */
+
+/**
+ * NOTE: We import everything from index.js to ensure we're testing the public
+ * interface of our package.
+ */
+import type vm from "vm";
+import {runServer} from "@khanacademy/wonder-stuff-render-server";
+import type {
+    RenderAPI,
+    ICloseable,
+} from "@khanacademy/wonder-stuff-render-server";
+import * as JSDOM from "../../src/index";
+
+async function main() {
+    const config = new JSDOM.Configuration(
+        () => Promise.resolve(["http://localhost:8080/render.ts"]),
+        (url: string, renderAPI: RenderAPI) =>
+            new JSDOM.FileResourceLoader(__dirname),
+        (
+            url: string,
+            fileURLs: ReadonlyArray<string>,
+            renderAPI: RenderAPI,
+            vmContext: vm.Context,
+        ): Promise<ICloseable | null | undefined> => {
+            vmContext._renderAPI = renderAPI;
+            vmContext._API = {
+                url,
+                renderAPI,
+                fileURLs,
+            };
+            return Promise.resolve(null);
+        },
+    );
+    const renderEnvironment = new JSDOM.Environment(config);
+
+    runServer({
+        name: "DEV_LOCAL",
+        port: 8080,
+        host: "127.0.0.1",
+        renderEnvironment,
+    });
+}
+
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(`Error caught from main setup: ${err}`);
+});

packages/wonder-stuff-render-environment-jsdom/package.json

@@ -12,6 +12,7 @@
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
+        "example": "bash -c 'RUNNER=\"./examples/$0/run.ts\"; KA_LOG_LEVEL=silly NODE_ENV=development babel-watch --config-file ../../babel.config.js \"$RUNNER\" --extensions .ts'",
         "test": "bash -c 'yarn --silent --cwd \"../..\" test ${@:0} $($([[ ${@: -1} = -* ]] || [[ ${@: -1} = bash ]]) && echo $PWD)'"
     },
     "dependencies": {

packages/wonder-stuff-render-environment-jsdom/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "exclude": [
-    "dist"
+    "dist", "examples"
   ],
   "extends": "../tsconfig-shared.json",
   "compilerOptions": {
@@ -10,6 +10,6 @@
   "references": [
     {"path": "../wonder-stuff-core"},
     {"path": "../wonder-stuff-server"},
-    {"path": "../wonder-stuff-render-server"},
+    {"path": "../wonder-stuff-render-server"}
   ]
 }

packages/wonder-stuff-render-server/examples/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+Each folder in this location must contain a file named `run.ts` that is
+responsible for executing the given example. To execute an example, you can
+run the following command from the root folder, where `<EXAMPLE>` is the name
+of the example folder.
+
+```shell
+yarn example <EXAMPLE>
+```

packages/wonder-stuff-render-server/examples/error/run.ts

@@ -0,0 +1,29 @@
+/**
+ * This is a simple local server for testing what happens if rendering errors.
+ */
+
+/**
+ * NOTE: We import everything from index.js to ensure we're testing the public
+ * interface of this package.
+ */
+import {runServer} from "../../src/index";
+import type {RenderAPI, RenderResult} from "../../src/index";
+
+async function main() {
+    const renderEnvironment = {
+        render: (url: string, renderAPI: RenderAPI): Promise<RenderResult> =>
+            Promise.reject(new Error(`OH NO! We couldn't render ${url}`)),
+    };
+
+    runServer({
+        name: "DEV_LOCAL",
+        port: 8080,
+        host: "127.0.0.1",
+        renderEnvironment,
+    });
+}
+
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(`Error caught from main setup: ${err}`);
+});

packages/wonder-stuff-render-server/examples/logging/run.ts

@@ -0,0 +1,51 @@
+/**
+ * This is a simple local server for testing that logging works in a request
+ * context.
+ */
+
+/**
+ * NOTE: We import everything from index.js to ensure we're testing the public
+ * interface of this package.
+ */
+import {runServer} from "../../src/index";
+import type {RenderAPI, RenderResult} from "../../src/index";
+
+async function main() {
+    const renderEnvironment = {
+        render: (url: string, renderAPI: RenderAPI): Promise<RenderResult> => {
+            const traceSession = renderAPI.trace(
+                "LOGGING",
+                "Testing logging things",
+            );
+            try {
+                renderAPI.logger.silly("A silly log", {with: "metadata"});
+                renderAPI.logger.debug("A debug log", {with: "metadata"});
+                renderAPI.logger.info("An info log", {with: "metadata"});
+                renderAPI.logger.warn("A warning", {with: "metadata"});
+                renderAPI.logger.error("An error", {with: "metadata"});
+
+                return Promise.resolve({
+                    body: `You asked us to render ${url}`,
+                    status: 200,
+                    headers: {},
+                });
+            } finally {
+                traceSession.end({
+                    with: "metadata",
+                });
+            }
+        },
+    };
+
+    runServer({
+        name: "DEV_LOCAL",
+        port: 8080,
+        host: "127.0.0.1",
+        renderEnvironment,
+    });
+}
+
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(`Error caught from main setup: ${err}`);
+});

packages/wonder-stuff-render-server/examples/simple/run.ts

@@ -0,0 +1,33 @@
+/**
+ * This is a simple local server for testing this code works.
+ */
+
+/**
+ * NOTE: We import everything from index.js to ensure we're testing the public
+ * interface of this package.
+ */
+import {runServer} from "../../src/index";
+import type {RenderAPI, RenderResult} from "../../src/index";
+
+async function main() {
+    const renderEnvironment = {
+        render: (url: string, renderAPI: RenderAPI): Promise<RenderResult> =>
+            Promise.resolve({
+                body: `You asked us to render ${url}`,
+                status: 200,
+                headers: {},
+            }),
+    };
+
+    runServer({
+        name: "DEV_LOCAL",
+        port: 8080,
+        host: "127.0.0.1",
+        renderEnvironment,
+    });
+}
+
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(`Error caught from main setup: ${err}`);
+});

packages/wonder-stuff-render-server/package.json

@@ -12,6 +12,7 @@
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
+        "example": "bash -c 'RUNNER=\"./examples/$0/run.ts\"; KA_LOG_LEVEL=silly NODE_ENV=development babel-watch --config-file ../../babel.config.js \"$RUNNER\" --extensions .ts'",
         "test": "bash -c 'yarn --silent --cwd \"../..\" test ${@:0} $($([[ ${@: -1} = -* ]] || [[ ${@: -1} = bash ]]) && echo $PWD)'"
     },
     "dependencies": {

packages/wonder-stuff-render-server/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "exclude": [
-    "dist"
+    "dist", "examples"
   ],
   "extends": "../tsconfig-shared.json",
   "compilerOptions": {