apache-iggy 0.6.0 → 0.7.0

package/dist/client/client.connection.d.ts

@@ -19,22 +19,71 @@
 import { EventEmitter } from 'node:events';
 import type { Socket } from 'node:net';
 import type { ClientConfig } from "./client.type.js";
+/**
+ * Manages the low-level TCP/TLS connection to the Iggy server.
+ * Handles connection lifecycle, reconnection, and data buffering.
+ */
 export declare class IggyConnection extends EventEmitter {
+    /** Client configuration */
     config: ClientConfig;
+    /** Underlying socket connection */
     socket: Socket;
+    /** Whether the connection is established */
     connected: boolean;
+    /** Whether a connection attempt is in progress */
     connecting: boolean;
+    /** Whether the connection is being intentionally closed */
     ending: boolean;
+    /** Whether waiting for more data to complete a response */
     private waitingResponseEnd;
+    /** Reconnection configuration */
     private reconnectOption;
+    /** Number of reconnection attempts made */
     private reconnectCount;
+    /** Buffer for incomplete response data */
     private readBuffers;
+    /**
+     * Creates a new IggyConnection.
+     *
+     * @param config - Client configuration
+     */
     constructor(config: ClientConfig);
+    /**
+     * Establishes the connection to the server.
+     * Sets up event handlers for data, errors, and disconnection.
+     *
+     * @returns Promise that resolves when connected
+     */
     connect(): Promise<unknown>;
+    /**
+     * Attempts to reconnect to the server.
+     * Respects maxRetries limit and emits error when exceeded.
+     *
+     * @param err - Optional error that triggered the reconnection
+     */
     reconnect(err?: Error): Promise<boolean | undefined>;
+    /**
+     * Destroys the connection and marks it as ending.
+     */
     _destroy(): void;
+    /**
+     * Clears the response buffer and resets the waiting state.
+     */
     _endResponseWait(): void;
+    /**
+     * Handles incoming data from the socket.
+     * Buffers incomplete responses and emits complete ones.
+     *
+     * @param data - Incoming data buffer
+     */
     _onData(data: Buffer): void;
+    /**
+     * Writes a command to the socket.
+     *
+     * @param command - Command code
+     * @param payload - Command payload
+     * @returns True if the write was successful
+     */
     writeCommand(command: number, payload: Buffer): boolean;
 }
 //# sourceMappingURL=client.connection.d.ts.map

package/dist/client/client.connection.js

@@ -21,13 +21,31 @@ import { createConnection } from 'node:net';
 import { connect as TLSConnect } from 'node:tls';
 import { serializeCommand } from './client.utils.js';
 import { debug } from './client.debug.js';
+/**
+ * Creates a TCP socket connection.
+ *
+ * @param options - TCP connection options
+ * @returns TCP socket
+ */
 const createTcpSocket = (options) => {
     return createConnection(options);
 };
+/**
+ * Creates a TLS socket connection.
+ *
+ * @param options - TLS connection options including port
+ * @returns TLS socket
+ */
 const createTlsSocket = ({ port, ...options }) => {
     const socket = TLSConnect(port, options);
     return socket;
 };
+/**
+ * Creates a socket based on the transport type in the configuration.
+ *
+ * @param config - Client configuration with transport type
+ * @returns Socket for the specified transport
+ */
 const getTransport = (config) => {
     const { transport, options } = config;
     switch (transport) {
@@ -37,11 +55,23 @@ const getTransport = (config) => {
             return createTcpSocket(options);
     }
 };
+/**
+ * Default reconnection settings.
+ * Attempts reconnection every 5 seconds, up to 12 times.
+ */
 const DefaultReconnectOption = {
     enabled: true,
     interval: 5 * 1000,
     maxRetries: 12
 };
+/**
+ * Recreates a socket after a delay.
+ * Used for reconnection attempts.
+ *
+ * @param option - Client configuration
+ * @param timer - Delay in milliseconds before recreating
+ * @returns Promise resolving to a new socket
+ */
 function recreate(option, timer = 1000) {
     return new Promise((resolve) => {
         setTimeout(() => {
@@ -49,16 +79,34 @@ function recreate(option, timer = 1000) {
         }, timer);
     });
 }
+/**
+ * Manages the low-level TCP/TLS connection to the Iggy server.
+ * Handles connection lifecycle, reconnection, and data buffering.
+ */
 export class IggyConnection extends EventEmitter {
+    /** Client configuration */
     config;
+    /** Underlying socket connection */
     socket;
+    /** Whether the connection is established */
     connected;
+    /** Whether a connection attempt is in progress */
     connecting;
+    /** Whether the connection is being intentionally closed */
     ending;
+    /** Whether waiting for more data to complete a response */
     waitingResponseEnd;
+    /** Reconnection configuration */
     reconnectOption;
+    /** Number of reconnection attempts made */
     reconnectCount;
+    /** Buffer for incomplete response data */
     readBuffers;
+    /**
+     * Creates a new IggyConnection.
+     *
+     * @param config - Client configuration
+     */
     constructor(config) {
         super();
         this.config = config;
@@ -71,6 +119,12 @@ export class IggyConnection extends EventEmitter {
         this.reconnectCount = 0;
         this.readBuffers = Buffer.allocUnsafe(0);
     }
+    /**
+     * Establishes the connection to the server.
+     * Sets up event handlers for data, errors, and disconnection.
+     *
+     * @returns Promise that resolves when connected
+     */
     connect() {
         this.connecting = true;
         this.socket.on('data', this._onData.bind(this));
@@ -98,6 +152,12 @@ export class IggyConnection extends EventEmitter {
             });
         });
     }
+    /**
+     * Attempts to reconnect to the server.
+     * Respects maxRetries limit and emits error when exceeded.
+     *
+     * @param err - Optional error that triggered the reconnection
+     */
     async reconnect(err) {
         const { enabled, interval, maxRetries } = this.reconnectOption;
         debug('reconnect# event/reconnect?', {
@@ -115,14 +175,26 @@ export class IggyConnection extends EventEmitter {
         this.socket = await recreate(this.config, interval);
         this.connect();
     }
+    /**
+     * Destroys the connection and marks it as ending.
+     */
     _destroy() {
         this.ending = true;
         this.socket.destroy();
     }
+    /**
+     * Clears the response buffer and resets the waiting state.
+     */
     _endResponseWait() {
         this.readBuffers = Buffer.allocUnsafe(0);
         this.waitingResponseEnd = false;
     }
+    /**
+     * Handles incoming data from the socket.
+     * Buffers incomplete responses and emits complete ones.
+     *
+     * @param data - Incoming data buffer
+     */
     _onData(data) {
         debug('ONDATA', typeof data, Buffer.isBuffer(data), data?.length, this.waitingResponseEnd);
         // Append new data to any buffered data
@@ -159,6 +231,13 @@ export class IggyConnection extends EventEmitter {
         // All data processed, reset buffers
         this._endResponseWait();
     }
+    /**
+     * Writes a command to the socket.
+     *
+     * @param command - Command code
+     * @param payload - Command payload
+     * @returns True if the write was successful
+     */
     writeCommand(command, payload) {
         const cmd = serializeCommand(command, payload);
         return this.socket.write(cmd);

package/dist/client/client.d.ts

@@ -19,20 +19,66 @@
 import { type Pool } from 'generic-pool';
 import type { RawClient, ClientConfig } from "./client.type.js";
 import { CommandAPI } from '../wire/command-set.js';
+/**
+ * Iggy client with connection pooling support.
+ * Manages a pool of connections for efficient resource utilization.
+ */
 export declare class Client extends CommandAPI {
+    /** Client configuration */
     _config: ClientConfig;
+    /** Connection pool instance */
     _pool: Pool<RawClient>;
+    /**
+     * Creates a new pooled client.
+     *
+     * @param config - Client configuration
+     */
     constructor(config: ClientConfig);
+    /**
+     * Destroys the client and drains all connections from the pool.
+     */
     destroy(): Promise<void>;
 }
+/**
+ * Iggy client that uses a single persistent connection.
+ * Suitable for applications that don't need connection pooling.
+ */
 export declare class SingleClient extends CommandAPI {
+    /** Client configuration */
     _config: ClientConfig;
+    /**
+     * Creates a new single-connection client.
+     *
+     * @param config - Client configuration
+     */
     constructor(config: ClientConfig);
+    /**
+     * Destroys the client connection.
+     */
     destroy(): Promise<void>;
 }
+/**
+ * Simple Iggy client wrapper around an existing RawClient.
+ * Useful when you already have a RawClient instance.
+ */
 export declare class SimpleClient extends CommandAPI {
+    /**
+     * Creates a new simple client from an existing RawClient.
+     *
+     * @param client - Existing RawClient instance
+     */
     constructor(client: RawClient);
+    /**
+     * Destroys the underlying client connection.
+     */
     destroy(): Promise<void>;
 }
+/**
+ * Creates a SimpleClient with the given configuration.
+ * Convenience function for quickly creating a client.
+ *
+ * @param config - Client configuration
+ * @returns SimpleClient instance
+ */
 export declare const getClient: (config: ClientConfig) => Promise<SimpleClient>;
 //# sourceMappingURL=client.d.ts.map

package/dist/client/client.debug.d.ts

@@ -17,5 +17,9 @@
  * under the License.
  */
 import Debug from 'debug';
+/**
+ * Debug logger for the Iggy client.
+ * Enable with DEBUG=iggy:client environment variable.
+ */
 export declare const debug: Debug.Debugger;
 //# sourceMappingURL=client.debug.d.ts.map

package/dist/client/client.debug.js

@@ -17,5 +17,9 @@
  * under the License.
  */
 import Debug from 'debug';
+/**
+ * Debug logger for the Iggy client.
+ * Enable with DEBUG=iggy:client environment variable.
+ */
 export const debug = Debug('iggy:client');
 //# sourceMappingURL=client.debug.js.map

package/dist/client/client.js

@@ -20,7 +20,12 @@ import { createPool } from 'generic-pool';
 import { getRawClient } from '../client/client.socket.js';
 import { CommandAPI } from '../wire/command-set.js';
 import { debug } from './client.debug.js';
-// create & destroy must be async
+/**
+ * Creates a pool factory for managing RawClient instances.
+ *
+ * @param config - Client configuration
+ * @returns Pool factory with create and destroy methods
+ */
 const createPoolFactory = (config) => ({
     create: async function () {
         return getRawClient(config);
@@ -29,6 +34,13 @@ const createPoolFactory = (config) => ({
         return client.destroy();
     }
 });
+/**
+ * Creates a client provider that uses connection pooling.
+ * Automatically acquires and releases clients from the pool.
+ *
+ * @param config - Client configuration including pool size options
+ * @returns Client provider function with attached pool reference
+ */
 const poolClientProvider = (config) => {
     const min = config.poolSize?.min || 1;
     const max = config.poolSize?.max || 4;
@@ -45,9 +57,20 @@ const poolClientProvider = (config) => {
     poolClientProvider._pool = pool;
     return poolClientProvider;
 };
+/**
+ * Iggy client with connection pooling support.
+ * Manages a pool of connections for efficient resource utilization.
+ */
 export class Client extends CommandAPI {
+    /** Client configuration */
     _config;
+    /** Connection pool instance */
     _pool;
+    /**
+     * Creates a new pooled client.
+     *
+     * @param config - Client configuration
+     */
     constructor(config) {
         const pcp = poolClientProvider(config);
         super(pcp);
@@ -55,6 +78,9 @@ export class Client extends CommandAPI {
         this._pool = pcp._pool;
     }
     ;
+    /**
+     * Destroys the client and drains all connections from the pool.
+     */
     async destroy() {
         debug('destroying client pool. pool size is', this._pool.size);
         await this._pool.drain();
@@ -62,34 +88,72 @@ export class Client extends CommandAPI {
         debug('destroyed client pool. pool size is', this._pool.size);
     }
 }
+/**
+ * Creates a client provider that reuses a single connection.
+ *
+ * @param config - Client configuration
+ * @returns Client provider function that always returns the same client
+ */
 const singleClientProvider = (config) => {
     const c = getRawClient(config);
     return async function singleClientProvider() {
         return c;
     };
 };
+/**
+ * Iggy client that uses a single persistent connection.
+ * Suitable for applications that don't need connection pooling.
+ */
 export class SingleClient extends CommandAPI {
+    /** Client configuration */
     _config;
+    /**
+     * Creates a new single-connection client.
+     *
+     * @param config - Client configuration
+     */
     constructor(config) {
         super(singleClientProvider(config));
         this._config = config;
     }
+    /**
+     * Destroys the client connection.
+     */
     async destroy() {
         const s = await this.clientProvider();
         s.destroy();
     }
 }
 ;
+/**
+ * Simple Iggy client wrapper around an existing RawClient.
+ * Useful when you already have a RawClient instance.
+ */
 export class SimpleClient extends CommandAPI {
+    /**
+     * Creates a new simple client from an existing RawClient.
+     *
+     * @param client - Existing RawClient instance
+     */
     constructor(client) {
         super(() => Promise.resolve(client));
     }
+    /**
+     * Destroys the underlying client connection.
+     */
     async destroy() {
         const s = await this.clientProvider();
         s.destroy();
     }
 }
 ;
+/**
+ * Creates a SimpleClient with the given configuration.
+ * Convenience function for quickly creating a client.
+ *
+ * @param config - Client configuration
+ * @returns SimpleClient instance
+ */
 export const getClient = async (config) => {
     const cli = getRawClient(config);
     return new SimpleClient(cli);

package/dist/client/client.socket.d.ts

@@ -18,31 +18,122 @@
  */
 import { EventEmitter } from 'node:events';
 import type { ClientConfig, ClientCredentials, CommandResponse, PasswordCredentials, RawClient, TokenCredentials } from '../client/client.type.js';
+/**
+ * Manages command execution and response handling for the Iggy server.
+ * Implements command queuing, authentication, and heartbeat functionality.
+ */
 export declare class CommandResponseStream extends EventEmitter {
+    /** Client configuration */
     private options;
+    /** Underlying connection to the server */
     private connection;
+    /** Queue of pending command jobs */
     private _execQueue;
+    /** Whether the stream is currently processing a command */
     busy: boolean;
+    /** Whether the client has been authenticated */
     isAuthenticated: boolean;
+    /** Authenticated user ID */
     userId?: number;
+    /** Heartbeat interval timer handle */
     heartbeatIntervalHandler?: NodeJS.Timeout;
+    /**
+     * Creates a new CommandResponseStream.
+     *
+     * @param options - Client configuration
+     */
     constructor(options: ClientConfig);
+    /**
+     * Initializes the stream by setting up heartbeat and connection event handlers.
+     */
     _init(): void;
+    /**
+     * Sends a command to the server.
+     * Automatically handles connection and authentication if needed.
+     *
+     * @param command - Command code to send
+     * @param payload - Command payload buffer
+     * @param handleResponse - Whether to parse the response (default: true)
+     * @param last - Whether to add to end of queue (default: true)
+     * @returns Promise resolving to the command response
+     */
     sendCommand(command: number, payload: Buffer, handleResponse?: boolean, last?: boolean): Promise<CommandResponse>;
+    /**
+     * Processes queued commands sequentially.
+     * Emits 'finishQueue' when all commands are processed.
+     *
+     * @param handleResponse - Whether to parse responses
+     */
     _processQueue(handleResponse?: boolean): Promise<void>;
+    /**
+     * Processes a single command by writing it to the connection and waiting for response.
+     *
+     * @param command - Command code
+     * @param payload - Command payload
+     * @param handleResp - Whether to parse the response
+     * @returns Promise resolving to the command response
+     */
     _processNext(command: number, payload: Buffer, handleResp?: boolean): Promise<CommandResponse>;
+    /**
+     * Fails all queued commands with the given error.
+     *
+     * @param err - Error to reject all queued commands with
+     */
     _failQueue(err: Error): void;
+    /**
+     * Authenticates the client with the server.
+     *
+     * @param creds - Authentication credentials (token or password)
+     * @returns True if authentication succeeded
+     */
     authenticate(creds: ClientCredentials): Promise<boolean>;
+    /**
+     * Authenticates using username and password.
+     *
+     * @param creds - Password credentials
+     * @returns Login response with user ID
+     */
     _authWithPassword(creds: PasswordCredentials): Promise<{
         userId: number;
     }>;
+    /**
+     * Authenticates using a token.
+     *
+     * @param creds - Token credentials
+     * @returns Login response with user ID
+     */
     _authWithToken(creds: TokenCredentials): Promise<{
         userId: number;
     }>;
+    /**
+     * Sends a ping command to the server.
+     *
+     * @returns Ping response
+     */
     ping(): Promise<boolean>;
+    /**
+     * Starts sending periodic heartbeat pings to keep the connection alive.
+     *
+     * @param interval - Heartbeat interval in milliseconds
+     */
     heartbeat(interval?: number): void;
+    /**
+     * Returns the underlying socket as a readable stream.
+     *
+     * @returns The connection socket
+     */
     getReadStream(): import("net").Socket;
+    /**
+     * Destroys the stream and cleans up resources.
+     * Stops heartbeat and destroys the connection.
+     */
     destroy(): void;
 }
+/**
+ * Creates a new RawClient instance.
+ *
+ * @param options - Client configuration
+ * @returns RawClient instance
+ */
 export declare function getRawClient(options: ClientConfig): RawClient;
 //# sourceMappingURL=client.socket.d.ts.map