Peek Messages

Overview

Peeking lets you look at what's sitting in a queue without touching it — the messages stay exactly where they are, still waiting for whichever consumer eventually receives them. It's the tool you reach for when you need visibility into queue state — checking backlog depth, inspecting payloads while debugging a stuck pipeline, or building an operational dashboard — without risking a collision with real consumers competing for the same work.

peekQueueMessages() is a variant of the same call receiveQueueMessages() uses, just in read-only mode: it takes the same channel, maxMessages, and waitTimeoutSeconds, but the broker never marks the returned messages as delivered, locks them, or starts a visibility timeout — so no acknowledgment is needed or even possible.

Gotchas: peeked messages aren't reserved for you — a consumer can receiveQueueMessages() and remove them the instant after you peek, so treat the count as a point-in-time estimate, not a guarantee. Peek also won't surface messages already locked inside another consumer's in-flight receive, and it's not a substitute for receiving when you actually intend to process what you see.

Prerequisites

• KubeMQ server running on localhost:50000
• Node.js SDK installed (npm install kubemq-js)

Code

/**
 * Example: Peek (Waiting) Messages Without Consuming
 *
 * Demonstrates peeking at messages in a queue without removing them.
 * Useful for monitoring queue depth or inspecting messages before
 * deciding whether to process them.
 *
 * Prerequisites:
 *   - KubeMQ server running on localhost:50000
 *
 * Run: npx tsx examples/queues/peek-messages.ts
 */
import { KubeMQClient, createQueueMessage } from 'kubemq-js';

async function main(): Promise<void> {
  const client = await KubeMQClient.create({
    address: 'localhost:50000',
    clientId: 'js-queues-peek-messages-client',
  });

  try {
    // Send a few messages to inspect.
    for (let i = 1; i <= 3; i++) {
      await client.sendQueueMessage(
        createQueueMessage({
          channel: 'js-queues.peek-messages',
          body: `Report #${i} ready for review`,
        }),
      );
    }

    // Peek at waiting messages — they remain in the queue.
    const peeked = await client.peekQueueMessages({
      channel: 'js-queues.peek-messages',
      waitTimeoutSeconds: 5,
      maxMessages: 10,
    });

    console.log(`Found ${peeked.length} messages waiting:`);
    for (const msg of peeked) {
      console.log(`  - ${new TextDecoder().decode(msg.body)}`);
    }
  } finally {
    await client.close();
  }
}

main().catch(console.error);

How It Works

• peekQueueMessages() is a non-destructive read: messages are inspected but not locked or removed — the queue state is unchanged after the call.
• Unlike receiveQueueMessages(), no acknowledgment is required because peek does not lock the messages; other consumers can still receive them.
• waitTimeoutSeconds: 5 and maxMessages: 10 work the same as in receive — the call returns early if messages are available before the timeout.
• Use peek for monitoring queue depth, debugging message content, or inspecting headers before committing to processing a batch.

Related

• Pattern overview
• Node.js SDK Reference
• Send & Receive
• Ack All