For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/proposal-json-parseimmutable.md.
TC39 Atlas
  • English

      • JSON.parseImmutable S2

      Proposal details
      Proposal overview

      This proposal addresses the need for parsing JSON strings into deeply immutable objects. It introduces a JSON.parseImmutable function that returns a deeply frozen object, similar to using Object.freeze recursively.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      JSON.parseImmutable Proposal

      Status

      Stage 2

      Champions:

      • Nicolò Ribaudo (Igalia)
      • Ashley Claymore (Bloomberg)
      • Peter Klecha (Bloomberg)

      Overview

      This proposal identifies a need in ECMAScript for a function which parses JSON 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 had been recursively called on it.

      const obj = JSON.parseImmutable('{ "one": { "two": 3 } }');
assert(Object.isFrozen(obj));
assert(Object.isFrozen(obj.one));

      To achieve a similar result today a reviver can be used:

      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 but split off into a separate proposal to reduce the scope of the core Records and Tuples proposal. #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.