feat: Added support for user defined host UDP port and IP address

Modified discover function signatures so that `options` is the first parameter and it can also be a number (`timeout`) to provide backwards compatibility

fix #20

Author: maszaa

README.md

@@ -76,26 +76,26 @@ The `heos` object has two ways of finding devices and one way to connect to a de
 -   `heos.discoverOneDevice()`
 -   `heos.connect()`
 
-#### heos.discoverDevices(timeout, onDiscover[, onTimeout])
+#### heos.discoverDevices(options, onDiscover[, onTimeout])
 
--   `timeout`: number
+-   `options`: { timeout?: number, port?: number, address?: string } || number
 -   `onDiscover`: (address: string) => void
 -   `onTimeout`: (addresses: string[]) => void
 
-Tries to discover all available HEOS devices in the network. When `timeout` milliseconds have passed the search will end. Every time a HEOS device is discovered `onDiscover(address)` will be triggered, where `address` is the ip-address of the device found. When the search ends `onTimeout(addresses[])` will be triggered with an array with all the devices found.
+Tries to discover all available HEOS devices in the network. `port` and `address` of `options` is for connecting to a user specified network interface. When `options.timeout` or `options` (type `number`) milliseconds have passed the search will end. Every time a HEOS device is discovered `onDiscover(address)` will be triggered, where `address` is the ip-address of the device found. When the search ends `onTimeout(addresses[])` will be triggered with an array with all the devices found.
 
 The function does not return a value.
 
 ```js
-heos.discoverDevices(5000, console.log)
-// Logs out the addresses of every HEOS device in the network
+heos.discoverDevices({ timeout: 3000 }, console.log, () => {})
+// Logs out the addresses of every HEOS device in the network, and will end search after 3 seconds
 ```
 
-#### heos.discoverOneDevice([timeout])
+#### heos.discoverOneDevice([options])
 
--   `timeout`: number
+-   `options`: { timeout?: number, port?: number, address?: string } || number
 
-Finds one HEOS device in the network. A promise is returned that will resolve when the first device is found, or reject if no devices are found before `timeout` milliseconds have passed. If the function resolves it will resolve with the address of the HEOS device found.
+Finds one HEOS device in the network. `port` and `address` of `options` is for connecting to a user specified network interface. A promise is returned that will resolve when the first device is found, or reject if no devices are found before `options.timeout` or `options` (type `number`) milliseconds have passed. If the function resolves it will resolve with the address of the HEOS device found.
 
 `heos.discoverDevices()` is used under the hood
 
@@ -104,11 +104,11 @@ heos.discoverOneDevice().then(console.log)
 // Logs out the address of a HEOS device
 ```
 
-#### heos.discoverAndConnect([timeout])
+#### heos.discoverAndConnect([options])
 
--   `timeout`: number
+-   `options`: { timeout?: number, port?: number, address?: string } || number
 
-Finds one HEOS device in the network, and connects to it. A promise is returned that will resolve when the first device is found, or reject if no devices are found before `timeout` milliseconds have passed. If the function resolves it will resolve with a HeosConnection.
+Finds one HEOS device in the network, and connects to it. `port` and `address` of `options` is for connecting to a user specified network interface. A promise is returned that will resolve when the first device is found, or reject if no devices are found before `options.timeout` or `options` (type `number`) milliseconds have passed. If the function resolves it will resolve with a HeosConnection.
 
 ```js
 heos.discoverAndConnect().then(console.log)

__tests__/connection/discover.ts

@@ -11,12 +11,19 @@ describe('discoverOneDevice()', () => {
 		return expect(discoverOneDevice()).resolves.toEqual('192.168.0.5')
 	})
 
+	test('One device can be discovered with options', () => {
+		expect.assertions(1)
+		return expect(discoverOneDevice({ address: '192.168.0.1', timeout: 10 })).resolves.toEqual(
+			'192.168.0.5'
+		)
+	})
+
 	test('Discover fails when no devices are found', () => {
 		expect.assertions(1)
 		// @ts-ignore
 		dgram.__setOn(() => {})
 
-		return expect(discoverOneDevice(10)).rejects.toEqual('No devices found')
+		return expect(discoverOneDevice({ timeout: 10 })).rejects.toEqual('No devices found')
 	})
 
 	test('discoverOneDevice only returns one address even if multiple devices are found', () => {

src/connection/discover.ts

@@ -20,21 +20,31 @@ type RInfo = {
 	size: number
 }
 
+export type DiscoverOptions = {
+	timeout?: number
+	port?: number
+	address?: string
+}
+
 const defaultTimeout = 5000
 
 /**
  * Tries to discover all available HEOS devices in the network.
- * @param timeout Will stop searching for HEOS devices when `timeout` milliseconds has ellapsed.
+ * @param options Options for discovering devices.
  * @param onDiscover Will trigger every time a HEOS device is discovered.
  * @param onTimeout Will trigger when `timeout` has ellapsed.
  */
 export function discoverDevices(
-	timeout: number = defaultTimeout,
+	options: DiscoverOptions | number,
 	onDiscover: (address: string) => void,
 	onTimeout?: (addresses: string[]) => void
 ): () => void {
+	const timeout: number =
+		typeof options === 'number' ? options || defaultTimeout : options.timeout || defaultTimeout
+
 	const socket = createSocket('udp4')
-	socket.bind()
+
+	typeof options !== 'number' ? socket.bind(options.port, options.address) : socket.bind()
 
 	socket.on('listening', () => {
 		socket.send(message, 1900, '239.255.255.250')
@@ -65,10 +75,12 @@ export function discoverDevices(
 
 /**
  * Finds one HEOS device in the network.
- * @param timeout Will stop searching for a HEOS device when `timeout` milliseconds has ellapsed.
+ * @param options Options for discovering a device.
  * @returns A promise that will resolve when the first device is found, or reject if no devices are found before `timeout` milliseconds have passed. If the function resolves it will resolve with the address of the HEOS device found.
  */
-export function discoverOneDevice(timeout: number = defaultTimeout): Promise<string> {
+export function discoverOneDevice(
+	options: DiscoverOptions | number = defaultTimeout
+): Promise<string> {
 	return new Promise((resolve, reject) => {
 		let oneDiscovered: boolean = false
 
@@ -88,18 +100,20 @@ export function discoverOneDevice(timeout: number = defaultTimeout): Promise<str
 			}
 		}
 
-		const quit = discoverDevices(timeout, onDiscover, onTimeout)
+		const quit = discoverDevices(options, onDiscover, onTimeout)
 	})
 }
 
 /**
  * Finds one HEOS device in the network, and connects to it.
- * @param timeout Will stop searching for a HEOS device when `timeout` milliseconds has ellapsed.
+ * @param options Options for discovering a device.
  * @returns A promise that will resolve when the first device is found, or reject if no devices are found before `timeout` milliseconds have passed. If the function resolves it will resolve with a HeosConnection.
  */
-export function discoverAndConnect(timeout: number = defaultTimeout): Promise<HeosConnection> {
+export function discoverAndConnect(
+	options: DiscoverOptions | number = defaultTimeout
+): Promise<HeosConnection> {
 	return new Promise((resolve, reject) => {
-		discoverOneDevice(timeout)
+		discoverOneDevice(options)
 			.then(connect)
 			.then(resolve)
 			.catch(reject)