Merge pull request #5 from tc39/fix/cleanup

revise readme to reflect new direction

Author: peetklecha

README.md

@@ -6,37 +6,33 @@ Stage 2
 
 **Champions:**
 
-- Rick Button (Bloomberg)
 - Nicolò Ribaudo (Igalia)
 - Ashley Claymore (Bloomberg)
 - Peter Klecha (Bloomberg)
 
 ## Overview
 
-This proposal complements the [Records and Tuples Proposal][rec-tup-proposal].
-It was originally part of that proposal but split off into a separate proposal to reduce the scope of the core Records and Tuples proposal. [#330](https://github.com/tc39/proposal-record-tuple/issues/330)
-
-The problem being explored is ergonomic and efficient creation of a deeply immutable data structure from a [JSON][json-mdn] string.
+This proposal identifies a need in ECMAScript for a function which parses [JSON][json-mdn] strings but returns deeply immutable objects. The current state of the proposal is to add a `JSON.parseImmutable` function to the specification which takes a string and optionally a reviver function, and returns an object which is deeply frozen, i.e., an object which is configured as if [`Object.freeze`][object-freeze-mdn] had been recursively called on it.
 
 ```javascript
-JSON.parse(data, (key, value) => {
-  if (typeof value === 'object' && value !== null) {
-      if (Array.isArray(value)) {
-        return Tuple.from(value);
-      } else {
-        return Record(value);
-      }
-  }
-  return value;
-});
+const obj = JSON.parseImmutable('{ "one": { "two": 3 } }');
+assert(Object.isFrozen(obj));
+assert(Object.isFrozen(obj.one));
 ```
 
-Could be replaced with:
+To achieve a similar result today a reviver can be used:
 
 ```javascript
-JSON.parseImmutable(data);
+JSON.parse(data, (key, value) => Object.freeze(value));
 ```
 
+But a native implementation could be much faster than a reviver-based implementation, and static analysis would greatly benfit from the knowledge that the result of `JSON.parseImmutable` is always deeply frozen.
+
+## History
+
+This proposal was originally part of the [Records and Tuples Proposal][rec-tup-proposal] but split off into a separate proposal to reduce the scope of the core Records and Tuples proposal. [#330](https://github.com/tc39/proposal-record-tuple/issues/330). At this point the proposal was that the `JSON.parseImmutable` function would return a Record or a Tuple, those being the two types proposed by the Records and Tuples Proposal. The Records and Tuples Proposal was withdrawn, requiring a change of scope for this proposal.
+
 <!-- References -->
 [rec-tup-proposal]: https://github.com/tc39/proposal-record-tuple
 [json-mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON
+[object-freeze-mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze

index.html

@@ -2524,7 +2524,7 @@
 </ul></div><div id="menu-toggle"><svg xmlns="http://www.w3.org/2000/svg" style="width:100%; height:100%; stroke:currentColor" viewBox="0 0 120 120">
       <title>Menu</title>
       <path stroke-width="10" stroke-linecap="round" d="M30,60 h60  M30,30 m0,5 h60  M30,90 m0,-5 h60"></path>
-    </svg></div><div id="menu-spacer"></div><div id="menu"><div id="menu-search"><input type="text" id="menu-search-box" placeholder="Search..."><div id="menu-search-results" class="inactive"></div></div><div id="menu-pins"><div class="menu-pane-header">Pins</div><ul id="menu-pins-list"></ul></div><div class="menu-pane-header">Table of Contents</div><div id="menu-toc"><ol class="toc"><li><span class="item-toggle">◢</span><a href="#sec-structured-data" title="Structured Data"><span class="secnum">1</span> Structured Data</a><ol class="toc"><li><span class="item-toggle">◢</span><a href="#sec-json-object" title="The JSON Object"><span class="secnum">1.1</span> The JSON Object</a><ol class="toc"><li><span class="item-toggle">◢</span><a href="#sec-json.parse" title="JSON.parse ( text [ , reviver ] )"><span class="secnum">1.1.1</span> JSON.parse ( <var>text</var> [ , <var>reviver</var> ] )</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-parsejsontext" title="ParseJSONText ( text )"><span class="secnum">1.1.1.1</span> <ins>ParseJSONText ( <var>text</var> )</ins></a></li></ol></li><li><span class="item-toggle">◢</span><a href="#sec-json.parseimmutable" title="JSON.parseImmutable ( text [ , reviver ] )"><span class="secnum">1.1.2</span> <ins>JSON.parseImmutable ( <var>text</var> [ , <var>reviver</var> ] )</ins></a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-buildimmutableproperty" title="BuildImmutableProperty ( value, name, reviver )"><span class="secnum">1.1.2.1</span> <ins>BuildImmutableProperty ( <var>value</var>, <var>name</var>, <var>reviver</var> )</ins></a></li></ol></li><li><span class="item-toggle">◢</span><a href="#sec-json.stringify" title="JSON.stringify ( value [ , replacer [ , space ] ] )"><span class="secnum">1.1.3</span> JSON.stringify ( <var>value</var> [ , <var>replacer</var> [ , <var>space</var> ] ] )</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-serializejsonproperty" title="SerializeJSONProperty ( state, key, holder )"><span class="secnum">1.1.3.1</span> SerializeJSONProperty ( <var>state</var>, <var>key</var>, <var>holder</var> )</a></li></ol></li></ol></li></ol></li><li><span class="item-toggle-none"></span><a href="#sec-copyright-and-software-license" title="Copyright &amp; Software License"><span class="secnum">A</span> Copyright &amp; Software License</a></li></ol></div></div><div id="spec-container"><h1 class="version">Stage 2 Draft / March 2, 2026</h1><h1 class="title">JSON.parseImmutable</h1>
+    </svg></div><div id="menu-spacer"></div><div id="menu"><div id="menu-search"><input type="text" id="menu-search-box" placeholder="Search..."><div id="menu-search-results" class="inactive"></div></div><div id="menu-pins"><div class="menu-pane-header">Pins</div><ul id="menu-pins-list"></ul></div><div class="menu-pane-header">Table of Contents</div><div id="menu-toc"><ol class="toc"><li><span class="item-toggle">◢</span><a href="#sec-structured-data" title="Structured Data"><span class="secnum">1</span> Structured Data</a><ol class="toc"><li><span class="item-toggle">◢</span><a href="#sec-json-object" title="The JSON Object"><span class="secnum">1.1</span> The JSON Object</a><ol class="toc"><li><span class="item-toggle">◢</span><a href="#sec-json.parse" title="JSON.parse ( text [ , reviver ] )"><span class="secnum">1.1.1</span> JSON.parse ( <var>text</var> [ , <var>reviver</var> ] )</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-parsejsontext" title="ParseJSONText ( text )"><span class="secnum">1.1.1.1</span> <ins>ParseJSONText ( <var>text</var> )</ins></a></li></ol></li><li><span class="item-toggle">◢</span><a href="#sec-json.parseimmutable" title="JSON.parseImmutable ( text [ , reviver ] )"><span class="secnum">1.1.2</span> <ins>JSON.parseImmutable ( <var>text</var> [ , <var>reviver</var> ] )</ins></a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-buildimmutableproperty" title="BuildImmutableProperty ( value, name, reviver )"><span class="secnum">1.1.2.1</span> <ins>BuildImmutableProperty ( <var>value</var>, <var>name</var>, <var>reviver</var> )</ins></a></li></ol></li><li><span class="item-toggle">◢</span><a href="#sec-json.stringify" title="JSON.stringify ( value [ , replacer [ , space ] ] )"><span class="secnum">1.1.3</span> JSON.stringify ( <var>value</var> [ , <var>replacer</var> [ , <var>space</var> ] ] )</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-serializejsonproperty" title="SerializeJSONProperty ( state, key, holder )"><span class="secnum">1.1.3.1</span> SerializeJSONProperty ( <var>state</var>, <var>key</var>, <var>holder</var> )</a></li></ol></li></ol></li></ol></li><li><span class="item-toggle-none"></span><a href="#sec-copyright-and-software-license" title="Copyright &amp; Software License"><span class="secnum">A</span> Copyright &amp; Software License</a></li></ol></div></div><div id="spec-container"><h1 class="version">Stage 2 Draft / June 16, 2026</h1><h1 class="title">JSON.parseImmutable</h1>
 
 <emu-biblio href="./biblio.json"></emu-biblio>