feat: Added prepend and getBuffers methods. (#154)

ShogunPanda · web-flow · commit e9eda9549b12 · 2025-03-11T11:20:26.000-07:00
* feat: Added prepend and getBuffers methods.

* chore: Use common method to add and prepend.

* chore: Avoid internal choices.
diff --git a/BufferList.d.ts b/BufferList.d.ts
@@ -45,6 +45,14 @@ interface BufferList {
 
   append(buffer: BufferListAcceptedTypes): this;
 
+  /**
+   * Adds an additional buffer or BufferList at the beginning of the internal list.
+   * this is returned so it can be chained.
+   *
+   * @param buffer
+   */
+  prepend(buffer: BufferListAcceptedTypes): this;
+
   /**
    * Will return the byte at the specified index.
    * @param index
@@ -169,6 +177,11 @@ interface BufferList {
     encoding?: string
   ): number;
 
+  /**
+   * Will return the internal list of buffers.
+   */
+  getBuffers(): Buffer[];
+
   /**
    * All of the standard byte-reading methods of the Buffer interface are implemented and will operate across internal Buffer boundaries transparently.
    * See the [Buffer](http://nodejs.org/docs/latest/api/buffer.html) documentation for how these work.
diff --git a/BufferList.js b/BufferList.js
@@ -53,6 +53,10 @@ BufferList.prototype._reverseOffset = function (blOffset) {
   return offset
 }
 
+BufferList.prototype.getBuffers = function getBuffers () {
+  return this._bufs
+}
+
 BufferList.prototype.get = function get (index) {
   if (index > this.length || index < 0) {
     return undefined
@@ -223,21 +227,33 @@ BufferList.prototype.duplicate = function duplicate () {
 }
 
 BufferList.prototype.append = function append (buf) {
+  return this._attach(buf, BufferList.prototype._appendBuffer)
+}
+
+BufferList.prototype.prepend = function prepend (buf) {
+  return this._attach(buf, BufferList.prototype._prependBuffer, true)
+}
+
+BufferList.prototype._attach = function _attach (buf, attacher, prepend) {
   if (buf == null) {
     return this
   }
 
   if (buf.buffer) {
-    // append a view of the underlying ArrayBuffer
-    this._appendBuffer(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength))
+    // append/prepend a view of the underlying ArrayBuffer
+    attacher.call(this, Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength))
   } else if (Array.isArray(buf)) {
-    for (let i = 0; i < buf.length; i++) {
-      this.append(buf[i])
+    const [starting, modifier] = prepend ? [buf.length - 1, -1] : [0, 1]
+
+    for (let i = starting; i >= 0 && i < buf.length; i += modifier) {
+      this._attach(buf[i], attacher, prepend)
     }
   } else if (this._isBufferList(buf)) {
     // unwrap argument into individual BufferLists
-    for (let i = 0; i < buf._bufs.length; i++) {
-      this.append(buf._bufs[i])
+    const [starting, modifier] = prepend ? [buf._bufs.length - 1, -1] : [0, 1]
+
+    for (let i = starting; i >= 0 && i < buf._bufs.length; i += modifier) {
+      this._attach(buf._bufs[i], attacher, prepend)
     }
   } else {
     // coerce number arguments to strings, since Buffer(number) does
@@ -246,7 +262,7 @@ BufferList.prototype.append = function append (buf) {
       buf = buf.toString()
     }
 
-    this._appendBuffer(Buffer.from(buf))
+    attacher.call(this, Buffer.from(buf))
   }
 
   return this
@@ -257,6 +273,11 @@ BufferList.prototype._appendBuffer = function appendBuffer (buf) {
   this.length += buf.length
 }
 
+BufferList.prototype._prependBuffer = function prependBuffer (buf) {
+  this._bufs.unshift(buf)
+  this.length += buf.length
+}
+
 BufferList.prototype.indexOf = function (search, offset, encoding) {
   if (encoding === undefined && typeof offset === 'string') {
     encoding = offset
diff --git a/README.md b/README.md
@@ -90,6 +90,7 @@ bl.pipe(fs.createWriteStream('gibberish.txt'))
   * <a href="#isBufferList"><code><b>BufferList.isBufferList(obj)</b></code></a>
   * <a href="#length"><code>bl.<b>length</b></code></a>
   * <a href="#append"><code>bl.<b>append(buffer)</b></code></a>
+  * <a href="#prepend"><code>bl.<b>append(buffer)</b></code></a>
   * <a href="#get"><code>bl.<b>get(index)</b></code></a>
   * <a href="#indexOf"><code>bl.<b>indexOf(value[, byteOffset][, encoding])</b></code></a>
   * <a href="#slice"><code>bl.<b>slice([ start[, end ] ])</b></code></a>
@@ -100,7 +101,8 @@ bl.pipe(fs.createWriteStream('gibberish.txt'))
   * <a href="#toString"><code>bl.<b>toString([encoding, [ start, [ end ]]])</b></code></a>
   * <a href="#readXX"><code>bl.<b>readDoubleBE()</b></code>, <code>bl.<b>readDoubleLE()</b></code>, <code>bl.<b>readFloatBE()</b></code>, <code>bl.<b>readFloatLE()</b></code>, <code>bl.<b>readBigInt64BE()</b></code>, <code>bl.<b>readBigInt64LE()</b></code>, <code>bl.<b>readBigUInt64BE()</b></code>, <code>bl.<b>readBigUInt64LE()</b></code>, <code>bl.<b>readInt32BE()</b></code>, <code>bl.<b>readInt32LE()</b></code>, <code>bl.<b>readUInt32BE()</b></code>, <code>bl.<b>readUInt32LE()</b></code>, <code>bl.<b>readInt16BE()</b></code>, <code>bl.<b>readInt16LE()</b></code>, <code>bl.<b>readUInt16BE()</b></code>, <code>bl.<b>readUInt16LE()</b></code>, <code>bl.<b>readInt8()</b></code>, <code>bl.<b>readUInt8()</b></code></a>
   * <a href="#ctorStream"><code><b>new BufferListStream([ callback ])</b></code></a>
-
+  * <a href="#getBuffers"><code>bl.<b>getBuffers()</b></code></a>
+  
 --------------------------------------------------------
 <a name="ctor"></a>
 ### new BufferList([ Buffer | Buffer array | BufferList | BufferList array | String ])
@@ -135,6 +137,11 @@ Get the length of the list in bytes. This is the sum of the lengths of all of th
 ### bl.append(Buffer | Buffer array | BufferList | BufferList array | String)
 `append(buffer)` adds an additional buffer or BufferList to the internal list. `this` is returned so it can be chained.
 
+--------------------------------------------------------
+<a name="prepend"></a>
+### bl.prepend(Buffer | Buffer array | BufferList | BufferList array | String)
+`prepend(buffer)` adds an additional buffer or BufferList at the beginning of the internal list. `this` is returned so it can be chained.
+
 --------------------------------------------------------
 <a name="get"></a>
 ### bl.get(index)
@@ -230,6 +237,11 @@ const BufferListStream = require('bl')
 ```
 
 --------------------------------------------------------
+<a name="getBuffers"></a>
+### bl.getBuffers()
+
+`getBuffers()` returns the internal list of buffers.
+
 
 ## Contributors
 
diff --git a/test/test.js b/test/test.js
@@ -249,6 +249,78 @@ tape('append chainable (test results)', function (t) {
   t.end()
 })
 
+tape('prepend accepts arrays of Buffers', function (t) {
+  const bl = new BufferListStream()
+
+  bl.prepend(Buffer.from('abc'))
+  bl.prepend([Buffer.from('def')])
+  bl.prepend([Buffer.from('ghi'), Buffer.from('jkl')])
+  bl.prepend([Buffer.from('mnop'), Buffer.from('qrstu'), Buffer.from('vwxyz')])
+  t.equal(bl.length, 26)
+  t.equal(bl.slice().toString('ascii'), 'mnopqrstuvwxyzghijkldefabc')
+
+  t.end()
+})
+
+tape('prepend accepts arrays of Uint8Arrays', function (t) {
+  const bl = new BufferListStream()
+
+  bl.prepend(new Uint8Array([97, 98, 99]))
+  bl.prepend([Uint8Array.from([100, 101, 102])])
+  bl.prepend([new Uint8Array([103, 104, 105]), new Uint8Array([106, 107, 108])])
+  bl.prepend([new Uint8Array([109, 110, 111, 112]), new Uint8Array([113, 114, 115, 116, 117]), new Uint8Array([118, 119, 120, 121, 122])])
+  t.equal(bl.length, 26)
+  t.equal(bl.slice().toString('ascii'), 'mnopqrstuvwxyzghijkldefabc')
+
+  t.end()
+})
+
+tape('prepend accepts arrays of BufferLists', function (t) {
+  const bl = new BufferListStream()
+
+  bl.prepend(Buffer.from('abc'))
+  bl.prepend([new BufferListStream('def')])
+  bl.prepend(
+    new BufferListStream([Buffer.from('ghi'), new BufferListStream('jkl')])
+  )
+  bl.prepend([
+    Buffer.from('mnop'),
+    new BufferListStream([Buffer.from('qrstu'), Buffer.from('vwxyz')])
+  ])
+  t.equal(bl.length, 26)
+  t.equal(bl.slice().toString('ascii'), 'mnopqrstuvwxyzghijkldefabc')
+
+  t.end()
+})
+
+tape('prepend chainable', function (t) {
+  const bl = new BufferListStream()
+
+  t.ok(bl.prepend(Buffer.from('abcd')) === bl)
+  t.ok(bl.prepend([Buffer.from('abcd')]) === bl)
+  t.ok(bl.prepend(new BufferListStream(Buffer.from('abcd'))) === bl)
+  t.ok(bl.prepend([new BufferListStream(Buffer.from('abcd'))]) === bl)
+
+  t.end()
+})
+
+tape('prepend chainable (test results)', function (t) {
+  const bl = new BufferListStream('abc')
+    .prepend([new BufferListStream('def')])
+    .prepend(
+      new BufferListStream([Buffer.from('ghi'), new BufferListStream('jkl')])
+    )
+    .prepend([
+      Buffer.from('mnop'),
+      new BufferListStream([Buffer.from('qrstu'), Buffer.from('vwxyz')])
+    ])
+
+  t.equal(bl.length, 26)
+  t.equal(bl.slice().toString('ascii'), 'mnopqrstuvwxyzghijkldefabc')
+
+  t.end()
+})
+
 tape('consuming from multiple buffers', function (t) {
   const bl = new BufferListStream()
 
@@ -555,6 +627,18 @@ tape('test toString encoding', function (t) {
   t.end()
 })
 
+tape('getBuffers', function (t) {
+  const bl = new BufferListStream([Buffer.from('First'), Buffer.from('Second'), Buffer.from('Third')])
+
+  t.deepEquals(
+    bl.getBuffers(),
+    // @ts-ignore
+    bl._bufs
+  )
+
+  t.end()
+})
+
 tape('uninitialized memory', function (t) {
   const secret = crypto.randomBytes(256)
   for (let i = 0; i < 1e6; i++) {
