Guidance on io typescript typing

[cmidgley]

(several edits since I first posted, all before any feedback)

I'm working on the typings for embedded:network/websocket/client, but it quickly devolved into needing to flush out other types. I have a few questions and likely will have more later, so it seemed appropriate to start a discussion.

For websocket/client:

• The onControl interface is inconsistent with the ECMA-419 specification, as the implementation returns a Uint8Array but the specification says it should be ArrayBuffer. I would prefer Uint8Array as the data is more immediately accessible but it's inconsistent with ECMA-419. Should this be changed to ArrayBuffer or should the spec change?
• The ECMA-419 spec says there should be a network.ws.client and network.wss.client with options on the "Host provider instance" (device) but they are currently missing, instead being used as network.ws and network.wss. I've left it for now as implemented, but either the spec or the implementation should be updated.
• I find using close difficult to use with the ECMA-419 definition. To get the close code and reason the consumer of the API must decode the payload with knowledge of the websocket packet format, and the consumer is also responsible for building a similar outbound message to close the connection correctly. It also leaves the definition of close codes and handling of network vs. non-network code usage as the consumer's responsibility. In a future update to the spec, it would be great to see close, with close codes and reasons, fully part of the interface with const definitions and types for the codes themselves. Let me know if I can help.

I've noticed that some io implementations do not use the embedded:xxx namespace, and at least some do not conform to the 2nd ECMA-419 spec. For example, sntp, which I was going to use but fell back on the legacy version for now since it didn't seem current. Am I correct in assuming I should ignore them if they are not part of embedded: and await updates? Or do you have advice on which io types are correct/current?

I find error handling difficult to work with in io. Most onError implementations have no error argument, making it difficult to diagnose failures. For example, I have a web socket getting an error during connection. I have no idea why or what module causing the error (since they cascade the error). The few places that implement an error argument use a string, rather than an Error object, which means there is no stack or attachments. Additionally, the strings themselves don't identify which module caused the error, are short, and are not necessarily unique. Not only does this make debugging difficult, it means I can't present any meaningful error to my users as to why something failed.

I find the directory structure of io confusing. The typings are fairly clean, but the implementations and examples are difficult to navigate. Some are in modules, some are in examples; some directory namespaces are significantly different than module namespace; it's not obvious which files in the examples set are test code vs. actual implementations. It would be great to clean up and unify the directory to be consistent with the namespace, and move core implementations into modules and out of examples.

I'll be doing a PR soon for further discussion and review. I've adjusted udp, tcp, tls, dns, websocket, and builtin - those that websocket depends upon - to be more comprehensive and usability. Similar work likely should be done on the other implemented types (I may do some of this before the PR). Some of the things I've done so far include:

• Moved Device into the global namespace, to pair with device being global.
• Augment the Device type when extended by modules, such as websocket/client that adds network
• Added a new xxxDevice type for several of the types that are the type used in device, to avoid the redundancy currently used to define these types. For example, you now import from dns a DNSUDPDevice type, and can use it for any place where dns is used within the Device type (or when augmenting types)
• Made option type names consistent and unique to the type, and exported them for external use.
• Reduced duplication of typing (by exporting and importing the associated types from their module-specific implementation files)

[cmidgley]

Closing as i’ve made progress on types (#1429) so the original reason for this discussion is resolved.