apache-iggy 0.6.0 → 0.7.0

package/dist/client/client.socket.js

@@ -22,19 +22,38 @@ import { responseError } from '../wire/error.utils.js';
 import { debug } from './client.debug.js';
 import { IggyConnection } from './client.connection.js';
 import { LOGIN, LOGIN_WITH_TOKEN, PING } from '../wire/index.js';
+/**
+ * Command codes that can be executed without authentication.
+ */
 const UNLOGGED_COMMAND_CODE = [
     PING.code,
     LOGIN.code,
     LOGIN_WITH_TOKEN.code
 ];
+/**
+ * Manages command execution and response handling for the Iggy server.
+ * Implements command queuing, authentication, and heartbeat functionality.
+ */
 export class CommandResponseStream extends EventEmitter {
+    /** Client configuration */
     options;
+    /** Underlying connection to the server */
     connection;
+    /** Queue of pending command jobs */
     _execQueue;
+    /** Whether the stream is currently processing a command */
     busy;
+    /** Whether the client has been authenticated */
     isAuthenticated;
+    /** Authenticated user ID */
     userId;
+    /** Heartbeat interval timer handle */
     heartbeatIntervalHandler;
+    /**
+     * Creates a new CommandResponseStream.
+     *
+     * @param options - Client configuration
+     */
     constructor(options) {
         super();
         this.options = options;
@@ -45,12 +64,25 @@ export class CommandResponseStream extends EventEmitter {
         this._init();
     }
     ;
+    /**
+     * Initializes the stream by setting up heartbeat and connection event handlers.
+     */
     _init() {
         this.heartbeat(this.options.heartbeatInterval);
         this.connection.on('disconnected', async () => {
             this.isAuthenticated = false;
         });
     }
+    /**
+     * 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
+     */
     async sendCommand(command, payload, handleResponse = true, last = true) {
         if (!this.connection.connected)
             await this.connection.connect();
@@ -64,6 +96,12 @@ export class CommandResponseStream extends EventEmitter {
             this._processQueue(handleResponse);
         });
     }
+    /**
+     * Processes queued commands sequentially.
+     * Emits 'finishQueue' when all commands are processed.
+     *
+     * @param handleResponse - Whether to parse responses
+     */
     async _processQueue(handleResponse = true) {
         if (this.busy)
             return;
@@ -83,6 +121,14 @@ export class CommandResponseStream extends EventEmitter {
         this.busy = false;
         this.emit('finishQueue');
     }
+    /**
+     * 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, payload, handleResp = true) {
         const lastWrite = this.connection.writeCommand(command, payload);
         debug('==> writeCommand', lastWrite);
@@ -103,10 +149,21 @@ export class CommandResponseStream extends EventEmitter {
             });
         });
     }
+    /**
+     * Fails all queued commands with the given error.
+     *
+     * @param err - Error to reject all queued commands with
+     */
     _failQueue(err) {
         this._execQueue.forEach(({ reject }) => reject(err));
         this._execQueue = [];
     }
+    /**
+     * Authenticates the client with the server.
+     *
+     * @param creds - Authentication credentials (token or password)
+     * @returns True if authentication succeeded
+     */
     async authenticate(creds) {
         const r = ('token' in creds) ?
             await this._authWithToken(creds) :
@@ -115,21 +172,43 @@ export class CommandResponseStream extends EventEmitter {
         this.userId = r.userId;
         return this.isAuthenticated;
     }
+    /**
+     * Authenticates using username and password.
+     *
+     * @param creds - Password credentials
+     * @returns Login response with user ID
+     */
     async _authWithPassword(creds) {
         const pl = LOGIN.serialize(creds);
         const logr = await this.sendCommand(LOGIN.code, pl, true, false);
         return LOGIN.deserialize(logr);
     }
+    /**
+     * Authenticates using a token.
+     *
+     * @param creds - Token credentials
+     * @returns Login response with user ID
+     */
     async _authWithToken(creds) {
         const pl = LOGIN_WITH_TOKEN.serialize(creds);
         const logr = await this.sendCommand(LOGIN_WITH_TOKEN.code, pl, true, false);
         return LOGIN_WITH_TOKEN.deserialize(logr);
     }
+    /**
+     * Sends a ping command to the server.
+     *
+     * @returns Ping response
+     */
     async ping() {
         const pl = PING.serialize();
         const pingR = await this.sendCommand(PING.code, pl, true);
         return PING.deserialize(pingR);
     }
+    /**
+     * Starts sending periodic heartbeat pings to keep the connection alive.
+     *
+     * @param interval - Heartbeat interval in milliseconds
+     */
     heartbeat(interval) {
         if (!interval)
             return;
@@ -140,9 +219,18 @@ export class CommandResponseStream extends EventEmitter {
             }
         }, interval);
     }
+    /**
+     * Returns the underlying socket as a readable stream.
+     *
+     * @returns The connection socket
+     */
     getReadStream() {
         return this.connection.socket;
     }
+    /**
+     * Destroys the stream and cleans up resources.
+     * Stops heartbeat and destroys the connection.
+     */
     destroy() {
         if (this.heartbeatIntervalHandler)
             clearInterval(this.heartbeatIntervalHandler);
@@ -150,6 +238,12 @@ export class CommandResponseStream extends EventEmitter {
     }
 }
 ;
+/**
+ * Creates a new RawClient instance.
+ *
+ * @param options - Client configuration
+ * @returns RawClient instance
+ */
 export function getRawClient(options) {
     return new CommandResponseStream(options);
 }

package/dist/client/client.type.d.ts

@@ -19,51 +19,123 @@
 import type { Readable } from 'stream';
 import { type TcpSocketConnectOpts } from 'node:net';
 import { type ConnectionOptions } from 'node:tls';
+/**
+ * TCP socket connection options.
+ * Alias for Node.js TcpSocketConnectOpts.
+ */
 export type TcpOption = TcpSocketConnectOpts;
+/**
+ * TLS socket connection options.
+ * Combines port number with Node.js TLS ConnectionOptions.
+ */
 export type TlsOption = {
     port: number;
 } & ConnectionOptions;
+/**
+ * Response from a command sent to the Iggy server.
+ */
 export type CommandResponse = {
+    /** Response status code (0 indicates success) */
     status: number;
+    /** Length of the response data in bytes */
     length: number;
+    /** Response payload data */
     data: Buffer;
 };
+/**
+ * Low-level client interface for communicating with the Iggy server.
+ * Provides direct access to command sending and event handling.
+ */
 export type RawClient = {
+    /** Sends a command to the server and returns the response */
     sendCommand: (code: number, payload: Buffer, handleResponse?: boolean) => Promise<CommandResponse>;
+    /** Whether the client has been authenticated */
     isAuthenticated: boolean;
+    /** Authenticates the client with the server */
     authenticate: (c: ClientCredentials) => Promise<boolean>;
+    /** Destroys the client connection */
     destroy: () => void;
+    /** Registers an event listener */
     on: (ev: string, cb: (e?: unknown) => void) => void;
+    /** Registers a one-time event listener */
     once: (ev: string, cb: (e?: unknown) => void) => void;
+    /** Returns the underlying readable stream */
     getReadStream: () => Readable;
 };
+/**
+ * Function type that provides a RawClient instance.
+ * Used for dependency injection and connection pooling.
+ */
 export type ClientProvider = () => Promise<RawClient>;
+/**
+ * Available transport protocols for connecting to the Iggy server.
+ */
 export declare const Transports: readonly ["TCP", "TLS"];
+/**
+ * Transport protocol type.
+ * Currently supports 'TCP' and 'TLS'.
+ */
 export type TransportType = typeof Transports[number];
+/**
+ * Configuration options for automatic reconnection.
+ */
 export type ReconnectOption = {
+    /** Whether automatic reconnection is enabled */
     enabled: boolean;
+    /** Interval between reconnection attempts in milliseconds */
     interval: number;
+    /** Maximum number of reconnection attempts */
     maxRetries: number;
 };
+/**
+ * Union type for transport-specific connection options.
+ */
 export type TransportOption = TcpOption | TlsOption;
+/**
+ * Token-based authentication credentials.
+ */
 export type TokenCredentials = {
+    /** Authentication token */
     token: string;
 };
+/**
+ * Username/password authentication credentials.
+ */
 export type PasswordCredentials = {
+    /** Username for authentication */
     username: string;
+    /** Password for authentication */
     password: string;
 };
+/**
+ * Union type for client authentication credentials.
+ * Supports either token-based or password-based authentication.
+ */
 export type ClientCredentials = TokenCredentials | PasswordCredentials;
+/**
+ * Connection pool size configuration.
+ */
 export type PoolSizeOption = {
+    /** Minimum number of connections in the pool */
     min?: number;
+    /** Maximum number of connections in the pool */
     max?: number;
 };
+/**
+ * Complete client configuration for connecting to the Iggy server.
+ */
 export type ClientConfig = {
+    /** Transport protocol to use (TCP or TLS) */
     transport: TransportType;
+    /** Transport-specific connection options */
     options: TransportOption;
+    /** Authentication credentials */
     credentials: ClientCredentials;
+    /** Connection pool size configuration */
     poolSize?: PoolSizeOption;
+    /** Automatic reconnection configuration */
     reconnect?: ReconnectOption;
+    /** Interval for sending heartbeat pings in milliseconds */
     heartbeatInterval?: number;
 };
 //# sourceMappingURL=client.type.d.ts.map

package/dist/client/client.type.js

@@ -16,5 +16,8 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+/**
+ * Available transport protocols for connecting to the Iggy server.
+ */
 export const Transports = ['TCP', 'TLS' /**, 'QUIC' */];
 //# sourceMappingURL=client.type.js.map

package/dist/client/client.utils.d.ts

@@ -18,12 +18,40 @@
  */
 import { Transform } from 'node:stream';
 import type { CommandResponse } from './client.type.js';
+/**
+ * Parses a raw response buffer into a structured CommandResponse.
+ * Extracts status code, length, and payload data from the buffer.
+ *
+ * @param r - Raw response buffer from the server
+ * @returns Parsed command response with status, length, and data
+ */
 export declare const handleResponse: (r: Buffer) => {
     status: number;
     length: number;
     data: Buffer<ArrayBufferLike>;
 };
+/**
+ * Creates a Transform stream that parses response buffers.
+ * Transforms raw server responses into just the data payload.
+ *
+ * @returns Transform stream for processing server responses
+ */
 export declare const handleResponseTransform: () => Transform;
+/**
+ * Deserializes a void response from the server.
+ * Returns true if the command succeeded with no data.
+ *
+ * @param r - Command response to check
+ * @returns True if the response indicates success with no data
+ */
 export declare const deserializeVoidResponse: (r: CommandResponse) => boolean;
+/**
+ * Serializes a command and its payload into a buffer for sending to the server.
+ * Creates the wire format: [payload_size (4 bytes)][command (4 bytes)][payload]
+ *
+ * @param command - Command code to send
+ * @param payload - Command payload buffer
+ * @returns Buffer ready to be sent to the server
+ */
 export declare const serializeCommand: (command: number, payload: Buffer) => Buffer<ArrayBuffer>;
 //# sourceMappingURL=client.utils.d.ts.map

package/dist/client/client.utils.js

@@ -19,6 +19,13 @@
 import { Transform } from 'node:stream';
 import { translateCommandCode } from '../wire/command.code.js';
 import { debug } from './client.debug.js';
+/**
+ * Parses a raw response buffer into a structured CommandResponse.
+ * Extracts status code, length, and payload data from the buffer.
+ *
+ * @param r - Raw response buffer from the server
+ * @returns Parsed command response with status, length, and data
+ */
 export const handleResponse = (r) => {
     const status = r.readUint32LE(0);
     const length = r.readUint32LE(4);
@@ -27,6 +34,12 @@ export const handleResponse = (r) => {
         status, length, data: r.subarray(8)
     };
 };
+/**
+ * Creates a Transform stream that parses response buffers.
+ * Transforms raw server responses into just the data payload.
+ *
+ * @returns Transform stream for processing server responses
+ */
 export const handleResponseTransform = () => new Transform({
     transform(chunk, encoding, cb) {
         try {
@@ -39,8 +52,24 @@ export const handleResponseTransform = () => new Transform({
         }
     }
 });
+/**
+ * Deserializes a void response from the server.
+ * Returns true if the command succeeded with no data.
+ *
+ * @param r - Command response to check
+ * @returns True if the response indicates success with no data
+ */
 export const deserializeVoidResponse = (r) => r.status === 0 && r.data.length === 0;
+/** Length of the command code in bytes */
 const COMMAND_LENGTH = 4;
+/**
+ * Serializes a command and its payload into a buffer for sending to the server.
+ * Creates the wire format: [payload_size (4 bytes)][command (4 bytes)][payload]
+ *
+ * @param command - Command code to send
+ * @param payload - Command payload buffer
+ * @returns Buffer ready to be sent to the server
+ */
 export const serializeCommand = (command, payload) => {
     const payloadSize = payload.length + COMMAND_LENGTH;
     const data = Buffer.allocUnsafe(8 + payload.length);

package/dist/e2e/tcp.cluster.e2e.js

@@ -20,7 +20,7 @@ import { after, describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { getTestClient } from "./test-client.utils.js";
 // cluster mode still in dev atm
-// response is mocked from /core/configs/server.toml
+// response is mocked from /core/server/config.toml
 const expectedMeta = {
     name: "iggy-cluster",
     nodes: [

package/dist/index.d.ts

@@ -16,7 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-export { type Id, PollingStrategy, Consumer, Partitioning, HeaderValue, } from './wire/index.js';
-export * from './client/index.js';
-export * from './stream/index.js';
+export { type Id, PollingStrategy, Consumer, Partitioning, HeaderValue, HeaderKeyFactory, } from "./wire/index.js";
+export * from "./client/index.js";
+export * from "./stream/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -16,7 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-export { PollingStrategy, Consumer, Partitioning, HeaderValue, } from './wire/index.js';
-export * from './client/index.js';
-export * from './stream/index.js';
+export { PollingStrategy, Consumer, Partitioning, HeaderValue, HeaderKeyFactory, } from "./wire/index.js";
+export * from "./client/index.js";
+export * from "./stream/index.js";
 //# sourceMappingURL=index.js.map

package/dist/tcp.sm.utils.d.ts

@@ -16,79 +16,68 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { type Partitioning, type Message } from './wire/index.js';
-import type { ClientProvider } from './client/client.type.js';
-import type { Id } from './wire/identifier.utils.js';
+import { type Partitioning, type Message } from "./wire/index.js";
+import type { ClientProvider } from "./client/client.type.js";
+import type { Id } from "./wire/identifier.utils.js";
 export declare const someMessageContent: () => {
     payload: string;
-    headers: {
-        foo: import("./wire/message/header.type.js").HeaderValueInt32;
-        bar: import("./wire/message/header.type.js").HeaderValueUint8;
-    };
-    Headers?: undefined;
+    headers: ({
+        key: import("./wire/message/header.type.js").HeaderKeyString;
+        value: import("./wire/message/header.type.js").HeaderValueInt32;
+    } | {
+        key: import("./wire/message/header.type.js").HeaderKeyString;
+        value: import("./wire/message/header.type.js").HeaderValueUint8;
+    })[];
 } | {
     payload: string;
     headers?: undefined;
-    Headers?: undefined;
 } | {
     payload: string;
     headers: {
-        'x-header-string-1': import("./wire/message/header.type.js").HeaderValueString;
-    };
-    Headers?: undefined;
+        key: import("./wire/message/header.type.js").HeaderKeyString;
+        value: import("./wire/message/header.type.js").HeaderValueString;
+    }[];
 } | {
     payload: string;
     headers: {
-        'x-header-bool': import("./wire/message/header.type.js").HeaderValueBool;
-    };
-    Headers?: undefined;
-} | {
-    payload: string;
-    Headers: {
-        'x-header-bool': import("./wire/message/header.type.js").HeaderValueBool;
-    };
-    headers?: undefined;
+        key: import("./wire/message/header.type.js").HeaderKeyString;
+        value: import("./wire/message/header.type.js").HeaderValueBool;
+    }[];
 };
 export declare const generateMessages: (count?: number) => ({
     payload: string;
-    headers: {
-        foo: import("./wire/message/header.type.js").HeaderValueInt32;
-        bar: import("./wire/message/header.type.js").HeaderValueUint8;
-    };
-    Headers?: undefined;
+    headers: ({
+        key: import("./wire/message/header.type.js").HeaderKeyString;
+        value: import("./wire/message/header.type.js").HeaderValueInt32;
+    } | {
+        key: import("./wire/message/header.type.js").HeaderKeyString;
+        value: import("./wire/message/header.type.js").HeaderValueUint8;
+    })[];
     id: string;
 } | {
     payload: string;
     headers?: undefined;
-    Headers?: undefined;
     id: string;
 } | {
     payload: string;
     headers: {
-        'x-header-string-1': import("./wire/message/header.type.js").HeaderValueString;
-    };
-    Headers?: undefined;
+        key: import("./wire/message/header.type.js").HeaderKeyString;
+        value: import("./wire/message/header.type.js").HeaderValueString;
+    }[];
     id: string;
 } | {
     payload: string;
     headers: {
-        'x-header-bool': import("./wire/message/header.type.js").HeaderValueBool;
-    };
-    Headers?: undefined;
-    id: string;
-} | {
-    payload: string;
-    Headers: {
-        'x-header-bool': import("./wire/message/header.type.js").HeaderValueBool;
-    };
-    headers?: undefined;
+        key: import("./wire/message/header.type.js").HeaderKeyString;
+        value: import("./wire/message/header.type.js").HeaderValueBool;
+    }[];
     id: string;
 })[];
 export declare const sendSomeMessages: (s: ClientProvider) => (streamId: Id, topicId: Id, partition: Partitioning) => Promise<true>;
 export declare const formatPolledMessages: (msgs: Message[]) => {
-    id: string | BigInt;
+    id: string | bigint;
     offset: bigint;
-    headers: import("./wire/message/header.utils.js").HeadersMap;
+    headers: import("./wire/message/header.utils.js").ParsedHeaderEntry[];
     payload: string;
     timestamp: Date;
     checksum: bigint;

package/dist/tcp.sm.utils.js

@@ -16,23 +16,36 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import assert from 'node:assert/strict';
-import { v7 } from './wire/uuid.utils.js';
-import { sendMessages, HeaderValue } from './wire/index.js';
-const h0 = { 'foo': HeaderValue.Int32(42), 'bar': HeaderValue.Uint8(123) };
-const h1 = { 'x-header-string-1': HeaderValue.String('incredible') };
-const h2 = { 'x-header-bool': HeaderValue.Bool(false) };
+import assert from "node:assert/strict";
+import { v7 } from "./wire/uuid.utils.js";
+import { sendMessages, HeaderValue, HeaderKeyFactory, } from "./wire/index.js";
+const h0 = [
+    { key: HeaderKeyFactory.String("foo"), value: HeaderValue.Int32(42) },
+    { key: HeaderKeyFactory.String("bar"), value: HeaderValue.Uint8(123) },
+];
+const h1 = [
+    {
+        key: HeaderKeyFactory.String("x-header-string-1"),
+        value: HeaderValue.String("incredible"),
+    },
+];
+const h2 = [
+    {
+        key: HeaderKeyFactory.String("x-header-bool"),
+        value: HeaderValue.Bool(false),
+    },
+];
 const messages = [
-    { payload: 'content with header', headers: h0 },
-    { payload: 'content solo' },
-    { payload: 'yolo msg' },
-    { payload: 'yolo msg 2' },
-    { payload: 'this is fuu', headers: h1 },
-    { payload: 'this is bar', headers: h2 },
-    { payload: 'yolo msg 3' },
-    { payload: 'fuu again', headers: h1 },
-    { payload: 'damnit', headers: h0 },
-    { payload: 'yolo msg 4', Headers: h2 },
+    { payload: "content with header", headers: h0 },
+    { payload: "content solo" },
+    { payload: "yolo msg" },
+    { payload: "yolo msg 2" },
+    { payload: "this is fuu", headers: h1 },
+    { payload: "this is bar", headers: h2 },
+    { payload: "yolo msg 3" },
+    { payload: "fuu again", headers: h1 },
+    { payload: "damnit", headers: h0 },
+    { payload: "yolo msg 4", headers: h2 },
 ];
 export const someMessageContent = () => messages[Math.floor(Math.random() * messages.length)];
 export const generateMessages = (count = 1) => {
@@ -40,25 +53,28 @@ export const generateMessages = (count = 1) => {
 };
 export const sendSomeMessages = (s) => async (streamId, topicId, partition) => {
     const rSend = await sendMessages(s)({
-        topicId, streamId, messages: generateMessages(100), partition
+        topicId,
+        streamId,
+        messages: generateMessages(100),
+        partition,
     });
     assert.ok(rSend);
     return rSend;
 };
-export const formatPolledMessages = (msgs) => msgs.map(m => {
-    const { headers: { id, offset, timestamp, checksum }, payload, userHeaders } = m;
+export const formatPolledMessages = (msgs) => msgs.map((m) => {
+    const { headers: { id, offset, timestamp, checksum }, payload, userHeaders, } = m;
     return {
         id,
         offset,
         headers: userHeaders,
         payload: payload.toString(),
         timestamp,
-        checksum
+        checksum,
     };
 });
-export const getIggyAddress = (host = '127.0.0.1', port = 8090) => {
+export const getIggyAddress = (host = "127.0.0.1", port = 8090) => {
     if (process.env.IGGY_TCP_ADDRESS) {
-        const s = (process.env.IGGY_TCP_ADDRESS || '').split(':');
+        const s = (process.env.IGGY_TCP_ADDRESS || "").split(":");
         [host, port] = [s[0], s[1] ? parseInt(s[1].toString(), 10) : port];
     }
     return [host, port];

package/dist/type.utils.d.ts

@@ -16,6 +16,20 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+/**
+ * Reverses the keys and values of a record object.
+ * Creates a new record where the original values become keys and vice versa.
+ *
+ * @typeParam T - Type of the original keys
+ * @typeParam U - Type of the original values (becomes keys in result)
+ * @param input - Record object to reverse
+ * @returns New record with swapped keys and values
+ */
 export declare function reverseRecord<T extends PropertyKey, U extends PropertyKey>(input: Record<T, U>): Record<U, T>;
+/**
+ * Extracts the value types from an object type.
+ *
+ * @typeParam T - Object type to extract values from
+ */
 export type ValueOf<T> = T[keyof T];
 //# sourceMappingURL=type.utils.d.ts.map