Migrate codebase to Typescript

.eslintignore

@@ -0,0 +1,10 @@
+node_modules
+coverage
+.nyc_output
+
+# Compiled output for packages already converted to TypeScript
+packages/*/**/*.js
+packages/*/**/*.d.ts
+!packages/*/test/**
+!packages/preset-qpf/**/*.js
+!packages/server/**/*.js

.eslintrc

@@ -197,6 +197,83 @@
       rules: {
         "import/no-extraneous-dependencies": "off"
       }
+    },
+    {
+      // TypeScript source files
+      files: [ "packages/**/*.ts" ],
+      parser: "@typescript-eslint/parser",
+      extends: [ "plugin:@typescript-eslint/recommended-requiring-type-checking" ],
+      parserOptions: {
+        ecmaVersion: 9,
+        sourceType: "module",
+        project: "./tsconfig.json"
+      },
+      plugins: [ "@typescript-eslint" ],
+      rules: {
+        "no-unused-vars": "off",
+        "@typescript-eslint/no-unused-vars": [ 2, { args: "none" } ],
+        // The TS compiler already catches undefined references, and this rule
+        // otherwise misfires on TS-only constructs (interfaces, type imports).
+        "no-undef": "off",
+        // Misfires on TS function-overload signatures (multiple declarations
+        // for one implementation) — the TS compiler already validates those.
+        "no-redeclare": "off",
+        // Third-party type names (e.g. rdf-js's Quad_Graph) aren't ours to rename.
+        "camelcase": "off",
+        // Comunica's own eslint config disables these same three as "TODO: check
+        // if these can be enabled" — any flowing through further calls/assignments
+        // is too common a real pattern here to enforce yet.
+        "@typescript-eslint/no-unsafe-assignment": "off",
+        "@typescript-eslint/no-unsafe-argument": "off",
+        "@typescript-eslint/no-unsafe-return": "off",
+        // This codebase uses `let` pervasively as a long-standing style choice;
+        // enforcing const-where-possible would touch nearly every converted file.
+        "prefer-const": "off",
+        // 'text ' + someNumber is safe and pervasive in this codebase's string-building
+        // style; keep the rule's real catches (undefined, objects, Terms) active.
+        "@typescript-eslint/restrict-plus-operands": [ 2, { allowNumberAndString: true } ],
+        // Every hit is a destructured DataFactory method (quad/namedNode/literal) or
+        // lodash's _.noop — none use `this`, but the rule can't see that from the
+        // third-party type declarations alone.
+        "@typescript-eslint/unbound-method": "off",
+        // no-floating-promises' own suggested fix for an intentionally-unawaited
+        // promise chain is prefixing it with `void`.
+        "no-void": [ 2, { allowAsStatement: true } ],
+        // `x as unknown as Y` opts out of type checking entirely for x. Files with
+        // an existing, individually-reviewed need for it are exempted below;
+        // this catches it showing up anywhere else. Prefer a real type, or
+        // String(x)/Number(x) if this is really just coercion.
+        "no-restricted-syntax": [ 2, {
+          selector: "TSAsExpression > TSAsExpression[typeAnnotation.type='TSUnknownKeyword']",
+          message: "as unknown as X bypasses type checking. Prefer a real type; if unavoidable, add this file to the no-restricted-syntax exemption list in .eslintrc."
+        } ]
+      }
+    },
+    {
+      // HdtDatasource's constructor swaps in an ExternalHdtDatasource instance in place
+      // of `this`; the two are sibling classes (not a subtype relationship), and each
+      // independently overrides several of Datasource's protected methods, which brands
+      // them as structurally incompatible for TS's purposes even though they're
+      // interchangeable at runtime. Resolving this for real means either widening those
+      // protected overrides to public across both classes, or replacing the pattern with
+      // a factory function — both bigger changes than a type-only cleanup; see the
+      // commit history for the investigation.
+      files: [
+        "packages/datasource-hdt/lib/datasources/HdtDatasource.ts"
+      ],
+      rules: {
+        "no-restricted-syntax": "off"
+      }
+    },
+    {
+      // Needs `as unknown as X` to reach n3.Parser's internals,
+      // since @types/n3 has no typing for them.
+      files: [
+        "packages/core/lib/N3ParserExtended.ts"
+      ],
+      rules: {
+        "no-restricted-syntax": "off"
+      }
     }
   ]
 }

.github/workflows/ci.yml

@@ -40,6 +40,8 @@ jobs:
           key: ${{ runner.os }}-test-modules-${{ hashFiles('**/yarn.lock') }}
       - name: Install dependencies
         run: yarn install
+      - name: Build TypeScript
+        run: yarn run build
       - name: Run tests
         run: yarn run test-ci
       - name: Submit coverage results

.gitignore

@@ -13,4 +13,14 @@ config/*.json
 
 # Ignore dev environment files
 .idea
-.devcontainer
+.devcontainer
+
+# Compiled output for packages already converted to TypeScript
+packages/*/**/*.js
+packages/*/**/*.js.map
+packages/*/**/*.d.ts
+!packages/*/test/**
+!packages/preset-qpf/**/*.js
+!packages/preset-qpf/**/*.js.map
+!packages/server/**/*.js
+!packages/server/**/*.js.map

package.json

@@ -5,21 +5,33 @@
     "packages/*"
   ],
   "engines": {
-    "node": ">=10.0"
+    "node": ">=20.0"
   },
   "devDependencies": {
+    "@types/lodash": "^4.17.24",
+    "@types/lru-cache": "^5.1.1",
+    "@types/mime": "^2.0.3",
+    "@types/node": "^22.20.1",
+    "@types/parse-cache-control": "^1.0.4",
+    "@types/q": "^1.5.8",
+    "@types/request": "^2.48.13",
+    "@typescript-eslint/eslint-plugin": "^5.62.0",
+    "@typescript-eslint/parser": "^5.62.0",
     "chai": "^4.0.0",
     "coveralls": "^3.0.9",
     "eslint": "^7.0.0",
     "eslint-plugin-import": "^2.22.0",
-    "lerna": "9.0.7",
+    "lerna": "^4.0.0",
     "manual-git-changelog": "^1.0.1",
     "mocha": "^8.0.0",
+    "node-gyp": "^11.0.0",
     "nyc": "^15.0.0",
     "pre-commit": "^1.1.3",
+    "rdf-object": "^1.14.0",
     "sinon": "^1.17.4",
     "sinon-chai": "^2.14.0",
-    "supertest": "^6.0.0"
+    "supertest": "^6.0.0",
+    "typescript": "^5.9.3"
   },
   "pre-commit": [
     "lint",
@@ -31,12 +43,14 @@
     "mocha": "mocha \"packages/*/test/**/*-test.js\" --recursive --require ./test/test-setup --timeout 500",
     "test": "nyc npm run mocha",
     "test-ci": "nyc --reporter=lcov npm run mocha",
-    "lint": "eslint packages/*/bin/* packages/*/lib packages/*/test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint packages/*/bin/* packages/*/lib packages/*/test --ext .js,.ts",
     "clean": "rm -rf ./node_modules && rm -rf ./packages/*/node_modules",
     "dedupe": "npx yarn-deduplicate yarn.lock --scopes",
     "publish": "lerna publish",
     "publish-bare": "lerna exec -- npm publish --silent",
-    "postinstall": "lerna run prepare",
+    "postinstall": "lerna run prepare && yarn run build",
     "version": "manual-git-changelog onversion"
   }
 }

packages/core/index.ts

@@ -0,0 +1,13 @@
+/*! @license MIT ©2015-2016 Ruben Verborgh, Ghent University - imec */
+/* Exports of the components of this package */
+
+export * as controllers from './lib/controllers';
+export * as datasources from './lib/datasources';
+export * as routers from './lib/routers';
+export * as views from './lib/views';
+export { runCli, runCustom } from './lib/CliRunner';
+export { LinkedDataFragmentsServer } from './lib/LinkedDataFragmentsServer';
+export { LinkedDataFragmentsServerWorker } from './lib/LinkedDataFragmentsServerWorker';
+export { UrlData } from './lib/UrlData';
+export * as Util from './lib/Util';
+export * from './lib/types';

packages/core/lib/CliRunner.js → packages/core/lib/CliRunner.ts

@@ -1,17 +1,35 @@
 /*! @license MIT ©2013-2017 Ruben Verborgh and Ruben Taelman, Ghent University - imec */
 /* Logic for starting an LDF server with a given config from the command line. */
 
-let cluster = require('cluster'),
-    ComponentsManager = require('componentsjs').ComponentsManager;
+import type { Cluster } from 'cluster';
+import { ComponentsManager } from 'componentsjs';
+import type { ConfigRegistry, IComponentsManagerBuilderOptions } from 'componentsjs';
+
+// The 'cluster' module's own type declarations use an ESM-style default
+// export that doesn't line up with plain CJS `require()` under
+// esModuleInterop:false, so the value is pulled in untyped and annotated
+// explicitly against the real `Cluster` interface instead.
+const cluster: Cluster = require('cluster');
+import { LinkedDataFragmentsServerWorker } from './LinkedDataFragmentsServerWorker';
+import type { WorkerConfig } from './types';
+
+type Writable = { write(chunk: string): void };
 
 // Run function for starting the server from the command line
-function runCli(moduleRootPath) {
+export function runCli(moduleRootPath: string): void {
   let argv = process.argv.slice(2);
   runCustom(argv, process.stdin, process.stdout, process.stderr, null, { mainModulePath: moduleRootPath });
 }
 
 // Generic run function for starting the server from a given config
-function runCustom(args, stdin, stdout, stderr, componentConfigUri, properties) {
+export function runCustom(
+  args: string[],
+  stdin: NodeJS.ReadableStream,
+  stdout: Writable,
+  stderr: Writable,
+  componentConfigUri: string | null,
+  properties: Record<string, any>,
+): void {
   if (args.length < 1 || args.length > 4 || /^--?h(elp)?$/.test(args[0])) {
     stdout.write('usage: server config.json [port [workers [componentConfigUri]]]\n');
     return process.exit(1);
@@ -21,10 +39,10 @@ function runCustom(args, stdin, stdout, stderr, componentConfigUri, properties)
       cliWorkers = parseInt(args[2], 10),
       configUri = args[3] || componentConfigUri || 'urn:ldf-server:my';
 
-  ComponentsManager.build({
+  ComponentsManager.build<LinkedDataFragmentsServerWorker>({
     ...properties,
-    configLoader: (registry) => registry.register(args[0]),
-  })
+    configLoader: (registry: ConfigRegistry) => registry.register(args[0]),
+  } as IComponentsManagerBuilderOptions<LinkedDataFragmentsServerWorker>)
     .then((manager) => {
       return manager.instantiate(configUri)
         .then((worker) => {
@@ -33,19 +51,19 @@ function runCustom(args, stdin, stdout, stderr, componentConfigUri, properties)
           else
             worker.run(cliPort);
         })
-        .catch((e) => {
+        .catch((e: Error) => {
           stderr.write('Instantiation error:\n');
-          stderr.write(e.stack + '\n');
+          stderr.write((e.stack as string) + '\n');
           process.exit(1);
         });
     })
-    .catch((e) => {
+    .catch((e: Error) => {
       stderr.write('Component definition error:\n');
-      stderr.write(e.stack + '\n');
+      stderr.write((e.stack as string) + '\n');
       process.exit(1);
     });
 
-  function startClusterMaster(config) {
+  function startClusterMaster(config: WorkerConfig & { workers?: number }): void {
     let workers = cliWorkers || config.workers || 1;
 
     // Create workers
@@ -57,7 +75,7 @@ function runCustom(args, stdin, stdout, stderr, componentConfigUri, properties)
     cluster.on('listening', (worker) => {
       worker.once('exit', (code, signal) => {
         if (!worker.exitedAfterDisconnect) {
-          stdout.write('Worker ' + worker.process.pid + 'died with ' + (code || signal) + '. Starting new worker.\n');
+          stdout.write('Worker ' + (worker.process.pid as number) + 'died with ' + (code || signal) + '. Starting new worker.\n');
           cluster.fork();
         }
       });
@@ -75,7 +93,7 @@ function runCustom(args, stdin, stdout, stderr, componentConfigUri, properties)
       process.removeListener('SIGHUP', respawn);
 
       // Retrieve a list of old workers that will be replaced by new ones
-      let workers = Object.keys(cluster.workers).map((id) => { return cluster.workers[id]; });
+      let workers = Object.keys(cluster.workers!).map((id) => { return cluster.workers![id]!; });
       (function respawnNext() {
         // If there are still old workers, respawn a new one
         if (workers.length) {
@@ -86,17 +104,17 @@ function runCustom(args, stdin, stdout, stderr, componentConfigUri, properties)
             if (!worker)
               return newWorker.kill(), respawnNext(); // Dead workers are replaced automatically
             worker.once('exit', () => {
-              stdout.write('Worker ' + newWorker.process.pid + ' replaces killed worker ' + worker.process.pid + '.\n');
+              stdout.write('Worker ' + (newWorker.process.pid as number) + ' replaces killed worker ' + (worker.process.pid as number) + '.\n');
               respawnNext();
             });
             worker.kill();
             newWorker.removeListener('exit', abort);
           });
           // Abort the respawning process if creating a new worker fails
           newWorker.on('exit', abort);
-          function abort(code, signal) {
-            if (!newWorker.suicide) {
-              stdout.write('Respawning aborted because worker ' + newWorker.process.pid + ' died with ' +
+          function abort(code: number, signal: string) {
+            if (!newWorker.exitedAfterDisconnect) {
+              stdout.write('Respawning aborted because worker ' + (newWorker.process.pid as number) + ' died with ' +
                 (code || signal) + '.\n');
               process.addListener('SIGHUP', respawn);
               process.removeListener('SIGHUP', respawnPending);
@@ -115,4 +133,3 @@ function runCustom(args, stdin, stdout, stderr, componentConfigUri, properties)
   }
 }
 
-module.exports = { runCli: runCli, runCustom: runCustom };