Merge branch 'binary_protocol_arrays' into arrays_support

Author: glasstiger

src/buffer/base.ts

@@ -17,13 +17,12 @@ import {
   TimestampUnit,
 } from "../utils";
 
+// Default maximum length for table and column names.
 const DEFAULT_MAX_NAME_LENGTH = 127;
 
-/** @classdesc
- * The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection.
- * If no custom agent is configured, the Sender will use its own agent which overrides some default values
- * of <i>undici.Agent</i>. The Sender's own agent uses persistent connections with 1 minute idle timeout, pipelines requests default to 1.
- * </p>
+/**
+ * Abstract base class for SenderBuffer implementations. <br>
+ * Provides common functionality for writing data into the buffer.
  */
 abstract class SenderBufferBase implements SenderBuffer {
   private bufferSize: number;
@@ -41,7 +40,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   protected readonly log: Logger;
 
   /**
-   * Creates an instance of Sender.
+   * Creates an instance of SenderBufferBase.
    *
    * @param {SenderOptions} options - Sender configuration object. <br>
    * See SenderOptions documentation for detailed description of configuration options. <br>
@@ -69,7 +68,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Extends the size of the sender's buffer. <br>
+   * Extends the size of the buffer. <br>
    * Can be used to increase the size of buffer if overflown.
    * The buffer's content is copied into the new buffer.
    *
@@ -113,22 +112,20 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * @ignore
-   * @return {Buffer} Returns a cropped buffer, or null if there is nothing to send.
-   * The returned buffer is backed by the sender's buffer.
-   * Used only in tests.
+   * @return {Buffer} Returns a cropped buffer, or null if there is nothing to send. <br>
+   * The returned buffer is backed by this buffer instance, meaning the view can change as the buffer is mutated.
+   * Used only in tests to assert the buffer's content.
    */
   toBufferView(pos = this.endOfLastRow): Buffer {
     return pos > 0 ? this.buffer.subarray(0, pos) : null;
   }
 
   /**
-   * @ignore
-   * @return {Buffer|null} Returns a cropped buffer ready to send to the server, or null if there is nothing to send.
-   * The returned buffer is a copy of the sender's buffer.
-   * It also compacts the Sender's buffer.
+   * @return {Buffer} Returns a cropped buffer ready to send to the server, or null if there is nothing to send. <br>
+   * The returned buffer is a copy of this buffer.
+   * It also compacts the buffer.
    */
-  toBufferNew(pos = this.endOfLastRow): Buffer | null {
+  toBufferNew(pos = this.endOfLastRow): Buffer {
     if (pos > 0) {
       const data = Buffer.allocUnsafe(pos);
       this.buffer.copy(data, 0, 0, pos);
@@ -139,7 +136,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Write the table name into the buffer of the sender.
+   * Write the table name into the buffer.
    *
    * @param {string} table - Table name.
    * @return {Sender} Returns with a reference to this sender.
@@ -159,7 +156,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Write a symbol name and value into the buffer of the sender.
+   * Write a symbol name and value into the buffer.
    *
    * @param {string} name - Symbol name.
    * @param {unknown} value - Symbol value, toString() is called to extract the actual symbol value from the parameter.
@@ -186,7 +183,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Write a string column with its value into the buffer of the sender.
+   * Write a string column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {string} value - Column value, accepts only string values.
@@ -208,7 +205,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Write a boolean column with its value into the buffer of the sender.
+   * Write a boolean column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {boolean} value - Column value, accepts only boolean values.
@@ -228,7 +225,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Write a float column with its value into the buffer of the sender.
+   * Write a float column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {number} value - Column value, accepts only number values.
@@ -239,11 +236,12 @@ abstract class SenderBufferBase implements SenderBuffer {
   abstract arrayColumn(name: string, value: unknown[]): SenderBuffer;
 
   /**
-   * Write an integer column with its value into the buffer of the sender.
+   * Write an integer column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {number} value - Column value, accepts only number values.
    * @return {Sender} Returns with a reference to this sender.
+   * @throws Error if the value is not an integer
    */
   intColumn(name: string, value: number): SenderBuffer {
     if (!Number.isInteger(value)) {
@@ -259,7 +257,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Write a timestamp column with its value into the buffer of the sender.
+   * Write a timestamp column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {number | bigint} value - Epoch timestamp, accepts numbers or BigInts.
@@ -285,7 +283,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Closing the row after writing the designated timestamp into the buffer of the sender.
+   * Closing the row after writing the designated timestamp into the buffer.
    *
    * @param {number | bigint} timestamp - Designated epoch timestamp, accepts numbers or BigInts.
    * @param {string} [unit=us] - Timestamp unit. Supported values: 'ns' - nanoseconds, 'us' - microseconds, 'ms' - milliseconds. Defaults to 'us'.
@@ -311,7 +309,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Closing the row without writing designated timestamp into the buffer of the sender. <br>
+   * Closing the row without writing designated timestamp into the buffer. <br>
    * Designated timestamp will be populated by the server on this record.
    */
   atNow() {
@@ -325,6 +323,14 @@ abstract class SenderBufferBase implements SenderBuffer {
     this.startNewRow();
   }
 
+  /**
+   * Returns the current position of the buffer. <br>
+   * New data will be written into the buffer starting from this position.
+   */
+  currentPosition(): number {
+    return this.position;
+  }
+
   protected checkCapacity(data: string[], base = 0) {
     let length = base;
     for (const str of data) {

src/buffer/bufferv1.ts

@@ -3,11 +3,22 @@ import { SenderOptions } from "../options";
 import { SenderBuffer } from "./index";
 import { SenderBufferBase } from "./base";
 
+/**
+ * Buffer implementation for protocol version 1.
+ * Sends floating point numbers in their text form.
+ */
 class SenderBufferV1 extends SenderBufferBase {
   constructor(options: SenderOptions) {
     super(options);
   }
 
+  /**
+   * Write a float column with its value into the buffer using v1 serialization (text format).
+   *
+   * @param {string} name - Column name.
+   * @param {number} value - Column value, accepts only number values.
+   * @return {Sender} Returns with a reference to this sender.
+   */
   floatColumn(name: string, value: number): SenderBuffer {
     this.writeColumn(
       name,

src/buffer/bufferv2.ts

@@ -12,11 +12,22 @@ const ENTITY_TYPE_DOUBLE: number = 16;
 
 const EQUALS_SIGN: number = "=".charCodeAt(0);
 
+/**
+ * Buffer implementation for protocol version 2.
+ * Sends floating point numbers in binary form.
+ */
 class SenderBufferV2 extends SenderBufferBase {
   constructor(options: SenderOptions) {
     super(options);
   }
 
+  /**
+   * Write a float column with its value into the buffer using v2 serialization (binary format).
+   *
+   * @param {string} name - Column name.
+   * @param {number} value - Column value, accepts only number values.
+   * @return {Sender} Returns with a reference to this sender.
+   */
   floatColumn(name: string, value: number): SenderBuffer {
     this.writeColumn(
       name,

src/buffer/index.ts

@@ -34,11 +34,8 @@ function createBuffer(options: SenderOptions): SenderBuffer {
   }
 }
 
-/** @classdesc
- * The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection.
- * If no custom agent is configured, the Sender will use its own agent which overrides some default values
- * of <i>undici.Agent</i>. The Sender's own agent uses persistent connections with 1 minute idle timeout, pipelines requests default to 1.
- * </p>
+/**
+ * Buffer used by the Sender.
  */
 interface SenderBuffer {
   /**
@@ -50,31 +47,29 @@ interface SenderBuffer {
   reset(): SenderBuffer;
 
   /**
-   * @ignore
-   * @return {Buffer} Returns a cropped buffer, or null if there is nothing to send.
-   * The returned buffer is backed by the sender's buffer.
-   * Used only in tests.
+   * @return {Buffer} Returns a cropped buffer, or null if there is nothing to send. <br>
+   * The returned buffer is backed by this buffer instance, meaning the view can change as the buffer is mutated.
+   * Used only in tests to assert the buffer's content.
    */
   toBufferView(pos?: number): Buffer;
 
   /**
-   * @ignore
-   * @return {Buffer|null} Returns a cropped buffer ready to send to the server, or null if there is nothing to send.
-   * The returned buffer is a copy of the sender's buffer.
-   * It also compacts the Sender's buffer.
+   * @return {Buffer} Returns a cropped buffer ready to send to the server, or null if there is nothing to send. <br>
+   * The returned buffer is a copy of this buffer.
+   * It also compacts the buffer.
    */
   toBufferNew(pos?: number): Buffer | null;
 
   /**
-   * Write the table name into the buffer of the sender.
+   * Write the table name into the buffer.
    *
    * @param {string} table - Table name.
    * @return {Sender} Returns with a reference to this sender.
    */
   table(table: string): SenderBuffer;
 
   /**
-   * Write a symbol name and value into the buffer of the sender.
+   * Write a symbol name and value into the buffer.
    *
    * @param {string} name - Symbol name.
    * @param {unknown} value - Symbol value, toString() is called to extract the actual symbol value from the parameter.
@@ -83,7 +78,7 @@ interface SenderBuffer {
   symbol(name: string, value: unknown): SenderBuffer;
 
   /**
-   * Write a string column with its value into the buffer of the sender.
+   * Write a string column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {string} value - Column value, accepts only string values.
@@ -92,7 +87,7 @@ interface SenderBuffer {
   stringColumn(name: string, value: string): SenderBuffer;
 
   /**
-   * Write a boolean column with its value into the buffer of the sender.
+   * Write a boolean column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {boolean} value - Column value, accepts only boolean values.
@@ -101,7 +96,7 @@ interface SenderBuffer {
   booleanColumn(name: string, value: boolean): SenderBuffer;
 
   /**
-   * Write a float column with its value into the buffer of the sender.
+   * Write a float column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {number} value - Column value, accepts only number values.
@@ -112,16 +107,17 @@ interface SenderBuffer {
   arrayColumn(name: string, value: unknown[]): SenderBuffer;
 
   /**
-   * Write an integer column with its value into the buffer of the sender.
+   * Write an integer column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {number} value - Column value, accepts only number values.
    * @return {Sender} Returns with a reference to this sender.
+   * @throws Error if the value is not an integer
    */
   intColumn(name: string, value: number): SenderBuffer;
 
   /**
-   * Write a timestamp column with its value into the buffer of the sender.
+   * Write a timestamp column with its value into the buffer.
    *
    * @param {string} name - Column name.
    * @param {number | bigint} value - Epoch timestamp, accepts numbers or BigInts.
@@ -135,18 +131,24 @@ interface SenderBuffer {
   ): SenderBuffer;
 
   /**
-   * Closing the row after writing the designated timestamp into the buffer of the sender.
+   * Closing the row after writing the designated timestamp into the buffer.
    *
    * @param {number | bigint} timestamp - Designated epoch timestamp, accepts numbers or BigInts.
    * @param {string} [unit=us] - Timestamp unit. Supported values: 'ns' - nanoseconds, 'us' - microseconds, 'ms' - milliseconds. Defaults to 'us'.
    */
   at(timestamp: number | bigint, unit: TimestampUnit): void;
 
   /**
-   * Closing the row without writing designated timestamp into the buffer of the sender. <br>
+   * Closing the row without writing designated timestamp into the buffer. <br>
    * Designated timestamp will be populated by the server on this record.
    */
   atNow(): void;
+
+  /**
+   * Returns the current position of the buffer. <br>
+   * New data will be written into the buffer starting from this position.
+   */
+  currentPosition(): number;
 }
 
 export {