feat: new binding interface (#19)

- We now only return a port object if it's open and list and open methods are now exported on an interface
- hardware tests now work and only require a loopback (no ready event)
- Test pass on darwin (not on mock - it's not up to date yet and coverage is going to drop)
- cleanup up tests with modern javascript
- Breaking - change the names of the exported types
- No more constructors, now all binding specicific open options are specificd on open
- Arduino test file for loopback

Author: reconbot

README.md

@@ -31,6 +31,7 @@ The Bindings provide a low level interface to work with your serialport. It is p
 1. Clone this repo `git clone [email protected]:serialport/bindings-cpp.git`
 1. Run `npm install` to setup local package dependencies (run this any time you depend on a package local to this repo)
 1. Run `npm test` to ensure everything is working properly
+1. If you have a serial loopback device (TX to RX) you can run run `TEST_PORT=/path/to/port npm test` for a more comprehensive test suite. (Defaults to 115200 baud customize with the TEST_BAUD env.) You can use an arduino with the `test/arduino-echo` sketch.
 
 ### Developing Docs
 

lib/binding-interface.test.ts

@@ -14,24 +14,28 @@ export interface PortInfo {
 }
 
 export interface OpenOptions {
+  /** The path of the port */
+  path: string
   /** The baud rate of the port to be opened. This should match one of the commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, or 115200. Custom rates are supported best effort per platform. The device connected to the serial port is not guaranteed to support the requested baud rate, even if the port itself supports that baud rate. */
   baudRate: number
-  /** Must be one of these: 8, 7, 6, or 5  */
-  dataBits: 8 | 7 | 6 | 5
-  /** Prevent other processes from opening the port. Windows does not currently support `false`. */
-  lock: boolean
-  stopBits: 1 | 2
-  parity: 'none' | 'event' | 'mark' | 'odd' | 'space'
-  /** Flow control Setting */
-  rtscts: boolean
-  /** Flow control Setting */
-  xon: boolean
-  /** Flow control Setting */
-  xoff: boolean
-  /** Flow control Setting */
-  xany: boolean
-  /** drop DTR on close */
-  hupcl: boolean
+  /** Must be one of these: 8, 7, 6, or 5 defaults to 8 */
+  dataBits?: 8 | 7 | 6 | 5
+  /** Prevent other processes from opening the port. Windows does not currently support `false`. Defaults to true */
+  lock?: boolean
+  /** defaults to 1 - TODO should be a string */
+  stopBits?: 1 | 2 | 3
+  /** Device parity defaults to none */
+  parity?: 'none' | 'event' | 'mark' | 'odd' | 'space'
+  /** Flow control Setting. Defaults to false */
+  rtscts?: boolean
+  /** Flow control Setting. Defaults to false */
+  xon?: boolean
+  /** Flow control Setting. Defaults to false */
+  xoff?: boolean
+  /** Flow control Setting defaults to false*/
+  xany?: boolean
+  /** drop DTR on close. Defaults to true */
+  hupcl?: boolean
 }
 
 export interface UpdateOptions {
@@ -56,39 +60,28 @@ export interface PortStatus {
 /**
  * You never have to use `Binding` objects directly. SerialPort uses them to access the underlying hardware. This documentation is geared towards people who are making bindings for different platforms. This interface is implemented in all bindings.
  */
-export abstract class BindingInterface {
-  /**
-    Retrieves a list of available serial ports with metadata. The `path` must be guaranteed, and all other fields should be undefined if unavailable. The `path` is either the path or an identifier (eg `COM1`) used to open the serialport.
-   */
-  static async list(): Promise<PortInfo[]> {
-    throw new Error('Method not implemented.')
-  }
-
+export interface BindingPortInterface {
+  readonly openOptions: Required<OpenOptions>
   /**
    * Required property. `true` if the port is open, `false` otherwise. Should be read-only.
    */
-  abstract isOpen: boolean
-
-  /**
-   * Opens a connection to the serial port referenced by the path.
-   */
-  abstract open(path: string, options?: OpenOptions): Promise<void>
+  isOpen: boolean
 
   /**
    * Closes an open connection
    */
-  abstract close(): Promise<void>
+  close(): Promise<void>
 
   /**
-    Request a number of bytes from the SerialPort. This function is similar to Node's [`fs.read`](http://nodejs.org/api/fs.html#fs_fs_read_fd_buffer_offset_length_position_callback) except it will always return at least one byte.
+    Request a number of bytes from the SerialPort. This function is similar to Node's [`fs.read`](http://nodejs.org/api/fs.html#fs_fs_read_fd_buffer_offset_length_position_callback) as it will attempt to read up to `length` number of bytes. This function has a guarantee that it will always return at least one byte. This leverages os specific polling or async reads so you don't have to.
 
     The in progress reads must error when the port is closed with an error object that has the property `canceled` equal to `true`. Any other error will cause a disconnection.
 
    * @param offset The offset in the buffer to start writing at.
    * @param length Specifies the maximum number of bytes to read.
    * @returns {Promise} Resolves with the number of bytes read after a read operation.
    */
-  abstract read(buffer: Buffer, offset: number, length: number): Promise<{ buffer: Buffer; bytesRead: number }>
+  read(buffer: Buffer, offset: number, length: number): Promise<{ buffer: Buffer; bytesRead: number }>
 
   /**
   Write bytes to the SerialPort. Only called when there is no pending write operation.
@@ -97,39 +90,51 @@ export abstract class BindingInterface {
 
   Resolves after the data is passed to the operating system for writing.
    */
-  abstract write(buffer: Buffer): Promise<void>
+  write(buffer: Buffer): Promise<void>
 
   /**
     Changes connection settings on an open port.
    */
-  abstract update(options: UpdateOptions): Promise<void>
+  update(options: UpdateOptions): Promise<void>
 
   /**
    * Set control flags on an open port.
    * All options are operating system default when the port is opened. Every flag is set on each call to the provided or default values.
    */
-  abstract set(options: SetOptions): Promise<void>
+  set(options: SetOptions): Promise<void>
 
   /**
    * Get the control flags (CTS, DSR, DCD) on the open port.
    */
-  abstract get(): Promise<PortStatus>
+  get(): Promise<PortStatus>
 
   /**
    * Get the OS reported baud rate for the open port.
    * Used mostly for debugging custom baud rates.
    */
-  abstract getBaudRate(): Promise<{ baudRate: number }>
+  getBaudRate(): Promise<{ baudRate: number }>
 
   /**
    * Flush (discard) data received but not read, and written but not transmitted.
    * Resolves once the flush operation finishes.
    */
-  abstract flush(): Promise<void>
+  flush(): Promise<void>
 
   /**
    * Drain waits until all output data is transmitted to the serial port. An in progress write should be completed before this returns.
    * Resolves once the drain operation finishes.
    */
-  abstract drain(): Promise<void>
+  drain(): Promise<void>
+}
+
+export interface BindingInterface<Port extends BindingPortInterface = BindingPortInterface, Open extends OpenOptions = OpenOptions> {
+  /**
+    Retrieves a list of available serial ports with metadata. The `path` must be guaranteed, and all other fields should be undefined if unavailable. The `path` is either the path or an identifier (eg `COM1`) used to open the serialport.
+   */
+  list(): Promise<PortInfo[]>
+  /**
+   * Opens a connection to the serial port referenced by the path.
+   */
+  open(options: Open): Promise<Port>
+
 }