WebHID: methods which write (sendReport) to the device should be async

[loucadufault]

The implementation of the generic write() method which is called by the various XKeys methods (e.g. setting backlights) is asynchronous in nature, yet resolves synchronously before the promise returned by the underlying call to sendReport() has resolved:

xkeys/packages/webhid/src/web-hid-wrapper.ts

Lines 24 to 32 in e9d925e

	public write(data: number[]): void {
	this.reportQueue
	.add(async () => {
	await this.device.sendReport(data[0], new Uint8Array(data.slice(1)))
	})
	.catch((err) => {
	this.emit('error', err)
	})
	}

Promise rejections are handled by emitting them as error events.

This forces usage of the API to always have an error listener registered for the duration of the program in order for the code to be safe; if the listener is removed at any point, it is possible that a pending promise rejects and emits an error event which would be unhandled.

This makes it near impossible to clean up an XKeys object by calling methods on it such as setAllBacklights() before un-registering the listeners such that it can be GC'd:

// setup
const xKeys = setupXKeysPanel(device)
const errorListener = (e) => console.error(e)
xKeys.on('error', errorListener)

// ... later, after an abnormal event
// cleanup
xKeys.setAllBacklights(false)
xKeys.removeListener('error', errorListener)
// the promise indirectly created from the call to `setAllBacklights` resolves at some point after the synchronous code, when the error listener has already been un-registered

A workaround is to keep the listener registered for an arbitrary amount of time to handle any pending promises:

// cleanup
xKeys.setAllBacklights(false)
setTimeout(() => xKeys.removeListener('error', errorListener), 5000)

A proper solution would be to allow checking that all sendReport promises have settled before cleaning up the device, which would entail making the API methods async.

[nytamin]

After some consideration, I propose these changes to address this:

• Add a flush(): Promise<void> method to wait for any lingering writes.
• Also: Once close() is called, promise to never emit any errors anymore.

With these changes, you should be able to acheive a proper cleanup like so:

const xKeys = setupXKeysPanel()
const errorListener = (e) => console.error(e)
xKeys.on('error', errorListener)

xKeys.setAllBacklights(false)

// cleanup:
await xKeys.flush() // waits for all writes to finish
await xKeys.close() // close the device.
xKeys.off('error', errorListener)