feat: Add finishInto() for zero-copy finish into existing buffers

[jiang1997]

Introduce finishInto(), which allows writing directly into an existing buffer (e.g., WebAssembly memory), thereby avoiding extra copying.

[dcodeIO]

Do you plan to use finishTo somewhere within the library to speed it up? If not, then this should likely not live in protobufjs source itself, but be provided externally.

[jiang1997]

Do you plan to use finishTo somewhere within the library to speed it up? If not, then this should likely not live in protobufjs source itself, but be provided externally.

To be honest, my initial motivation was simply to solve an issue in my own project (serializing directly into Wasm memory to avoid extra copies). I haven't really explored using it to speed up the library internally yet.
I understand that users could technically implement this externally by iterating over writer.head. However, I was concerned that this might not be the best approach, as it would require external code to break encapsulation and rely on internal implementation details.

[dcodeIO]

One approach to integrate it into protobuf.js itself might be to use finishTo to implement finish. Then it's not just dead code. Ideally, though, such a change should not require a bunch of additional runtime checks that only exist because of that split.

[jiang1997]

One approach to integrate it into protobuf.js itself might be to use finishTo to implement finish. Then it's not just dead code. Ideally, though, such a change should not require a bunch of additional runtime checks that only exist because of that split.

Yeah, totally agree. I've already made the changes — finish() now delegates to finishTo(), all runtime checks have been removed, and the documentation has been updated to note that callers are responsible for ensuring sufficient buffer space.

[dcodeIO]

This turns offsets >= 2 GiB negative. Perhaps:

Suggested change

	offset |= 0;
	offset >>>= 0;

[jiang1997]

Good catch, learned something new! Updated to offset >>>= 0.

[jiang1997]

The offset >>>= 0 operation reduces the value to a 32-bit number. Node lets TypedArray indices go beyond 2³², so a large offset might end up near the start of the buffer.
I’d suggest making offset required, not optional, to avoid any unexpected behavior.

What are your thoughts on this, @dcodeIO ?

[dcodeIO]

Since this returns the provided buffer, I think we can make the JSDoc generic here:

Suggested change

	* @param {Uint8Array} buf Target buffer
	* @param {number} [offset=0] Offset to start writing at
	* @returns {Uint8Array} The provided buffer
	* @param {T} buf Target buffer
	* @param {number} [offset=0] Offset to start writing at
	* @returns {T} The provided buffer
	* @template T extends Uint8Array

The definitions generator should then generate finishTo<T extends Uint8Array>(buf: T, offset?: number): T, preserving Buffer and other Uint8Array subclasses.

[dcodeIO]

Thinking about naming a bit here, I guess a good name could be finishInto, then mirroring APIs like TextEncoder#encodeInto. Wdyt?