Typings for io module

[meganetaaan]

Hello,

Anyone who is trying to add type definitions for the io module?
If not, I'm going to make one.
I can look at the IO API is almost fixed. I think it's ready to be typed.

[phoddie]

The IO API is now an International standard! Please see Ecma-419 for the full text of the standard.

So, yes, the API is ready for TypeScript type declarations. ;) And having TypeScript declarations will help more developers to use Ecma-419.

I don't have the bandwidth to start creating the declarations myself, but I would be happy to help answer any questions and review the declarations.

I'm tagging @HipsterBrown and @cmidgley here as they may have an interest in this effort too.

[meganetaaan]

Alright. Thanks.

I've started to implement typings. Here is my first attempt at my repository.

During this work, I noticed there are several modules that are not documented on io docs such as SPI, System, and PulseCount. Are there experimental? Or stable but merely undocumented?

[phoddie]

That looks like a solid start. There's almost all I/O (except SPI and SMBus). You got many of the subtle details correct.

I noticed there are several modules that are not documented on io docs such as SPI, System, and PulseCount. Are there experimental? Or stable but merely undocumented?

The definitive documentation for IO is Ecma-419. The original IO document pre-dates the standard, which is confusing. Apologies. Both SPI and PulseCount are standardized in Ecma-419.

System is non-standard. It is temporary to support the IO examples. It contains a DNS resolver, which will be part of Ecma-419 2nd Edition. It also contains shims for setInterval and friends, which we are still deciding how to best handle.

I have some initial comments on the typings. This can be a little tricky, so please let me know if you have questions.

• You have Digital as an extension of DigitalBank. That is how the Moddable SDK implements it. But, it is not required. Each should be a standalone class.
• Digital define read correctly but does not define write (which accepts only 0 and 1).
• In DigitalBank the values of Input, etc are not part of the formal specification. They can vary by device. Ideally the values would not be in the type declaration.
• The read function of DigitalBank returns a number rather than void.
• DigitalBank has onReadable as an instance method? I'm not sure I understand. I think it should be enough to have onReadable as part of the constructor's options object.
• For Digital, I2C, Analog, PWM, and Serial the pin properties are not always a number. They are in the Moddable SDK implementation today, but... the specification calls them a "pin specifier" and allows them to be a string or even an object. It might make sense to define a pin specifier type to use in these places. It can be number today and can be extended in the future to support other implementations.
• In Serial the TypedArray has some unsupported types. The 1st Edition specification text is imperfect here. Multibyte array views are disallowed because there is a potential foot-gun with multiple-byte values due to endianness. The draft 2nd Edition text is better and I suggest you use that here.
• In Serial read, it is also allowed to pass in a buffer. See the description of read in the IO Class Pattern. (This applies to TCP, UDP, I2C, SPI as well)
• In Serial write it looks like you copied the optional stop argument from I2C.
• I2C read needs an argument (number or buffer, as described above) and optional stop argument
• The serial options object has many more optional properties (serial is so old that it has too many options!)
• I2C, Serial, and SPI all have an optional port property in their constructor options object. This is defined by a port specifier. In the Moddable SDK this can be a string (ESP8266) or number (ESP32). Like a pin specifier, they can also be an object.

BTW – I learned about the special this parameter to callback functions in TypeScript from studying your typings. Thank you!

[meganetaaan]

@phoddie Thank you for your feedback! The draft 2nd Edition text helped me a lot to type.
I've fixed it according to your comment and created a draft pull request so that you can feel easy to leave further comments. I tested that the Digital and Serial modules can be compiled and work with TypeScript. Still needs more tests.

[meganetaaan]

@phoddie When I tested to build /examples/io/spi/ili9341 with TypeScript I got this error.

main.ts:106:13 - error TS2345: Argument of type 'ArrayBufferLike' is not assignable to parameter of type 'Buffer'.
  Type 'HostBuffer' is not assignable to type 'Buffer'.
    Type 'HostBuffer' is missing the following properties from type 'Uint8ClampedArray': BYTES_PER_ELEMENT, buffer, byteOffset, copyWithin, and 25 more.

106   spi.write(pixels.buffer);
                ~~~~~~~~~~~~~

Should we accept HostBuffer as a member of "buffer" format arguments? How about other modules than SPI?

[phoddie]

Yes, a HostBuffer is accepted as a buffer. It is more-or-less equivalent to SharedArrayBuffer. For details see this blog post Best Practices for Accessing Memory Buffers from Native Code with the XS JavaScript Engine. Our ECMA-419 implementations all use the xsmcGetBuffer* calls described there to access JavaScript buffers for read and write.