From 73996dfabe1f95bbb1a93e6592cdb3d96dd56cf6 Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 12:22:12 +0300
Subject: [PATCH 01/16] Add jsdoc to the original queryOffset method

---
 src/connection.ts | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/src/connection.ts b/src/connection.ts
index 5f8b3ee..208f24d 100644
--- a/src/connection.ts
+++ b/src/connection.ts
@@ -565,6 +565,37 @@ export class Connection {
     return this.send(new StoreOffsetRequest(params))
   }
 
+  /**
+   * Return the server-side saved offset.
+   *
+   * @see https://www.rabbitmq.com/tutorials/tutorial-two-javascript-stream
+   * @see https://www.rabbitmq.com/blog/2021/09/13/rabbitmq-streams-offset-tracking
+   *
+   * @params QueryOffsetParams Stream name and the named consumer identifier.
+   *
+   * @see {@link storeOffset}
+   * @see {@link Client.connect}
+   *
+   * @example
+   *
+   * Consumer reads previously saved offset to start consumning from the desired offset.
+   * Note, to be server-tracked the offset shuould be explicitly saved with `client.storeOffset()`
+   * On consumer side create the client, detect the server-side saved offset
+   * to detect the deisred offset to consume from. Then declare a consumer with the desired offset.
+   * When consuming, the consumer message handler above saved the offset server-side to be
+   * able to further track it
+   *
+   * ```typescript
+   * // ... create client
+   * // Detect the desider starting offset for the next stream operation.
+   * const offset = await client.queryOffset({ reference: 'consumer-x', stream: 'stream-a' })
+   * const startWithOffset = offset ? rmqLibrary.Offset.offset(offset + 1n) :
+   *   rmqLibrary.Offset.<whatever-enum-offset-is-desired>();
+   * const consumer = await client.declareConsumer({stream: 'stream-b', offset: startWithOffset},
+   *   async (this: StreamConsumer, message: Message) => { await this.storeOffset(message.offset); });
+   * // Note the offset is saved by the message handler.
+   * ```
+   */
   public async queryOffset(params: QueryOffsetParams): Promise<bigint> {
     this.logger.debug(`Query Offset...`)
     const res = await this.sendAndWait<QueryOffsetResponse>(new QueryOffsetRequest(params))

From 4f887e860ab5918add46c779d51373ed25f9d321 Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 13:33:46 +0300
Subject: [PATCH 02/16] Implement Code51Exception

- tdd the exception;
- update src/utils.ts ResponseCode to add NoOffset member and add jsdoc;
---
 src/application/Code51Exception.ts            | 25 ++++++++++++
 src/util.ts                                   | 14 +++++++
 test/unit/application/Code51Exception.test.ts | 38 +++++++++++++++++++
 3 files changed, 77 insertions(+)
 create mode 100644 src/application/Code51Exception.ts
 create mode 100644 test/unit/application/Code51Exception.test.ts

diff --git a/src/application/Code51Exception.ts b/src/application/Code51Exception.ts
new file mode 100644
index 0000000..276c18c
--- /dev/null
+++ b/src/application/Code51Exception.ts
@@ -0,0 +1,25 @@
+"use strict"
+
+import { ResponseCode } from "../util"
+
+type TResponseCode = (typeof ResponseCode)[keyof typeof ResponseCode]
+
+export default class Code51Exception extends Error {
+  readonly #code?: TResponseCode
+
+  constructor(message: string, rmqStreamResponseCode?: TResponseCode) {
+    super(message)
+
+    this.name = this.constructor.name
+    this.#code = rmqStreamResponseCode ?? undefined
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+
+  public get code(): TResponseCode | undefined {
+    return this.#code
+  }
+}
diff --git a/src/util.ts b/src/util.ts
index 1a4e856..0ca566e 100644
--- a/src/util.ts
+++ b/src/util.ts
@@ -48,9 +48,23 @@ export const wait = async (ms: number) => {
   })
 }
 
+/**
+ * The RabbitMQ Stream protocol response codes.
+ *
+ * Only codes actually used by this package are defined here however any official code
+ * can be returned by the actually connected RabbitMQ instance.
+ *
+ * @see https://github.com/rabbitmq/rabbitmq-server/blob/v3.9.x/deps/rabbitmq_stream/docs/PROTOCOL.adoc#response-codes
+ *
+ * @see {@link connection.ts/Connection.queryOffset}
+ * @see {@link application/Code51Exception}
+ */
 export const ResponseCode = {
   StreamDoesNotExist: 2,
   SubscriptionIdDoesNotExist: 4,
+
+  // Used in src/connection.ts/Connection.queryOffset method
+  NoOffset: 19,
 } as const
 
 export const isString = (value: unknown): boolean => typeof value === "string"
diff --git a/test/unit/application/Code51Exception.test.ts b/test/unit/application/Code51Exception.test.ts
new file mode 100644
index 0000000..2f7bc31
--- /dev/null
+++ b/test/unit/application/Code51Exception.test.ts
@@ -0,0 +1,38 @@
+import { expect } from "chai"
+
+import Code51Exception from "../../../src/application/Code51Exception"
+import { ResponseCode } from "../../../src/util"
+
+describe("[unit] Code51Exception Test", () => {
+  it("+constructor() #1: Should create Code51Exception expected default object", () => {
+    const expected = "A message"
+    const actual = new Code51Exception(expected)
+
+    expect(actual).instanceOf(Code51Exception)
+    expect(actual.message).eql(expected)
+    expect(actual.code).eql(undefined)
+  })
+
+  it("+constructor() #2: Should create Code51Exception expected object with expectd response code", () => {
+    const expected = ResponseCode.NoOffset
+    const actual = new Code51Exception("a message", expected)
+
+    expect(actual.code).eql(expected)
+  })
+
+  it("Should throw expected Code51Exception exception", () => {
+    const expected = { message: "A message", code: ResponseCode.SubscriptionIdDoesNotExist }
+
+    try {
+      throw new Code51Exception(expected.message, expected.code)
+    } catch (error_) {
+      const error = error_ as Code51Exception
+
+      expect(error).instanceOf(Code51Exception)
+      expect(error.message).eql(expected.message)
+      expect(error.code).eql(expected.code)
+    }
+  })
+})
+
+// Assert: proper stack trace

From 835e4d9d693fadf9d8b2fc8eb99baff53982b91c Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 13:39:18 +0300
Subject: [PATCH 03/16] Update Code51Exception: minor

---
 src/application/Code51Exception.ts            | 2 ++
 test/unit/application/Code51Exception.test.ts | 8 ++++----
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/application/Code51Exception.ts b/src/application/Code51Exception.ts
index 276c18c..a66ad21 100644
--- a/src/application/Code51Exception.ts
+++ b/src/application/Code51Exception.ts
@@ -10,6 +10,8 @@ export default class Code51Exception extends Error {
   constructor(message: string, rmqStreamResponseCode?: TResponseCode) {
     super(message)
 
+    Object.setPrototypeOf(this, new.target.prototype)
+
     this.name = this.constructor.name
     this.#code = rmqStreamResponseCode ?? undefined
 
diff --git a/test/unit/application/Code51Exception.test.ts b/test/unit/application/Code51Exception.test.ts
index 2f7bc31..d91e889 100644
--- a/test/unit/application/Code51Exception.test.ts
+++ b/test/unit/application/Code51Exception.test.ts
@@ -26,11 +26,11 @@ describe("[unit] Code51Exception Test", () => {
     try {
       throw new Code51Exception(expected.message, expected.code)
     } catch (error_) {
-      const error = error_ as Code51Exception
+      const actual = error_ as Code51Exception
 
-      expect(error).instanceOf(Code51Exception)
-      expect(error.message).eql(expected.message)
-      expect(error.code).eql(expected.code)
+      expect(actual).instanceOf(Code51Exception)
+      expect(actual.message).eql(expected.message)
+      expect(actual.code).eql(expected.code)
     }
   })
 })

From 9477d034cb413c74aeadabc2b65b1f22835b7128 Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 13:59:20 +0300
Subject: [PATCH 04/16] Update QueryOffsetParams: add jsdoc

---
 src/client.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/client.ts b/src/client.ts
index 1ae9377..b37bd6f 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -835,6 +835,15 @@ export interface StoreOffsetParams {
   offsetValue: bigint
 }
 
+/**
+ * Query offset parameters.
+ *
+ * @see https://www.rabbitmq.com/tutorials/tutorial-two-javascript-stream#server-side-offset-tracking
+ *
+ * @member reference The named consumer's name. Identifies the concrete stable consumer to
+ * persistently track the dedicated offset. Also named as `condumerRef` elsewhere.
+ * @member stream A stream name.
+ */
 export interface QueryOffsetParams {
   reference: string
   stream: string

From 99cee43c492f7caf2ce9adfbf9af90dbdb805804 Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 14:16:54 +0300
Subject: [PATCH 05/16] Update StoreOffsetParams: add jsdoc

---
 src/client.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/client.ts b/src/client.ts
index b37bd6f..63cdf88 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -829,6 +829,15 @@ export interface SubscribeParams {
   offset: Offset
 }
 
+/**
+ * The parameters to store the concrete named consumer offset at the given stream.
+ *
+ * @member reference See {@link QueryOffsetParams.reference}
+ * @member stream See {@link QueryOffsetParams.stream}
+ * @member offsetValue The BigInt offset value.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
+ */
 export interface StoreOffsetParams {
   reference: string
   stream: string

From 489011057291e30562d3edaf2f5b07ba3b39496a Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 14:17:30 +0300
Subject: [PATCH 06/16] Update Connection.storeOffset: add jsdoc

---
 src/connection.ts | 40 ++++++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 12 deletions(-)

diff --git a/src/connection.ts b/src/connection.ts
index 208f24d..c59c2cb 100644
--- a/src/connection.ts
+++ b/src/connection.ts
@@ -561,6 +561,21 @@ export class Connection {
     return res.sequence
   }
 
+  /**
+   * Store the provided offset at the RabbitMQ server in the given stream for the given consumer.
+   *
+   * @param StoreOffsetParams The stream name, consumer name and the offset value.
+   *
+   * The offset is stored on the given stream as the additional service message not visible to
+   * a stream consumers but counted for in the RabbitMQ UI.
+   *
+   * For streams with millions of messages per second it is recommended to store the offset
+   * once per a number of messages to not litter the stream and potentially worsen the performance
+   * when very high throughput is required.
+   *
+   * @see https://www.rabbitmq.com/blog/2021/09/13/rabbitmq-streams-offset-tracking#the-dark-side-of-server-side-offset-tracking
+   * @see https://www.rabbitmq.com/docs/streams#offset-tracking
+   */
   public storeOffset(params: StoreOffsetParams): Promise<void> {
     return this.send(new StoreOffsetRequest(params))
   }
@@ -571,29 +586,30 @@ export class Connection {
    * @see https://www.rabbitmq.com/tutorials/tutorial-two-javascript-stream
    * @see https://www.rabbitmq.com/blog/2021/09/13/rabbitmq-streams-offset-tracking
    *
-   * @params QueryOffsetParams Stream name and the named consumer identifier.
+   * @param QueryOffsetParams The stream name and the named consumer identifier object.
+   *
+   * @see {@link Connection.connect}
+   * @see {@link Connection.storeOffset}
    *
-   * @see {@link storeOffset}
-   * @see {@link Client.connect}
+   * @example Consumer reads previously saved server-tracked offset to start consumning
+   * from the desired offset.
    *
-   * @example
+   * On consumer side create the client, detect the server-side saved offset to detect
+   * the deisred offset to consume from. Then declare a consumer with the desired offset
+   * and the consumed message handler.
    *
-   * Consumer reads previously saved offset to start consumning from the desired offset.
-   * Note, to be server-tracked the offset shuould be explicitly saved with `client.storeOffset()`
-   * On consumer side create the client, detect the server-side saved offset
-   * to detect the deisred offset to consume from. Then declare a consumer with the desired offset.
-   * When consuming, the consumer message handler above saved the offset server-side to be
-   * able to further track it
+   * When consuming, the consumer message handler may save the offset server-side
+   * for the `client.queryOffset()` to be able to further read it.
    *
    * ```typescript
-   * // ... create client
+   * // ... create the RabbitMQ client here
    * // Detect the desider starting offset for the next stream operation.
    * const offset = await client.queryOffset({ reference: 'consumer-x', stream: 'stream-a' })
    * const startWithOffset = offset ? rmqLibrary.Offset.offset(offset + 1n) :
    *   rmqLibrary.Offset.<whatever-enum-offset-is-desired>();
    * const consumer = await client.declareConsumer({stream: 'stream-b', offset: startWithOffset},
    *   async (this: StreamConsumer, message: Message) => { await this.storeOffset(message.offset); });
-   * // Note the offset is saved by the message handler.
+   *   // Note the offset is saved by the message handler on the server.
    * ```
    */
   public async queryOffset(params: QueryOffsetParams): Promise<bigint> {

From 4b642bb74f8236f158de3dde4b9354528c82f0e3 Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 14:35:23 +0300
Subject: [PATCH 07/16] Update Code51Exception: export a type

---
 src/application/Code51Exception.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/application/Code51Exception.ts b/src/application/Code51Exception.ts
index a66ad21..570c280 100644
--- a/src/application/Code51Exception.ts
+++ b/src/application/Code51Exception.ts
@@ -2,7 +2,7 @@
 
 import { ResponseCode } from "../util"
 
-type TResponseCode = (typeof ResponseCode)[keyof typeof ResponseCode]
+export type TResponseCode = (typeof ResponseCode)[keyof typeof ResponseCode]
 
 export default class Code51Exception extends Error {
   readonly #code?: TResponseCode

From 2c448477632b6e9abad07bdd991f3f0ece6c348a Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 14:36:43 +0300
Subject: [PATCH 08/16] Update offset test: a typo

---
 test/e2e/offset.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/offset.test.ts b/test/e2e/offset.test.ts
index 000b415..cdf58d7 100644
--- a/test/e2e/offset.test.ts
+++ b/test/e2e/offset.test.ts
@@ -267,7 +267,7 @@ describe("offset", () => {
       })
     }).timeout(10000)
 
-    it("declaring a consumer without consumerRef and querying for the offset should rise an error", async () => {
+    it("declaring a consumer without consumerRef and querying for the offset should raise an error", async () => {
       const consumer = await client.declareConsumer(
         { stream: testStreamName, offset: Offset.first() },
         (_message: Message) => {

From 09ec85b7f088caafb0b1733ba11923a853b95f89 Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 15:47:06 +0300
Subject: [PATCH 09/16] Add jsdoc to DeclareConsumerParams interface

---
 src/client.ts | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/src/client.ts b/src/client.ts
index 63cdf88..cbf812b 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -803,6 +803,51 @@ export interface ConsumerFilter {
   matchUnfiltered: boolean
 }
 
+/**
+ * The parameters to declare a stream consumer.
+ *
+ * @param stream A stream name from which the consumer will be consuming messages.
+ *
+ * @param consumerRef A named consumer's name (identifier) for server-side offset tracking and single
+ * active consumer behvior.
+ *
+ * @see https://github.com/coders51/rabbitmq-stream-js-client/blob/main/example/src/offset_tracking_example.js
+ * @see https://github.com/coders51/rabbitmq-stream-js-client/blob/main/example/src/single_active_consumer_update_example.js
+ *
+ * @see {@link QueryOffsetParams.reference}
+ * @see {@link StoreOffsetParams.reference}
+ *
+ * @param offset The value object {@link Offset} representing the possible values for the
+ * RabbitMQ stream offset. Tells the client from where in the stream you want to start consuming.
+ * Could be "first", "last", "next", a specific numeric offset, or timestamp depending on the Offset type.
+ *
+ * @see https://github.com/WhereJuly/rabbitmq-stream-js-client?tab=readme-ov-file#basic-consuming
+ * @see https://www.rabbitmq.com/blog/2021/09/13/rabbitmq-streams-offset-tracking#the-different-offset-specifications-in-a-stream
+ *
+ * @param connectionClosedListener A callback {@link ConnectionClosedListener} invoked if the connection
+ * is closed (with parameter indicating error or not) to let you react to the consumer’s connection
+ * being closed.
+ *
+ * @param consumerUpdateListener {@link ConsumerUpdateListener}
+ *
+ * @param singleActive A flag to indicate "single active consumer" mode.
+ * Single active consumer provides exclusive consumption and consumption continuity on a stream.
+ * @see https://www.rabbitmq.com/blog/2022/07/05/rabbitmq-3-11-feature-preview-single-active-consumer-for-streams
+ * @see https://github.com/coders51/rabbitmq-stream-js-client?tab=readme-ov-file#single-active-consumer
+ *
+ * @param filter A filter object {@link ConsumerFilter} specifying consumer filtering criteria.
+ * @see https://www.rabbitmq.com/docs/stream-filtering#filter-stages-overview
+ * @see https://github.com/coders51/rabbitmq-stream-js-client?tab=readme-ov-file#filtering
+ *
+ * @param creditPolicy {@link ConsumerCreditPolicy} determines if the consumer requests more message chunks from the broker
+ * while still processing the current chunk. By default only one chunk is processed ensuring
+ * the messages will be processed in order.
+ *
+ * @see https://github.com/coders51/rabbitmq-stream-js-client?tab=readme-ov-file#custom-policy
+ *
+ * @param consumerTag A simpler alias/identifier if you need to tag the consumer on the broker side
+ * for monitoring or naming.
+ */
 export interface DeclareConsumerParams {
   stream: string
   consumerRef?: string

From a8ea375bf130b474817d702d493c1e1f79c164a6 Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 15:58:24 +0300
Subject: [PATCH 10/16] Update Connection.queryOffset: implement custom
 exception with response code

---
 src/connection.ts       |  5 ++++-
 test/e2e/offset.test.ts | 23 ++++++++++++++++++++++-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/src/connection.ts b/src/connection.ts
index c59c2cb..753c665 100644
--- a/src/connection.ts
+++ b/src/connection.ts
@@ -57,6 +57,7 @@ import { coerce, lt } from "semver"
 import EventEmitter from "events"
 import { MetadataUpdateResponse } from "./responses/metadata_update_response"
 import { MetadataInfo } from "./responses/raw_response"
+import Code51Exception, { TResponseCode } from "./application/Code51Exception"
 
 export type ConnectionClosedListener = (hadError: boolean) => void
 
@@ -616,7 +617,9 @@ export class Connection {
     this.logger.debug(`Query Offset...`)
     const res = await this.sendAndWait<QueryOffsetResponse>(new QueryOffsetRequest(params))
     if (!res.ok) {
-      throw new Error(`Query offset command returned error with code ${res.code}`)
+      const code = res.code as TResponseCode
+
+      throw new Code51Exception(`Query offset command returned error with code ${res.code}`, code)
     }
     this.logger.debug(`Query Offset response: ${res.ok} with params: '${inspect(params)}'`)
     return res.offsetValue
diff --git a/test/e2e/offset.test.ts b/test/e2e/offset.test.ts
index cdf58d7..dc4f890 100644
--- a/test/e2e/offset.test.ts
+++ b/test/e2e/offset.test.ts
@@ -13,6 +13,8 @@ import {
   username,
   wait,
 } from "../support/util"
+import Code51Exception from "../../src/application/Code51Exception"
+import { ResponseCode } from "../../src/util"
 
 describe("offset", () => {
   const rabbit = new Rabbit(username, password)
@@ -146,7 +148,7 @@ describe("offset", () => {
       }, 5000)
     }).timeout(10000)
 
-    it("if offset is of type timestamp, all the messages belonging to batches sent earlier than the timestamp should be skipped", async () => {
+    it.skip("if offset is of type timestamp, all the messages belonging to batches sent earlier than the timestamp should be skipped", async () => {
       const receivedMessages: Message[] = []
       const publisher = await client.declarePublisher({ stream: testStreamName })
       const previousMessages = await sendANumberOfRandomMessages(publisher)
@@ -292,5 +294,24 @@ describe("offset", () => {
       await wait(200)
       await expectToThrowAsync(() => consumer.queryOffset(), Error, `This socket has been ended by the other party`)
     })
+
+    it("query offset is able to raise Code51Exception with ResponseCode.NoOffset code value set if there is no offset", async () => {
+      const params = { stream: testStreamName, consumerRef: "my_consumer", offset: Offset.first() }
+      const handler = (_message: Message) => { return } // prettier-ignore
+      const consumer = await client.declareConsumer(params, handler)
+
+      try {
+        await consumer.queryOffset()
+
+        throw new Error("Expected Code51Exception to be thrown")
+      } catch (error) {
+        const actual = error as Code51Exception
+
+        expect(actual).instanceOf(Error)
+        expect(actual).instanceOf(Code51Exception)
+        expect(actual.code).equals(ResponseCode.NoOffset)
+        expect(actual.message).contain("error with code 19")
+      }
+    })
   })
 })

From 1c5a89792bc6f0744d2cbf115e12a1b63d5d90ec Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 17:18:52 +0300
Subject: [PATCH 11/16] Add jsdoc to Code51Exception

---
 src/application/Code51Exception.ts | 35 ++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/src/application/Code51Exception.ts b/src/application/Code51Exception.ts
index 570c280..b7a7518 100644
--- a/src/application/Code51Exception.ts
+++ b/src/application/Code51Exception.ts
@@ -4,6 +4,41 @@ import { ResponseCode } from "../util"
 
 export type TResponseCode = (typeof ResponseCode)[keyof typeof ResponseCode]
 
+/**
+ * Provides distinct domain exception for the package. Contains the optional
+ * RabbitMQ Stream protocol response code for more convenient processing.
+ *
+ * @param message A custom error message.
+ * @param rmqStreamResponseCode The above mentioned response code.
+ *
+ * @see https://github.com/rabbitmq/rabbitmq-server/blob/main/deps/rabbitmq_stream/docs/PROTOCOL.adoc#response-codes
+ *
+ * @example Selectively manage the exception type and react differently.
+ *
+ * ```typescript
+ * let result: any;
+ *
+ * const isRethrowable = (error_: Error) => {
+ *     const isGenericError = error_ instanceof Code51Exception;
+ *     const isNonManagedResponseCode = (error_ as Code51Exception).code !== ResponseCode.NoOffset;
+ *
+ *     return isGenericError && isNonManagedResponseCode;
+ * };
+ *
+ * try {
+ *     result = consumer.queryOffset();
+ *     // ... process result
+ * } catch (error_) {
+ *     if (isRethrowable(error_)) { throw error_; }
+ *
+ *     const error = error_ as Code51Exception;
+ *     if (error.code === ResponseCode.NoOffset) { return null; }
+ *
+ *     return result;
+ * }
+ * ```
+ *
+ */
 export default class Code51Exception extends Error {
   readonly #code?: TResponseCode
 

From 1731ad84d405d65e6fca51d6ed279bcbf81e598c Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Tue, 11 Nov 2025 17:19:46 +0300
Subject: [PATCH 12/16] Update queryOffset: jsdoc

---
 src/connection.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/connection.ts b/src/connection.ts
index 753c665..6c34990 100644
--- a/src/connection.ts
+++ b/src/connection.ts
@@ -582,7 +582,8 @@ export class Connection {
   }
 
   /**
-   * Return the server-side saved offset.
+   * Return the server-side saved offset or throws {@link Code51Exception} with the
+   * RabbitMQ response code.
    *
    * @see https://www.rabbitmq.com/tutorials/tutorial-two-javascript-stream
    * @see https://www.rabbitmq.com/blog/2021/09/13/rabbitmq-streams-offset-tracking
@@ -612,6 +613,11 @@ export class Connection {
    *   async (this: StreamConsumer, message: Message) => { await this.storeOffset(message.offset); });
    *   // Note the offset is saved by the message handler on the server.
    * ```
+   *
+   * @throws {@link Code51Exception} if the server-side offset cannot be retrieved. The exception
+   * contains the `code` field that equals the RabbitMQ stream protocol response code value.
+   *
+   * @see https://github.com/rabbitmq/rabbitmq-server/blob/main/deps/rabbitmq_stream/docs/PROTOCOL.adoc#response-codes
    */
   public async queryOffset(params: QueryOffsetParams): Promise<bigint> {
     this.logger.debug(`Query Offset...`)

From 1b4b359d7b3b06ff35a4adf287f3d53415580ff8 Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Wed, 12 Nov 2025 09:07:18 +0300
Subject: [PATCH 13/16] Update GitHub CI: checking tests success

---
 .github/workflows/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 34cfae6..88f783d 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -5,7 +5,7 @@ name: Node.js CI
 
 on:
   push:
-    branches: [main]
+    branches: [main,develop/check-testing-in-ci]
   pull_request:
     branches: [main]
 

From 6ddcd9b179f8c6ef73bb7b3dbd4bc667e71a0a8d Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Wed, 12 Nov 2025 09:17:42 +0300
Subject: [PATCH 14/16] Update misc files: typos

---
 src/client.ts                                 | 4 ++--
 src/connection.ts                             | 6 +++---
 test/unit/application/Code51Exception.test.ts | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/client.ts b/src/client.ts
index cbf812b..51a532b 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -809,7 +809,7 @@ export interface ConsumerFilter {
  * @param stream A stream name from which the consumer will be consuming messages.
  *
  * @param consumerRef A named consumer's name (identifier) for server-side offset tracking and single
- * active consumer behvior.
+ * active consumer behavior.
  *
  * @see https://github.com/coders51/rabbitmq-stream-js-client/blob/main/example/src/offset_tracking_example.js
  * @see https://github.com/coders51/rabbitmq-stream-js-client/blob/main/example/src/single_active_consumer_update_example.js
@@ -895,7 +895,7 @@ export interface StoreOffsetParams {
  * @see https://www.rabbitmq.com/tutorials/tutorial-two-javascript-stream#server-side-offset-tracking
  *
  * @member reference The named consumer's name. Identifies the concrete stable consumer to
- * persistently track the dedicated offset. Also named as `condumerRef` elsewhere.
+ * persistently track the dedicated offset. Also named as `consumerRef` elsewhere.
  * @member stream A stream name.
  */
 export interface QueryOffsetParams {
diff --git a/src/connection.ts b/src/connection.ts
index 6c34990..39c96be 100644
--- a/src/connection.ts
+++ b/src/connection.ts
@@ -593,11 +593,11 @@ export class Connection {
    * @see {@link Connection.connect}
    * @see {@link Connection.storeOffset}
    *
-   * @example Consumer reads previously saved server-tracked offset to start consumning
+   * @example Consumer reads previously saved server-tracked offset to start consuming
    * from the desired offset.
    *
    * On consumer side create the client, detect the server-side saved offset to detect
-   * the deisred offset to consume from. Then declare a consumer with the desired offset
+   * the desired offset to consume from. Then declare a consumer with the desired offset
    * and the consumed message handler.
    *
    * When consuming, the consumer message handler may save the offset server-side
@@ -605,7 +605,7 @@ export class Connection {
    *
    * ```typescript
    * // ... create the RabbitMQ client here
-   * // Detect the desider starting offset for the next stream operation.
+   * // Detect the decider starting offset for the next stream operation.
    * const offset = await client.queryOffset({ reference: 'consumer-x', stream: 'stream-a' })
    * const startWithOffset = offset ? rmqLibrary.Offset.offset(offset + 1n) :
    *   rmqLibrary.Offset.<whatever-enum-offset-is-desired>();
diff --git a/test/unit/application/Code51Exception.test.ts b/test/unit/application/Code51Exception.test.ts
index d91e889..0b16050 100644
--- a/test/unit/application/Code51Exception.test.ts
+++ b/test/unit/application/Code51Exception.test.ts
@@ -13,7 +13,7 @@ describe("[unit] Code51Exception Test", () => {
     expect(actual.code).eql(undefined)
   })
 
-  it("+constructor() #2: Should create Code51Exception expected object with expectd response code", () => {
+  it("+constructor() #2: Should create Code51Exception expected object with expected response code", () => {
     const expected = ResponseCode.NoOffset
     const actual = new Code51Exception("a message", expected)
 

From ed50fd617ec3607f9f34684333aa6f74eecccdcc Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Wed, 12 Nov 2025 09:23:51 +0300
Subject: [PATCH 15/16] Restore: skipped brittle test

---
 test/e2e/offset.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/offset.test.ts b/test/e2e/offset.test.ts
index dc4f890..2d3359c 100644
--- a/test/e2e/offset.test.ts
+++ b/test/e2e/offset.test.ts
@@ -148,7 +148,7 @@ describe("offset", () => {
       }, 5000)
     }).timeout(10000)
 
-    it.skip("if offset is of type timestamp, all the messages belonging to batches sent earlier than the timestamp should be skipped", async () => {
+    it("if offset is of type timestamp, all the messages belonging to batches sent earlier than the timestamp should be skipped", async () => {
       const receivedMessages: Message[] = []
       const publisher = await client.declarePublisher({ stream: testStreamName })
       const previousMessages = await sendANumberOfRandomMessages(publisher)

From 8dadbb9a7d7464b871727f5d4d95ecb6e9a2481d Mon Sep 17 00:00:00 2001
From: WhereJuly <where.july@googlemail.com>
Date: Wed, 12 Nov 2025 09:31:30 +0300
Subject: [PATCH 16/16] Clean up: CI test branch trigger

---
 .github/workflows/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 88f783d..34cfae6 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -5,7 +5,7 @@ name: Node.js CI
 
 on:
   push:
-    branches: [main,develop/check-testing-in-ci]
+    branches: [main]
   pull_request:
     branches: [main]