I guess I don't really understand why it's better to have objects created explicitly in JS rather than "magically" by the UA. We could have device enumeration just return a dictionary for each device, including a unique identifier for each one, and then let the user construct a USBDevice object over one of those identifiers? And we could do the same for each interface, alternate, endpoint, etc. But what is the advantage to doing this? It seems like the API would be more annoying to use in that case.

Any further thoughts on this? Note that devices don't have any inherent, reliable unique identifier, and even if they did we wouldn't want to expose it through the API. Adding a constructor for USBDevice would mean the UA would have to provide some artificial notion of a device identifier. I am wary of doing anything like that because it's hard to make guarantees about the stability of that identifier under certain conditions (i.e. device detach and reattach), and in turn it's easy for developers to make bad assumptions about the stability of that identifier.

Though even without device IDs, the other types could trivially get constructors that take a device object and some numbers; so pending further feedback, I'll make that addition now.

I guess I don't really understand why it's better to have objects created explicitly in JS rather than "magically" by the UA.

Well, in general reducing the magic in the platform to a small core is ideal.

We could have device enumeration just return a dictionary for each device, including a unique identifier for each one, and then let the user construct a USBDevice object over one of those identifiers?

No need to return a dictionary; you can return the constructed object. But from what you describe, it'd be perfectly possible to have a working JavaScript-exposed USBDevice constructor that takes a dictionary. If that's possible, then you have a (non-magical) explanation for where USBDevice instances come from, which is great!

And we could do the same for each interface, alternate, endpoint, etc. But what is the advantage to doing this? It seems like the API would be more annoying to use in that case.

Definitely no need to make it more annoying. Return actual class instances. But if those classes don't require any UA-provided data to be initialized, and can instead be initialized from simple dictionaries, then JS should be allowed to do so too!

Any further thoughts on this? Note that devices don't have any inherent, reliable unique identifier, and even if they did we wouldn't want to expose it through the API. Adding a constructor for USBDevice would mean the UA would have to provide some artificial notion of a device identifier. I am wary of doing anything like that because it's hard to make guarantees about the stability of that identifier under certain conditions (i.e. device detach and reattach), and in turn it's easy for developers to make bad assumptions about the stability of that identifier.

OK, that's a perfectly good example of the "core magic" that we'd just need to keep.

Though even without device IDs, the other types could trivially get constructors that take a device object and some numbers; so pending further feedback, I'll make that addition now.

Makes sense! I'll go review that PR.

Thanks. So actually I just had a discussion with Reilly and we've concluded that there are real benefits to having some notion of a device "instance ID" which remains stable for the lifetime of a device's connection to the host, so we are going to try to work with that approach and be explicit about its meaning in the spec. Zero magic!

We initially had a guid property on the device. Unfortunately in Chrome the same value was used across all renderers which didn't seem like a good idea so I remove it entirely. The correct option seems like creating a per-origin set of device IDs. This seems useful for communicating the desired device to a worker, for example. However these IDs aren't stable across disconnecting and reconnecting a device so the usefulness is limited.

In the current API a site can request all devices with navigator.usb.getDevices() and then do whatever matching they like, for example checking device serial numbers which while not guaranteed to be unique will be stable across reconnections.

Thoughts @domenic?

The other issue with adding a constructor for USBDevice is that in Chrome until getDevices() is called the renderer doesn't have any information on connected devices so a constructor would need to perform a synchronous IPC.

I think given that getDevices() performs roughly the same function as a USBDevice constructor and other objects such as USBConfiguration and USBInterface do have sensible constructors it is okay to not have a USBDevice constructor.

I think given that getDevices() performs roughly the same function as a USBDevice constructor and other objects such as USBConfiguration and USBInterface do have sensible constructors it is okay to not have a USBDevice constructor.

This sounds reasonable. In this case the decision is that it's explicitly impossible for author code to create USBDevice instances; that can only be done by the UA, on behalf of the author, in part because the UA needs to do it asynchronously.