Which to use

For the task-oriented how-to, see Delayed Messages. This page focuses on the policy: { delaySeconds } delay-policy option itself — its evaluation point and interaction with redelivery.

Overview

policy: { delaySeconds } is the option passed to createQueueMessage that defers when a queued message becomes visible to consumers — set it before sending, and the broker excludes the message from delivery until the countdown expires. It starts the moment the broker accepts the message, not when the client sends it, and is evaluated once, at send time.

Gotchas: the delay is a floor, not a guarantee — the message becomes eligible when the timer expires, but actual delivery still waits for a consumer to poll, so don't rely on it for precise scheduling. It's one-shot: there's no recurrence or cron-like behavior, so long or repeating delays need application logic on top. And it's independent of redelivery — a delayed message that's later nacked or times out after delivery follows normal visibility-timeout/retry rules, not the original send-time delay.

Prerequisites

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

Code

delay-policy.ts

/**
 * Example: Queue Stream — Delayed Message Delivery
 *
 * Demonstrates sending messages with a delay policy via the stream
 * upstream API. Messages are not delivered to consumers until the
 * specified delay has elapsed.
 *
 * Prerequisites:
 *   - KubeMQ server running on localhost:50000
 *
 * Run: npx tsx examples/queues-stream/delay-policy.ts
 */
import { KubeMQClient, createQueueMessage } from 'kubemq-js';

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

  try {
    const upstream = client.createQueueUpstream();

    const result = await upstream.send([
      createQueueMessage({
        channel: 'js-queues-stream.delay-policy',
        body: 'Order #1 — deliver after 5 seconds',
        policy: { delaySeconds: 5 },
      }),
      createQueueMessage({
        channel: 'js-queues-stream.delay-policy',
        body: 'Order #2 — deliver after 10 seconds',
        policy: { delaySeconds: 10 },
      }),
    ]);

    console.log('Sent', result.results.length, 'delayed messages');
    for (const r of result.results) {
      const delayed =
        r.delayedTo instanceof Date && !isNaN(r.delayedTo.getTime())
          ? r.delayedTo.toISOString()
          : 'N/A';
      console.log(`  ${r.messageId}: delayedTo=${delayed}`);
    }

    console.log('Waiting 6 seconds for first message to become available...');
    await new Promise((resolve) => setTimeout(resolve, 6000));

    const handle = client.streamQueueMessages({
      channel: 'js-queues-stream.delay-policy',
      maxMessages: 10,
      waitTimeoutSeconds: 3,
    });

    handle.onMessages((msgs) => {
      console.log(`Received ${msgs.length} message(s):`);
      for (const msg of msgs) {
        console.log(`  ${new TextDecoder().decode(msg.body)}`);
        msg.ack();
      }
    });

    handle.onError((err) => {
      console.error('Downstream error:', err.message);
    });

    await new Promise((resolve) => setTimeout(resolve, 5000));
    handle.close();
    upstream.close();
  } finally {
    await client.close();
  }
}

main().catch(console.error);

How It Works

policy: { delaySeconds: 5 } and { delaySeconds: 10 } tell the server to hold each message for the specified duration before making it visible to consumers.
The QueueUpstreamResult from upstream.send() includes delayedTo — a Date showing when the message will become available — confirming the server accepted the policy.
After waiting 6 seconds, only the first message (5 s delay) is visible; the second (10 s delay) is still hidden and requires waiting the remaining 4 seconds.
msg.ack() inside onMessages is called synchronously on the stream message; for stream API messages, ack does not return a Promise.

Delayed Messages — task-oriented walkthrough for sending delayed messages
Pattern overview
Node.js SDK Reference
Send & Receive
Ack All

Delay Policy

Overview

Prerequisites

Code

How It Works

On this page

Delay Policy

Overview

Prerequisites

Code

How It Works

Related

On this page