refactor: move listing ports into serial host binding

packages/serial/package.json

@@ -27,6 +27,11 @@
       "import": "./build/esm/index_mock.js",
       "require": "./build/cjs/index_mock.js"
     },
+    "./bindings/*": {
+      "@@dev": "./src/bindings/*.ts",
+      "import": "./build/esm/bindings/*.js",
+      "require": "./build/cjs/bindings/*.js"
+    },
     "./package.json": "./package.json"
   },
   "keywords": [],

packages/serial/src/bindings/node.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SerialPort } from "serialport";
+import { type EnumeratedPort, type Serial } from "../serialport/Bindings.js";
+import { createNodeSerialPortFactory } from "../serialport/NodeSerialPort.js";
+import { createNodeSocketFactory } from "../serialport/NodeSocket.js";
+
+/** An implementation of the Serial bindings for Node.js */
+export const serial: Serial = {
+	createFactoryByPath(path) {
+		if (path.startsWith("tcp://")) {
+			const url = new URL(path);
+			return Promise.resolve(createNodeSocketFactory({
+				host: url.hostname,
+				port: parseInt(url.port),
+			}));
+		} else {
+			return Promise.resolve(createNodeSerialPortFactory(
+				path,
+			));
+		}
+	},
+
+	async list() {
+		// Put symlinks to the serial ports first if possible
+		const ret: EnumeratedPort[] = [];
+		if (os.platform() === "linux") {
+			const dir = "/dev/serial/by-id";
+			const symlinks = await fs.readdir(dir).catch(() => []);
+
+			for (const l of symlinks) {
+				try {
+					const fullPath = path.join(dir, l);
+					const target = path.join(
+						dir,
+						await fs.readlink(fullPath),
+					);
+					if (!target.startsWith("/dev/tty")) continue;
+
+					ret.push({
+						type: "link",
+						path: fullPath,
+					});
+				} catch {
+					// Ignore. The target might not exist or we might not have access.
+				}
+			}
+		}
+
+		// Then the actual serial ports
+		const ports = await SerialPort.list();
+		ret.push(...ports.map((port) => ({
+			type: "tty" as const,
+			path: port.path,
+		})));
+
+		return ret;
+	},
+};

packages/serial/src/index.ts

@@ -11,6 +11,7 @@ export * from "./parsers/SerialAPIParser.js";
 export * from "./parsers/ZWaveSerialFrame.js";
 export * from "./parsers/ZnifferSerialFrame.js";
 export * from "./plumbing/Faucet.js";
+export type * from "./serialport/Bindings.js";
 export * from "./serialport/LegacyBindingWrapper.js";
 export * from "./serialport/NodeSerialPort.js";
 export * from "./serialport/NodeSocket.js";

packages/serial/src/index_safe.ts

@@ -4,3 +4,4 @@ export type { SerialLogContext } from "./log/Logger_safe.js";
 export * from "./message/Constants.js";
 export * from "./message/MessageHeaders.js";
 export * from "./message/SuccessIndicator.js";
+export type * from "./serialport/Bindings.js";

packages/serial/src/serialport/Bindings.ts

@@ -0,0 +1,24 @@
+import { type ZWaveSerialBindingFactory } from "./ZWaveSerialStream.js";
+
+export type EnumeratedPort = {
+	type: "link";
+	path: string;
+} | {
+	type: "tty";
+	path: string;
+} | {
+	type: "socket";
+	path: string;
+} | {
+	type: "custom";
+	factory: ZWaveSerialBindingFactory;
+};
+
+/** Abstractions to interact with serial ports on different platforms */
+export interface Serial {
+	/** Create a binding factory from the given path, if supported by the platform */
+	createFactoryByPath?: (path: string) => Promise<ZWaveSerialBindingFactory>;
+
+	/** List the available serial ports, if supported by the platform */
+	list?: () => Promise<EnumeratedPort[]>;
+}

packages/shared/src/bindings.ts

@@ -135,9 +135,3 @@ export interface FileSystem
 {}
 
 export type Platform = "linux" | "darwin" | "win32" | "browser" | "other";
-
-/** Abstractions for a host system Z-Wave JS is running on */
-export interface Host {
-	fs: FileSystem;
-	platform: Platform;
-}

packages/zwave-js/src/lib/driver/Driver.ts

@@ -116,6 +116,7 @@ import {
 import {
 	type BootloaderChunk,
 	BootloaderChunkType,
+	type EnumeratedPort,
 	FunctionType,
 	type HasNodeId,
 	Message,
@@ -131,8 +132,6 @@ import {
 	type ZWaveSerialPortImplementation,
 	type ZWaveSerialStream,
 	ZWaveSerialStreamFactory,
-	createNodeSerialPortFactory,
-	createNodeSocketFactory,
 	getDefaultPriority,
 	hasNodeId,
 	isSuccessIndicator,
@@ -165,6 +164,17 @@ import {
 	isSendDataTransmitReport,
 	isTransmitReport,
 } from "@zwave-js/serial/serialapi";
+import {
+	SendTestFrameRequest,
+	SendTestFrameTransmitReport,
+} from "@zwave-js/serial/serialapi";
+import {
+	type CommandRequest,
+	type ContainsCC,
+	containsCC,
+	containsSerializedCC,
+	isCommandRequest,
+} from "@zwave-js/serial/serialapi";
 import {
 	AsyncQueue,
 	Bytes,
@@ -182,18 +192,20 @@ import {
 	num2hex,
 	pick,
 } from "@zwave-js/shared";
+import {
+	type ReadFile,
+	type ReadFileSystemInfo,
+} from "@zwave-js/shared/bindings";
 import { distinct } from "alcalzone-shared/arrays";
 import { wait } from "alcalzone-shared/async";
 import {
 	type DeferredPromise,
 	createDeferredPromise,
 } from "alcalzone-shared/deferred-promise";
 import { isArray, isObject } from "alcalzone-shared/typeguards";
-import fs from "node:fs/promises";
-import os from "node:os";
 import * as util from "node:util";
 import path from "pathe";
-import { SerialPort } from "serialport";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "../_version.js";
 import { ZWaveController } from "../controller/Controller.js";
 import { InclusionState, RemoveNodeReason } from "../controller/Inclusion.js";
 import { DriverLogger } from "../log/Driver.js";
@@ -206,23 +218,6 @@ import {
 	type ZWaveNotificationCallback,
 	zWaveNodeEvents,
 } from "../node/_Types.js";
-
-import {
-	SendTestFrameRequest,
-	SendTestFrameTransmitReport,
-} from "@zwave-js/serial/serialapi";
-import {
-	type CommandRequest,
-	type ContainsCC,
-	containsCC,
-	containsSerializedCC,
-	isCommandRequest,
-} from "@zwave-js/serial/serialapi";
-import {
-	type ReadFile,
-	type ReadFileSystemInfo,
-} from "@zwave-js/shared/bindings";
-import { PACKAGE_NAME, PACKAGE_VERSION } from "../_version.js";
 import { type ZWaveNodeBase } from "../node/mixins/00_Base.js";
 import { type NodeWakeup } from "../node/mixins/30_Wakeup.js";
 import { type NodeValues } from "../node/mixins/40_Values.js";
@@ -1226,44 +1221,38 @@ export class Driver extends TypedEventTarget<DriverEventCallbacks>
 		local?: boolean;
 		remote?: boolean;
 	} = {}): Promise<string[]> {
-		const symlinkedPorts: string[] = [];
-		const localPorts: string[] = [];
-		const remotePorts: string[] = [];
-		// FIXME: Move this into the serial bindings
-		if (local) {
-			// Put symlinks to the serial ports first if possible
-			if (os.platform() === "linux") {
-				const dir = "/dev/serial/by-id";
-				const symlinks = await fs.readdir(dir).catch(() => []);
-
-				for (const l of symlinks) {
-					try {
-						const fullPath = path.join(dir, l);
-						const target = path.join(
-							dir,
-							await fs.readlink(fullPath),
-						);
-						if (!target.startsWith("/dev/tty")) continue;
+		const ret: (EnumeratedPort & { path: string })[] = [];
 
-						symlinkedPorts.push(fullPath);
-					} catch {
-						// Ignore. The target might not exist or we might not have access.
-					}
-				}
-			}
+		// Ideally we'd use the host bindings used by the driver, but we can't access them in a static method
 
-			// Then the actual serial ports
-			const ports = await SerialPort.list();
-			localPorts.push(...ports.map((port) => port.path));
+		const bindings =
+			(await import("@zwave-js/serial/bindings/node")).serial;
+		if (local && typeof bindings.list === "function") {
+			for (const port of await bindings.list()) {
+				if (port.type === "custom") continue;
+				ret.push(port);
+			}
 		}
 		if (remote) {
 			const ports = await discoverRemoteSerialPorts();
 			if (ports) {
-				remotePorts.push(...ports.map((p) => p.port));
+				ret.push(...ports.map((p) => ({
+					type: "socket" as const,
+					path: p.port,
+				})));
 			}
 		}
 
-		return distinct([...symlinkedPorts, ...remotePorts, ...localPorts]);
+		const portOrder: EnumeratedPort["type"][] = ["link", "socket", "tty"];
+
+		ret.sort((a, b) => {
+			const typeA = portOrder.indexOf(a.type);
+			const typeB = portOrder.indexOf(b.type);
+			if (typeA !== typeB) return typeA - typeB;
+			return a.path.localeCompare(b.path);
+		});
+
+		return distinct(ret.map((p) => p.path));
 	}
 
 	/** Updates a subset of the driver options on the fly */
@@ -1341,6 +1330,8 @@ export class Driver extends TypedEventTarget<DriverEventCallbacks>
 		this.bindings = {
 			fs: this._options.host?.fs
 				?? (await import("@zwave-js/core/bindings/fs/node")).fs,
+			serial: this._options.host?.serial
+				?? (await import("@zwave-js/serial/bindings/node")).serial,
 		};
 
 		const spOpenPromise = createDeferredPromise();
@@ -1355,19 +1346,22 @@ export class Driver extends TypedEventTarget<DriverEventCallbacks>
 		// Open the serial port
 		let binding: ZWaveSerialBindingFactory;
 		if (typeof this.port === "string") {
-			if (this.port.startsWith("tcp://")) {
-				const url = new URL(this.port);
-				this.driverLog.print(`opening serial port ${this.port}`);
-				binding = createNodeSocketFactory({
-					host: url.hostname,
-					port: parseInt(url.port),
-				});
-			} else {
+			if (
+				typeof this.bindings.serial.createFactoryByPath === "function"
+			) {
 				this.driverLog.print(`opening serial port ${this.port}`);
-				binding = createNodeSerialPortFactory(
+				binding = await this.bindings.serial.createFactoryByPath(
 					this.port,
-					// this._options.testingHooks?.serialPortBinding,
 				);
+			} else {
+				spOpenPromise.reject(
+					new ZWaveError(
+						"This platform does not support creating a serial connection by path",
+						ZWaveErrorCodes.Driver_Failed,
+					),
+				);
+				void this.destroy();
+				return;
 			}
 		} else if (isZWaveSerialPortImplementation(this.port)) {
 			this.driverLog.print(

packages/zwave-js/src/lib/driver/Host.ts

@@ -0,0 +1,11 @@
+// FIXME: This should eventually live in @zwave-js/host
+
+import { type Serial } from "@zwave-js/serial";
+import { type FileSystem, type Platform } from "@zwave-js/shared/bindings";
+
+/** Abstractions for a host system Z-Wave JS is running on */
+export interface Host {
+	fs: FileSystem;
+	platform: Platform;
+	serial: Serial;
+}

packages/zwave-js/src/lib/driver/ZWaveOptions.ts

@@ -4,7 +4,7 @@ import type {
 	LongRangeChannel,
 	RFRegion,
 } from "@zwave-js/core";
-import { type ZWaveSerialStream } from "@zwave-js/serial";
+import { type Serial, type ZWaveSerialStream } from "@zwave-js/serial";
 import { type DeepPartial, type Expand } from "@zwave-js/shared";
 import type { FileSystem } from "@zwave-js/shared/bindings";
 import type {
@@ -132,6 +132,11 @@ export interface ZWaveOptions {
 		 * reading or writing the cache, or loading device configuration files.
 		 */
 		fs?: FileSystem;
+
+		/**
+		 * Specifies which bindings are used interact with serial ports.
+		 */
+		serial?: Serial;
 	};
 
 	storage: {

packages/zwave-js/src/lib/zniffer/Zniffer.ts

@@ -58,8 +58,6 @@ import {
 	ZnifferStartResponse,
 	ZnifferStopRequest,
 	ZnifferStopResponse,
-	createNodeSerialPortFactory,
-	createNodeSocketFactory,
 	isZWaveSerialPortImplementation,
 	wrapLegacySerialBinding,
 } from "@zwave-js/serial";
@@ -355,23 +353,24 @@ export class Zniffer extends TypedEventTarget<ZnifferEventCallbacks> {
 		this.bindings = {
 			fs: this._options.host?.fs
 				?? (await import("@zwave-js/core/bindings/fs/node")).fs,
+			serial: this._options.host?.serial
+				?? (await import("@zwave-js/serial/bindings/node")).serial,
 		};
 
 		// Open the serial port
 		let binding: ZWaveSerialBindingFactory;
 		if (typeof this.port === "string") {
-			if (this.port.startsWith("tcp://")) {
-				const url = new URL(this.port);
-				this.znifferLog.print(`opening serial port ${this.port}`);
-				binding = createNodeSocketFactory({
-					host: url.hostname,
-					port: parseInt(url.port),
-				});
-			} else {
+			if (
+				typeof this.bindings.serial.createFactoryByPath === "function"
+			) {
 				this.znifferLog.print(`opening serial port ${this.port}`);
-				binding = createNodeSerialPortFactory(
+				binding = await this.bindings.serial.createFactoryByPath(
 					this.port,
-					// this._options.testingHooks?.serialPortBinding,
+				);
+			} else {
+				throw new ZWaveError(
+					"This platform does not support creating a serial connection by path",
+					ZWaveErrorCodes.Driver_Failed,
 				);
 			}
 		} else if (isZWaveSerialPortImplementation(this.port)) {