# Poll Mode (/sdks/nodejs/how-to/queues/poll-mode)



## Overview [#overview]

**Poll mode** is a pull-based way to consume queue messages: the consumer decides exactly when to ask for work and how much, instead of holding an open stream the broker pushes into. That control matters for batch jobs, cron-triggered workers, and any consumer that only runs intermittently and would rather ask "is there anything for me?" than keep a subscription alive.

A single call to `receiveQueueMessages()` sends a channel, `maxMessages`, and `waitTimeoutSeconds`; the broker holds the request open as a long poll and returns once enough messages are available or the timeout elapses, so the call never spins on an empty queue. There's no persistent streaming session to manage — just a plain request and a batch of messages back.

**Gotchas:** messages received but not acked stay locked (invisible to other consumers) until the visibility timeout expires — always ack or nack in production code, unlike this minimal example; the timeout bounds latency, not throughput, so a small `maxMessages` on a busy queue means many round trips; and reach for `streamQueueMessages()` instead when you need continuous delivery callbacks or fine-grained ack/nack control in one long-lived session.

## Prerequisites [#prerequisites]

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

## Code [#code]

```typescript title="poll-mode.ts"
import { KubeMQClient, createQueueMessage } from 'kubemq-js';

async function main() {
  const client = await KubeMQClient.create({
    address: 'localhost:50000',
    clientId: 'js-queues-stream-poll-mode-client',
  });

  try {
    await client.sendQueueMessage(
      createQueueMessage({ channel: 'js-queues-stream.poll-mode', body: 'poll-me' }),
    );

    const messages = await client.receiveQueueMessages({
      channel: 'js-queues-stream.poll-mode',
      maxMessages: 1,
      waitTimeoutSeconds: 5,
    });

    for (const msg of messages) {
      console.log('Polled:', new TextDecoder().decode(msg.body));
    }
    console.log('Total polled:', messages.length);
  } finally {
    await client.close();
  }
}

main().catch(console.error);

```

## How It Works [#how-it-works]

* `receiveQueueMessages()` is a one-shot blocking poll: it waits up to `waitTimeoutSeconds` for up to `maxMessages: 1` to become available and then returns.
* This is the simplest consumption model — no streaming session, no persistent handle. Call it in a loop to implement continuous polling.
* Messages received but not acked are locked (invisible to other consumers) until the visibility timeout expires. This example omits the ack to keep the demo minimal; production code should always ack or nack.
* Compare with `streamQueueMessages()` when you need batch delivery callbacks or fine-grained ack/nack/requeue control within the same session.

## Related [#related]

* [Pattern overview](/learn/queues/getting-started)
* [Node.js SDK Reference](/sdks/nodejs/reference)
* [Send & Receive](/sdks/nodejs/tutorials/send-receive)
* [Ack All](/sdks/nodejs/how-to/queues/ack-all)