apache-iggy 0.6.0 → 0.7.0

package/dist/wire/message/message.utils.d.ts

@@ -19,17 +19,77 @@
 import { type Headers } from './header.utils.js';
 import { type Id } from '../identifier.utils.js';
 import { type Partitioning } from './partitioning.utils.js';
+/** Valid types for message ID: numeric, bigint, or UUID string */
 export type MessageIdKind = number | bigint | string;
+/**
+ * Message creation parameters.
+ */
 export type CreateMessage = {
+    /** Optional message ID (auto-generated if not provided) */
     id?: MessageIdKind;
+    /** Optional user-defined headers */
     headers?: Headers;
+    /** Message payload as string or Buffer */
     payload: string | Buffer;
 };
+/**
+ * Type guard to check if a value is a valid message ID.
+ *
+ * @param x - Value to check
+ * @returns True if the value is a valid MessageIdKind
+ */
 export declare const isValidMessageId: (x?: unknown) => x is MessageIdKind;
+/**
+ * Serializes a message ID to a 16-byte buffer.
+ * Supports undefined (zero), numeric, bigint, and UUID string formats.
+ *
+ * @param id - Message ID to serialize
+ * @returns 16-byte buffer containing the serialized ID
+ * @throws Error if the ID format is invalid
+ */
 export declare const serializeMessageId: (id?: unknown) => Buffer<ArrayBufferLike>;
+/**
+ * Serializes a single message to wire format.
+ * Format: [iggy_header][payload][user_headers]
+ *
+ * @param msg - Message to serialize
+ * @returns Serialized message buffer
+ */
 export declare const serializeMessage: (msg: CreateMessage) => Buffer<ArrayBuffer>;
+/**
+ * Serializes multiple messages to an array of buffers.
+ *
+ * @param messages - Array of messages to serialize
+ * @returns Array of serialized message buffers
+ */
 export declare const serializeMessages: (messages: CreateMessage[]) => Buffer<ArrayBuffer>[];
+/**
+ * Creates an index buffer for a batch of messages.
+ * Each index entry is 16 bytes tracking message positions.
+ *
+ * @param messages - Array of serialized message buffers
+ * @returns Index buffer
+ */
 export declare const createMessagesIndex: (messages: Buffer[]) => Buffer<ArrayBuffer>;
+/**
+ * Serializes a send messages command payload.
+ * Includes stream/topic identifiers, partitioning, and all messages with index.
+ *
+ * @param streamId - Stream identifier
+ * @param topicId - Topic identifier
+ * @param messages - Array of messages to send
+ * @param partitioning - Optional partitioning strategy
+ * @returns Serialized command payload
+ */
 export declare const serializeSendMessages: (streamId: Id, topicId: Id, messages: CreateMessage[], partitioning?: Partitioning) => Buffer<ArrayBuffer>;
+/**
+ * Serializes a flush unsaved buffers command payload.
+ *
+ * @param streamId - Stream identifier
+ * @param topicId - Topic identifier
+ * @param partitionId - Partition ID to flush
+ * @param fsync - Whether to force sync to disk
+ * @returns Serialized command payload
+ */
 export declare const serializeFlushUnsavedBuffers: (streamId: Id, topicId: Id, partitionId: number, fsync?: boolean) => Buffer<ArrayBuffer>;
 //# sourceMappingURL=message.utils.d.ts.map

package/dist/wire/message/message.utils.js

@@ -24,12 +24,26 @@ import { serializePartitioning } from './partitioning.utils.js';
 import { parse as parseUUID } from '../uuid.utils.js';
 import { serializeIggyMessageHeader } from './iggy-header.utils.js';
 const debug = Debug('iggy:client');
-/** index size per messages in bit */
+/** Size of the message index entry in bytes (16 bytes per message) */
 const INDEX_SIZE = 16;
+/**
+ * Type guard to check if a value is a valid message ID.
+ *
+ * @param x - Value to check
+ * @returns True if the value is a valid MessageIdKind
+ */
 export const isValidMessageId = (x) => x === undefined ||
     'string' === typeof x ||
     'bigint' === typeof x ||
     'number' === typeof x;
+/**
+ * Serializes a message ID to a 16-byte buffer.
+ * Supports undefined (zero), numeric, bigint, and UUID string formats.
+ *
+ * @param id - Message ID to serialize
+ * @returns 16-byte buffer containing the serialized ID
+ * @throws Error if the ID format is invalid
+ */
 export const serializeMessageId = (id) => {
     if (!isValidMessageId(id))
         throw new Error(`invalid message id: '${id}' (use uuid string | number | bigint >= 0)`);
@@ -49,6 +63,13 @@ export const serializeMessageId = (id) => {
         throw new Error(`invalid message id: '${id}' (use uuid string | number | bigint >= 0)`, { cause: err });
     }
 };
+/**
+ * Serializes a single message to wire format.
+ * Format: [iggy_header][payload][user_headers]
+ *
+ * @param msg - Message to serialize
+ * @returns Serialized message buffer
+ */
 export const serializeMessage = (msg) => {
     const { id, headers, payload } = msg;
     const bId = serializeMessageId(id);
@@ -64,7 +85,20 @@ export const serializeMessage = (msg) => {
     );
     return r;
 };
+/**
+ * Serializes multiple messages to an array of buffers.
+ *
+ * @param messages - Array of messages to serialize
+ * @returns Array of serialized message buffers
+ */
 export const serializeMessages = (messages) => messages.map(c => serializeMessage(c));
+/**
+ * Creates an index buffer for a batch of messages.
+ * Each index entry is 16 bytes tracking message positions.
+ *
+ * @param messages - Array of serialized message buffers
+ * @returns Index buffer
+ */
 export const createMessagesIndex = (messages) => {
     const bIndex = Buffer.allocUnsafe(messages.length * INDEX_SIZE);
     let currentIndex = 0;
@@ -78,6 +112,16 @@ export const createMessagesIndex = (messages) => {
     });
     return bIndex;
 };
+/**
+ * Serializes a send messages command payload.
+ * Includes stream/topic identifiers, partitioning, and all messages with index.
+ *
+ * @param streamId - Stream identifier
+ * @param topicId - Topic identifier
+ * @param messages - Array of messages to send
+ * @param partitioning - Optional partitioning strategy
+ * @returns Serialized command payload
+ */
 export const serializeSendMessages = (streamId, topicId, messages, partitioning) => {
     const streamIdentifier = serializeIdentifier(streamId);
     const topicIdentifier = serializeIdentifier(topicId);
@@ -97,6 +141,15 @@ export const serializeSendMessages = (streamId, topicId, messages, partitioning)
         ...bMessagesArray
     ]);
 };
+/**
+ * Serializes a flush unsaved buffers command payload.
+ *
+ * @param streamId - Stream identifier
+ * @param topicId - Topic identifier
+ * @param partitionId - Partition ID to flush
+ * @param fsync - Whether to force sync to disk
+ * @returns Serialized command payload
+ */
 export const serializeFlushUnsavedBuffers = (streamId, topicId, partitionId, fsync = false) => {
     const streamIdentifier = serializeIdentifier(streamId);
     const topicIdentifier = serializeIdentifier(topicId);

package/dist/wire/message/partitioning.utils.d.ts

@@ -17,35 +17,74 @@
  * under the License.
  */
 import type { ValueOf } from '../../type.utils.js';
+/**
+ * Enumeration of partition selection strategies.
+ */
 export declare const PartitionKind: {
+    /** Server selects partition using round-robin */
     readonly Balanced: 1;
+    /** Client specifies exact partition ID */
     readonly PartitionId: 2;
+    /** Client provides a key for consistent hashing */
     readonly MessageKey: 3;
 };
+/** Type alias for the PartitionKind object */
 export type PartitionKind = typeof PartitionKind;
+/** String literal type of partition kind names */
 export type PartitionKindId = keyof PartitionKind;
+/** Numeric values of partition kinds */
 export type PartitionKindValue = ValueOf<PartitionKind>;
+/** Balanced partitioning (server selects partition) */
 export type Balanced = {
     kind: PartitionKind['Balanced'];
     value: null;
 };
+/** Explicit partition ID selection */
 export type PartitionId = {
     kind: PartitionKind['PartitionId'];
+    /** Partition ID (uint32) */
     value: number;
 };
+/** Possible types for message key values */
 export type MessageKeyValue = string | number | bigint | Buffer;
+/** Message key-based partitioning for consistent hashing */
 export type MessageKey = {
     kind: PartitionKind['MessageKey'];
     value: MessageKeyValue;
 };
+/** Union of all partitioning strategies */
 export type Partitioning = Balanced | PartitionId | MessageKey;
+/**
+ * Factory object for creating partitioning strategies.
+ */
 export declare const Partitioning: {
     Balanced: Balanced;
     PartitionId: (id: number) => PartitionId;
     MessageKey: (key: MessageKeyValue) => MessageKey;
 };
+/**
+ * Serializes a message key value to a buffer.
+ *
+ * @param v - Message key value
+ * @returns Serialized buffer
+ * @throws Error if the value type is not supported
+ */
 export declare const serializeMessageKey: (v: MessageKeyValue) => Buffer<ArrayBufferLike>;
+/**
+ * Serializes the value portion of a partitioning strategy.
+ *
+ * @param part - Partitioning strategy
+ * @returns Serialized value buffer
+ */
 export declare const serializePartitioningValue: (part: Partitioning) => Buffer;
+/** Default partitioning strategy (balanced) */
 export declare const default_partionning: Balanced;
+/**
+ * Serializes a partitioning strategy to wire format.
+ * Format: [kind (1 byte)][value_length (1 byte)][value]
+ *
+ * @param p - Optional partitioning strategy (defaults to balanced)
+ * @returns Serialized partitioning buffer
+ */
 export declare const serializePartitioning: (p?: Partitioning) => Buffer<ArrayBuffer>;
 //# sourceMappingURL=partitioning.utils.d.ts.map

package/dist/wire/message/partitioning.utils.js

@@ -17,29 +17,57 @@
  * under the License.
  */
 import { uint32ToBuf, uint64ToBuf } from '../number.utils.js';
+/**
+ * Enumeration of partition selection strategies.
+ */
 export const PartitionKind = {
+    /** Server selects partition using round-robin */
     Balanced: 1,
+    /** Client specifies exact partition ID */
     PartitionId: 2,
+    /** Client provides a key for consistent hashing */
     MessageKey: 3
 };
+/** Balanced partitioning constant */
 const Balanced = {
     kind: PartitionKind.Balanced,
     value: null
 };
+/**
+ * Creates a partition ID partitioning strategy.
+ *
+ * @param id - Partition ID to target
+ * @returns PartitionId partitioning object
+ */
 const PartitionId = (id) => ({
     kind: PartitionKind.PartitionId,
     value: id
 });
+/**
+ * Creates a message key partitioning strategy.
+ *
+ * @param key - Key for consistent hashing
+ * @returns MessageKey partitioning object
+ */
 const MessageKey = (key) => ({
     kind: PartitionKind.MessageKey,
     value: key
 });
-// Helper
+/**
+ * Factory object for creating partitioning strategies.
+ */
 export const Partitioning = {
     Balanced,
     PartitionId,
     MessageKey
 };
+/**
+ * Serializes a message key value to a buffer.
+ *
+ * @param v - Message key value
+ * @returns Serialized buffer
+ * @throws Error if the value type is not supported
+ */
 export const serializeMessageKey = (v) => {
     if (v instanceof Buffer)
         return v;
@@ -51,6 +79,12 @@ export const serializeMessageKey = (v) => {
         return uint64ToBuf(v);
     throw new Error(`cannot serialize messageKey ${v}, ${typeof v}`);
 };
+/**
+ * Serializes the value portion of a partitioning strategy.
+ *
+ * @param part - Partitioning strategy
+ * @returns Serialized value buffer
+ */
 export const serializePartitioningValue = (part) => {
     const { kind, value } = part;
     switch (kind) {
@@ -59,10 +93,18 @@ export const serializePartitioningValue = (part) => {
         case PartitionKind.MessageKey: return serializeMessageKey(value);
     }
 };
+/** Default partitioning strategy (balanced) */
 export const default_partionning = {
     kind: PartitionKind.Balanced,
     value: null
 };
+/**
+ * Serializes a partitioning strategy to wire format.
+ * Format: [kind (1 byte)][value_length (1 byte)][value]
+ *
+ * @param p - Optional partitioning strategy (defaults to balanced)
+ * @returns Serialized partitioning buffer
+ */
 export const serializePartitioning = (p) => {
     const part = p || default_partionning;
     const b = Buffer.alloc(2);

package/dist/wire/message/poll-messages.command.d.ts

@@ -20,15 +20,29 @@ import type { Id } from '../identifier.utils.js';
 import type { CommandResponse } from '../../client/client.type.js';
 import type { Consumer } from '../offset/offset.utils.js';
 import { type PollingStrategy, type PollMessagesResponse } from './poll.utils.js';
+/**
+ * Parameters for the poll messages command.
+ */
 export type PollMessages = {
+    /** Stream identifier */
     streamId: Id;
+    /** Topic identifier */
     topicId: Id;
+    /** Consumer configuration */
     consumer: Consumer;
+    /** Partition ID (null for all partitions) */
     partitionId: number | null;
+    /** Strategy for selecting messages */
     pollingStrategy: PollingStrategy;
+    /** Maximum number of messages to poll */
     count: number;
+    /** Whether to auto-commit offset after polling */
     autocommit: boolean;
 };
+/**
+ * Poll messages command definition.
+ * Retrieves messages from a topic partition.
+ */
 export declare const POLL_MESSAGES: {
     code: number;
     serialize: ({ streamId, topicId, consumer, partitionId, pollingStrategy, count, autocommit }: PollMessages) => Buffer<ArrayBuffer>;
@@ -39,5 +53,8 @@ export declare const POLL_MESSAGES: {
         messages: import("./poll.utils.js").Message[];
     };
 };
+/**
+ * Executable poll messages command function.
+ */
 export declare const pollMessages: (getClient: import("../../client/client.type.js").ClientProvider) => (arg: PollMessages) => Promise<PollMessagesResponse>;
 //# sourceMappingURL=poll-messages.command.d.ts.map

package/dist/wire/message/poll-messages.command.js

@@ -19,6 +19,10 @@
 import { wrapCommand } from '../command.utils.js';
 import { COMMAND_CODE } from '../command.code.js';
 import { serializePollMessages, deserializePollMessages } from './poll.utils.js';
+/**
+ * Poll messages command definition.
+ * Retrieves messages from a topic partition.
+ */
 export const POLL_MESSAGES = {
     code: COMMAND_CODE.PollMessages,
     serialize: ({ streamId, topicId, consumer, partitionId, pollingStrategy, count, autocommit }) => {
@@ -28,5 +32,8 @@ export const POLL_MESSAGES = {
         return deserializePollMessages(r.data);
     }
 };
+/**
+ * Executable poll messages command function.
+ */
 export const pollMessages = wrapCommand(POLL_MESSAGES);
 //# sourceMappingURL=poll-messages.command.js.map

package/dist/wire/message/poll.utils.d.ts

@@ -16,43 +16,65 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { type Id } from '../identifier.utils.js';
-import { type ValueOf } from '../../type.utils.js';
-import { type Consumer } from '../offset/offset.utils.js';
-import { type HeadersMap } from './header.utils.js';
-import { Transform } from 'node:stream';
-import { IggyMessageHeader } from './iggy-header.utils.js';
+import { type Id } from "../identifier.utils.js";
+import { type ValueOf } from "../../type.utils.js";
+import { type Consumer } from "../offset/offset.utils.js";
+import { type ParsedHeaderEntry } from "./header.utils.js";
+import { Transform } from "node:stream";
+import { type IggyMessageHeader } from "./iggy-header.utils.js";
+/**
+ * Enumeration of message polling strategies.
+ */
 export declare const PollingStrategyKind: {
+    /** Poll from a specific offset */
     readonly Offset: 1;
+    /** Poll from a specific timestamp */
     readonly Timestamp: 2;
+    /** Poll from the first message */
     readonly First: 3;
+    /** Poll from the last message */
     readonly Last: 4;
+    /** Poll the next unconsumed message */
     readonly Next: 5;
 };
+/** Type alias for the PollingStrategyKind object */
 export type PollingStrategyKind = typeof PollingStrategyKind;
+/** String literal type of polling strategy names */
 export type PollingStrategyKindId = keyof PollingStrategyKind;
+/** Numeric values of polling strategies */
 export type PollingStrategyKindValue = ValueOf<PollingStrategyKind>;
+/** Polling from a specific offset */
 export type OffsetPollingStrategy = {
-    kind: PollingStrategyKind['Offset'];
+    kind: PollingStrategyKind["Offset"];
+    /** Offset to start polling from */
     value: bigint;
 };
+/** Polling from a specific timestamp */
 export type TimestampPollingStrategy = {
-    kind: PollingStrategyKind['Timestamp'];
+    kind: PollingStrategyKind["Timestamp"];
+    /** Timestamp in microseconds */
     value: bigint;
 };
+/** Polling from the first message */
 export type FirstPollingStrategy = {
-    kind: PollingStrategyKind['First'];
+    kind: PollingStrategyKind["First"];
     value: 0n;
 };
+/** Polling from the last message */
 export type LastPollingStrategy = {
-    kind: PollingStrategyKind['Last'];
+    kind: PollingStrategyKind["Last"];
     value: 0n;
 };
+/** Polling the next unconsumed message */
 export type NextPollingStrategy = {
-    kind: PollingStrategyKind['Next'];
+    kind: PollingStrategyKind["Next"];
     value: 0n;
 };
+/** Union of all polling strategy types */
 export type PollingStrategy = OffsetPollingStrategy | TimestampPollingStrategy | FirstPollingStrategy | LastPollingStrategy | NextPollingStrategy;
+/**
+ * Factory object for creating polling strategies.
+ */
 export declare const PollingStrategy: {
     Next: NextPollingStrategy;
     First: FirstPollingStrategy;
@@ -60,35 +82,94 @@ export declare const PollingStrategy: {
     Offset: (n: bigint) => OffsetPollingStrategy;
     Timestamp: (n: bigint) => TimestampPollingStrategy;
 };
+/**
+ * Serializes a poll messages command payload.
+ *
+ * @param streamId - Stream identifier
+ * @param topicId - Topic identifier
+ * @param consumer - Consumer configuration
+ * @param partitionId - Partition ID (null for all partitions)
+ * @param pollingStrategy - Strategy for selecting messages
+ * @param count - Maximum number of messages to poll
+ * @param autocommit - Whether to auto-commit offset after polling
+ * @returns Serialized command payload
+ */
 export declare const serializePollMessages: (streamId: Id, topicId: Id, consumer: Consumer, partitionId: number | null, pollingStrategy: PollingStrategy, // default to OffsetPollingStrategy
 count?: number, autocommit?: boolean) => Buffer<ArrayBuffer>;
+/**
+ * Enumeration of message states.
+ */
 export declare const MessageState: {
+    /** Message is available for consumption */
     Available: number;
+    /** Message is temporarily unavailable */
     Unavailable: number;
+    /** Message processing failed */
     Poisoned: number;
+    /** Message is scheduled for deletion */
     MarkedForDeletion: number;
 };
+/** Type alias for the MessageState object */
 type MessageState = typeof MessageState;
+/** String literal type of message state names */
 type MessageStateId = keyof MessageState;
+/**
+ * Maps a numeric message state to its string identifier.
+ *
+ * @param k - Numeric state value
+ * @returns State identifier string
+ * @throws Error if the state is unknown
+ */
 export declare const mapMessageState: (k: number) => MessageStateId;
+/**
+ * A polled message with headers, payload, and user headers.
+ */
 export type Message = {
+    /** Iggy message header metadata */
     headers: IggyMessageHeader;
+    /** Message payload data */
     payload: Buffer;
-    userHeaders: HeadersMap;
+    /** User-defined headers */
+    userHeaders: ParsedHeaderEntry[];
 };
+/**
+ * Response from a poll messages command.
+ */
 export type PollMessagesResponse = {
+    /** Partition the messages came from */
     partitionId: number;
+    /** Current offset in the partition */
     currentOffset: bigint;
+    /** Number of messages returned */
     count: number;
+    /** Array of polled messages */
     messages: Message[];
 };
+/**
+ * Deserializes an array of messages from a buffer.
+ *
+ * @param b - Buffer containing serialized messages
+ * @returns Array of deserialized messages
+ */
 export declare const deserializeMessages: (b: Buffer) => Message[];
+/**
+ * Deserializes a poll messages response from a buffer.
+ *
+ * @param r - Response buffer
+ * @param pos - Starting position
+ * @returns Parsed PollMessagesResponse
+ */
 export declare const deserializePollMessages: (r: Buffer, pos?: number) => {
     partitionId: number;
     currentOffset: bigint;
     count: number;
     messages: Message[];
 };
+/**
+ * Creates a Transform stream for deserializing poll messages responses.
+ *
+ * @returns Transform stream that outputs PollMessagesResponse objects
+ */
 export declare const deserializePollMessagesTransform: () => Transform;
 export {};
 //# sourceMappingURL=poll.utils.d.ts.map