feat: Add finishInto() for zero-copy serialization into existing buffers (#2196)

Author: jiang1997

index.d.ts

@@ -2859,6 +2859,16 @@ export class Writer {
      * @returns Finished buffer
      */
     public finish(): Uint8Array;
+
+    /**
+     * Finishes the write operation, writing into the provided buffer.
+     * The caller must ensure that `buf` has enough space starting at `offset`
+     * to hold {@link Writer#len} bytes.
+     * @param buf Target buffer
+     * @param [offset=0] Offset to start writing at
+     * @returns The provided buffer
+     */
+    public finishInto<T extends Uint8Array>(buf: T, offset?: number): T;
 }
 
 /** Wire format writer using node buffers. */

src/writer.js

@@ -456,15 +456,28 @@ 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.finishInto(this.constructor.alloc(this.len), 0);
+};
+
+/**
+ * Finishes the write operation, writing into the provided buffer.
+ * The caller must ensure that `buf` has enough space starting at `offset`
+ * to hold {@link Writer#len} bytes.
+ * @param {T} buf Target buffer
+ * @param {number} [offset=0] Offset to start writing at
+ * @returns {T} The provided buffer
+ * @template T extends Uint8Array
+ */
+Writer.prototype.finishInto = function finishInto(buf, offset) {
+    if (offset === undefined)
+        offset = 0;
+    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

@@ -145,6 +145,29 @@ tape.test("writer & reader", function(test) {
         test.end();
     });
 
+    test.test(test.name + " - finishInto", function(test) {
+
+        // 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.finishInto(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: {