js doc for buffer

Author: glasstiger

src/buffer/base.ts

@@ -16,13 +16,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;
@@ -40,7 +39,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>
@@ -68,7 +67,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.
    *
@@ -112,22 +111,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);
@@ -138,7 +135,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.
@@ -158,7 +155,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.
@@ -185,7 +182,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.
@@ -207,7 +204,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.
@@ -227,7 +224,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.
@@ -236,11 +233,12 @@ abstract class SenderBufferBase implements SenderBuffer {
   abstract floatColumn(name: string, value: number): 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)) {
@@ -256,7 +254,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.
@@ -282,7 +280,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'.
@@ -308,7 +306,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() {
@@ -323,7 +321,7 @@ abstract class SenderBufferBase implements SenderBuffer {
   }
 
   /**
-   * Returns the current position of the buffer.
+   * Returns the current position of the buffer. <br>
    * New data will be written into the buffer starting from this position.
    */
   currentPosition(): number {

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

@@ -6,11 +6,22 @@ import { SenderBufferBase } from "./base";
 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

@@ -38,6 +38,7 @@ function createBuffer(options: SenderOptions): SenderBuffer {
  * Buffer used by the Sender.
  */
 interface SenderBuffer {
+
   /**
    * Resets the buffer, data added to the buffer will be lost. <br>
    * In other words it clears the buffer and sets the writing position to the beginning of the buffer.
@@ -47,31 +48,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.
@@ -80,7 +79,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.
@@ -89,7 +88,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.
@@ -98,7 +97,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.
@@ -107,16 +106,17 @@ interface SenderBuffer {
   floatColumn(name: string, value: number): 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.
@@ -130,21 +130,21 @@ 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.
+   * Returns the current position of the buffer. <br>
    * New data will be written into the buffer starting from this position.
    */
   currentPosition(): number;

src/transport/tcp.ts

@@ -175,7 +175,7 @@ class TcpTransport implements SenderTransport {
   }
 
   /**
-   * Closes the TCP connection to the database.
+   * Closes the TCP connection to the database. <br>
    */
   async close(): Promise<void> {
     if (this.socket) {

src/utils.ts

@@ -36,6 +36,13 @@ function timestampToNanos(timestamp: bigint, unit: TimestampUnit) {
   }
 }
 
+/**
+ * Fetches JSON data from a URL.
+ * @template T - The expected type of the JSON response
+ * @param url - The URL to fetch from
+ * @returns Promise resolving to the parsed JSON data
+ * @throws Error if the request fails or returns a non-OK status
+ */
 async function fetchJson<T>(url: string): Promise<T> {
   let response: globalThis.Response;
   try {