ECMA-262 (12th Edition) ECMAScript 2021 Language Specification - page 56

This property has the attributes { [[Writable]]: 

false

, [[Enumerable]]: 

false

, [[Configurable]]: 

true

 }.

The JSON object:

is 

%JSON%

.

is the initial value of the 

"JSON"

 property of the 

global object

.

is an 

ordinary object

.

contains two functions, 

parse

parse

 and 

stringify

stringify

, that are used to parse and construct JSON texts.

has a [[Prototype]] internal slot whose value is 

%Object.prototype%

.

does not have a [[Construct]] internal method; it cannot be used as a 

constructor

 with the 

new

new

 operator.

does not have a [[Call]] internal method; it cannot be invoked as a function.

The JSON Data Interchange Format is defined in ECMA-404. The JSON interchange format used in this specification is
exactly that described by ECMA-404. Conforming implementations of 

JSON.parse

JSON.parse

 and 

JSON.stringify

JSON.stringify

 must

support the exact interchange format described in the ECMA-404 specification without any deletions or extensions to
the format.

The 

parse

parse

 function parses a JSON text (a JSON-formatted String) and produces an ECMAScript value. The JSON

format represents literals, arrays, and objects with a syntax similar to the syntax for ECMAScript literals, Array
Initializers, and Object Initializers. After parsing, JSON objects are realized as ECMAScript objects. JSON arrays are
realized as ECMAScript Array instances. JSON strings, numbers, booleans, and null are realized as ECMAScript
Strings, Numbers, Booleans, and 

null

.

The optional 

reviver

 parameter is a function that takes two parameters, 

key

 and 

value

. It can filter and transform the

results. It is called with each of the 

key

/

value

 pairs produced by the parse, and its return value is used instead of the

original value. If it returns what it received, the structure is not modified. If it returns 

undefined

 then the property is

deleted from the result.

1.  Let 

jsonString

 be ? 

ToString

(

text

).

2.  Parse ! 

StringToCodePoints

(

jsonString

) as a JSON text as specified in ECMA-404. Throw a 

SyntaxError

exception if it is not a valid JSON text as defined in that specification.

3.  Let 

scriptString

 be the 

string-concatenation

 of 

"("

, 

jsonString

, and 

");"

.

4.  Let 

script

 be 

ParseText

(! 

StringToCodePoints

(

scriptString

), 

Script

).

5. 

Assert

: 

script

 is a 

Parse Node

.

6.  Let 

completion

 be the result of evaluating 

script

. The extended 

PropertyDefinitionEvaluation

 semantics defined

in 

B.3.1

 must not be used during the evaluation.

7.  Let 

unfiltered

 be 

completion

.[[Value]].

8. 

Assert

: 

unfiltered

 is either a String, Number, Boolean, Null, or an Object that is defined by either an 

ArrayLiteral

or an 

ObjectLiteral

.

9.  If 

IsCallable

(

reviver

) is 

true

, then

a.  Let 

root

 be ! 

OrdinaryObjectCreate

(

%Object.prototype%

).

b.  Let 

rootName

 be the empty String.

c.  Perform ! 

CreateDataPropertyOrThrow

(

root

, 

rootName

, 

unfiltered

).

d.  Return ? 

InternalizeJSONProperty

(

root

, 

rootName

, 

reviver

).

25.5  The JSON Object

25.5.1  JSON.parse ( 

text

 [ , 

reviver

 ] )

736

10.  Else,

a.  Return 

unfiltered

.

The 

"length"

 property of the 

parse

parse

 function is 

2

𝔽

.

NOTE

The abstract operation InternalizeJSONProperty takes arguments 

holder

 (an Object), 

name

 (a String), and 

reviver

 (a

function object

). It performs the following steps when called:

NOTE 1

1.  Let 

val

 be ? 

Get

(

holder

, 

name

).

2.  If 

Type

(

val

) is Object, then

a.  Let 

isArray

 be ? 

IsArray

(

val

).

b.  If 

isArray

 is 

true

, then

i.  Let 

I

 be 0.

ii.  Let 

len

 be ? 

LengthOfArrayLike

(

val

).

iii.  Repeat, while 

I

 < 

len

,

1.  Let 

prop

 be ! 

ToString

(

(

I

)).

2.  Let 

newElement

 be ? 

InternalizeJSONProperty

(

val

, 

prop

, 

reviver

).

3.  If 

newElement

 is 

undefined

, then

a.  Perform ? 

val

.[[Delete]](

prop

).

4.  Else,

a.  Perform ? 

CreateDataProperty

(

val

, 

prop

, 

newElement

).

5.  Set 

I

 to 

I

 + 1.

c.  Else,

i.  Let 

keys

 be ? 

EnumerableOwnPropertyNames

(

val

, 

key

).

ii.  For each String 

P

 of 

keys

, do

1.  Let 

newElement

 be ? 

InternalizeJSONProperty

(

val

, 

P

, 

reviver

).

2.  If 

newElement

 is 

undefined

, then

a.  Perform ? 

val

.[[Delete]](

P

).

3.  Else,

a.  Perform ? 

CreateDataProperty

(

val

, 

P

, 

newElement

).

3.  Return ? 

Call

(

reviver

, 

holder

, « 

name

, 

val

 »).

Valid JSON text is a subset of the ECMAScript 

PrimaryExpression

 syntax. Step 

2

 verifies that

jsonString

 conforms to that subset, and step 

8

 asserts that that parsing and evaluation returns a

value of an appropriate type.

However, because 

B.3.1

 applies when evaluating ECMAScript source text and does not apply

during 

JSON.parse

JSON.parse

, the same source text can produce different results when evaluated as a 

PrimaryExpression

 rather than as JSON. Furthermore, the Early Error for duplicate 

"__proto__"

properties in object literals, which likewise does not apply during 

JSON.parse

JSON.parse

, means that not

all texts accepted by 

JSON.parse

JSON.parse

 are valid as a 

PrimaryExpression

, despite matching the

grammar.

This algorithm intentionally does not throw an exception if either [[Delete]] or

CreateDataProperty

 return 

false

.

25.5.1.1  InternalizeJSONProperty ( 

holder

, 

name

, 

reviver

 )

737

It is not permitted for a conforming implementation of 

JSON.parse

JSON.parse

 to extend the JSON grammars. If an

implementation wishes to support a modified or extended JSON interchange format it must do so by defining a
different parse function.

NOTE 2

The 

stringify

stringify

 function returns a String in UTF-16 encoded JSON format representing an ECMAScript value, or

undefined

. It can take three parameters. The 

value

 parameter is an ECMAScript value, which is usually an object or

array, although it can also be a String, Boolean, Number or 

null

. The optional 

replacer

 parameter is either a function

that alters the way objects and arrays are stringified, or an array of Strings and Numbers that acts as an inclusion list
for selecting the object properties that will be stringified. The optional 

space

 parameter is a String or Number that

allows the result to have white space injected into it to improve human readability.

These are the steps in stringifying an object:

1.  Let 

stack

 be a new empty 

List

.

2.  Let 

indent

 be the empty String.

3.  Let 

PropertyList

 and 

ReplacerFunction

 be 

undefined

.

4.  If 

Type

(

replacer

) is Object, then

a.  If 

IsCallable

(

replacer

) is 

true

, then

i.  Set 

ReplacerFunction

 to 

replacer

.

b.  Else,

i.  Let 

isArray

 be ? 

IsArray

(

replacer

).

ii.  If 

isArray

 is 

true

, then

1.  Set 

PropertyList

 to a new empty 

List

.

2.  Let 

len

 be ? 

LengthOfArrayLike

(

replacer

).

3.  Let 

k

 be 0.

4.  Repeat, while 

k

 < 

len

,

a.  Let 

prop

 be ! 

ToString

(

(

k

)).

b.  Let 

v

 be ? 

Get

(

replacer

, 

prop

).

c.  Let 

item

 be 

undefined

.

d.  If 

Type

(

v

) is String, set 

item

 to 

v

.

e.  Else if 

Type

(

v

) is Number, set 

item

 to ! 

ToString

(

v

).

f.  Else if 

Type

(

v

) is Object, then

i.  If 

v

 has a [[StringData]] or [[NumberData]] internal slot, set 

item

 to

? 

ToString

(

v

).

g.  If 

item

 is not 

undefined

 and 

item

 is not currently an element of 

PropertyList

, then

i.  Append 

item

 to the end of 

PropertyList

.

h.  Set 

k

 to 

k

 + 1.

5.  If 

Type

(

space

) is Object, then

a.  If 

space

 has a [[NumberData]] internal slot, then

i.  Set 

space

 to ? 

ToNumber

(

space

).

b.  Else if 

space

 has a [[StringData]] internal slot, then

i.  Set 

space

 to ? 

ToString

(

space

).

In the case where there are duplicate name Strings within an object, lexically preceding values for
the same key shall be overwritten.

25.5.2  JSON.stringify ( 

value

 [ , 

replacer

 [ , 

space

 ] ] )

738

6.  If 

Type

(

space

) is Number, then

a.  Let 

spaceMV

 be ! 

ToIntegerOrInfinity

(

space

).

b.  Set 

spaceMV

 to 

min

(10, 

spaceMV

).

c.  If 

spaceMV

 < 1, let 

gap

 be the empty String; otherwise let 

gap

 be the String value containing 

spaceMV

occurrences of the code unit 0x0020 (SPACE).

7.  Else if 

Type

(

space

) is String, then

a.  If the length of 

space

 is 10 or less, let 

gap

 be 

space

; otherwise let 

gap

 be the 

substring

 of 

space

 from 0 to 10.

8.  Else,

a.  Let 

gap

 be the empty String.

9.  Let 

wrapper

 be ! 

OrdinaryObjectCreate

(

%Object.prototype%

).

10.  Perform ! 

CreateDataPropertyOrThrow

(

wrapper

, the empty String, 

value

).

11.  Let 

state

 be the 

Record

 { [[ReplacerFunction]]: 

ReplacerFunction

, [[Stack]]: 

stack

, [[Indent]]: 

indent

, [[Gap]]: 

gap

,

[[PropertyList]]: 

PropertyList

 }.

12.  Return ? 

SerializeJSONProperty

(

state

, the empty String, 

wrapper

).

The 

"length"

 property of the 

stringify

stringify

 function is 

3

𝔽

.

NOTE 1

NOTE 2

NOTE 3

NOTE 4

NOTE 5

JSON structures are allowed to be nested to any depth, but they must be acyclic. If 

value

 is or

contains a cyclic structure, then the stringify function must throw a 

TypeError

 exception. This is

an example of a value that cannot be stringified:

a = [];
a[

0

] = a;

my_text = 

JSON

.stringify(a); 

// This must throw a TypeError.

Symbolic primitive values are rendered as follows:

The 

null

 value is rendered in JSON text as the String 

"null"

.

The 

undefined

 value is not rendered.

The 

true

 value is rendered in JSON text as the String 

"true"

.

The 

false

 value is rendered in JSON text as the String 

"false"

.

String values are wrapped in QUOTATION MARK (

""

) code units. The code units 

""

 and 

\\

 are

escaped with 

\\

 prefixes. Control characters code units are replaced with escape sequences

\u

\u

HHHH, or with the shorter forms, 

\b

\b

 (BACKSPACE), 

\f

\f

 (FORM FEED), 

\n

\n

 (LINE FEED),

\r

\r

 (CARRIAGE RETURN), 

\t

\t

 (CHARACTER TABULATION).

Finite numbers are stringified as if by calling 

ToString

(

number

). 

NaN

 and 

Infinity

 regardless of

sign are represented as the String 

"null"

.

Values that do not have a JSON representation (such as 

undefined

 and functions) do not produce

a String. Instead they produce the 

undefined

 value. In arrays these values are represented as the

String 

"null"

. In objects an unrepresentable value causes the property to be excluded from

stringification.

739

NOTE 6

The abstract operation SerializeJSONProperty takes arguments 

state

, 

key

, and 

holder

. It performs the following steps

when called:

1.  Let 

value

 be ? 

Get

(

holder

, 

key

).

2.  If 

Type

(

value

) is Object or BigInt, then

a.  Let 

toJSON

 be ? 

GetV

(

value

, 

"toJSON"

).

b.  If 

IsCallable

(

toJSON

) is 

true

, then

i.  Set 

value

 to ? 

Call

(

toJSON

, 

value

, « 

key

 »).

3.  If 

state

.[[ReplacerFunction]] is not 

undefined

, then

a.  Set 

value

 to ? 

Call

(

state

.[[ReplacerFunction]], 

holder

, « 

key

, 

value

 »).

4.  If 

Type

(

value

) is Object, then

a.  If 

value

 has a [[NumberData]] internal slot, then

i.  Set 

value

 to ? 

ToNumber

(

value

).

b.  Else if 

value

 has a [[StringData]] internal slot, then

i.  Set 

value

 to ? 

ToString

(

value

).

c.  Else if 

value

 has a [[BooleanData]] internal slot, then

i.  Set 

value

 to 

value

.[[BooleanData]].

d.  Else if 

value

 has a [[BigIntData]] internal slot, then

i.  Set 

value

 to 

value

.[[BigIntData]].

5.  If 

value

 is 

null

, return 

"null"

.

6.  If 

value

 is 

true

, return 

"true"

.

7.  If 

value

 is 

false

, return 

"false"

.

8.  If 

Type

(

value

) is String, return 

QuoteJSONString

(

value

).

9.  If 

Type

(

value

) is Number, then

a.  If 

value

 is finite, return ! 

ToString

(

value

).

b.  Return 

"null"

.

10.  If 

Type

(

value

) is BigInt, throw a 

TypeError

 exception.

11.  If 

Type

(

value

) is Object and 

IsCallable

(

value

) is 

false

, then

a.  Let 

isArray

 be ? 

IsArray

(

value

).

b.  If 

isArray

 is 

true

, return ? 

SerializeJSONArray

(

state

, 

value

).

c.  Return ? 

SerializeJSONObject

(

state

, 

value

).

12.  Return 

undefined

.

The abstract operation QuoteJSONString takes argument 

value

. It wraps 

value

 in 0x0022 (QUOTATION MARK) code

units and escapes certain other code units within it. This operation interprets 

value

 as a sequence of UTF-16 encoded

code points, as described in 

6.1.4

. It performs the following steps when called:

An object is rendered as U+007B (LEFT CURLY BRACKET) followed by zero or more properties,
separated with a U+002C (COMMA), closed with a U+007D (RIGHT CURLY BRACKET). A
property is a quoted String representing the key or 

property name

, a U+003A (COLON), and

then the stringified property value. An array is rendered as an opening U+005B (LEFT SQUARE
BRACKET followed by zero or more values, separated with a U+002C (COMMA), closed with a
U+005D (RIGHT SQUARE BRACKET).

25.5.2.1  SerializeJSONProperty ( 

state

, 

key

, 

holder

 )

25.5.2.2  QuoteJSONString ( 

value

 )

740

1.  Let 

product

 be the String value consisting solely of the code unit 0x0022 (QUOTATION MARK).

2.  For each code point 

C

 of ! 

StringToCodePoints

(

value

), do

a.  If 

C

 is listed in the “Code Point” column of 

Table 61

, then

i.  Set 

product

 to the 

string-concatenation

 of 

product

 and the escape sequence for 

C

 as specified in the

“Escape Sequence” column of the corresponding row.

b.  Else if 

C

 has a numeric value less than 0x0020 (SPACE), or if 

C

 has the same numeric value as a 

leading

surrogate

 or 

trailing surrogate

, then

i.  Let 

unit

 be the code unit whose numeric value is that of 

C

.

ii.  Set 

product

 to the 

string-concatenation

 of 

product

 and 

UnicodeEscape

(

unit

).

c.  Else,

i.  Set 

product

 to the 

string-concatenation

 of 

product

 and ! 

UTF16EncodeCodePoint

(

C

).

3.  Set 

product

 to the 

string-concatenation

 of 

product

 and the code unit 0x0022 (QUOTATION MARK).

4.  Return 

product

.

Table 61: JSON Single Character Escape Sequences

Code Point

Unicode Character Name

Escape Sequence

U+0008

BACKSPACE

\b

\b

U+0009

CHARACTER TABULATION

\t

\t

U+000A

LINE FEED (LF)

\n

\n

U+000C

FORM FEED (FF)

\f

\f

U+000D

CARRIAGE RETURN (CR)

\r

\r

U+0022

QUOTATION MARK

\"

\"

U+005C

REVERSE SOLIDUS

\\

\\

The abstract operation UnicodeEscape takes argument 

C

 (a code unit). It represents 

C

 as a Unicode escape sequence. It

performs the following steps when called:

1.  Let 

n

 be the numeric value of 

C

.

2. 

Assert

: 

n

 

≤

 0xFFFF.

3.  Return the 

string-concatenation

 of:

the code unit 0x005C (REVERSE SOLIDUS)

"u"

the String representation of 

n

, formatted as a four-digit lowercase hexadecimal number, padded to the

left with zeroes if necessary

The abstract operation SerializeJSONObject takes arguments 

state

 and 

value

. It serializes an object. It performs the

following steps when called:

1.  If 

state

.[[Stack]] contains 

value

, throw a 

TypeError

 exception because the structure is cyclical.

25.5.2.3  UnicodeEscape ( 

C

 )

25.5.2.4  SerializeJSONObject ( 

state

, 

value

 )

741

2.  Append 

value

 to 

state

.[[Stack]].

3.  Let 

stepback

 be 

state

.[[Indent]].

4.  Set 

state

.[[Indent]] to the 

string-concatenation

 of 

state

.[[Indent]] and 

state

.[[Gap]].

5.  If 

state

.[[PropertyList]] is not 

undefined

, then

a.  Let 

K

 be 

state

.[[PropertyList]].

6.  Else,

a.  Let 

K

 be ? 

EnumerableOwnPropertyNames

(

value

, 

key

).

7.  Let 

partial

 be a new empty 

List

.

8.  For each element 

P

 of 

K

, do

a.  Let 

strP

 be ? 

SerializeJSONProperty

(

state

, 

P

, 

value

).

b.  If 

strP

 is not 

undefined

, then

i.  Let 

member

 be 

QuoteJSONString

(

P

).

ii.  Set 

member

 to the 

string-concatenation

 of 

member

 and 

":"

.

iii.  If 

state

.[[Gap]] is not the empty String, then

1.  Set 

member

 to the 

string-concatenation

 of 

member

 and the code unit 0x0020 (SPACE).

iv.  Set 

member

 to the 

string-concatenation

 of 

member

 and 

strP

.

v.  Append 

member

 to 

partial

.

9.  If 

partial

 is empty, then

a.  Let 

final

 be 

"{}"

.

10.  Else,

a.  If 

state

.[[Gap]] is the empty String, then

i.  Let 

properties

 be the String value formed by concatenating all the element Strings of 

partial

 with

each adjacent pair of Strings separated with the code unit 0x002C (COMMA). A comma is not
inserted either before the first String or after the last String.

ii.  Let 

final

 be the 

string-concatenation

 of 

"{"

, 

properties

, and 

"}"

.

b.  Else,

i.  Let 

separator

 be the 

string-concatenation

 of the code unit 0x002C (COMMA), the code unit 0x000A

(LINE FEED), and 

state

.[[Indent]].

ii.  Let 

properties

 be the String value formed by concatenating all the element Strings of 

partial

 with

each adjacent pair of Strings separated with 

separator

. The 

separator

 String is not inserted either

before the first String or after the last String.

iii.  Let 

final

 be the 

string-concatenation

 of 

"{"

, the code unit 0x000A (LINE FEED), 

state

.[[Indent]],

properties

, the code unit 0x000A (LINE FEED), 

stepback

, and 

"}"

.

11.  Remove the last element of 

state

.[[Stack]].

12.  Set 

state

.[[Indent]] to 

stepback

.

13.  Return 

final

.

The abstract operation SerializeJSONArray takes arguments 

state

 and 

value

. It serializes an array. It performs the

following steps when called:

1.  If 

state

.[[Stack]] contains 

value

, throw a 

TypeError

 exception because the structure is cyclical.

2.  Append 

value

 to 

state

.[[Stack]].

3.  Let 

stepback

 be 

state

.[[Indent]].

4.  Set 

state

.[[Indent]] to the 

string-concatenation

 of 

state

.[[Indent]] and 

state

.[[Gap]].

5.  Let 

partial

 be a new empty 

List

.

6.  Let 

len

 be ? 

LengthOfArrayLike

(

value

).

25.5.2.5  SerializeJSONArray ( 

state

, 

value

 )

742

7.  Let 

index

 be 0.

8.  Repeat, while 

index

 < 

len

,

a.  Let 

strP

 be ? 

SerializeJSONProperty

(

state

, ! 

ToString

(

index

)), 

value

).

b.  If 

strP

 is 

undefined

, then

i.  Append 

"null"

 to 

partial

.

c.  Else,

i.  Append 

strP

 to 

partial

.

d.  Set 

index

 to 

index

 + 1.

9.  If 

partial

 is empty, then

a.  Let 

final

 be 

"[]"

.

10.  Else,

a.  If 

state

.[[Gap]] is the empty String, then

i.  Let 

properties

 be the String value formed by concatenating all the element Strings of 

partial

 with

each adjacent pair of Strings separated with the code unit 0x002C (COMMA). A comma is not
inserted either before the first String or after the last String.

ii.  Let 

final

 be the 

string-concatenation

 of 

"["

, 

properties

, and 

"]"

.

b.  Else,

i.  Let 

separator

 be the 

string-concatenation

 of the code unit 0x002C (COMMA), the code unit 0x000A

(LINE FEED), and 

state

.[[Indent]].

ii.  Let 

properties

 be the String value formed by concatenating all the element Strings of 

partial

 with

each adjacent pair of Strings separated with 

separator

. The 

separator

 String is not inserted either

before the first String or after the last String.

iii.  Let 

final

 be the 

string-concatenation

 of 

"["

, the code unit 0x000A (LINE FEED), 

state

.[[Indent]],

properties

, the code unit 0x000A (LINE FEED), 

stepback

, and 

"]"

.

11.  Remove the last element of 

state

.[[Stack]].

12.  Set 

state

.[[Indent]] to 

stepback

.

13.  Return 

final

.

NOTE

The initial value of the 

@@toStringTag

 property is the String value 

"JSON"

.

This property has the attributes { [[Writable]]: 

false

, [[Enumerable]]: 

false

, [[Configurable]]: 

true

 }.

A 

WeakRef

 is an object that is used to refer to a target object without preserving it from garbage collection. WeakRefs

The representation of arrays includes only the elements between zero and 

array.length

array.length

 - 1

inclusive. Properties whose keys are not 

array indexes

 are excluded from the stringification. An

array is stringified as an opening LEFT SQUARE BRACKET, elements separated by COMMA,
and a closing RIGHT SQUARE BRACKET.

25.5.3  JSON [ @@toStringTag ]

26  Managing Memory

26.1  WeakRef Objects

743

can be dereferenced to allow access to the target object, if the target object hasn't been reclaimed by garbage collection.

The 

WeakRef

 

constructor

:

is 

%WeakRef%

.

is the initial value of the 

"WeakRef"

 property of the 

global object

.

creates and initializes a new WeakRef object when called as a 

constructor

.

is not intended to be called as a function and will throw an exception when called in that manner.
is designed to be subclassable. It may be used as the value in an 

extends

extends

 clause of a class definition. Subclass

constructors that intend to inherit the specified 

WeakRef

WeakRef

 behaviour must include a 

super

super

 call to the

WeakRef

WeakRef

 

constructor

 to create and initialize the subclass instance with the internal state necessary to support

the 

WeakRef.prototype

WeakRef.prototype

 built-in methods.

When the 

WeakRef

WeakRef

 function is called with argument 

target

, the following steps are taken:

1.  If NewTarget is 

undefined

, throw a 

TypeError

 exception.

2.  If 

Type

(

target

) is not Object, throw a 

TypeError

 exception.

3.  Let 

weakRef

 be ? 

OrdinaryCreateFromConstructor

(NewTarget, 

"%WeakRef.prototype%"

, « [[WeakRefTarget]]

»).

4.  Perform ! 

AddToKeptObjects

(

target

).

5.  Set 

weakRef

.[[WeakRefTarget]] to 

target

.

6.  Return 

weakRef

.

The 

WeakRef

 

constructor

:

has a [[Prototype]] internal slot whose value is 

%Function.prototype%

.

has the following properties:

The initial value of 

WeakRef.prototype

WeakRef.prototype

 is the 

WeakRef prototype

 object.

This property has the attributes { [[Writable]]: 

false

, [[Enumerable]]: 

false

, [[Configurable]]: 

false

 }.

The 

WeakRef prototype

 object:

is 

%WeakRef.prototype%

.

has a [[Prototype]] internal slot whose value is 

%Object.prototype%

.

is an 

ordinary object

.

does not have a [[WeakRefTarget]] internal slot.

26.1.1  The WeakRef Constructor

26.1.1.1  WeakRef ( 

target

 )

26.1.2  Properties of the WeakRef Constructor

26.1.2.1  WeakRef.prototype

26.1.3  Properties of the WeakRef Prototype Object

744

NORMATIVE OPTIONAL

The initial value of 

WeakRef.prototype.constructor

WeakRef.prototype.constructor

 is 

%WeakRef%

.

This property has the attributes { [[Writable]]: 

false

, [[Enumerable]]: 

false

, [[Configurable]]: 

true

 }.

The following steps are taken:

1.  Let 

weakRef

 be the 

this

 value.

2.  Perform ? 

RequireInternalSlot

(

weakRef

, [[WeakRefTarget]]).

3.  Return ! 

WeakRefDeref

(

weakRef

).

NOTE

The initial value of the 

@@toStringTag

 property is the String value 

"WeakRef"

.

This property has the attributes { [[Writable]]: 

false

, [[Enumerable]]: 

false

, [[Configurable]]: 

true

 }.

The abstract operation WeakRefDeref takes argument 

weakRef

 (a 

WeakRef

). It performs the following steps when

called:

1.  Let 

target

 be 

weakRef

.[[WeakRefTarget]].

2.  If 

target

 is not 

empty

, then

a.  Perform ! 

AddToKeptObjects

(

target

).

If the 

WeakRef

 returns a 

target

 Object that is not 

undefined

, then this 

target

 object should not be

garbage collected until the current execution of ECMAScript code has completed. The

AddToKeptObjects

 operation makes sure read consistency is maintained.

In the above example, if the first deref does not evaluate to 

undefined

 then the second deref

cannot either.

target = { 

foo

: 

function

() {} };

let

 weakRef = 

new

 WeakRef(target);

... later ...

if

 (weakRef.deref()) {

  weakRef.deref().foo();
}

26.1.3.1  WeakRef.prototype.constructor

26.1.3.2  WeakRef.prototype.deref ( )

26.1.3.3  WeakRef.prototype [ @@toStringTag ]

26.1.4  WeakRef Abstract Operations

26.1.4.1  WeakRefDeref ( 

weakRef

 )

745

b.  Return 

target

.

3.  Return 

undefined

.

NOTE

WeakRef

 instances are ordinary objects that inherit properties from the 

WeakRef prototype

. 

WeakRef

 instances also

have a [[WeakRefTarget]] internal slot.

A 

FinalizationRegistry

 is an object that manages registration and unregistration of cleanup operations that are

performed when target objects are garbage collected.

The 

FinalizationRegistry

 

constructor

:

is 

%FinalizationRegistry%

.

is the initial value of the 

"FinalizationRegistry"

 property of the 

global object

.

creates and initializes a new FinalizationRegistry object when called as a 

constructor

.

is not intended to be called as a function and will throw an exception when called in that manner.
is designed to be subclassable. It may be used as the value in an 

extends

extends

 clause of a class definition. Subclass

constructors that intend to inherit the specified 

FinalizationRegistry

FinalizationRegistry

 behaviour must include a

super

super

 call to the 

FinalizationRegistry

FinalizationRegistry

 

constructor

 to create and initialize the subclass instance with

the internal state necessary to support the 

FinalizationRegistry.prototype

FinalizationRegistry.prototype

 built-in methods.

When the 

FinalizationRegistry

FinalizationRegistry

 function is called with argument 

cleanupCallback

, the following steps are

taken:

1.  If NewTarget is 

undefined

, throw a 

TypeError

 exception.

2.  If 

IsCallable

(

cleanupCallback

) is 

false

, throw a 

TypeError

 exception.

3.  Let 

finalizationRegistry

 be ? 

OrdinaryCreateFromConstructor

(NewTarget, 

"%FinalizationRegistry.prototype%"

,

« [[Realm]], [[CleanupCallback]], [[Cells]] »).

4.  Let 

fn

 be the 

active function object

.

5.  Set 

finalizationRegistry

.[[Realm]] to 

fn

.[[Realm]].

6.  Set 

finalizationRegistry

.[[CleanupCallback]] to 

cleanupCallback

.

7.  Set 

finalizationRegistry

.[[Cells]] to a new empty 

List

.

8.  Return 

finalizationRegistry

.

This abstract operation is defined separately from WeakRef.prototype.deref strictly to make it
possible to succinctly define liveness.

26.1.5  Properties of WeakRef Instances

26.2  FinalizationRegistry Objects

26.2.1  The FinalizationRegistry Constructor

26.2.1.1  FinalizationRegistry ( 

cleanupCallback

 )

26.2.2  Properties of the FinalizationRegistry Constructor

746

The 

FinalizationRegistry

 

constructor

:

has a [[Prototype]] internal slot whose value is 

%Function.prototype%

.

has the following properties:

The initial value of 

FinalizationRegistry.prototype

FinalizationRegistry.prototype

 is the 

FinalizationRegistry prototype

 object.

This property has the attributes { [[Writable]]: 

false

, [[Enumerable]]: 

false

, [[Configurable]]: 

false

 }.

The 

FinalizationRegistry prototype

 object:

is 

%FinalizationRegistry.prototype%

.

has a [[Prototype]] internal slot whose value is 

%Object.prototype%

.

is an 

ordinary object

.

does not have [[Cells]] and [[CleanupCallback]] internal slots.

The initial value of 

FinalizationRegistry.prototype.constructor

FinalizationRegistry.prototype.constructor

 is 

%FinalizationRegistry%

.

The following steps are taken:

1.  Let 

finalizationRegistry

 be the 

this

 value.

2.  Perform ? 

RequireInternalSlot

(

finalizationRegistry

, [[Cells]]).

3.  If 

Type

(

target

) is not Object, throw a 

TypeError

 exception.

4.  If 

SameValue

(

target

, 

heldValue

) is 

true

, throw a 

TypeError

 exception.

5.  If 

Type

(

unregisterToken

) is not Object, then

a.  If 

unregisterToken

 is not 

undefined

, throw a 

TypeError

 exception.

b.  Set 

unregisterToken

 to 

empty

.

6.  Let 

cell

 be the 

Record

 { [[WeakRefTarget]]: 

target

, [[HeldValue]]: 

heldValue

, [[UnregisterToken]]: 

unregisterToken

 }.

7.  Append 

cell

 to 

finalizationRegistry

.[[Cells]].

8.  Return 

undefined

.

NOTE

The following steps are taken:

1.  Let 

finalizationRegistry

 be the 

this

 value.

Based on the algorithms and definitions in this specification, 

cell

.[[HeldValue]] is 

live

 when 

cell

 is

in 

finalizationRegistry

.[[Cells]]; however, this does not necessarily mean that 

cell

.

[[UnregisterToken]] or 

cell

.[[Target]] are 

live

. For example, registering an object with itself as its

unregister token would not keep the object alive forever.

26.2.2.1  FinalizationRegistry.prototype

26.2.3  Properties of the FinalizationRegistry Prototype Object

26.2.3.1  FinalizationRegistry.prototype.constructor

26.2.3.2  FinalizationRegistry.prototype.register ( 

target

, 

heldValue

 [ , 

unregisterToken

 ] )

26.2.3.3  FinalizationRegistry.prototype.unregister ( 

unregisterToken

 )

747

2.  Perform ? 

RequireInternalSlot

(

finalizationRegistry

, [[Cells]]).

3.  If 

Type

(

unregisterToken

) is not Object, throw a 

TypeError

 exception.

4.  Let 

removed

 be 

false

.

5.  For each 

Record

 { [[WeakRefTarget]], [[HeldValue]], [[UnregisterToken]] } 

cell

 of 

finalizationRegistry

.[[Cells]], do

a.  If 

cell

.[[UnregisterToken]] is not 

empty

 and 

SameValue

(

cell

.[[UnregisterToken]], 

unregisterToken

) is 

true

,

then

i.  Remove 

cell

 from 

finalizationRegistry

.[[Cells]].

ii.  Set 

removed

 to 

true

.

6.  Return 

removed

.

The initial value of the 

@@toStringTag

 property is the String value 

"FinalizationRegistry"

.

This property has the attributes { [[Writable]]: 

false

, [[Enumerable]]: 

false

, [[Configurable]]: 

true

 }.

FinalizationRegistry

 instances are ordinary objects that inherit properties from the 

FinalizationRegistry prototype

.

FinalizationRegistry

 instances also have [[Cells]] and [[CleanupCallback]] internal slots.

An interface is a set of property keys whose associated values match a specific specification. Any object that provides
all the properties as described by an interface's specification 

conforms

 to that interface. An interface is not represented

by a distinct object. There may be many separately implemented objects that conform to any interface. An individual
object may conform to multiple interfaces.

The 

Iterable

 interface includes the property described in 

Table 62

:

Table 62: 

Iterable

 Interface Required Properties

Property

Value

Requirements

@@iterator

@@iterator

A function that returns an 

Iterator

object.

The returned object must conform to the 

Iterator

interface.

26.2.3.4  FinalizationRegistry.prototype [ @@toStringTag ]

26.2.4  Properties of FinalizationRegistry Instances

27  Control Abstraction Objects

27.1  Iteration

27.1.1  Common Iteration Interfaces

27.1.1.1  The 

Iterable

 Interface

27.1.1.2  The 

Iterator

 Interface

748

An object that implements the 

Iterator

 interface must include the property in 

Table 63

. Such objects may also

implement the properties in 

Table 64

.

Table 63: 

Iterator

 Interface Required Properties

Property

Value

Requirements

"next"

A function
that returns
an

IteratorResult

object.

The returned object must conform to the 

IteratorResult

 interface. If a previous call to the

next

next

 method of an 

Iterator

 has returned an 

IteratorResult

 object whose 

"done"

 property is

true

, then all subsequent calls to the 

next

next

 method of that object should also return an

IteratorResult

 object whose 

"done"

 property is 

true

. However, this requirement is not

enforced.

NOTE 1

Table 64: 

Iterator

 Interface Optional Properties

Property

Value

Requirements

"return"

A function
that returns
an

IteratorResult

object.

The returned object must conform to the 

IteratorResult

 interface. Invoking this method

notifies the 

Iterator

 object that the caller does not intend to make any more 

next

next

 method

calls to the 

Iterator

. The returned 

IteratorResult

 object will typically have a 

"done"

 property

whose value is 

true

, and a 

"value"

 property with the value passed as the argument of the

return

return

 method. However, this requirement is not enforced.

"throw"

A function
that returns
an

IteratorResult

object.

The returned object must conform to the 

IteratorResult

 interface. Invoking this method

notifies the 

Iterator

 object that the caller has detected an error condition. The argument

may be used to identify the error condition and typically will be an exception object. A
typical response is to 

throw

throw

 the value passed as the argument. If the method does not

throw

throw

, the returned 

IteratorResult

 object will typically have a 

"done"

 property whose

value is 

true

.

NOTE 2

The 

AsyncIterable

 interface includes the properties described in 

Table 65

:

Arguments may be passed to the 

next

next

 function but their interpretation and validity is

dependent upon the target 

Iterator

. The for-of statement and other common users of 

Iterators

 do

not pass any arguments, so 

Iterator

 objects that expect to be used in such a manner must be

prepared to deal with being called with no arguments.

Typically callers of these methods should check for their existence before invoking them. Certain
ECMAScript language features including 

for

for

-

of

of

, 

yield*

yield*

, and array destructuring call these

methods after performing an existence check. Most ECMAScript library functions that accept

Iterable

 objects as arguments also conditionally call them.

27.1.1.3  The 

AsyncIterable

 Interface

749

Table 65: 

AsyncIterable

 Interface Required Properties

Property

Value

Requirements

@@asyncIterator

@@asyncIterator

A function that returns an

AsyncIterator

 object.

The returned object must conform to the

AsyncIterator

 interface.

An object that implements the 

AsyncIterator

 interface must include the properties in 

Table 66

. Such objects may also

implement the properties in 

Table 67

.

Table 66: 

AsyncIterator

 Interface Required Properties

Property

Value

Requirements

"next"

A function
that returns
a promise
for an

IteratorResult

object.

The returned promise, when fulfilled, must fulfill with an object which conforms to the

IteratorResult

 interface. If a previous call to the 

next

next

 method of an 

AsyncIterator

 has

returned a promise for an 

IteratorResult

 object whose 

"done"

 property is 

true

, then all

subsequent calls to the 

next

next

 method of that object should also return a promise for an

IteratorResult

 object whose 

"done"

 property is 

true

. However, this requirement is not

enforced.

Additionally, the 

IteratorResult

 object that serves as a fulfillment value should have a

"value"

 property whose value is not a promise (or "thenable"). However, this requirement

is also not enforced.

NOTE 1

Arguments may be passed to the 

next

next

 function but their interpretation and validity is

dependent upon the target 

AsyncIterator

. The 

for

for

-

await

await

-

of

of

 statement and other common

users of 

AsyncIterators

 do not pass any arguments, so 

AsyncIterator

 objects that expect to be used

in such a manner must be prepared to deal with being called with no arguments.

27.1.1.4  The 

AsyncIterator

 Interface

750

Table 67: 

AsyncIterator

 Interface Optional Properties

Property

Value

Requirements

"return"

A function
that returns
a promise
for an

IteratorResult

object.

The returned promise, when fulfilled, must fulfill with an object which conforms to the

IteratorResult

 interface. Invoking this method notifies the 

AsyncIterator

 object that the caller

does not intend to make any more 

next

next

 method calls to the 

AsyncIterator

. The returned

promise will fulfill with an 

IteratorResult

 object which will typically have a 

"done"

property whose value is 

true

, and a 

"value"

 property with the value passed as the

argument of the 

return

return

 method. However, this requirement is not enforced.

Additionally, the 

IteratorResult

 object that serves as a fulfillment value should have a

"value"

 property whose value is not a promise (or "thenable"). If the argument value is

used in the typical manner, then if it is a rejected promise, a promise rejected with the
same reason should be returned; if it is a fulfilled promise, then its fulfillment value
should be used as the 

"value"

 property of the returned promise's 

IteratorResult

 object

fulfillment value. However, these requirements are also not enforced.

"throw"

A function
that returns
a promise
for an

IteratorResult

object.

The returned promise, when fulfilled, must fulfill with an object which conforms to the

IteratorResult

 interface. Invoking this method notifies the 

AsyncIterator

 object that the caller

has detected an error condition. The argument may be used to identify the error condition
and typically will be an exception object. A typical response is to return a rejected promise
which rejects with the value passed as the argument.

If the returned promise is fulfilled, the 

IteratorResult

 fulfillment value will typically have a

"done"

 property whose value is 

true

. Additionally, it should have a 

"value"

 property

whose value is not a promise (or "thenable"), but this requirement is not enforced.

NOTE 2

The 

IteratorResult

 interface includes the properties listed in 

Table 68

:

Typically callers of these methods should check for their existence before invoking them. Certain
ECMAScript language features including 

for

for

-

await

await

-

of

of

 and 

yield*

yield*

 call these methods after

performing an existence check.

27.1.1.5  The 

IteratorResult

 Interface

751