Normative: add base64 and hex methods for Uint8Array

[bakkot]

Pending stage 4.

[jhnaldo]

I added type modeling for each separate case of TypedArray (e.g., Uint8Array) to resolve the esmeta type check error in ESMeta v0.6.4. After merging #3656, I hope this PR passes the esmeta typecheck.

[syg]

This looks great to me.

[michaelficarra]

Nothing with normative consequences, but lots of little editorial things to fix up. I'll take another look after the current comments are addressed.

[bakkot]

Comments addressed, thanks @michaelficarra.

[syg]

I think Michael's suggestion for _throwOnExtraBits_ has made this parameter pretty convoluted. I was fine with the previous optional bool, or if Michael remains feeling strongly about that being an "abuse", then my preference is something like optional _optionalBehavior_: ~throw-on-extra-bits~ instead of the current state.

[bakkot]

My preference would be to put it back how it was.

[michaelficarra]

I really don't want to use optionality for anything other than defaulting to something you could have passed. If we don't like bool+1, what about a 3-state enum?

[syg]

There are two states that matter, the 3rd one is an artifact. Reflecting that state is more confusing than helpful to the reader, because they follow it all the way to realize it doesn't affect behavior.

[nicolo-ribaudo]

What if we just have a boolean there, and have a separate DecodeBase64Octet AO that does:

DecodeBase64Octet(_chunk_: a String with length 4)
1. Return ! DecodeBase64Chunk(_chunk_, *true*).
2. NOTE: The above step does not throw because a String of length 4 never has extra bits

[nicolo-ribaudo]

Well octet isn't the right word, but probably there is a word for 24 bits. Or DecodeBase64CompleteChunk

EDIT: DecodeBase64Bidozen!

[ljharb]

"bidozen" could be both 6 or 24 tho. I think how it was is fine.

[bakkot]

Started doing this but ended up going a slightly different direction in f8b8442, now we have

DecodeFinalBase64Chunk (
  _chunk_: a String of length 2 or 3,
  _throwOnExtraBits_: a Boolean,
): either a normal completion containing a List of byte values, or a throw completion

and

DecodeFullLengthBase64Chunk (
  _chunk_: a String of length 4
): a List of byte values of length 3

thoughts?

[michaelficarra]

WFM

[syg]

lgtm!

[jmdyck]

Suggested change

	): a Record with fields [[Read]] (an integral Number), [[Bytes]] (a List of byte values), and [[Error]] (either ~none~ or a *SyntaxError* object)
	): a Record with fields [[Read]] (an integer), [[Bytes]] (a List of byte values), and [[Error]] (a *SyntaxError* object or ~none~)

• Other appearances of [[Read]] indicate that it's an integer, not an integral Number.
• In a type disjunction, multi-valued types should precede singular values.
• "either" is unnecessary after a left paren.

Additionally, this Record type should maybe be named and declared separately.

[bakkot]

Thanks, fixed. I don't personally think it's worth naming this type so I've left it unnamed for now.

[jmdyck]

Normally, the spec uses "such that" to express a constraint, but that's presumably not what's intended here. Maybe:

Suggested change

	1. Let _byteSequence_ be the unique sequence of 3 bytes resulting from decoding _chunk_ as base64 (such that applying the base64 encoding specified in section 4 of <a href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</a> to _byteSequence_ would produce _chunk_).
	1. Let _byteSequence_ be the unique sequence of 3 bytes resulting from decoding _chunk_ as base64. (That is, applying the base64 encoding specified in section 4 of <a href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</a> to _byteSequence_ would produce _chunk_.)

I also tried the parenthetical as a NOTE step and as an Assert step. They work, but they don't have the same feel.

Alternatively, don't get into "decode" at all:

Suggested change

	1. Let _byteSequence_ be the unique sequence of 3 bytes resulting from decoding _chunk_ as base64 (such that applying the base64 encoding specified in section 4 of <a href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</a> to _byteSequence_ would produce _chunk_).
	1. Let _byteSequence_ be the unique sequence of 3 bytes such that applying the base64 encoding specified in section 4 of <a href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</a> to _byteSequence_ would produce _chunk_.

[bakkot]

I went with "i.e., the sequence such that", which makes it clearly expressing a constraint but I think reads better than either of these suggestions. In particular I do want to continue to describe this as "decoding" because that is how everyone thinks of it, even though the RFC does not formally define a decoding algorithm.

[github-actions]

The rendered spec for this PR is available at https://tc39.es/ecma262/pr/3655.

changes addressed