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

domenic left a comment (whatwg/webidl#1495)

I think this is the current state of things:

1. If you want to expose an array, and the values won't change from author or UA action, use a readonly FrozenArray attribute.
2. If you want to expose an array whose values can only change from UA action, use a readonly ObservableArray attribute with throwing "set an indexed value" and "delete an indexed value" algorithms
3. If you want to expose an array whose values can change from author (and possibly UA) action, use a non-readonly ObservableArray attribute with appropriately-validating "set an indexed value" and "delete an indexed value" algorithms
4. If you want to get a snapshot of values at a given time, use a method that returns a sequence. Note that this is the only suitable choice if your values are dictionaries, because dictionaries are inherently snapshots.

Historical notes and subtleties:

- The only author-facing difference between a FrozenArray and an ObservableArray-with-throwing-algorithms is whether `Object.isFrozen(a)` returns true or false. It's not really clear whether this is important; if we abandon this, then we could eliminate (1) in favor of lumping it in with (2).
- Historically people have used FrozenArray attributes for case (2) and (3) because ObservableArray didn't exist. Nobody seems to want to take the time to convert.
- We vaguely envisioned introducing a ReadonlyArray type for case (2) as a specification authoring device. That is part of why all the examples in the ObservableArray section are for case (3). This has kind of stalled, but wouldn't be too hard to do, so I'm unsure whether to give up on it and encourage ObservableArray, or just keep hoping that someday someone will make the time.
- Apart from that, the specification-writing experience for ObservableArray is, IMO, very good. The "backing list", "set an indexed value", and "delete an indexed value" concepts are easy to work with, and the way in which they only work with attributes simplifies things greatly. In contrast, the specification-writing experience for FrozenArray is not great, as it's trying to pretend to be a generic type, and spec authors have to do a lot of work manually. https://github.com/whatwg/webidl/issues/810#issuecomment-538651524 is a relatively-recent take on how this could be improved, and https://github.com/whatwg/webidl/pull/1413 laid some of the groundwork.
- None of these technologies work for if you want to add methods to your array (e.g., an `item()` method). (The feature request is #1342)

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

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