[whatwg/webidl] Specify best practices for sequence/FrozenArray/ObservableArray (Issue #1495)

tabatkins created an issue (whatwg/webidl#1495)

### What is the issue with the Web IDL Standard?

There's a *lot* of legacy APIs that were created before ObservableArray was added, so we have a panoply of behaviors across the web. It's very difficult for spec authors to know which of the three types they should use for representing some array value.

I think the basic summary of best practices is:

1. If you want to expose an array, and the values won't change from author *or* UA action, use a read-only `FrozenArray`.
2. If you want to expose an array, and the values are changeable from author action (and possibly from UA action), use an `ObservableArray`.
3. If you want to expose an array, and the values are only changeable from UA action, choose between a read-only `FrozenArray` (especially if authors will want to poll the values frequently) and a method that returns a `sequence`. Consider exposing a promise-returning method to let authors wait for updates, if changes are infrequent, so they don't have to poll. (Frequently-changing values are fine to poll for, usually.)

Notably, I think best practice should warn against using a mutable FrozenArray; this was used in the past to allow replacing the value *wholesale* (there's even an example of that exact behavior in [the FrozenArray section](https://webidl.spec.whatwg.org/#idl-frozen-array)), but if you allow replacing all of the items, you should allow replacing individual items as well, and just use an ObservableArray.

Thoughts?

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/webidl/issues/1495
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/webidl/issues/1495@github.com>