feat: add finishTo() for zero-copy serialization into existing buffers

Author: jiang1997

index.d.ts

@@ -2777,6 +2777,15 @@ export class Writer {
      * @returns Finished buffer
      */
     public finish(): Uint8Array;
+
+    /**
+     * Finishes the write operation, writing into the provided buffer.
+     * @param buf Target buffer
+     * @param [offset=0] Offset to start writing at
+     * @returns The provided buffer
+     * @throws {RangeError} If the buffer is too small
+     */
+    public finishTo(buf: Uint8Array, offset?: number): Uint8Array;
 }
 
 /** Wire format writer using node buffers. */

src/writer.js

@@ -446,15 +446,27 @@ Writer.prototype.ldelim = function ldelim() {
  * @returns {Uint8Array} Finished buffer
  */
 Writer.prototype.finish = function finish() {
-    var head = this.head.next, // skip noop
-        buf  = this.constructor.alloc(this.len),
-        pos  = 0;
+    return this.finishTo(this.constructor.alloc(this.len), 0);
+};
+
+/**
+ * Finishes the write operation, writing into the provided buffer.
+ * @param {Uint8Array} buf Target buffer
+ * @param {number} [offset=0] Offset to start writing at
+ * @returns {Uint8Array} The provided buffer
+ * @throws {RangeError} If the buffer is too small
+ */
+Writer.prototype.finishTo = function finishTo(buf, offset) {
+    offset |= 0;
+    if (buf.length - offset < this.len)
+        throw new RangeError("buffer too small: need " + this.len + " bytes, have " + (buf.length - offset));
+    var head = this.head.next,
+        pos  = offset;
     while (head) {
         head.fn(head.val, buf, pos);
         pos += head.len;
         head = head.next;
     }
-    // this.head = this.tail = null;
     return buf;
 };
 

tests/api_writer-reader.js

@@ -129,6 +129,36 @@ tape.test("writer & reader", function(test) {
         test.end();
     });
 
+    test.test(test.name + " - finishTo", function(test) {
+
+        // throws when buffer is too small
+        var w1 = Writer.create();
+        w1.uint32(1).uint32(2).uint32(3);
+        test.throws(function() {
+            w1.finishTo(new Uint8Array(1));
+        }, RangeError, "throws RangeError when buffer too small");
+
+        // writes at offset and preserves existing data
+        var w2 = Writer.create();
+        w2.uint32(100).string("hello").bool(true);
+        var expected = w2.finish();
+
+        var w3 = Writer.create();
+        w3.uint32(100).string("hello").bool(true);
+        var offset = 3;
+        var buf3 = new Uint8Array(offset + w3.len);
+        for (var i = 0; i < offset; ++i)
+            buf3[i] = 99;
+        w3.finishTo(buf3, offset);
+
+        for (var i = 0; i < offset; ++i)
+            test.equal(buf3[i], 99, "preserves byte at index " + i + " before offset");
+        for (var i = 0; i < expected.length; ++i)
+            test.equal(buf3[offset + i], expected[i], "byte at offset+" + i + " matches finish()");
+
+        test.end();
+    });
+
     test.throws(function() {
       const root = protobuf.Root.fromJSON({
         nested: {