Merge pull request #158 from eyelidlessness/refactor/typescript-build

Convert remainder of library to TypeScript, Vite build, include type checking in CI

.eslintrc.json

@@ -21,7 +21,7 @@
         "ecmaVersion": 2020
     },
     "settings": {
-        "import/extensions": [".js", ".ts"],
+        "import/extensions": [".ts"],
         "import/parsers": {
             "@typescript-eslint/parser": [".ts"]
         },
@@ -46,18 +46,25 @@
         "import/no-extraneous-dependencies": [
             "error",
             {
-                "devDependencies": ["vite.config.ts", "test/**/*.ts"],
+                "devDependencies": [
+                    "app.js",
+                    "app.ts",
+                    "vite.config.ts",
+                    "src/api.ts",
+                    "test/**/*.ts"
+                ],
                 "optionalDependencies": false,
                 "peerDependencies": false
             }
         ],
         "import/no-unresolved": [
             "error",
             {
-                "ignore": ["vitest/config"]
+                "ignore": ["vitest/config", ".*?raw"]
             }
         ],
         "import/order": "warn",
+        "import/prefer-default-export": "off",
         "no-param-reassign": "warn",
         "no-restricted-syntax": [
             "warn",
@@ -85,17 +92,16 @@
             }
         },
 
-        {
-            "files": ["./**/*.js"],
-            "rules": {
-                "@typescript-eslint/no-var-requires": "off"
-            }
-        },
-
         {
             "files": ["./**/*.ts"],
             "rules": {
-                "@typescript-eslint/no-unused-expressions": "off",
+                "no-useless-constructor": "off",
+                "@typescript-eslint/no-useless-constructor": "error",
+                "no-unused-vars": "off",
+                "@typescript-eslint/no-unused-vars": "error",
+                "no-empty-function": "off",
+                "@typescript-eslint/no-empty-function": "error",
+
                 "import/extensions": [
                     "error",
                     "ignorePackages",
@@ -109,6 +115,20 @@
             }
         },
 
+        {
+            "files": ["./test/**/*.ts"],
+            "rules": {
+                "@typescript-eslint/no-unused-expressions": "off"
+            }
+        },
+
+        {
+            "files": ["./**/*.d.ts"],
+            "rules": {
+                "no-unused-vars": "off"
+            }
+        },
+
         {
             "files": ["./test/**/*.ts"],
             "plugins": ["vitest"],

.github/workflows/npmjs.yml

@@ -28,7 +28,6 @@ jobs:
             - if: steps.cache.outputs.cache-hit != 'true'
               run: npm ci
             - run: npm test
-            - run: npm run build-docs
             - if: github.event_name == 'release' && github.event.action == 'published' && matrix.node == '16'
               run: npm publish
               env:

.gitignore

@@ -10,3 +10,4 @@ Thumbs.db
 .nyc_output
 test-coverage
 coverage.shield.badge.md
+dist

.prettierignore

@@ -2,5 +2,6 @@
 
 .nyc*
 */node_modules/*
+dist/*
 docs/*
 test-coverage/*

README.md

@@ -5,8 +5,6 @@
 
 NodeJS library that transforms OpenRosa/ODK XForms into a format the Enketo understands. It works both as a library module, as well as a standalone app.
 
-[Technical Documentation](https://enketo.github.io/enketo-transformer/)
-
 ### Prerequisites
 
 1. Volta (optional, but recommended)
@@ -20,30 +18,32 @@ npm install enketo-transformer --save
 
 ### Use as module
 
-```js
-const transformer = require('enketo-transformer');
+```ts
+import { transform } from 'enketo-transformer';
+
 const xform = fs.readFileSync('path/to/xform.xml');
+const result = await transform({
+    // required string of XForm
+    xform: xform,
+
+    // optional string, to add theme if no theme is defined in the XForm
+    theme: 'sometheme',
+
+    // optional map, to replace jr://..../myfile.png URLs
+    media: {
+        'myfile.png': '/path/to/somefile.png',
+        'myfile.mp3': '/another/path/to/2.mp3',
+    },
+
+    // optional ability to disable markdown rendering (default is true)
+    markdown: false,
+
+    // optional preprocess function that transforms the XForm (as libXMLJs object) to
+    // e.g. correct incompatible XForm syntax before Enketo's transformation takes place
+    preprocess: (doc) => doc,
+});
 
-transformer
-    .transform({
-        // required string of XForm
-        xform: xform,
-        // optional string, to add theme if no theme is defined in the XForm
-        theme: 'sometheme',
-        // optional map, to replace jr://..../myfile.png URLs
-        media: {
-            'myfile.png': '/path/to/somefile.png',
-            'myfile.mp3': '/another/path/to/2.mp3',
-        },
-        // optional ability to disable markdown rendering (default is true)
-        markdown: false,
-        // optional preprocess function that transforms the XForm (as libXMLJs object) to
-        // e.g. correct incompatible XForm syntax before Enketo's transformation takes place
-        preprocess: (doc) => doc,
-    })
-    .then(function (result) {
-        // do something with result
-    });
+// ... do something with result
 ```
 
 ### Install as app (web API)
@@ -129,7 +129,6 @@ Releases are done each time a dependent tool needs an `enketo-transformer` chang
     - Run `npm audit fix --production` to apply most important fixes
 1. Run `npm i`
 1. Run `npm test`
-1. Run `npm run build-docs`
 1. Merge PR with all changes
 1. Create GitHub release
 1. Tag and publish the release

app.js

@@ -1,22 +1,63 @@
-const express = require('express');
+// @ts-check
 
-const app = express();
-const bodyParser = require('body-parser');
-const config = require('./config/config.json');
+import { createServer } from 'vite';
+import { VitePluginNode } from 'vite-plugin-node';
+import {
+    config,
+    external,
+    resolvePath,
+    rootDir,
+} from './config/build.shared.js';
 
-for (const item in config) {
-    app.set(item, config[item]);
-}
+const appPath = resolvePath('./app.ts');
 
-app.use(bodyParser.json());
-app.use(
-    bodyParser.urlencoded({
-        extended: true,
-    })
-);
+const init = async () => {
+    /** @type {import('vite').UserConfig} */
+    const baseOptions = {
+        mode: 'development',
+        build: {
+            rollupOptions: {
+                external,
+            },
+        },
+        optimizeDeps: {
+            disabled: true,
+        },
+        root: rootDir,
+        ssr: {
+            target: 'node',
+        },
+    };
 
-require('./src/api')(app);
+    const servers = await Promise.all([
+        createServer({
+            ...baseOptions,
+            configFile: false,
+            plugins: VitePluginNode({
+                adapter: 'express',
+                appPath,
+                exportName: 'app',
+                tsCompiler: 'esbuild',
+            }),
+            server: {
+                port: config.port,
+            },
+        }),
+        createServer({
+            ...baseOptions,
+            configFile: false,
+            publicDir: resolvePath('./test/forms'),
+            server: {
+                port: 8081,
+            },
+        }),
+    ]);
 
-app.listen(app.get('port'), () => {
-    console.warn(`enketo-transformer running on port ${app.get('port')}!`);
-});
+    await Promise.all(servers.map((server) => server.listen()));
+
+    servers.forEach((server) => {
+        server.printUrls();
+    });
+};
+
+init();

app.ts

@@ -0,0 +1,21 @@
+import bodyParser from 'body-parser';
+import express from 'express';
+import { config } from './config/build.shared';
+import { api } from './src/api';
+
+const app = express();
+
+Object.entries(config).forEach(([key, value]) => {
+    app.set(key, value);
+});
+
+app.use(bodyParser.json());
+app.use(
+    bodyParser.urlencoded({
+        extended: true,
+    })
+);
+
+api(app);
+
+export { app };

config/build.shared.d.ts

@@ -0,0 +1,7 @@
+export {
+    config,
+    external,
+    resolvePath,
+    readFile,
+    rootDir,
+} from './build.shared';

config/build.shared.js

@@ -0,0 +1,42 @@
+// @ts-check
+
+import fs from 'fs';
+import { createRequire } from 'module';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const require = createRequire(import.meta.url);
+
+export const config = require('./config.json');
+
+export const external = [
+    'body-parser',
+    'crypto',
+    'css.escape',
+    'express',
+    'fs',
+    'language-tags',
+    'libxslt',
+    'node1-libxmljsmt-myh',
+    'path',
+    'string-direction',
+    'undici',
+    'url',
+    'vite-node',
+    'vite',
+];
+
+export const rootDir = dirname(fileURLToPath(import.meta.url)).replace(
+    /(\/enketo-transformer)(\/.*$)/,
+    '$1'
+);
+
+/**
+ * @param {string} path
+ */
+export const resolvePath = (path) => resolve(rootDir, path);
+
+/**
+ * @param {string} path
+ */
+export const readFile = (path) => fs.readFileSync(resolvePath(path), 'utf-8');