Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

give advice on read-only lists #50

Open
dbaron opened this issue Feb 22, 2017 · 8 comments
Open

give advice on read-only lists #50

dbaron opened this issue Feb 22, 2017 · 8 comments
Assignees
Labels
Status: In Progress We're working on it but ideas not fully formed yet.

Comments

@dbaron
Copy link
Member

dbaron commented Feb 22, 2017

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 torgo added the Status: In Progress We're working on it but ideas not fully formed yet. label Jul 26, 2017
@torgo
Copy link
Member

torgo commented Apr 6, 2018

We agreed we should keep this open but lower priority.

@hober
Copy link
Contributor

hober commented May 7, 2020

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

@dbaron
Copy link
Member Author

dbaron commented May 28, 2020

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
Copy link
Contributor

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
Copy link
Member

domenic commented May 29, 2020

Always sequence for method arguments.

@dbaron
Copy link
Member Author

dbaron commented Sep 24, 2020

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

@atanassov
Copy link
Contributor

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
Copy link
Member

domenic commented Sep 24, 2020

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

@plinss plinss added this to the 2021-02-01-week milestone Feb 1, 2021
@plinss plinss assigned atanassov and unassigned dbaron Feb 1, 2021
@torgo torgo added the Status: Consensus to write We have TAG consensus about the principle but someone needs to write it (see "To Write" project) label Feb 1, 2021
atanassov added a commit that referenced this issue Mar 3, 2021
The added recommendation is about the types of static lists to be considered for API design.
Addresses #50
@atanassov atanassov removed the Status: Consensus to write We have TAG consensus about the principle but someone needs to write it (see "To Write" project) label Mar 3, 2021
atanassov added a commit that referenced this issue May 13, 2021
* Add advice about read-only lists

The added recommendation is about the types of static lists to be considered for API design.
Addresses #50

* Addressing CR feedback

* One last nit addressed
hober pushed a commit that referenced this issue Apr 20, 2023
* Add advice about read-only lists

The added recommendation is about the types of static lists to be considered for API design.
Addresses #50

* Addressing CR feedback

* One last nit addressed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Status: In Progress We're working on it but ideas not fully formed yet.
Projects
None yet
Development

No branches or pull requests

7 participants