Initial Considerations #1
Description
For the key considerations for this proposal:
- A key goal is to provide an API for concatenation of two-or-more TypedArray instances in a single call that returns a new TypedArray and new backing ArrayBuffer.
- The spec text for this new API should afford implementers the ability to provide an implementation-defined concat alternative, but should also define a reasonable spec-defined fallback algorithm.
- The existing
TypedArray.prototype.set(...)does not meet this requirement for a couple reasons:
a. The API works with only oneTypedArrayat a time
b. The current definition ofTypedArray.prototype.set(...)does not include any specific callout for implementation-defined behavior. - The specification should not attempt to impose any specific optimization mechanism for implementations (e.g. no attempt to impose copy-on-write, ropes, etc). It is fully implementation defined.
- The API needs to appropriately consider the differences in interpretation of different TypedArray types. Specifically, it should be possible to concat only like-types (e.g. Uint8Array + Uint8Array, Float64Array + Float64Array, etc). Mixing types should likely be forbidden.
- It is still an open question whether or not we should use a static API (e.g.
Uint8Array.concat(...)) or a prototype API (e.g.u8_1.concat([u8_2, u8_3, ...])). Personally, I believe that the static API is likely best for the intended use cases but this is something worth debating and hashing out.
API Proposal
By example
const u8_1 = new Uint8Array(10);
const u8_2 = new Uint8Array(20);
const u8_3 = Uint8Array.concat([u8_1, u8_2]);%TypedArray%.concat(source)
Where: source is a synchronous iterable of %TypedArray%.
Why not Uint8Array.concat(...source)?
A common use case for this API will be to incrementally accumulate a collection of %TypedArray% instances and only after a certain point pass that collection into the %TypedArray%.concat(...) function. Using the ...source API model, that collection would need to be spread in order to work, which just adds an additional friction for users.
Naming Bikeshed
Is concat the best name? Who knows!? Let's figure out the right name for the bikeshed. Other options could include join(...) given the possible semantic similarity to joining strings.. but that seems weird, especially given that %TypedArray% is itself an iterable and we may be having a join(...) API for Iterables in general.
New API or existing?
We could, at least theoretically, modify %TypedArray%.from to support this case by allowing source to be an iterable of %TypedArray% instead of an iterable of elements. That seems a bit problematic for several reasons. One, it's confusing. Two, it's not discoverable for user code and is likely more difficult to polyfill.