give advice on read-only lists

[dbaron]

In a comment on #47, which created the section on live versus static objects, @domenic wrote:

Maybe not as part of this PR or even this section, but a common point of confusion is the case of "read only lists" (where only the implementation can change them). Currently we tend to recommend people return static snapshots as arrays (for methods, when they change frequently) or frozen arrays (for attributes, when they change infrequently). It's not the best solution, compared to some kind of real read-only array type, but we tend to be going in that direction. Notably we are moving away from creating various fake-array types like NodeList or StyleSheetList for this purpose.

[torgo]

We agreed we should keep this open but lower priority.

[hober]

This continues to be something that people run into; see WICG/construct-stylesheets#45 for instance.

[dbaron]

So it's not clear to me what we need to recommend about sequence<T> versus FrozenArray<T> versus ObservableArray<T>... or for that matter how stable and widely adopted the latter two are.

It also seems that the notion of returning static snapshots that the initial comment here suggests was the problem in WICG/construct-stylesheets#45 because that case required an API for mutation, so I think we have at least some evidence that static snapshots aren't a good API for mutation. I think this aligns with the existing advice on live versus static objects which I think is relevant here (particularly the bit about how things that are the way state is mutated should be live).

Is the intent of ObservableArray<T> that it can replace all of these custom array classes in the case where mutation is needed? That's what it looks like from a quick skim.

[marcoscaceres]

Sorry if this is covered already (it's kinda hinted at in the OP)... there is also cases I've seen where FrozenArray<T> have been specified to be passed as method arguments:

  // PaymentDelegation is just a dictionary or whatever
  Promise<void> enableDelegations(FrozenArray<PaymentDelegation> delegations);

What's the right thing to use above? A FrozenArray or sequence?

[domenic]

Always sequence for method arguments.

[dbaron]

There appears to be a good bit of useful background for this in heycam/webidl#796.

[atanassov]

Upon further discussion with @dbaron as part of our Cork virtual f2f the following recommendation should be considered and made. What are the recommended list types used for:

1. Function parameters - from comment above it should be sequence<T>
2. Attributes - ObservableArray<T> must only be use with attributes, what about FrozenArray<T> and when?
3. Return values - given that return values are closer to attributes than function parameters, should the recommendation align with 2? If not (as the initial comment says), what would static snapshots of arrays mean in current types?

[domenic]

Return values from methods should be sequences; those give static snapshots of arrays.