Definitions for W3C's Web Locks API - browser externs #4156
Conversation
| * @param {string} name | ||
| * @param {!LockOptions|!LockGrantedCallback} options | ||
| * @param {!LockGrantedCallback|undefined=} callback | ||
| * @return {!Promise<void>} |
There was a problem hiding this comment.
Should this be either !Promise<*> or !Promise<?>, as https://www.w3.org/TR/web-locks/#api-lock-manager has this returning Promise<any>?
!Promise<*> seems safer as it forces people to typecast the result before using it, but OTOH https://github.com/microsoft/TypeScript/blob/main/src/lib/dom.generated.d.ts has Promise<any> which is equivalent to Promise<?>, and we're generally trying to maintain compatibility with the TS typings
|
|
||
|
|
||
| /** | ||
| * @typedef {function(!Lock): !Promise<void>} |
There was a problem hiding this comment.
Similar to above, should this be !Promise<?> (or !Promise<*>)? https://www.w3.org/TR/web-locks/#api-lock-manager
|
|
||
| /** | ||
| * @typedef {{ | ||
| * mode : !LockMode, |
There was a problem hiding this comment.
From my understanding of the spec language, these should all be optional |undefined as they're not explicitly specified as required
There was a problem hiding this comment.
They are required, each member of LockInfo has defined non-nullable type and none is marked as optional - that is explicit requirement. LockInfo itself is then specified as non-nullable and not optional type in non-nullable and not optional sequence that defines both members of LockManagerSnapshot and thus making them also explicitly required. None in this chain can be optional or even undefined:
In the JavaScript binding, a value of undefined for the property corresponding to a dictionary member is treated the same as omitting that property.
Now those sequences of LockManagerSnapshot are zero-length by default (no locks held or pending) and can be zero-length at any point in time, but even then they are not optional. So putting in all together the promise of query() method not only cannot reject, but also when it resolves it must always resolve to LockManagerSnapshot with both members present, even if they are just empty arrays.
And so it does:
|
|
||
| /** | ||
| * @typedef {{ | ||
| * held : !Array<!LockInfo>, |
There was a problem hiding this comment.
Same comment about |undefined as in LockInfo
Added browser externs for Web Locks API - based on definitions from latest W3C draft
. The coverage is already great and API synergy with web workers cannot be overstated. Feel free to poke holes in it.