apache-iggy 0.6.0 → 0.7.0

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

@@ -16,46 +16,83 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { reverseRecord } from '../../type.utils.js';
-import { serializeGetOffset } from '../offset/offset.utils.js';
-import { deserializeHeaders } from './header.utils.js';
-import { Transform } from 'node:stream';
-import { deserializeIggyMessageHeaders, IGGY_MESSAGE_HEADER_SIZE } from './iggy-header.utils.js';
+import { reverseRecord } from "../../type.utils.js";
+import { serializeGetOffset } from "../offset/offset.utils.js";
+import { deserializeHeaders } from "./header.utils.js";
+import { Transform } from "node:stream";
+import { deserializeIggyMessageHeaders, IGGY_MESSAGE_HEADER_SIZE, } from "./iggy-header.utils.js";
+/**
+ * Enumeration of message polling strategies.
+ */
 export const PollingStrategyKind = {
+    /** Poll from a specific offset */
     Offset: 1,
+    /** Poll from a specific timestamp */
     Timestamp: 2,
+    /** Poll from the first message */
     First: 3,
+    /** Poll from the last message */
     Last: 4,
-    Next: 5
+    /** Poll the next unconsumed message */
+    Next: 5,
 };
+/** Next polling strategy constant */
 const Next = {
     kind: PollingStrategyKind.Next,
-    value: 0n
+    value: 0n,
 };
+/** First polling strategy constant */
 const First = {
     kind: PollingStrategyKind.First,
-    value: 0n
+    value: 0n,
 };
+/** Last polling strategy constant */
 const Last = {
     kind: PollingStrategyKind.Last,
-    value: 0n
+    value: 0n,
 };
+/**
+ * Creates an offset polling strategy.
+ *
+ * @param n - Offset to start from
+ * @returns Offset polling strategy
+ */
 const Offset = (n) => ({
     kind: PollingStrategyKind.Offset,
-    value: n
+    value: n,
 });
+/**
+ * Creates a timestamp polling strategy.
+ *
+ * @param n - Timestamp in microseconds
+ * @returns Timestamp polling strategy
+ */
 const Timestamp = (n) => ({
     kind: PollingStrategyKind.Timestamp,
-    value: n
+    value: n,
 });
-// helper
+/**
+ * Factory object for creating polling strategies.
+ */
 export const PollingStrategy = {
     Next,
     First,
     Last,
     Offset,
-    Timestamp
+    Timestamp,
 };
+/**
+ * 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 const serializePollMessages = (streamId, topicId, consumer, partitionId, pollingStrategy, // default to OffsetPollingStrategy
 count = 10, autocommit = false) => {
     const b = Buffer.allocUnsafe(14);
@@ -65,21 +102,42 @@ count = 10, autocommit = false) => {
     b.writeUInt8(!!autocommit ? 1 : 0, 13);
     return Buffer.concat([
         serializeGetOffset(streamId, topicId, consumer, partitionId),
-        b
+        b,
     ]);
 };
+/**
+ * Enumeration of message states.
+ */
 export const MessageState = {
+    /** Message is available for consumption */
     Available: 1,
+    /** Message is temporarily unavailable */
     Unavailable: 10,
+    /** Message processing failed */
     Poisoned: 20,
-    MarkedForDeletion: 30
+    /** Message is scheduled for deletion */
+    MarkedForDeletion: 30,
 };
+/** Reverse mapping from numeric value to state name */
 const ReverseMessageState = reverseRecord(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 const mapMessageState = (k) => {
     if (!ReverseMessageState[k])
         throw new Error(`unknow message state: ${k}`);
     return ReverseMessageState[k];
 };
+/**
+ * Deserializes an array of messages from a buffer.
+ *
+ * @param b - Buffer containing serialized messages
+ * @returns Array of deserialized messages
+ */
 export const deserializeMessages = (b) => {
     const messages = [];
     let pos = 0;
@@ -95,19 +153,27 @@ export const deserializeMessages = (b) => {
             break;
         const payload = b.subarray(pos, plEnd);
         pos += headers.payloadLength;
-        let userHeaders = {};
-        if (headers.userHeadersLength > 0 && plEnd + headers.userHeadersLength <= len) {
+        let userHeaders = [];
+        if (headers.userHeadersLength > 0 &&
+            plEnd + headers.userHeadersLength <= len) {
             userHeaders = deserializeHeaders(b.subarray(plEnd, plEnd + headers.userHeadersLength));
             pos += headers.userHeadersLength;
         }
         messages.push({
             headers,
             payload,
-            userHeaders
+            userHeaders,
         });
     }
     return messages;
 };
+/**
+ * Deserializes a poll messages response from a buffer.
+ *
+ * @param r - Response buffer
+ * @param pos - Starting position
+ * @returns Parsed PollMessagesResponse
+ */
 export const deserializePollMessages = (r, pos = 0) => {
     const partitionId = r.readUInt32LE(pos);
     const currentOffset = r.readBigUInt64LE(pos + 4);
@@ -117,9 +183,14 @@ export const deserializePollMessages = (r, pos = 0) => {
         partitionId,
         currentOffset,
         count,
-        messages
+        messages,
     };
 };
+/**
+ * Creates a Transform stream for deserializing poll messages responses.
+ *
+ * @returns Transform stream that outputs PollMessagesResponse objects
+ */
 export const deserializePollMessagesTransform = () => new Transform({
     objectMode: true,
     transform(chunk, encoding, cb) {
@@ -127,8 +198,8 @@ export const deserializePollMessagesTransform = () => new Transform({
             return cb(null, deserializePollMessages(chunk));
         }
         catch (err) {
-            cb(new Error('deserializePollMessage::transform error', { cause: err }), null);
+            cb(new Error("deserializePollMessage::transform error", { cause: err }), null);
         }
-    }
+    },
 });
 //# sourceMappingURL=poll.utils.js.map

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

@@ -19,16 +19,30 @@
 import { type Id } from '../identifier.utils.js';
 import { type CreateMessage } from './message.utils.js';
 import type { Partitioning } from './partitioning.utils.js';
+/**
+ * Parameters for the send messages command.
+ */
 export type SendMessages = {
+    /** Stream identifier */
     streamId: Id;
+    /** Topic identifier */
     topicId: Id;
+    /** Array of messages to send */
     messages: CreateMessage[];
+    /** Optional partitioning strategy */
     partition?: Partitioning;
 };
+/**
+ * Send messages command definition.
+ * Publishes messages to a topic.
+ */
 export declare const SEND_MESSAGES: {
     code: number;
     serialize: ({ streamId, topicId, messages, partition }: SendMessages) => Buffer<ArrayBuffer>;
     deserialize: (r: import("../../index.js").CommandResponse) => boolean;
 };
+/**
+ * Executable send messages command function.
+ */
 export declare const sendMessages: (getClient: import("../../index.js").ClientProvider) => (arg: SendMessages) => Promise<boolean>;
 //# sourceMappingURL=send-messages.command.d.ts.map

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

@@ -20,6 +20,10 @@ import { serializeSendMessages } from './message.utils.js';
 import { deserializeVoidResponse } from '../../client/client.utils.js';
 import { wrapCommand } from '../command.utils.js';
 import { COMMAND_CODE } from '../command.code.js';
+/**
+ * Send messages command definition.
+ * Publishes messages to a topic.
+ */
 export const SEND_MESSAGES = {
     code: COMMAND_CODE.SendMessages,
     serialize: ({ streamId, topicId, messages, partition }) => {
@@ -27,5 +31,8 @@ export const SEND_MESSAGES = {
     },
     deserialize: deserializeVoidResponse
 };
+/**
+ * Executable send messages command function.
+ */
 export const sendMessages = wrapCommand(SEND_MESSAGES);
 //# sourceMappingURL=send-messages.command.js.map

package/dist/wire/message/send-messages.command.test.js

@@ -16,70 +16,134 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { uuidv7, uuidv4 } from 'uuidv7';
-import { SEND_MESSAGES } from './send-messages.command.js';
-import { HeaderValue } from './header.utils.js';
-describe('SendMessages', () => {
-    describe('serialize', () => {
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { uuidv7, uuidv4 } from "uuidv7";
+import { SEND_MESSAGES } from "./send-messages.command.js";
+import { HeaderValue, HeaderKeyFactory } from "./header.utils.js";
+describe("SendMessages", () => {
+    describe("serialize", () => {
         const t1 = {
             streamId: 911,
             topicId: 213,
             messages: [
-                { payload: 'a' },
-                { id: 0, payload: 'b' },
-                { id: 123, payload: 'X' },
-                { id: 0n, payload: 'c' },
-                { id: 1236234534554n, payload: 'X' },
-                { id: uuidv4(), payload: 'd' },
-                { id: uuidv7(), payload: 'e' },
+                { payload: "a" },
+                { id: 0, payload: "b" },
+                { id: 123, payload: "X" },
+                { id: 0n, payload: "c" },
+                { id: 1236234534554n, payload: "X" },
+                { id: uuidv4(), payload: "d" },
+                { id: uuidv7(), payload: "e" },
             ],
         };
-        it('serialize SendMessages into a buffer', () => {
-            assert.deepEqual(SEND_MESSAGES.serialize(t1).length, 533);
+        it("serialize SendMessages into a buffer", () => {
+            assert.deepEqual(SEND_MESSAGES.serialize(t1).length, 589);
         });
-        it('serialize all kinds of messageId', () => {
+        it("serialize all kinds of messageId", () => {
             assert.doesNotThrow(() => SEND_MESSAGES.serialize(t1));
         });
-        it('does not throw on number message id', () => {
-            const t = { ...t1, messages: [{ id: 42, payload: 'm' }] };
+        it("does not throw on number message id", () => {
+            const t = { ...t1, messages: [{ id: 42, payload: "m" }] };
             assert.doesNotThrow(() => SEND_MESSAGES.serialize(t));
         });
-        it('does not throw on bigint message id', () => {
-            const t = { ...t1, messages: [{ id: 123n, payload: 'm' }] };
+        it("does not throw on bigint message id", () => {
+            const t = { ...t1, messages: [{ id: 123n, payload: "m" }] };
             assert.doesNotThrow(() => SEND_MESSAGES.serialize(t));
         });
-        it('does not throw on uuid message id', () => {
-            const t = { ...t1, messages: [{ id: uuidv4(), payload: 'uuid' }] };
+        it("does not throw on uuid message id", () => {
+            const t = { ...t1, messages: [{ id: uuidv4(), payload: "uuid" }] };
             assert.doesNotThrow(() => SEND_MESSAGES.serialize(t));
         });
-        it('throw on invalid string message id', () => {
-            const t = { ...t1, messages: [{ id: 'foo', payload: 'm' }] };
+        it("throw on invalid string message id", () => {
+            const t = { ...t1, messages: [{ id: "foo", payload: "m" }] };
             assert.throws(() => SEND_MESSAGES.serialize(t));
         });
-        it('throw on invalid number message id', () => {
-            const t = { ...t1, messages: [{ id: -12, payload: 'n' }] };
+        it("throw on invalid number message id", () => {
+            const t = { ...t1, messages: [{ id: -12, payload: "n" }] };
             assert.throws(() => SEND_MESSAGES.serialize(t));
         });
-        it('throw on invalid bigint message id', () => {
-            const t = { ...t1, messages: [{ id: -12n, payload: 'bn' }] };
+        it("throw on invalid bigint message id", () => {
+            const t = { ...t1, messages: [{ id: -12n, payload: "bn" }] };
             assert.throws(() => SEND_MESSAGES.serialize(t));
         });
-        it('serialize message with headers', () => {
+        it("serialize message with headers", () => {
             const t = {
                 streamId: 911,
                 topicId: 213,
                 messages: [
-                    { payload: 'm', headers: { p: HeaderValue.Bool(true) } },
-                    { payload: 'q', headers: { 'v-aze': HeaderValue.Uint8(128) } },
-                    { payload: 'x', headers: { q: HeaderValue.Double(1 / 3) } },
-                    { payload: 's', headers: { x: HeaderValue.Uint32(123) } },
-                    { payload: 'r', headers: { y: HeaderValue.Uint64(42n) } },
-                    { payload: 'g', headers: { y: HeaderValue.Float(42.3) } },
-                    { payload: 'c', headers: { ID: HeaderValue.String(uuidv7()) } },
-                    { payload: 'l', headers: { val: HeaderValue.Raw(Buffer.from(uuidv4())) } }
-                ]
+                    {
+                        payload: "m",
+                        headers: [
+                            {
+                                key: HeaderKeyFactory.String("p"),
+                                value: HeaderValue.Bool(true),
+                            },
+                        ],
+                    },
+                    {
+                        payload: "q",
+                        headers: [
+                            {
+                                key: HeaderKeyFactory.String("v-aze"),
+                                value: HeaderValue.Uint8(128),
+                            },
+                        ],
+                    },
+                    {
+                        payload: "x",
+                        headers: [
+                            {
+                                key: HeaderKeyFactory.String("q"),
+                                value: HeaderValue.Double(1 / 3),
+                            },
+                        ],
+                    },
+                    {
+                        payload: "s",
+                        headers: [
+                            {
+                                key: HeaderKeyFactory.String("x"),
+                                value: HeaderValue.Uint32(123),
+                            },
+                        ],
+                    },
+                    {
+                        payload: "r",
+                        headers: [
+                            {
+                                key: HeaderKeyFactory.String("y"),
+                                value: HeaderValue.Uint64(42n),
+                            },
+                        ],
+                    },
+                    {
+                        payload: "g",
+                        headers: [
+                            {
+                                key: HeaderKeyFactory.String("y"),
+                                value: HeaderValue.Float(42.3),
+                            },
+                        ],
+                    },
+                    {
+                        payload: "c",
+                        headers: [
+                            {
+                                key: HeaderKeyFactory.String("ID"),
+                                value: HeaderValue.String(uuidv7()),
+                            },
+                        ],
+                    },
+                    {
+                        payload: "l",
+                        headers: [
+                            {
+                                key: HeaderKeyFactory.String("val"),
+                                value: HeaderValue.Raw(Buffer.from(uuidv4())),
+                            },
+                        ],
+                    },
+                ],
             };
             assert.doesNotThrow(() => SEND_MESSAGES.serialize(t));
         });

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

@@ -16,17 +16,96 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+/**
+ * Converts a boolean value to a 1-byte Buffer.
+ *
+ * @param v - Boolean value to convert
+ * @returns Buffer containing 0x00 (false) or 0x01 (true)
+ */
 export declare const boolToBuf: (v: boolean) => Buffer<ArrayBuffer>;
+/**
+ * Converts an 8-bit signed integer to a 1-byte Buffer.
+ *
+ * @param v - Signed integer value (-128 to 127)
+ * @returns Buffer containing the value
+ */
 export declare const int8ToBuf: (v: number) => Buffer<ArrayBuffer>;
+/**
+ * Converts a 16-bit signed integer to a 2-byte Buffer in little-endian format.
+ *
+ * @param v - Signed integer value (-32,768 to 32,767)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare const int16ToBuf: (v: number) => Buffer<ArrayBuffer>;
+/**
+ * Converts a 32-bit signed integer to a 4-byte Buffer in little-endian format.
+ *
+ * @param v - Signed integer value (-2,147,483,648 to 2,147,483,647)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare const int32ToBuf: (v: number) => Buffer<ArrayBuffer>;
+/**
+ * Converts a 64-bit signed BigInt to an 8-byte Buffer in little-endian format.
+ *
+ * @param v - BigInt value
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare const int64ToBuf: (v: bigint) => Buffer<ArrayBuffer>;
+/**
+ * Converts an 8-bit unsigned integer to a 1-byte Buffer.
+ *
+ * @param v - Unsigned integer value (0 to 255)
+ * @returns Buffer containing the value
+ */
 export declare const uint8ToBuf: (v: number) => Buffer<ArrayBuffer>;
+/**
+ * Converts a 16-bit unsigned integer to a 2-byte Buffer in little-endian format.
+ *
+ * @param v - Unsigned integer value (0 to 65,535)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare const uint16ToBuf: (v: number) => Buffer<ArrayBuffer>;
+/**
+ * Converts a 32-bit unsigned integer to a 4-byte Buffer in little-endian format.
+ *
+ * @param v - Unsigned integer value (0 to 4,294,967,295)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare const uint32ToBuf: (v: number) => Buffer<ArrayBuffer>;
+/**
+ * Converts a 64-bit unsigned BigInt to an 8-byte Buffer in little-endian format.
+ *
+ * @param v - Unsigned BigInt value
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare const uint64ToBuf: (v: bigint) => Buffer<ArrayBuffer>;
+/**
+ * Converts a 32-bit floating-point number to a 4-byte Buffer in little-endian format.
+ *
+ * @param v - Float value (IEEE 754 single precision)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare const floatToBuf: (v: number) => Buffer<ArrayBuffer>;
+/**
+ * Converts a 64-bit floating-point number to an 8-byte Buffer in little-endian format.
+ *
+ * @param v - Double value (IEEE 754 double precision)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare const doubleToBuf: (v: number) => Buffer<ArrayBuffer>;
+/**
+ * Converts a BigInt to a 128-bit unsigned integer Buffer in little-endian format.
+ *
+ * @param num - BigInt value to convert
+ * @param width - Width in bytes (default: 16)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export declare function u128ToBuf(num: bigint, width?: number): Buffer;
+/**
+ * Converts a 128-bit unsigned integer Buffer in little-endian format to a BigInt.
+ *
+ * @param b - Buffer containing the value in little-endian byte order
+ * @returns BigInt representation of the value
+ */
 export declare function u128LEBufToBigint(b: Buffer): bigint;
 //# sourceMappingURL=number.utils.d.ts.map

package/dist/wire/number.utils.js

@@ -16,68 +16,145 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+/**
+ * Converts a boolean value to a 1-byte Buffer.
+ *
+ * @param v - Boolean value to convert
+ * @returns Buffer containing 0x00 (false) or 0x01 (true)
+ */
 export const boolToBuf = (v) => {
     const b = Buffer.allocUnsafe(1);
     b.writeUInt8(!v ? 0 : 1);
     return b;
 };
+/**
+ * Converts an 8-bit signed integer to a 1-byte Buffer.
+ *
+ * @param v - Signed integer value (-128 to 127)
+ * @returns Buffer containing the value
+ */
 export const int8ToBuf = (v) => {
     const b = Buffer.allocUnsafe(1);
     b.writeInt8(v);
     return b;
 };
+/**
+ * Converts a 16-bit signed integer to a 2-byte Buffer in little-endian format.
+ *
+ * @param v - Signed integer value (-32,768 to 32,767)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export const int16ToBuf = (v) => {
     const b = Buffer.allocUnsafe(2);
     b.writeInt16LE(v);
     return b;
 };
+/**
+ * Converts a 32-bit signed integer to a 4-byte Buffer in little-endian format.
+ *
+ * @param v - Signed integer value (-2,147,483,648 to 2,147,483,647)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export const int32ToBuf = (v) => {
     const b = Buffer.allocUnsafe(4);
     b.writeInt32LE(v);
     return b;
 };
+/**
+ * Converts a 64-bit signed BigInt to an 8-byte Buffer in little-endian format.
+ *
+ * @param v - BigInt value
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export const int64ToBuf = (v) => {
     const b = Buffer.allocUnsafe(8);
     b.writeBigInt64LE(v);
     return b;
 };
+/**
+ * Converts an 8-bit unsigned integer to a 1-byte Buffer.
+ *
+ * @param v - Unsigned integer value (0 to 255)
+ * @returns Buffer containing the value
+ */
 export const uint8ToBuf = (v) => {
     const b = Buffer.allocUnsafe(1);
     b.writeUInt8(v);
     return b;
 };
+/**
+ * Converts a 16-bit unsigned integer to a 2-byte Buffer in little-endian format.
+ *
+ * @param v - Unsigned integer value (0 to 65,535)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export const uint16ToBuf = (v) => {
     const b = Buffer.allocUnsafe(2);
     b.writeUInt16LE(v);
     return b;
 };
+/**
+ * Converts a 32-bit unsigned integer to a 4-byte Buffer in little-endian format.
+ *
+ * @param v - Unsigned integer value (0 to 4,294,967,295)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export const uint32ToBuf = (v) => {
     const b = Buffer.allocUnsafe(4);
     b.writeUInt32LE(v);
     return b;
 };
+/**
+ * Converts a 64-bit unsigned BigInt to an 8-byte Buffer in little-endian format.
+ *
+ * @param v - Unsigned BigInt value
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export const uint64ToBuf = (v) => {
     const b = Buffer.allocUnsafe(8);
     b.writeBigUInt64LE(v);
     return b;
 };
+/**
+ * Converts a 32-bit floating-point number to a 4-byte Buffer in little-endian format.
+ *
+ * @param v - Float value (IEEE 754 single precision)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export const floatToBuf = (v) => {
     const b = Buffer.allocUnsafe(4);
     b.writeFloatLE(v);
     return b;
 };
+/**
+ * Converts a 64-bit floating-point number to an 8-byte Buffer in little-endian format.
+ *
+ * @param v - Double value (IEEE 754 double precision)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export const doubleToBuf = (v) => {
     const b = Buffer.allocUnsafe(8);
     b.writeDoubleLE(v);
     return b;
 };
-// bigint => u128 LE
+/**
+ * Converts a BigInt to a 128-bit unsigned integer Buffer in little-endian format.
+ *
+ * @param num - BigInt value to convert
+ * @param width - Width in bytes (default: 16)
+ * @returns Buffer containing the value in little-endian byte order
+ */
 export function u128ToBuf(num, width = 16) {
     const hex = num.toString(16);
     const b = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
     return b.reverse();
 }
-// u128 LE => Bigint
+/**
+ * Converts a 128-bit unsigned integer Buffer in little-endian format to a BigInt.
+ *
+ * @param b - Buffer containing the value in little-endian byte order
+ * @returns BigInt representation of the value
+ */
 export function u128LEBufToBigint(b) {
     const hex = b.reverse().toString('hex');
     return hex.length === 0 ? BigInt(0) : BigInt(`0x${hex}`);