feat: add write method.

- Add write method to writing data to the specified position.
- Add writeToBuffer private method to handle append and write.
- Add test cases for write method.

Author: ghosind

src/dynamicBuffer.ts

@@ -97,6 +97,13 @@ export class DynamicBuffer {
   /**
    * Appends string to this buffer according to the character encoding.
    *
+   * ```js
+   * buf.append('Hello ');
+   * buf.append('world!');
+   * console.log(buf.toString());
+   * // Hello world!
+   * ```
+   *
    * @param data String to write to buffer.
    * @param length Maximum number of bytes to write, default the length of string.
    * @param encoding The character encoding to use, default from buffer encoding.
@@ -120,10 +127,6 @@ export class DynamicBuffer {
     lengthParam?: number | BufferEncoding,
     encodingParam?: BufferEncoding | number,
   ) {
-    if (typeof data !== 'string') {
-      throw new TypeError('argument must be a string');
-    }
-
     let length: number | undefined;
     let encoding: BufferEncoding | undefined;
 
@@ -137,19 +140,38 @@ export class DynamicBuffer {
       length = encodingParam;
     }
 
-    let lengthToWrite = data.length || 0;
-    if (length !== undefined && length >= 0 && length <= data.length) {
-      lengthToWrite = length;
-    }
+    const count = this.writeData(data, this.used, length, encoding);
+    this.used += count;
 
-    if (lengthToWrite === 0) {
-      return 0;
-    }
+    return count;
+  }
 
-    this.ensureSize(lengthToWrite + this.used);
+  /**
+   * Writes data to this buffer at offset according to the specific character encoding.
+   *
+   * ```js
+   * buf.write('Hello!');
+   * console.log(buf.toString());
+   * // Hello!
+   * buf.write(' world!', 5);
+   * console.log(buf.toString());
+   * // Hello world!
+   * ```
+   *
+   * @param data String to write to buffer.
+   * @param offset Number of bytes to skip before starting to write data, default 0.
+   * @param length Maximum number of bytes to write, default the length of string.
+   * @param encoding The character encoding to use, default from buffer encoding.
+   * @returns Number of bytes written.
+   */
+  write(data: string, offset?: number, length?: number, encoding?: BufferEncoding) {
+    const start = offset || 0;
+    if (start < 0) {
+      throw new RangeError('The value of "offset" is out of range.');
+    }
 
-    const count = this.buffer?.write(data, this.used, lengthToWrite, encoding || this.encoding);
-    this.used += count || 0;
+    const count = this.writeData(data, start, length, encoding);
+    this.used = start + count;
 
     return count;
   }
@@ -345,6 +367,36 @@ export class DynamicBuffer {
     }(this);
   }
 
+  /**
+   * Write data into internal buffer with the specified offset.
+   *
+   * @param data String to write to buffer.
+   * @param offset Number of bytes to skip before starting to write data.
+   * @param length Maximum number of bytes to write, default the length of string.
+   * @param encoding The character encoding to use, default from buffer encoding.
+   * @returns Number of bytes written.
+   */
+  private writeData(data: string, offset: number, length?: number, encoding?: BufferEncoding) {
+    if (typeof data !== 'string') {
+      throw new TypeError('argument must be a string');
+    }
+
+    let lengthToWrite = data.length || 0;
+    if (length !== undefined && length >= 0 && length <= data.length) {
+      lengthToWrite = length;
+    }
+
+    if (lengthToWrite === 0) {
+      return 0;
+    }
+
+    this.ensureSize(lengthToWrite + offset);
+
+    const count = this.buffer?.write(data, offset, lengthToWrite, encoding || this.encoding);
+
+    return count || 0;
+  }
+
   /**
    * Ensures the buffer size is at least equal to the expect size.
    *

test/dynamicBuffer.spec.ts

@@ -134,6 +134,120 @@ describe('Append tests', () => {
   });
 });
 
+describe('Write tests', () => {
+  it('Test writing string without offset', () => {
+    const buffer = new DynamicBuffer();
+    const str = 'Hello world';
+
+    const count = buffer.write(str);
+
+    assert.equal(count, str.length);
+    assert.equal(buffer.toString(), str);
+  });
+
+  it('Test writing string with offset', () => {
+    const buffer = new DynamicBuffer({ fill: ' ' });
+    const str = 'Hello world';
+
+    const count = buffer.write(str, 5);
+
+    assert.equal(count, str.length);
+    assert.equal(buffer.toString(), `     ${str}`);
+  });
+
+  it('Test writing string with negative offset', () => {
+    const buffer = new DynamicBuffer();
+    const str = 'Hello world';
+
+    assert.throws(() => {
+      buffer.write(str, -1);
+    });
+  });
+
+  it('Test writing string with large offset', () => {
+    const buffer = new DynamicBuffer({ fill: ' ' });
+    const str = 'Hello world';
+
+    assert.throws(() => {
+      buffer.write(str, constants.MAX_LENGTH * 2);
+    });
+  });
+
+  it('Test writing string without offset twice time', () => {
+    const buffer = new DynamicBuffer();
+    let str = 'Hello';
+    let count = buffer.write(str);
+    assert.equal(count, str.length);
+    assert.equal(buffer.toString(), str);
+
+    str = 'world';
+    count = buffer.write(str);
+    assert.equal(count, str.length);
+    assert.equal(buffer.toString(), str);
+    assert.equal(buffer.length, str.length);
+  });
+
+  it('Test writing string with offset twice time', () => {
+    const buffer = new DynamicBuffer();
+    let str = 'Hello!';
+    let count = buffer.write(str);
+    assert.equal(count, str.length);
+    assert.equal(buffer.toString(), str);
+
+    str = ' world!';
+    count = buffer.write(str, 5);
+    assert.equal(count, str.length);
+    assert.equal(buffer.toString(), 'Hello world!');
+    assert.equal(buffer.length, 12);
+  });
+
+  it('Test writing empty string without offset', () => {
+    const buffer = new DynamicBuffer();
+
+    const count = buffer.write('');
+
+    assert.equal(count, 0);
+    assert.equal(buffer.toString(), '');
+  });
+
+  it('Test writing string with parameters', () => {
+    const buffer = new DynamicBuffer();
+    const str = 'Hello world!!!';
+
+    const count = buffer.write(str, 0, 12, 'utf-8');
+
+    assert.equal(count, 12);
+    assert.equal(buffer.toString(), 'Hello world!');
+  });
+
+  it('Test writing without parameter', () => {
+    const buffer = new DynamicBuffer();
+
+    assert.throws(() => {
+      // @ts-ignore
+      buffer.write();
+    });
+  });
+
+  it('Test writing null', () => {
+    const buffer = new DynamicBuffer();
+
+    assert.throws(() => {
+      // @ts-ignore
+      buffer.write(null);
+    });
+  });
+
+  it('Test writing a number', () => {
+    const buffer = new DynamicBuffer();
+
+    assert.throws(() => {
+      // @ts-ignore
+      buffer.write(65);
+    });
+  });
+});
+
 describe('Export buffer tests', () => {
   it('Test toBuffer() before appending', () => {
     const buffer = new DynamicBuffer();