add some js doc, mostly copied from #51

Author: glasstiger

src/buffer/index.ts

@@ -16,11 +16,8 @@ const DEFAULT_MAX_NAME_LENGTH = 127;
 const DEFAULT_BUFFER_SIZE = 65536; //  64 KB
 const DEFAULT_MAX_BUFFER_SIZE = 104857600; // 100 MB
 
-/** @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.
  */
 class SenderBuffer {
   private bufferSize: number;
@@ -38,7 +35,7 @@ class SenderBuffer {
   private readonly log: Logger;
 
   /**
-   * Creates an instance of Sender.
+   * Creates an instance of SenderBuffer.
    *
    * @param {SenderOptions} options - Sender configuration object. <br>
    * See SenderOptions documentation for detailed description of configuration options. <br>
@@ -66,7 +63,7 @@ class 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.
    *

src/transport/http/base.ts

@@ -31,9 +31,9 @@ We are retrying on the following response codes (copied from the Rust client):
 */
 const RETRIABLE_STATUS_CODES = [500, 503, 504, 507, 509, 523, 524, 529, 599];
 
-/** @classdesc
- * The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection.
- * The supported protocols are HTTP and TCP. HTTP is preferred as it provides feedback in the HTTP response. <br>
+/**
+ * Abstract base class for HTTP-based transport implementations. <br>
+ * Provides common configuration and functionality for HTTP and HTTPS protocols.
  */
 abstract class HttpTransportBase implements SenderTransport {
   protected readonly secure: boolean;
@@ -53,6 +53,11 @@ abstract class HttpTransportBase implements SenderTransport {
 
   protected readonly log: Logger;
 
+  /**
+   * Creates a new HttpTransportBase instance.
+   * @param options - Sender configuration options including connection and authentication details
+   * @throws Error if required protocol or host options are missing
+   */
   protected constructor(options: SenderOptions) {
     if (!options || !options.protocol) {
       throw new Error("The 'protocol' option is mandatory");
@@ -99,16 +104,35 @@ abstract class HttpTransportBase implements SenderTransport {
     }
   }
 
+  /**
+   * HTTP transport does not require explicit connection establishment.
+   * @throws Error indicating connect is not required for HTTP transport
+   */
   connect(): Promise<boolean> {
     throw new Error("'connect()' is not required for HTTP transport");
   }
 
-  async close(): Promise<void> {}
+  /**
+   * HTTP transport does not require explicit connection closure.
+   * @returns Promise that resolves immediately
+   */
+  async close(): Promise<void> {
+  }
 
+  /**
+   * Gets the default auto-flush row count for HTTP transport.
+   * @returns Default number of rows that trigger auto-flush
+   */
   getDefaultAutoFlushRows(): number {
     return DEFAULT_HTTP_AUTO_FLUSH_ROWS;
   }
 
+  /**
+   * Sends data to the QuestDB server via HTTP.
+   * Must be implemented by concrete HTTP transport classes.
+   * @param data - Buffer containing the data to send
+   * @returns Promise resolving to true if data was sent successfully
+   */
   abstract send(data: Buffer): Promise<boolean>;
 }
 

src/transport/http/legacy.ts

@@ -10,19 +10,20 @@ import {
   HTTP_NO_CONTENT,
 } from "./base";
 
-// default options for HTTP agent
-// - persistent connections with 1 minute idle timeout, server side has 5 minutes set by default
-// - max open connections is set to 256, same as server side default
+/**
+ * Default configuration for HTTP agents.
+ * - Persistent connections with 1 minute idle timeout
+ * - Maximum of 256 open connections (matching server default)
+ */
 const DEFAULT_HTTP_AGENT_CONFIG = {
   maxSockets: 256,
   keepAlive: true,
   timeout: 60000, // 1 min
 };
 
-/** @classdesc
- * The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection.
- * The supported protocols are HTTP and TCP. HTTP is preferred as it provides feedback in the HTTP response. <br>
- * Based on benchmarks HTTP also provides higher throughput, if configured to ingest data in bigger batches.
+/**
+ * HTTP transport implementation using Node.js built-in http/https modules. <br>
+ * Supports both HTTP and HTTPS protocols with configurable authentication.
  */
 class HttpTransport extends HttpTransportBase {
   private static DEFAULT_HTTP_AGENT: http.Agent;
@@ -31,10 +32,10 @@ class HttpTransport extends HttpTransportBase {
   private readonly agent: http.Agent | https.Agent;
 
   /**
-   * Creates an instance of Sender.
+   * Creates a new HttpTransport instance using Node.js HTTP modules.
    *
-   * @param {SenderOptions} options - Sender configuration object. <br>
-   * See SenderOptions documentation for detailed description of configuration options. <br>
+   * @param options - Sender configuration object containing connection details
+   * @throws Error if the protocol is not 'http' or 'https'
    */
   constructor(options: SenderOptions) {
     super(options);
@@ -59,6 +60,14 @@ class HttpTransport extends HttpTransportBase {
     }
   }
 
+  /**
+   * Sends data to QuestDB using HTTP POST.
+   * @param data - Buffer containing data to send
+   * @param retryBegin - Internal parameter for tracking retry start time
+   * @param retryInterval - Internal parameter for tracking retry intervals
+   * @returns Promise resolving to true if data was sent successfully
+   * @throws Error if request fails after all retries or times out
+   */
   send(data: Buffer, retryBegin = -1, retryInterval = -1): Promise<boolean> {
     const request = this.secure ? https.request : http.request;
 

src/transport/http/undici.ts

@@ -10,6 +10,10 @@ import {
   HTTP_NO_CONTENT,
 } from "./base";
 
+/**
+ * Default HTTP options for the Undici agent.
+ * Configures keep-alive connections with 60-second timeout and single request pipelining.
+ */
 const DEFAULT_HTTP_OPTIONS: Agent.Options = {
   connect: {
     keepAlive: true,
@@ -18,11 +22,10 @@ const DEFAULT_HTTP_OPTIONS: Agent.Options = {
   keepAliveTimeout: 60000, // 1 minute
 };
 
-/** @classdesc
- * The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection.
- * The supported protocols are HTTP and TCP. HTTP is preferred as it provides feedback in the HTTP response. <br>
- * of <i>undici.Agent</i>. The Sender's own agent uses persistent connections with 1 minute idle timeout, pipelines requests default to 1.
- * </p>
+/**
+ * HTTP transport implementation using the Undici library. <br>
+ * Provides high-performance HTTP requests with connection pooling and retry logic. <br>
+ * Supports both HTTP and HTTPS protocols with configurable authentication.
  */
 class UndiciTransport extends HttpTransportBase {
   private static DEFAULT_HTTP_AGENT: Agent;
@@ -31,10 +34,10 @@ class UndiciTransport extends HttpTransportBase {
   private readonly dispatcher: RetryAgent;
 
   /**
-   * Creates an instance of Sender.
+   * Creates a new UndiciTransport instance.
    *
-   * @param {SenderOptions} options - Sender configuration object. <br>
-   * See SenderOptions documentation for detailed description of configuration options. <br>
+   * @param options - Sender configuration object containing connection and retry settings
+   * @throws Error if the protocol is not 'http' or 'https'
    */
   constructor(options: SenderOptions) {
     super(options);
@@ -89,6 +92,12 @@ class UndiciTransport extends HttpTransportBase {
     });
   }
 
+  /**
+   * Sends data to QuestDB using HTTP POST.
+   * @param data - Buffer containing data to send
+   * @returns Promise resolving to true if data was sent successfully
+   * @throws Error if request fails after all retries or times out
+   */
   async send(data: Buffer): Promise<boolean> {
     const headers: Record<string, string> = {};
     if (this.token) {

src/transport/index.ts

@@ -6,13 +6,45 @@ import { UndiciTransport } from "./http/undici";
 import { TcpTransport } from "./tcp";
 import { HttpTransport } from "./http/legacy";
 
+/**
+ * Interface for QuestDB transport implementations. <br>
+ * Defines the contract for different transport protocols (HTTP/HTTPS/TCP/TCPS).
+ */
 interface SenderTransport {
+  /**
+   * Establishes a connection to the database server. <br>
+   * Should not be called on HTTP transports.
+   * @returns Promise resolving to true if connection is successful
+   */
   connect(): Promise<boolean>;
+
+  /**
+   * Sends buffered data to the database server.
+   * @param data - Buffer containing the data to send
+   * @returns Promise resolving to true if data was sent successfully
+   */
   send(data: Buffer): Promise<boolean>;
+
+  /**
+   * Closes the connection to the database server. <br>
+   * Should not be called on HTTP transports.
+   * @returns Promise that resolves when the connection is closed
+   */
   close(): Promise<void>;
+
+  /**
+   * Gets the default number of rows that trigger auto-flush for this transport.
+   * @returns Default auto-flush row count
+   */
   getDefaultAutoFlushRows(): number;
 }
 
+/**
+ * Factory function to create appropriate transport instance based on configuration.
+ * @param options - Sender configuration options including protocol and connection details
+ * @returns Transport instance appropriate for the specified protocol
+ * @throws Error if protocol or host options are missing or invalid
+ */
 function createTransport(options: SenderOptions): SenderTransport {
   if (!options || !options.protocol) {
     throw new Error("The 'protocol' option is mandatory");

src/transport/tcp.ts

@@ -12,56 +12,16 @@ import { isBoolean } from "../utils";
 
 const DEFAULT_TCP_AUTO_FLUSH_ROWS = 600;
 
-// an arbitrary public key, not used in authentication
-// only used to construct a valid JWK token which is accepted by the crypto API
+// Arbitrary public key, used to construct valid JWK tokens.
+// These are not used for actual authentication, only required for crypto API compatibility.
 const PUBLIC_KEY = {
   x: "aultdA0PjhD_cWViqKKyL5chm6H1n-BiZBo_48T-uqc",
   y: "__ptaol41JWSpTTL525yVEfzmY8A6Vi_QrW1FjKcHMg",
 };
 
-/** @classdesc
- * The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection.
- * The supported protocols are HTTP and TCP. HTTP is preferred as it provides feedback in the HTTP response. <br>
- * Based on benchmarks HTTP also provides higher throughput, if configured to ingest data in bigger batches.
- * <p>
- * The client supports authentication. <br>
- * Authentication details can be passed to the Sender in its configuration options. <br>
- * The client supports Basic username/password and Bearer token authentication methods when used with HTTP protocol,
- * and JWK token authentication when ingesting data via TCP. <br>
- * Please, note that authentication is enabled by default in QuestDB Enterprise only. <br>
- * Details on how to configure authentication in the open source version of
- * QuestDB: {@link https://questdb.io/docs/reference/api/ilp/authenticate}
- * </p>
- * <p>
- * The client also supports TLS encryption for both, HTTP and TCP transports to provide a secure connection. <br>
- * Please, note that the open source version of QuestDB does not support TLS, and requires an external reverse-proxy,
- * such as Nginx to enable encryption.
- * </p>
- * <p>
- * The client uses a buffer to store data. It automatically flushes the buffer by sending its content to the server.
- * Auto flushing can be disabled via configuration options to gain control over transactions. Initial and maximum
- * buffer sizes can also be set.
- * </p>
- * <p>
- * It is recommended that the Sender is created by using one of the static factory methods,
- * <i>Sender.fromConfig(configString, extraOptions)</i> or <i>Sender.fromEnv(extraOptions)</i>.
- * If the Sender is created via its constructor, at least the SenderOptions configuration object should be
- * initialized from a configuration string to make sure that the parameters are validated. <br>
- * Detailed description of the Sender's configuration options can be found in
- * the <a href="SenderOptions.html">SenderOptions</a> documentation.
- * </p>
- * <p>
- * Extra options can be provided to the Sender in the <i>extraOptions</i> configuration object. <br>
- * A custom logging function and a custom HTTP(S) agent can be passed to the Sender in this object. <br>
- * The logger implementation provides the option to direct log messages to the same place where the host application's
- * log is saved. The default logger writes to the console. <br>
- * The custom HTTP(S) agent option becomes handy if there is a need to modify the default options set for the
- * HTTP(S) connections. A popular setting would be disabling persistent connections, in this case an agent can be
- * passed to the Sender with <i>keepAlive</i> set to <i>false</i>. <br>
- * For example: <i>Sender.fromConfig(`http::addr=host:port`, { agent: new undici.Agent({ connect: { keepAlive: false } })})</i> <br>
- * 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>
+/**
+ * TCP transport implementation. <br>
+ * Supports both plain TCP or secure TLS-encrypted connections with configurable JWK token authentication.
  */
 class TcpTransport implements SenderTransport {
   private readonly secure: boolean;
@@ -77,10 +37,10 @@ class TcpTransport implements SenderTransport {
   private readonly jwk: Record<string, string>;
 
   /**
-   * Creates an instance of Sender.
+   * Creates a new TcpTransport instance.
    *
-   * @param {SenderOptions} options - Sender configuration object. <br>
-   * See SenderOptions documentation for detailed description of configuration options. <br>
+   * @param options - Sender configuration object containing connection and authentication details
+   * @throws Error if required options are missing or protocol is not 'tcp' or 'tcps'
    */
   constructor(options: SenderOptions) {
     if (!options || !options.protocol) {
@@ -121,8 +81,8 @@ class TcpTransport implements SenderTransport {
 
   /**
    * Creates a TCP connection to the database.
-   *
-   * @return {Promise<boolean>} Resolves to true if the client is connected.
+   * @returns Promise resolving to true if the connection is established successfully
+   * @throws Error if connection fails or authentication is rejected
    */
   connect(): Promise<boolean> {
     const connOptions: net.NetConnectOpts | tls.ConnectionOptions = {
@@ -193,6 +153,12 @@ class TcpTransport implements SenderTransport {
     });
   }
 
+  /**
+   * Sends data over the established TCP connection.
+   * @param data - Buffer containing the data to send
+   * @returns Promise resolving to true if data was sent successfully
+   * @throws Error if the data could not be written to the socket
+   */
   send(data: Buffer): Promise<boolean> {
     if (!this.socket || this.socket.destroyed) {
       throw new Error("TCP transport is not connected");