Upgrading serialport from v4 to v6 (#20691)

* Upgrading serialport from v4 to v6

* Correcting baseurl and typeroots for v4 of library

* Exporting option interface and moving interfaces to Pascal case

* Removing redundent interface export, updating v4 library to fit with interface naming convention,  updating firmata package to point to the v4 library.

types/firmata/index.d.ts

@@ -155,7 +155,7 @@ declare namespace Board {
 	interface Options {
 		reportVersionTimeout?: number;
 		samplingInterval?: number;
-		serialport?: SerialPort.options;
+		serialport?: SerialPort.Options;
 	}
 
 	interface PinModes {

types/firmata/tsconfig.json

@@ -12,6 +12,9 @@
         "typeRoots": [
             "../"
         ],
+        "paths": {
+            "serialport": ["serialport/v4"]
+        },
         "types": [],
         "noEmit": true,
         "forceConsistentCasingInFileNames": true

types/serialport/index.d.ts

@@ -1,45 +1,70 @@
-// Type definitions for serialport 4.0
+// Type definitions for serialport 6.0
 // Project: https://github.com/EmergingTechnologyAdvisors/node-serialport
 // Definitions by: Jeremy Foster <https://github.com/codefoster>
+//                 Andrew Pearson <https://github.com/apearson>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
 /// <reference types="node" />
-/// <reference types="streamjs" />
 
-export = SerialPort;
+import * as Stream from 'stream';
 
-declare class SerialPort extends Stream<any> {
-	// openImmediately already removed in 4.0.7
-	constructor(path: string, options?: SerialPort.options|SerialPort.callback, callback?: SerialPort.callback);
-	isOpen(): boolean;
-	on(event: string, callback?: (data?: any) => void): void;
-	open(callback?: SerialPort.callback): void;
-	write(buffer: any, callback?: (err: any, bytesWritten: number) => void): void;
-	pause(): void;
-	resume(): void;
-	disconnected(err: Error): void;
-	close(callback?: SerialPort.callback): void;
-	flush(callback?: SerialPort.callback): void;
-	set(options: SerialPort.setOptions, callback: SerialPort.callback): void;
-	drain(callback?: SerialPort.callback): void;
-	update(options: SerialPort.updateOptions, callback?: SerialPort.callback): void;
-	static list(callback: (err: any, ports: SerialPort.portConfig[]) => void): void;
-	// https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/4.0.7/lib/parsers.js
-	static parsers: SerialPort.parsers;
+declare class SerialPort extends Stream.Duplex {
+	constructor(path: string, callback?: SerialPort.ErrorCallback);
+	constructor(path: string, options?: SerialPort.OpenOptions, callback?: SerialPort.ErrorCallback);
+
+	open(callback?: SerialPort.ErrorCallback): void;
+	update(options: SerialPort.UpdateOptions, callback?: SerialPort.ErrorCallback): void;
+
+	write(data: string| number[] | Buffer, callback?: (error: any, bytesWritten: number) => void): boolean;
+	write(buffer: string| number[] | Buffer, encoding?: 'ascii'|'utf8'|'utf16le'|'ucs2'|'base64'|'binary'|'hex', callback?: (error: any, bytesWritten: number) => void): boolean;
+
+	read(size?: number): string | Buffer | null;
+
+	close(callback?: (error: Error) => void): void;
+
+	set(options: SerialPort.SetOptions, callback?: SerialPort.ErrorCallback): void;
+	get(callback?: SerialPort.ModemBitsCallback): void;
+
+	flush(callback?: SerialPort.ErrorCallback): void;
+	drain(callback?: SerialPort.ErrorCallback): void;
+
+	pause(): this;
+	resume(): this;
+
+	on(event: string, callback?: (data?: any) => void): this;
+
+	static Binding: SerialPort.BaseBinding;
 }
 
 declare namespace SerialPort {
-	interface portConfig {
-		comName: string;
-		manufacturer: string;
-		serialNumber: string;
-		pnpId: string;
-		locationId: string;
-		vendorId: string;
-		productId: string;
-	}
+	// Callbacks Type Defs
+	type ErrorCallback = (error: Error) => void;
+	type ModemBitsCallback = (error: Error, status: {cts: boolean, dsr: boolean, dcd: boolean }) => void;
+	type ListCallback = (error: Error, port: any[]) => void;
 
-	interface setOptions {
+	// Options Type Defs
+	interface OpenOptions {
+		autoOpen?: boolean;
+		baudRate?: 115200|57600|38400|19200|9600|4800|2400|1800|1200|600|300|200|150|134|110|75|50|number;
+		dataBits?: 8|7|6|5;
+		highWaterMark?: number;
+		lock?: boolean;
+		stopBits?: 1|2;
+		parity?: 'none'|'even'|'mark'|'odd'|'space';
+		rtscts?: boolean;
+		xon?: boolean;
+		xoff?: boolean;
+		xany?: boolean;
+		binding?: BaseBinding;
+		bindingOptions?: {
+			vmin?: number;
+			vtime?: number;
+		};
+	}
+	interface UpdateOptions {
+		baudRate?: 115200|57600|38400|19200|9600|4800|2400|1800|1200|600|300|200|150|134|110|75|50|number;
+	}
+	interface SetOptions {
 		brk?: boolean;
 		cts?: boolean;
 		dsr?: boolean;
@@ -47,43 +72,48 @@ declare namespace SerialPort {
 		rts?: boolean;
 	}
 
-	interface updateOptions {
-		baudRate?: number;
+	namespace parsers {
+		class ByteLength extends Stream.Transform {
+			constructor(options: {length: number});
+		}
+		class CCTalk extends Stream.Transform {
+			constructor();
+		}
+		class Delimiter extends Stream.Transform {
+			constructor(options: {delimiter: string | Buffer | number[]});
+		}
+		class Readline extends Delimiter {
+			constructor(options: {delimiter: string | Buffer | number[], encoding?: 'ascii'|'utf8'|'utf16le'|'ucs2'|'base64'|'binary'|'hex'});
+		}
+		class Ready extends Stream.Transform {
+			constructor(options: {data: string | Buffer | number[]});
+		}
+		class Regex extends Stream.Transform {
+			constructor(options: {regex: RegExp});
+		}
 	}
 
-	type serialParser = (emitter: NodeJS.EventEmitter, buffer: Buffer|string) => void;
+		// Binding Type Defs
+		type win32Binding = BaseBinding;
+		type darwinBinding = BaseBinding;
+		type linuxBinding = BaseBinding;
 
-	type readlineParser = (delimiter: string, encoding?: 'ascii'|'utf8'|'utf16le'|'ucs2'|'base64'|'binary'|'hex') => serialParser;
+		// Binding Type Def
+		class BaseBinding {
+			constructor(options: any);
 
-	type byteLengthParser = (delimiter: number) => serialParser;
+			open(path: string, options: OpenOptions): Promise<any>;
+			close(): Promise<any>;
 
-	type byteDelimiterParser = (delimiter: number[]) => serialParser;
-
-	type callback = (error: any) => void;
-
-	interface parsers {
-		Raw: serialParser;
-		Readline: readlineParser;
-		ByteLength: byteLengthParser;
-		ByteDelimiter: byteDelimiterParser;
-	}
-
-	// https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/4.0.7/README.md#user-content-serialport-path-options-opencallback
-	interface options {
-		autoOpen?: boolean;
-		lock?: boolean;
-		baudRate?: 115200|57600|38400|19200|9600|4800|2400|1800|1200|600|300|200|150|134|110|75|50|number;
-		dataBits?: 8|7|6|5;
-		stopBits?: 1|2;
-		parity?: 'none'|'even'|'mark'|'odd'|'space';
-		rtscts?: boolean;
-		xon?: boolean;
-		xoff?: boolean;
-		bufferSize?: number;
-		parser?: serialParser;
-		platformOptions?: {
-			vmin?: number;
-			vtime?: number;
-		};
-	}
+			read(data: Buffer, offset: number, length: number): Promise<any>;
+			write(data: Buffer): Promise<any>;
+			update(options?: UpdateOptions): Promise<any>;
+			set(options?: SetOptions): Promise<any>;
+			get(): Promise<any>;
+			flush(): Promise<any>;
+			drain(): Promise<any>;
+			static list(): Promise<any>;
+		}
 }
+
+export = SerialPort;

types/serialport/serialport-tests.ts

@@ -8,26 +8,9 @@ function test_basic_connect() {
 
 function test_connect_config() {
     const port1 = new SerialPort('', {
-            baudRate: 0,
-            parser: SerialPort.parsers.Raw
-        }, (err: any) => {});
-
-    const port2 = new SerialPort('', {
-            baudRate: 0,
-            parser: SerialPort.parsers.Readline('\n', 'ascii')
-        }, (err: any) => {});
-
-    const port3 = new SerialPort('', {
-            baudRate: 0,
-            parser: SerialPort.parsers.ByteLength(7)
-        }, (err: any) => {});
+        }, (error: Error) => {});
 
     const port4 = new SerialPort('', {
-            baudRate: 0,
-            parser: SerialPort.parsers.ByteDelimiter([3, 4, 5])
-        }, (err: any) => {});
-
-    const port5 = new SerialPort('', {
             autoOpen: false,
             lock: false,
             baudRate: 115200,
@@ -37,24 +20,100 @@ function test_connect_config() {
             rtscts: true,
             xon: true,
             xoff: true,
-            bufferSize: 1024,
-            platformOptions: {
+            highWaterMark: 1024,
+            bindingOptions: {
                 vmin: 1,
                 vtime: 1
             }
-        }, (err: any) => {});
+        }, (error: Error) => {});
+}
+
+function test_open() {
+    const port = new SerialPort('');
+    port.open(() => {});
+}
+
+function test_update() {
+    const port = new SerialPort('');
+    port.update({baudRate: 57600});
 }
 
 function test_write() {
     const port = new SerialPort('');
-    port.write('main screen turn on', (err, bytesWritten) => {});
+
+    port.write('test', (error: Error) => {});
+    port.write('test', 'utf8', (error: Error) => {});
 }
 
-function test_events() {
+function test_read() {
     const port = new SerialPort('');
-    port.on('open', () => {});
+
+    const data = port.read(8);
 }
 
-function test_list_ports() {
-    SerialPort.list((err: string, ports: SerialPort.portConfig[]) => {});
+function test_close() {
+    const port = new SerialPort('');
+
+    port.close((error: Error) => {});
+}
+
+function test_set() {
+    const port = new SerialPort('');
+
+    port.set({}, (error: Error) => {});
+}
+
+function test_get() {
+    const port = new SerialPort('');
+
+    port.get((error, status) => {});
+}
+
+function test_flush() {
+    const port = new SerialPort('');
+
+    port.flush((error: Error) => {});
+}
+
+function test_drain() {
+    const port = new SerialPort('');
+
+    port.drain((error: Error) => {});
+}
+
+function test_pause_resume() {
+    const port = new SerialPort('');
+
+    const pauseItem: SerialPort =  port.pause();
+    const resumeItem: SerialPort = port.resume();
+}
+
+function test_on_events() {
+    const port = new SerialPort('');
+
+    const onItem: SerialPort = port.on('event', (data: any) => {});
+}
+
+function test_binding() {
+    const port = new SerialPort('');
+
+    const bindingItem: SerialPort.BaseBinding = SerialPort.Binding;
+}
+
+function test_parsers() {
+    const port = new SerialPort('');
+
+    const ByteLengthParser = new SerialPort.parsers.ByteLength({length: 8});
+    const CCTalkParser = new SerialPort.parsers.CCTalk();
+    const DelimiterParser = new SerialPort.parsers.Delimiter({ delimiter: Buffer.from('EOL') });
+    const ReadlineParser = new SerialPort.parsers.Readline({ delimiter: '\r\n' });
+    const ReadyParser = new SerialPort.parsers.Ready({ data: 'READY' });
+    const RegexParser = new SerialPort.parsers.Regex({regex: /.*/});
+
+    port.pipe(ByteLengthParser);
+    port.pipe(CCTalkParser);
+    port.pipe(DelimiterParser);
+    port.pipe(ReadlineParser);
+    port.pipe(ReadyParser);
+    port.pipe(RegexParser);
 }

types/serialport/v4/index.d.ts

@@ -0,0 +1,89 @@
+// Type definitions for serialport 4.0
+// Project: https://github.com/EmergingTechnologyAdvisors/node-serialport
+// Definitions by: Jeremy Foster <https://github.com/codefoster>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+
+/// <reference types="node" />
+/// <reference types="streamjs" />
+
+export = SerialPort;
+
+declare class SerialPort extends Stream<any> {
+	// openImmediately already removed in 4.0.7
+	constructor(path: string, options?: SerialPort.Options|SerialPort.callback, callback?: SerialPort.callback);
+	isOpen(): boolean;
+	on(event: string, callback?: (data?: any) => void): void;
+	open(callback?: SerialPort.callback): void;
+	write(buffer: any, callback?: (err: any, bytesWritten: number) => void): void;
+	pause(): void;
+	resume(): void;
+	disconnected(err: Error): void;
+	close(callback?: SerialPort.callback): void;
+	flush(callback?: SerialPort.callback): void;
+	set(options: SerialPort.SetOptions, callback: SerialPort.callback): void;
+	drain(callback?: SerialPort.callback): void;
+	update(options: SerialPort.UpdateOptions, callback?: SerialPort.callback): void;
+	static list(callback: (err: any, ports: SerialPort.PortConfig[]) => void): void;
+	// https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/4.0.7/lib/parsers.js
+	static parsers: SerialPort.Parsers;
+}
+
+declare namespace SerialPort {
+	interface PortConfig {
+		comName: string;
+		manufacturer: string;
+		serialNumber: string;
+		pnpId: string;
+		locationId: string;
+		vendorId: string;
+		productId: string;
+	}
+
+	interface SetOptions {
+		brk?: boolean;
+		cts?: boolean;
+		dsr?: boolean;
+		dtr?: boolean;
+		rts?: boolean;
+	}
+
+	interface UpdateOptions {
+		baudRate?: number;
+	}
+
+	type serialParser = (emitter: NodeJS.EventEmitter, buffer: Buffer|string) => void;
+
+	type readlineParser = (delimiter: string, encoding?: 'ascii'|'utf8'|'utf16le'|'ucs2'|'base64'|'binary'|'hex') => serialParser;
+
+	type byteLengthParser = (delimiter: number) => serialParser;
+
+	type byteDelimiterParser = (delimiter: number[]) => serialParser;
+
+	type callback = (error: any) => void;
+
+	interface Parsers {
+		Raw: serialParser;
+		Readline: readlineParser;
+		ByteLength: byteLengthParser;
+		ByteDelimiter: byteDelimiterParser;
+	}
+
+	// https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/4.0.7/README.md#user-content-serialport-path-options-opencallback
+	interface Options {
+		autoOpen?: boolean;
+		lock?: boolean;
+		baudRate?: 115200|57600|38400|19200|9600|4800|2400|1800|1200|600|300|200|150|134|110|75|50|number;
+		dataBits?: 8|7|6|5;
+		stopBits?: 1|2;
+		parity?: 'none'|'even'|'mark'|'odd'|'space';
+		rtscts?: boolean;
+		xon?: boolean;
+		xoff?: boolean;
+		bufferSize?: number;
+		parser?: serialParser;
+		platformOptions?: {
+			vmin?: number;
+			vtime?: number;
+		};
+	}
+}

types/serialport/v4/serialport-tests.ts

@@ -0,0 +1,60 @@
+// Tests taken from documentation samples.
+
+import * as SerialPort from 'serialport';
+
+function test_basic_connect() {
+    const port = new SerialPort('');
+}
+
+function test_connect_config() {
+    const port1 = new SerialPort('', {
+            baudRate: 0,
+            parser: SerialPort.parsers.Raw
+        }, (err: any) => {});
+
+    const port2 = new SerialPort('', {
+            baudRate: 0,
+            parser: SerialPort.parsers.Readline('\n', 'ascii')
+        }, (err: any) => {});
+
+    const port3 = new SerialPort('', {
+            baudRate: 0,
+            parser: SerialPort.parsers.ByteLength(7)
+        }, (err: any) => {});
+
+    const port4 = new SerialPort('', {
+            baudRate: 0,
+            parser: SerialPort.parsers.ByteDelimiter([3, 4, 5])
+        }, (err: any) => {});
+
+    const port5 = new SerialPort('', {
+            autoOpen: false,
+            lock: false,
+            baudRate: 115200,
+            dataBits: 5,
+            stopBits: 2,
+            parity: 'odd',
+            rtscts: true,
+            xon: true,
+            xoff: true,
+            bufferSize: 1024,
+            platformOptions: {
+                vmin: 1,
+                vtime: 1
+            }
+        }, (err: any) => {});
+}
+
+function test_write() {
+    const port = new SerialPort('');
+    port.write('main screen turn on', (err, bytesWritten) => {});
+}
+
+function test_events() {
+    const port = new SerialPort('');
+    port.on('open', () => {});
+}
+
+function test_list_ports() {
+    SerialPort.list((err: string, ports: SerialPort.PortConfig[]) => {});
+}

types/serialport/v4/tsconfig.json

@@ -0,0 +1,26 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "baseUrl": "../../",
+        "typeRoots": [
+            "../../"
+        ],
+        "paths": {
+            "serialport": ["serialport/v4"]
+        },
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "serialport-tests.ts"
+    ]
+}

types/serialport/v4/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }