chore: move to esm (#4403)

This pull request introduces several significant updates across the
codebase, primarily focused on modernizing the Node.js environment,
allow code sharing between backend and UI, improving TypeScript usage,
and enhancing import consistency. The most notable changes include
upgrading to Node.js 22, transitioning all imports to use explicit `.ts`
extensions and more precise type-only imports, and updating workflow and
configuration files to align with these changes.

**Node.js and Tooling Upgrades:**

* Upgraded Node.js version from 20 to 22 in both the GitHub Actions
workflow (`.github/workflows/test-application.yml`) and `.nvmrc`,
ensuring the project uses the latest LTS features and performance
improvements.
[[1]](diffhunk://#diff-9261914205164383e5e6930bef1909548ba0acc9cd1a241217e88b8dbb730894L21-R21)
[[2]](diffhunk://#diff-2c8effdf840690ccb88c7e21e56148978c6adb2c6926530c58ff0e47a9588b44L1-R1)
* Updated the workflow to build the backend before starting it, and
adjusted process checks and log outputs to match the new start command.
[[1]](diffhunk://#diff-9261914205164383e5e6930bef1909548ba0acc9cd1a241217e88b8dbb730894L84-R85)
[[2]](diffhunk://#diff-9261914205164383e5e6930bef1909548ba0acc9cd1a241217e88b8dbb730894R95-R108)

**TypeScript and Import Improvements:**

* Converted all internal imports to use explicit `.ts` extensions and
transitioned to type-only imports where appropriate, improving type
safety and compatibility with ES module standards. This affects nearly
all files in the `api/` directory, including `app.ts`,
`config/store.ts`, `lib/Gateway.ts`, and others.
[[1]](diffhunk://#diff-fe6a6140f19ab1b0dd1e7eac27de4a8366de9b7c0da27d292f99ba219e5a3e97L1-R31)
[[2]](diffhunk://#diff-fe6a6140f19ab1b0dd1e7eac27de4a8366de9b7c0da27d292f99ba219e5a3e97L35-R53)
[[3]](diffhunk://#diff-2abb3e2a5c46a2bdec870296307cc957672d574ee97c5c148d9947d3ea9fef1fL3-R7)
[[4]](diffhunk://#diff-3e2f08e1ca9a7cf0505f53c191827d903a5b7c23e37099590645c0fe8b34e7a0L1-R30)
[[5]](diffhunk://#diff-529b5159720cb6dfa3c4cbdc74cbd4e926b9d4b2ec1f861db52e4464c40dcdbcL1-R4)
[[6]](diffhunk://#diff-1181514579645f4a4c65086a3f127004ab212aa1aa37c9b66be0ab1b1e3b8e38L3-R23)
[[7]](diffhunk://#diff-9e87e739e41326d30862db11b85ba2fcbdfd938fd95aa1ff4be27b2e12ba83f9L3-R8)
[[8]](diffhunk://#diff-89d06f80641536a8b9d0cfc838a6f1528505040ed8509ad4809caf44d0c0114eR1-R20)
[[9]](diffhunk://#diff-21e7a2e7559aeee5103b6ea891ae6bdd44cda13256496671cd9b0a349a7ab0fbR1-L85)
[[10]](diffhunk://#diff-1ddaf3ef24f2e86d72fe6c6a971f5a10c696daaf5b3702fa16c110cb12d8001aL1-R8)
[[11]](diffhunk://#diff-5df935e8cb44f1ec7180e734ca106c3d6f5429654d9ccb6537a61f04431bfc76L1-R1)
[[12]](diffhunk://#diff-cce2f94deee2e0540eceb55c4ba5ff08ca38f50568ea2a7eea5b55b5d3804018L4-R4)
[[13]](diffhunk://#diff-fe9fabd25eb368d77a1700a270584d420f2631dcbdd691c29638683cc9456244L3-R3)

**Configuration and Linting Updates:**

* Changed `.prettierrc.js` to use ES module export syntax, aligning with
modern JavaScript module standards.
* Removed the `watch-files` option from `.mocharc.yml`, possibly to
streamline or fix test runner behavior.

**Codebase Consistency and Minor Fixes:**

* Standardized usage of Node.js built-in modules by using the `node:`
prefix (e.g., `node:fs`, `node:path`) across the codebase.
[[1]](diffhunk://#diff-fe6a6140f19ab1b0dd1e7eac27de4a8366de9b7c0da27d292f99ba219e5a3e97L1-R31)
[[2]](diffhunk://#diff-3e2f08e1ca9a7cf0505f53c191827d903a5b7c23e37099590645c0fe8b34e7a0L1-R30)
[[3]](diffhunk://#diff-1181514579645f4a4c65086a3f127004ab212aa1aa37c9b66be0ab1b1e3b8e38L3-R23)
[[4]](diffhunk://#diff-89d06f80641536a8b9d0cfc838a6f1528505040ed8509ad4809caf44d0c0114eR1-R20)
[[5]](diffhunk://#diff-1ddaf3ef24f2e86d72fe6c6a971f5a10c696daaf5b3702fa16c110cb12d8001aL1-R8)
* Added or updated utility exports and constants, such as introducing
`deviceConfigPriorityDir` in `Constants.ts` and updating its usage in
`config/store.ts`.
[[1]](diffhunk://#diff-6e3049fb752155a398da8d028881cd4e16401429ba95c63cb9ccfba85e071d79R48-R49)
[[2]](diffhunk://#diff-2abb3e2a5c46a2bdec870296307cc957672d574ee97c5c148d9947d3ea9fef1fL3-R7)

These changes collectively modernize the codebase, improve
maintainability, and ensure compatibility with the latest Node.js and
TypeScript features.

**References:**  

[[1]](diffhunk://#diff-9261914205164383e5e6930bef1909548ba0acc9cd1a241217e88b8dbb730894L21-R21)
[[2]](diffhunk://#diff-2c8effdf840690ccb88c7e21e56148978c6adb2c6926530c58ff0e47a9588b44L1-R1)
[[3]](diffhunk://#diff-9261914205164383e5e6930bef1909548ba0acc9cd1a241217e88b8dbb730894L84-R85)
[[4]](diffhunk://#diff-9261914205164383e5e6930bef1909548ba0acc9cd1a241217e88b8dbb730894R95-R108)
[[5]](diffhunk://#diff-fe6a6140f19ab1b0dd1e7eac27de4a8366de9b7c0da27d292f99ba219e5a3e97L1-R31)
[[6]](diffhunk://#diff-fe6a6140f19ab1b0dd1e7eac27de4a8366de9b7c0da27d292f99ba219e5a3e97L35-R53)
[[7]](diffhunk://#diff-2abb3e2a5c46a2bdec870296307cc957672d574ee97c5c148d9947d3ea9fef1fL3-R7)
[[8]](diffhunk://#diff-3e2f08e1ca9a7cf0505f53c191827d903a5b7c23e37099590645c0fe8b34e7a0L1-R30)
[[9]](diffhunk://#diff-529b5159720cb6dfa3c4cbdc74cbd4e926b9d4b2ec1f861db52e4464c40dcdbcL1-R4)
[[10]](diffhunk://#diff-1181514579645f4a4c65086a3f127004ab212aa1aa37c9b66be0ab1b1e3b8e38L3-R23)
[[11]](diffhunk://#diff-9e87e739e41326d30862db11b85ba2fcbdfd938fd95aa1ff4be27b2e12ba83f9L3-R8)
[[12]](diffhunk://#diff-89d06f80641536a8b9d0cfc838a6f1528505040ed8509ad4809caf44d0c0114eR1-R20)
[[13]](diffhunk://#diff-21e7a2e7559aeee5103b6ea891ae6bdd44cda13256496671cd9b0a349a7ab0fbR1-L85)
[[14]](diffhunk://#diff-1ddaf3ef24f2e86d72fe6c6a971f5a10c696daaf5b3702fa16c110cb12d8001aL1-R8)
[[15]](diffhunk://#diff-5df935e8cb44f1ec7180e734ca106c3d6f5429654d9ccb6537a61f04431bfc76L1-R1)
[[16]](diffhunk://#diff-cce2f94deee2e0540eceb55c4ba5ff08ca38f50568ea2a7eea5b55b5d3804018L4-R4)
[[17]](diffhunk://#diff-fe9fabd25eb368d77a1700a270584d420f2631dcbdd691c29638683cc9456244L3-R3)
[[18]](diffhunk://#diff-7312296367dd7c725b9beb500d7dab7bbeeb2aa03a1010a3fb2935f826d03fa6L1-R1)
[[19]](diffhunk://#diff-751a54bee66ebd0d32763befd5f74abfe8c00f15aeeb61b8509ff3ed8d52ec89L2-L3)
[[20]](diffhunk://#diff-6e3049fb752155a398da8d028881cd4e16401429ba95c63cb9ccfba85e071d79R48-R49)

Fixes #4401

---------

Co-authored-by: Dominic Griesel <[email protected]>

Author: robertsLando

.github/workflows/test-application.yml

@@ -18,7 +18,7 @@ jobs:
             - name: Set up Node.js
               uses: actions/setup-node@v5
               with:
-                  node-version: '20'
+                  node-version: '22'
                   cache: 'npm'
 
             - name: Install dependencies
@@ -81,7 +81,8 @@ jobs:
                   
             - name: Start backend
               run: |
-                  nohup npm run server > server.log 2>&1 &
+                  npm run build:server
+                  nohup npm start > server.log 2>&1 &
                   sleep 25
             
             - name: Test MQTT write and read
@@ -91,17 +92,20 @@ jobs:
                   docker exec broker mosquitto_sub -h localhost -p 1883 -t "zwave/nodeID_2/106/0/currentValue/3" -C 1
 
             - name: Output backend logs
+              if: always()
               run: |
                 sleep 5
                 cat server.log
             
             - name: Output broker logs
+              if: always()
               run: |
                   docker logs broker
 
             - name: Ensure backend is running
+              if: always()
               run: |
-                  if ! pgrep -f "npm run server" > /dev/null; then
+                  if ! pgrep -f "npm start" > /dev/null; then
                     echo "Backend crashed!" && exit 1
                   fi
                   echo "Backend is running successfully."

.mocharc.yml

@@ -1,3 +1 @@
 recursive: true
-watch-files:
-  - 'test/**/*.ts'

.nvmrc

@@ -1 +1 @@
-v20.19.4
+v22.20.0

.prettierrc.js

@@ -1,4 +1,4 @@
-module.exports = {
+export default {
 	semi: false,
 	singleQuote: true,
 	useTabs: true,

api/app.ts

@@ -1,29 +1,33 @@
-import express, { Request, RequestHandler, Response, Router } from 'express'
+import type { Request, RequestHandler, Response, Router } from 'express'
+import express from 'express'
 import history from 'connect-history-api-fallback'
 import cors from 'cors'
 import csrf from 'csurf'
 import morgan from 'morgan'
-import store, { Settings, User } from './config/store'
-import Gateway, { GatewayConfig, GatewayType } from './lib/Gateway'
-import jsonStore from './lib/jsonStore'
-import * as loggers from './lib/logger'
-import MqttClient from './lib/MqttClient'
-import SocketManager from './lib/SocketManager'
-import ZWaveClient, { CallAPIResult, SensorTypeScale } from './lib/ZwaveClient'
+import type { Settings, User } from './config/store.ts'
+import store from './config/store.ts'
+import type { GatewayConfig } from './lib/Gateway.ts'
+import Gateway, { GatewayType } from './lib/Gateway.ts'
+import jsonStore from './lib/jsonStore.ts'
+import * as loggers from './lib/logger.ts'
+import MqttClient from './lib/MqttClient.ts'
+import SocketManager from './lib/SocketManager.ts'
+import type { CallAPIResult, SensorTypeScale } from './lib/ZwaveClient.ts'
+import ZWaveClient from './lib/ZwaveClient.ts'
 import multer, { diskStorage } from 'multer'
 import extract from 'extract-zip'
 import { serverVersion } from '@zwave-js/server'
 import archiver from 'archiver'
 import rateLimit from 'express-rate-limit'
 import session from 'express-session'
-import fs, { mkdirp, move, readdir, rm, stat } from 'fs-extra'
-import { createServer as createHttpServer, Server as HttpServer } from 'http'
-import { createServer as createHttpsServer } from 'https'
+import type { Server as HttpServer } from 'node:http'
+import { createServer as createHttpServer } from 'node:http'
+import { createServer as createHttpsServer } from 'node:https'
 import jwt from 'jsonwebtoken'
-import path from 'path'
+import path from 'node:path'
 import sessionStore from 'session-file-store'
-import { Socket } from 'socket.io'
-import { promisify } from 'util'
+import type { Socket } from 'socket.io'
+import { promisify } from 'node:util'
 import { Driver, libVersion } from 'zwave-js'
 import {
 	defaultPsw,
@@ -32,18 +36,26 @@ import {
 	snippetsDir,
 	storeDir,
 	tmpDir,
-} from './config/app'
+} from './config/app.ts'
+import type { CustomPlugin, PluginConstructor } from './lib/CustomPlugin.ts'
+import { createPlugin } from './lib/CustomPlugin.ts'
+import { inboundEvents, socketEvents } from './lib/SocketEvents.ts'
+import * as utils from './lib/utils.ts'
+import backupManager from './lib/BackupManager.ts'
 import {
-	createPlugin,
-	CustomPlugin,
-	PluginConstructor,
-} from './lib/CustomPlugin'
-import { inboundEvents, socketEvents } from './lib/SocketEvents'
-import * as utils from './lib/utils'
-import backupManager from './lib/BackupManager'
-import { readFile, realpath } from 'fs/promises'
+	readFile,
+	realpath,
+	readdir,
+	stat,
+	rm,
+	rename,
+	writeFile,
+	lstat,
+	mkdir,
+} from 'node:fs/promises'
 import { generate } from 'selfsigned'
-import ZnifferManager, { ZnifferConfig } from './lib/ZnifferManager'
+import type { ZnifferConfig } from './lib/ZnifferManager.ts'
+import ZnifferManager from './lib/ZnifferManager.ts'
 import { getAllNamedScaleGroups, getAllSensors } from '@zwave-js/core'
 
 const createCertificate = promisify(generate)
@@ -72,7 +84,7 @@ function multerPromise(
 
 const Storage = diskStorage({
 	async destination(reqD, file, callback) {
-		await mkdirp(tmpDir)
+		await utils.ensureDir(tmpDir)
 		callback(null, tmpDir)
 	},
 	filename(reqF, file, callback) {
@@ -262,7 +274,7 @@ const defaultSnippets: utils.Snippet[] = []
 
 async function loadSnippets() {
 	const localSnippetsDir = utils.joinPath(false, 'snippets')
-	await mkdirp(snippetsDir)
+	await utils.ensureDir(snippetsDir)
 
 	const files = await readdir(localSnippetsDir)
 	for (const file of files) {
@@ -329,8 +341,8 @@ async function loadCertKey(): Promise<{
 	let cert: string
 
 	try {
-		cert = await fs.readFile(certFile, 'utf8')
-		key = await fs.readFile(keyFile, 'utf8')
+		cert = await readFile(certFile, 'utf8')
+		key = await readFile(keyFile, 'utf8')
 	} catch (error) {
 		// noop
 	}
@@ -349,8 +361,8 @@ async function loadCertKey(): Promise<{
 			key = result.private
 			cert = result.cert
 
-			await fs.writeFile(utils.joinPath(storeDir, 'key.pem'), key)
-			await fs.writeFile(utils.joinPath(storeDir, 'cert.pem'), cert)
+			await writeFile(utils.joinPath(storeDir, 'key.pem'), key)
+			await writeFile(utils.joinPath(storeDir, 'cert.pem'), cert)
 			logger.info('New cert and key created')
 		} catch (error) {
 			logger.error('Error creating cert and key for HTTPS', error)
@@ -447,14 +459,14 @@ function setupInterceptor() {
 
 async function parseDir(dir: string): Promise<StoreFileEntry[]> {
 	const toReturn = []
-	const files = await fs.readdir(dir)
+	const files = await readdir(dir)
 	for (const file of files) {
 		try {
 			const entry: StoreFileEntry = {
 				name: path.basename(file),
 				path: utils.joinPath(dir, file),
 			}
-			const stats = await fs.lstat(entry.path)
+			const stats = await lstat(entry.path)
 			if (stats.isDirectory()) {
 				if (entry.path === process.env.ZWAVEJS_EXTERNAL_CONFIG) {
 					// hide config-db
@@ -1367,18 +1379,18 @@ app.get('/api/store', storeLimiter, isAuthenticated, async function (req, res) {
 		if (req.query.path) {
 			const reqPath = getSafePath(req)
 			// lgtm [js/path-injection]
-			let stat = await fs.lstat(reqPath)
+			let stat = await lstat(reqPath)
 
 			// check symlink is secure
 			if (stat.isSymbolicLink()) {
 				const realPath = await realpath(reqPath)
 				getSafePath(realPath)
-				stat = await fs.lstat(realPath)
+				stat = await lstat(realPath)
 			}
 
 			if (stat.isFile()) {
 				// lgtm [js/path-injection]
-				data = await fs.readFile(reqPath, 'utf8')
+				data = await readFile(reqPath, 'utf8')
 			} else {
 				// read directory
 				// lgtm [js/path-injection]
@@ -1411,7 +1423,7 @@ app.put('/api/store', storeLimiter, isAuthenticated, async function (req, res) {
 
 		if (!isNew) {
 			// lgtm [js/path-injection]
-			const stat = await fs.lstat(reqPath)
+			const stat = await lstat(reqPath)
 
 			if (!stat.isFile()) {
 				throw Error('Path is not a file')
@@ -1420,10 +1432,10 @@ app.put('/api/store', storeLimiter, isAuthenticated, async function (req, res) {
 
 		if (!isDirectory) {
 			// lgtm [js/path-injection]
-			await fs.writeFile(reqPath, req.body.content, 'utf8')
+			await writeFile(reqPath, req.body.content, 'utf8')
 		} else {
 			// lgtm [js/path-injection]
-			await fs.mkdir(reqPath)
+			await mkdir(reqPath)
 		}
 
 		res.json({ success: true })
@@ -1442,7 +1454,7 @@ app.delete(
 			const reqPath = getSafePath(req)
 
 			// lgtm [js/path-injection]
-			await fs.remove(reqPath)
+			await rm(reqPath, { recursive: true, force: true })
 
 			res.json({ success: true })
 		} catch (error) {
@@ -1460,7 +1472,7 @@ app.put(
 		try {
 			const files = req.body.files || []
 			for (const f of files) {
-				await fs.remove(f)
+				await rm(f, { recursive: true, force: true })
 			}
 			res.json({ success: true })
 		} catch (error) {
@@ -1498,7 +1510,7 @@ app.post(
 		archive.pipe(res)
 
 		for (const f of files) {
-			const s = await fs.lstat(f)
+			const s = await lstat(f)
 			const name = f.replace(storeDir, '')
 			if (s.isFile()) {
 				archive.file(f, { name })
@@ -1559,7 +1571,7 @@ app.post(
 				const destinationPath = getSafePath(
 					path.join(storeDir, folder, file.originalname),
 				)
-				await move(file.path, destinationPath)
+				await rename(file.path, destinationPath)
 			}
 
 			res.json({ success: true })

api/bin/www.ts

@@ -4,10 +4,10 @@
 /**
  * Module dependencies.
  */
-import jsonStore from '../lib/jsonStore'
-import store from '../config/store'
-import * as conf from '../config/app'
-import app, { startServer } from '../app'
+import jsonStore from '../lib/jsonStore.ts'
+import store from '../config/store.ts'
+import * as conf from '../config/app.ts'
+import app, { startServer } from '../app.ts'
 
 console.log(
 	`  ______  __          __                      _  _____     _    _ _____ \n |___  /  \\ \\        / /                     | |/ ____|   | |  | |_   _|\n    / /____\\ \\  /\\  / /_ ___   _____         | | (___     | |  | | | |  \n   / /______\\ \\/  \\/ / _\' \\ \\ / / _ \\    _   | |\\___ \\    | |  | | | |  \n  / /__      \\  /\\  / (_| |\\ V /  __/   | |__| |____) |   | |__| |_| |_ \n /_____|      \\/  \\/ \\__,_| \\_/ \\___|    \\____/|_____/     \\____/|_____|\n`,

api/config/app.ts

@@ -1,4 +1,4 @@
-import { joinPath } from '../lib/utils'
+import { joinPath } from '../lib/utils.ts'
 import { config } from 'dotenv'
 
 config({ path: './.env.app' })

api/config/store.ts

@@ -1,9 +1,10 @@
 // config/store.js
 
-import { GatewayConfig } from '../lib/Gateway'
-import { MqttConfig } from '../lib/MqttClient'
-import { ZnifferConfig } from '../lib/ZnifferManager'
-import { ZwaveConfig, deviceConfigPriorityDir } from '../lib/ZwaveClient'
+import type { GatewayConfig } from '../lib/Gateway.ts'
+import type { MqttConfig } from '../lib/MqttClient.ts'
+import type { ZnifferConfig } from '../lib/ZnifferManager.ts'
+import type { ZwaveConfig } from '../lib/ZwaveClient.ts'
+import { deviceConfigPriorityDir } from '../lib/Constants.ts'
 
 export type StoreKeys = 'settings' | 'scenes' | 'nodes' | 'users'
 

api/hass/configurations.ts

@@ -1,7 +1,7 @@
 // List of Home-Assistant configuration for MQTT Discovery
 // https://www.home-assistant.io/docs/mqtt/discovery/
 
-import { HassDevice } from '../lib/ZwaveClient'
+import type { HassDevice } from '../lib/ZwaveClient.ts'
 
 type HassDeviceKey =
 	| 'binary_sensor'

api/hass/devices.ts

@@ -1,6 +1,6 @@
 // Place here repeated patterns
 
-import { HassDevice } from '../lib/ZwaveClient'
+import type { HassDevice } from '../lib/ZwaveClient.ts'
 
 const FAN_DIMMER: HassDevice = {
 	type: 'fan',