Add tests for CKAN + various improvements

.changeset/honest-cows-sniff.md

@@ -0,0 +1,8 @@
+---
+"trifid-core": minor
+---
+
+Improve types in general.
+
+`trifid.start` now returns a `Promise<import('http').Server>` instead of `void`.
+This allows to wait for the server to be ready before doing anything else.

.eslintrc.json

@@ -5,6 +5,7 @@
   },
   "ignorePatterns": ["**/*.ts", "**/*.d.ts", "**/*.d.ts.map"],
   "rules": {
-    "space-before-function-paren": "off"
+    "space-before-function-paren": "off",
+    "indent": ["error", 2, { "SwitchCase": 1 }]
   }
 }

packages/core/.gitignore

@@ -4,4 +4,5 @@ node_modules
 npm-debug.log
 *.tgz
 *.d.ts
+!types/*.d.ts
 *.d.ts.map

packages/core/index.js

@@ -1,5 +1,6 @@
+// @ts-check
 import express from 'express'
-import pino from 'pino'
+import { pino } from 'pino'
 import cors from 'cors'
 import cookieParser from 'cookie-parser'
 
@@ -16,59 +17,20 @@ import templateEngine from './lib/templateEngine.js'
 /**
  * Create a new Trifid instance.
  *
- * @param {{
- *   extends?: string[];
- *   server?: {
- *     listener: {
- *       host?: string;
- *       port?: number | string;
- *     };
- *     logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent";
- *     express?: Record<string, any>;
- *   };
- *   globals?: Record<string, any>;
- *   template?: Record<string, any>;
- *   middlewares?: Record<string, {
- *     order?: number,
- *     module: string;
- *     paths?: string | string[];
- *     methods?: string | string[];
- *     hosts?: string | string[];
- *     config?: Record<string, any>;
- *   }>;
- * }}?} config Trifid configuration.
+ * @param {import('./types/index.js').TrifidConfigWithExtends?} config Trifid configuration.
  * @param {Record<string, {
  *   order?: number,
- *   module: (trifid: {logger: any; server: unknown; config: Record<string, any>}) => Promise<()> | ();
+ *   module: import('./types/index.d.ts').TrifidMiddleware,
  *   paths?: string | string[];
  *   methods?: string | string[];
  *   hosts?: string | string[];
  *   config?: Record<string, any>;
- * }?} additionalMiddlewares Add additional middlewares.
+ * }>?} additionalMiddlewares Add additional middlewares.
  * @returns {Promise<{
- *  start: () => void;
- *  server: unknown;
- *  config: {{
- *   server?: {
- *     listener: {
- *       host?: string;
- *       port?: number | string;
- *     };
- *     logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent";
- *     express?: Record<string, any>;
- *   };
- *   globals?: Record<string, any>;
- *   template?: Record<string, any>;
- *   middlewares?: Record<string, {
- *     order?: number,
- *     module: string;
- *     paths?: string | string[];
- *     methods?: string | string[];
- *     hosts?: string | string[];
- *     config?: Record<string, any>;
- *   }>;
- * }}
- * >}}
+ *  start: () => Promise<import('http').Server>;
+ *  server: import('express').Express;
+ *  config: import('./types/index.js').TrifidConfig
+ * }>} Trifid instance.
  */
 const trifid = async (config, additionalMiddlewares = {}) => {
   const fullConfig = await handler(config)
@@ -97,6 +59,7 @@ const trifid = async (config, additionalMiddlewares = {}) => {
   // dynamic server configuration
   const port = fullConfig?.server?.listener?.port || defaultPort
   const host = fullConfig?.server?.listener?.host || defaultHost
+  const portNumber = typeof port === 'string' ? parseInt(port, 10) : port
 
   // logger configuration
   const logLevel = fullConfig?.server?.logLevel || defaultLogLevel
@@ -125,9 +88,16 @@ const trifid = async (config, additionalMiddlewares = {}) => {
     templateEngineInstance,
   )
 
-  const start = () => {
-    server.listen(port, host, () => {
-      logger.info(`Trifid instance listening on: http://${host}:${port}/`)
+  const start = async () => {
+    return await new Promise((resolve, reject) => {
+      const listener = server.listen(portNumber, host, (err) => {
+        if (err) {
+          return reject(err)
+        }
+
+        logger.info(`Trifid instance listening on: http://${host}:${portNumber}/`)
+        resolve(listener)
+      })
     })
   }
 

packages/core/lib/config/default.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 // some default configuration
 
 export const maxDepth = 50

packages/core/lib/config/handler.js

@@ -1,3 +1,4 @@
+// @ts-check
 import fs from 'fs/promises'
 import { dirname } from 'path'
 import merge from 'lodash/merge.js'
@@ -39,11 +40,13 @@ const resolveConfig = async (
   let configs = []
   if (Array.isArray(config.extends) && config.extends.length > 0) {
     config.extends = extendsResolver(config.extends, context)
-    configs = await Promise.all(
-      config.extends.map((configPath) =>
-        resolveConfigFile(configPath, depth + 1),
-      ),
-    )
+    if (Array.isArray(config.extends)) {
+      configs = await Promise.all(
+        config.extends.map((configPath) =>
+          resolveConfigFile(configPath, depth + 1),
+        ),
+      )
+    }
   }
 
   // merge all fields
@@ -78,7 +81,7 @@ const resolveConfig = async (
 const resolveConfigFile = async (filePath, depth = 0) => {
   // read config file
   const fileFullPath = cwdCallback(filePath)
-  const fileContent = await fs.readFile(fileFullPath)
+  const fileContent = await fs.readFile(fileFullPath, 'utf-8')
 
   let parsed
 
@@ -94,12 +97,16 @@ const resolveConfigFile = async (filePath, depth = 0) => {
 
 /**
  * Add default fields for a configuration.
+ * Warning: this function mutates the config object.
  *
- * @param {*} config
+ * @param {import('../../types/index.js').TrifidConfig} config Trifid configuration.
+ * @return {void}
  */
 const addDefaultFields = (config) => {
   if (!config.server) {
-    config.server = {}
+    config.server = {
+      listener: {},
+    }
   }
 
   if (!config.globals) {
@@ -113,8 +120,10 @@ const addDefaultFields = (config) => {
 
 /**
  * Add the default port for the server configuration.
+ * Warning: this function mutates the config object.
  *
- * @param {*} config
+ * @param {import('../../types/index.js').TrifidConfig} config Trifid configuration.
+ * @return {void}
  */
 const addDefaultPort = (config) => {
   if (!config.server.listener) {
@@ -127,8 +136,10 @@ const addDefaultPort = (config) => {
 
 /**
  * Add some default Express settings for the server configuration.
+ * Warning: this function mutates the config object.
  *
- * @param {*} config
+ * @param {import('../../types/index.js').TrifidConfig} config Trifid configuration.
+ * @return {void}
  */
 const addDefaultExpressSettings = (config) => {
   if (!config.server.express) {
@@ -140,6 +151,12 @@ const addDefaultExpressSettings = (config) => {
   }
 }
 
+/**
+ * Expand configuration and add default fields.
+ *
+ * @param {string | import('../../types/index.js').TrifidConfigWithExtends} configFile
+ * @returns {Promise<import('../../types/index.js').TrifidConfig>}
+ */
 const handler = async (configFile) => {
   let config = {}
   if (typeof configFile === 'string') {

packages/core/lib/config/parser.js

@@ -1,12 +1,18 @@
+// @ts-check
 import Ajv from 'ajv'
 import schema from './schema.js'
 
+// @ts-ignore
 const ajv = new Ajv()
 
 /**
  * Return the configuration object if it is valid or throw an error in other cases.
+ *
+ * @param {import('../../types/index.js').TrifidConfigWithExtends} config Configuration to validate.
+ * @returns {import('../../types/index.js').TrifidConfigWithExtends} Valid configuration.
  */
-const parser = (data = {}) => {
+const parser = (config) => {
+  const data = !config ? {} : config
   const valid = ajv.validate(schema, data)
   if (!valid) {
     throw new Error(ajv.errorsText())

packages/core/middlewares/errors.js

@@ -1,10 +1,17 @@
+// @ts-check
+
+/** @type {import('../types/index.d.ts').TrifidMiddleware} */
 const factory = (trifid) => {
   const { logger } = trifid
 
   return (err, _req, res, _next) => {
     logger.error(err.stack)
 
-    res.statusCode = err.statusCode || 500
+    res.statusCode = res.statusCode || 500
+    if (res.statusCode < 400) {
+      res.statusCode = 500
+    }
+
     res.end()
   }
 }

packages/core/middlewares/express.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { loader } from '../lib/middlewares/loader.js'
 
 /**
@@ -7,8 +8,8 @@ import { loader } from '../lib/middlewares/loader.js'
  *  - module (string, required): the name of the NPM module to load
  *  - options (any, optional): some options to pass to the Express middleware
  *
- * @param {*} trifid Trifid object containing the configuration, and other utility functions.
- * @returns Express middleware.
+ * @param {import('../types/index.d.ts').TrifidMiddlewareArgument} trifid Trifid object containing the configuration, and other utility functions.
+ * @returns {Promise<import('../types/index.d.ts').ExpressMiddleware>} Express middleware.
  */
 const factory = async (trifid) => {
   const { config } = trifid

packages/core/middlewares/health.js

@@ -1,3 +1,6 @@
+// @ts-check
+
+/** @type {import('../types/index.d.ts').TrifidMiddleware} */
 const factory = (trifid) => {
   const { logger } = trifid
 

packages/core/middlewares/iri.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import { URL } from 'url'
 import absoluteUrl from 'absolute-url'
 
@@ -22,6 +24,7 @@ const removeSearchParams = (originalUrl) => {
   return urlFrom(url)
 }
 
+/** @type {import('../types/index.d.ts').TrifidMiddleware} */
 const factory = (trifid) => {
   const { config, logger } = trifid
   const { datasetBaseUrl } = config

packages/core/middlewares/locals.js

@@ -1,6 +1,8 @@
+// @ts-check
 import url from 'url'
 import absoluteUrl from 'absolute-url'
 
+/** @type {import('../types/index.d.ts').TrifidMiddleware} */
 const factory = (trifid) => {
   const { logger } = trifid
 

packages/core/middlewares/notFound.js

@@ -1,8 +1,11 @@
+// @ts-check
+
 import { dirname } from 'path'
 import { fileURLToPath } from 'url'
 
 const currentDir = dirname(fileURLToPath(import.meta.url))
 
+/** @type {import('../types/index.d.ts').TrifidMiddleware} */
 const factory = (trifid) => {
   const { logger, render } = trifid
 
@@ -18,27 +21,27 @@ const factory = (trifid) => {
       'application/n-quads',
     ])
     switch (accepts) {
-    case 'json':
-      res.send({ success: false, message: 'Not found', status: 404 })
-      break
-
-    case 'application/n-quads':
-    case 'html':
-      res.send(
-        await render(
-          `${currentDir}/../views/404.hbs`,
-          {
-            url: req.url,
-            locals: res.locals,
-          },
-          { title: 'Not Found' },
-        ),
-      )
-      break
-
-    default:
-      res.send('Not Found\n')
-      break
+      case 'json':
+        res.send({ success: false, message: 'Not found', status: 404 })
+        break
+
+      case 'application/n-quads':
+      case 'html':
+        res.send(
+          await render(
+            `${currentDir}/../views/404.hbs`,
+            {
+              url: req.url,
+              locals: res.locals,
+            },
+            { title: 'Not Found' },
+          ),
+        )
+        break
+
+      default:
+        res.send('Not Found\n')
+        break
     }
   }
 }

packages/core/middlewares/redirect.js

@@ -1,3 +1,6 @@
+// @ts-check
+
+/** @type {import('../types/index.d.ts').TrifidMiddleware} */
 const factory = (trifid) => {
   const { config, logger } = trifid
   const { target } = config

packages/core/middlewares/rewrite.js

@@ -9,8 +9,8 @@ import camouflageRewrite from 'camouflage-rewrite'
  *
  * Other available options are documented here: https://github.com/zazuko/camouflage-rewrite#usage
  *
- * @param {*} trifid Trifid object containing the configuration, and other utility functions.
- * @returns Express middleware.
+ * @param {import('../types/index.d.ts').TrifidMiddlewareArgument} trifid Trifid object containing the configuration, and other utility functions.
+ * @returns {Promise<import('../types/index.d.ts').ExpressMiddleware>} Express middleware.
  */
 const factory = (trifid) => {
   const { config } = trifid

packages/core/middlewares/static.js

@@ -1,5 +1,7 @@
+// @ts-check
 import express from 'express'
 
+/** @type {import('../types/index.d.ts').TrifidMiddleware} */
 const factory = (trifid) => {
   const { directory } = trifid.config
   if (!directory) {