Can we agree on a list of design goals for the README?

[brad4d]

tl;dr - There is no list of design goals in the README.md, but I think that is really needed in order to make a case for this proposal being worth the implementation cost.

If we already had Records and Tuples today as they are defined in this proposal,
what would the concrete benefits be for JS developers?

Just having deeply immutable data structures built into the language isn't enough of an answer.
If we had them, what could you really do with them that would be a big improvement on the current state of things?

Here are some of the benefits I've come up with.

1. 100% confidence that an immutable thing you create cannot ever be modified accidentally, so you can safely pass it into whatever methods you like without fear.

   • Would adding a convenient Object.deepFreeze() method to the language, maybe with a convenient syntax for automatically doing it, be sufficient to get this benefit?

2. Structured keys for Maps and Sets would be really convenient.

   • Would https://github.com/tc39/proposal-richer-keys/tree/master/collection-rekey be a more direct way to address this problem?

3. Passing complex data across realm boundaries without having to marshal / unmarshal it into a string or something like that.

   • Are shared array buffers a better (faster) choice?

4. Equality comparison for large data structures that does not require customized JS code.

   • Couldn't we get this with a method something like Object.deepHasSameOwnProperties(obj1, obj2) that could be called on deeply-frozen objects?
   • When would it really be useful?
     • I could see it being useful for writing unit tests for code that builds such values.
     • NOTE: I've intentionally kept this separate from the "structured keys" benefit, because this isn't necessary to get that.

5. Really fast equality comparison for large data structures. (Already deemed too expensive.)

I feel a gut-level inclination to like this proposal, but I've been having trouble convincing myself that the inclination is really justified. Help me out here.

Let's document some really compelling use-cases in the README and explicitly enumerate what features they require.

[rricard]

Hi @brad4d, thank you for raising this, all of the things you are discussing here are things we already presented on previously either in talks, to the committee or to delegates but it is true that we did let the README rot a bit and it could benefit from bringing those resources in there so we can immediately see the benefits of the proposal clearly and why we think the deep immutability aspect is interlinked with the deep equality aspect.

[shicks]

Speaking to point 2:

The rekey proposal is complementary to R&T - without it, at best you're stuck with having to do some horrible string-encoding in the key function, which isn't great.

That said, if we had rekey then you could potentially get by with just tuples, which might be easier to get through since it seems like the records part has a disproportionate share of the concerns.