Skip to content

Add draft spec text for TypedArray.concat #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jasnell merged 10 commits into from
Feb 12, 2026
Merged

Add draft spec text for TypedArray.concat #6

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
7672833
Add draft spec text for TypedArray.concat
jasnell Feb 4, 2026
8988a70
Address ToIndex review comment
jasnell Feb 5, 2026
e9f6264
Add editorial note about the high-level description
jasnell Feb 5, 2026
45716ea
Address multiple discussion points
jasnell Feb 6, 2026
7908692
More clarifications/fixups
jasnell Feb 6, 2026
712e630
cleaups + add SharedArrayBuffer.concat
jasnell Feb 6, 2026
39c7d61
Document the test cases
jasnell Feb 6, 2026
b439771
Add polyfil
jasnell Feb 6, 2026
6de6b31
remove the polyfill
jasnell Feb 7, 2026
cabaae2
Fixups to conform to editorial guidelines
jasnell Feb 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 42 additions & 29 deletions spec.emu
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,36 +4,49 @@
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/github.min.css">
<script src="./spec.js"></script>
<pre class="metadata">
title: Proposal Title Goes Here
stage: -1
contributors: Your Name(s) Here
title: TypedArray.concat
stage: 1
contributors: James M Snell
</pre>

<emu-clause id="sec-demo-clause">
<h1>This is an emu-clause</h1>
<p>This is an algorithm:</p>
<emu-alg>
1. Let _proposal_ be *undefined*.
1. If IsAccepted(_proposal_) is *true*, then
1. Let _stage_ be *0*<sub>ℤ</sub>.
1. Else,
1. Let _stage_ be *-1*<sub>ℤ</sub>.
1. Return ? ToString(_stage_).
</emu-alg>
</emu-clause>
<emu-clause id="sec-typedarray-objects">
<h1>TypedArray Objects</h1>

<emu-clause id="sec-%typedarray%-intrinsic-object">
<h1>The %TypedArray% Intrinsic Object</h1>

<emu-clause id="sec-properties-of-the-%typedarray%-intrinsic-object">
<h1>Properties of the %TypedArray% Intrinsic Object</h1>

<emu-clause id="sec-is-accepted" type="abstract operation">
<h1>
IsAccepted (
_proposal_: an ECMAScript language value
): a Boolean
</h1>
<dl class="header">
<dt>description</dt>
<dd>Tells you if the proposal was accepted</dd>
</dl>
<emu-alg>
1. If _proposal_ is not a String, or is not accepted, return *false*.
1. Return *true*.
</emu-alg>
<emu-clause id="sec-%typedarray%.concat">
<h1>%TypedArray%.concat ( _items_ [ , _length_ ] )</h1>
<p>This method concatenates the elements of multiple TypedArrays of the same type into a new TypedArray. It performs the following steps when called:</p>
<emu-alg>
1. Let _C_ be the *this* value.
1. If IsConstructor(_C_) is *false*, throw a *TypeError* exception.
1. If _C_ does not have a [[TypedArrayName]] internal slot, throw a *TypeError* exception.
1. Let _arrayList_ be ? IteratorToList(? GetIteratorFromMethod(_items_, ? GetMethod(_items_, %Symbol.iterator%))).
Copy link
Member

@bakkot bakkot Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This works but is not idiomatic - the convention is to consume iterables as iterables, meaning that you'd be doing the ValidateTypedArray calls on each item as you consume the iterable, rather than deferring those checks until after the whole iterable has been consumed.

That said, there's arguably a reason to do it this way, which is that the iteration protocol calls user code, which could detach or resize a TypedArray that you've already looked at, which would be bad. Doing it this way ensures there's no user code running between the point at which you start computing the total length and the point at which you do the copies. If that's the intention, that's reasonable, but this should probably should be called out with a NOTE.

Copy link
Member

@ljharb ljharb Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

doing it this way, however, means that it can still throw conceptually mid-iteration, and the iterator will have been exhausted.

iow, i think that the extra burden of checking for resizing or detachment is necessary if it's going to take an iterable, so that an error on an item in the middle doesn't exhaust the iterator.

Copy link
Member

@bakkot bakkot Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a tradeoff - I agree that in the error case that it is very slightly nicer to not exhaust the iterator, but if that comes at the cost of slowing down the happy case, as I think it might here, it's not necessarily worth it.

Copy link
Collaborator Author

@jasnell jasnell Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm.. I can see it both ways and really not sure which is best. I do have a slight preference towards not slowing down the happy path, particularly since this is largely a perf-motivated proposal. One possibility for now is that we can document this as a discussion point (creating a tracking issue) and discuss in committee... but also happy to go with whatever y'all recommend on it.

Copy link
Member

@bakkot bakkot Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Opened #7 to track.

1. Let _totalLength_ be 0.
1. Let _elementType_ be TypedArrayElementType(_C_).
1. For each element _item_ of _arrayList_, do
1. Let _taRecord_ be ? ValidateTypedArray(_item_, ~seq-cst~).
1. If TypedArrayElementType(_item_) is not _elementType_, throw a *TypeError* exception.
1. Let _itemLength_ be TypedArrayLength(_taRecord_).
1. Set _totalLength_ to _totalLength_ + _itemLength_.
1. If _length_ is present and _length_ is not *undefined*, then
1. Let _newLength_ be ? ToIndex(_length_).
1. If _newLength_ &gt; _totalLength_, throw a *RangeError* exception.
1. Else,
1. Let _newLength_ be _totalLength_.
1. Let _A_ be a TypedArray that is an instance of _C_ with a length of _newLength_, containing the concatenated elements from _arrayList_ in order, truncated to _newLength_ elements.
1. Return _A_.
</emu-alg>
<emu-note>
<p>This method requires that the *this* value be a TypedArray constructor and that all elements of _items_ be TypedArrays of the same type. For example, `Uint8Array.concat([a, b])` requires that both _a_ and _b_ are `Uint8Array` instances.</p>
<p>If the optional _length_ parameter is provided and is less than the sum of the lengths of all input TypedArrays, the result is truncated to the specified length. If _length_ is greater than the total length of input arrays, a *RangeError* is thrown.</p>
<p>Implementations may use any technique to allocate and populate the result TypedArray, such as direct memory copy, deferred concatenation, or element-by-element copying, provided the observable result is a TypedArray containing the concatenated elements in order.</p>
</emu-note>
</emu-clause>
</emu-clause>
</emu-clause>
</emu-clause>