Delayed Messages

Overview

Use a delivery delay to hold a queue message out of consumers' reach for a fixed window after you send it — the broker accepts and persists the message immediately, but keeps it invisible to pollers until the delay expires. Reach for this when you need scheduled work — a reminder to fire in an hour, a retry with back-off, a task queued for off-peak processing — without standing up a separate scheduler or cron service.

Set it with policy: { delaySeconds: ... } when you create the message; the broker does the waiting. Check the send result's delayedTo field — it returns a Date confirming exactly when the message becomes visible, so you can log or monitor delayed pipelines. Until then, any poll you make via receiveQueueMessages against that channel simply returns nothing for that message — it isn't hidden in a separate place, it's the same queue, just not yet eligible for delivery.

Gotchas: set the delay once at send time — you can't extend or shorten it afterward, so send a new message if you need a different wait. A long delay still counts as an in-flight, persisted message, so it survives a broker restart, but it also occupies queue storage for the whole waiting period. Don't confuse this with a visibility timeout after delivery — that's a separate mechanism for redelivery on failed acknowledgment, not initial availability.

Prerequisites

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

Code

/**
 * Example: Delayed Message Delivery
 *
 * Demonstrates sending queue messages with a delay. The message is accepted
 * immediately but only becomes visible to consumers after the delay expires.
 * Useful for scheduling future work.
 *
 * Prerequisites:
 *   - KubeMQ server running on localhost:50000
 *
 * Run: npx tsx examples/queues/delayed-messages.ts
 */
import { KubeMQClient, createQueueMessage } from 'kubemq-js';

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

  try {
    // Send a message delayed by 10 seconds.
    const result = await client.sendQueueMessage(
      createQueueMessage({
        channel: 'js-queues.delayed-messages',
        body: 'Send follow-up email to user@example.com',
        policy: {
          delaySeconds: 10,
        },
      }),
    );

    console.log('Sent delayed message:', result.messageId);
    console.log('Message will become visible at:', result.delayedTo?.toISOString());

    // Immediate poll returns nothing — message is still delayed.
    const immediate = await client.receiveQueueMessages({
      channel: 'js-queues.delayed-messages',
      waitTimeoutSeconds: 2,
    });
    console.log('Immediate poll received:', immediate.length, 'messages');

    // Wait for the delay to expire, then poll again.
    console.log('Waiting 11 seconds for delay to expire...');
    await new Promise((resolve) => setTimeout(resolve, 11_000));

    const delayed = await client.receiveQueueMessages({
      channel: 'js-queues.delayed-messages',
      waitTimeoutSeconds: 5,
    });

    for (const msg of delayed) {
      console.log('Received delayed message:', new TextDecoder().decode(msg.body));
      await msg.ack();
    }
  } finally {
    await client.close();
  }
}

main().catch(console.error);

How It Works

• policy: { delaySeconds: 10 } makes the message invisible to consumers for 10 seconds after it is accepted by the server.
• result.delayedTo is a Date returned by the server confirming the exact visibility time — useful for logging or scheduling follow-up work.
• The first receiveQueueMessages() call with waitTimeoutSeconds: 2 returns immediately with 0 messages because the delay has not expired yet.
• After 11 seconds the message becomes visible, the second poll picks it up, and msg.ack() removes it permanently from the queue.

Related

• Delay Policy — field-level reference for policy: { delaySeconds }
• Pattern overview
• Node.js SDK Reference
• Send & Receive
• Ack All