KubeMQ SDK for Node.js / TypeScript

The official TypeScript/JavaScript client for KubeMQ — a Kubernetes-native message broker for microservices. This SDK provides a unified client for all messaging patterns (Events, Events Store, Queues, Commands, and Queries) with TypeScript-first types, auto-retry, structured error handling, and OpenTelemetry integration.

Table of Contents

• Installation
• Quick Start
  • Events (fire-and-forget)
  • Queues (guaranteed delivery)
  • RPC (request/reply)
• Messaging Patterns
• Configuration
• Error Handling
• Troubleshooting
• Requirements
• Deprecation Policy
• Version Lifecycle
  • Current Version Status
• Security
• Additional Resources
• Contributing
• License

Installation

npm install kubemq-js

Prerequisites:

• Node.js 20 or later (22, 24 also supported)
• A running KubeMQ server (default: localhost:50000)

Quick Start

Events (fire-and-forget)

import { KubeMQClient, createEventMessage } from 'kubemq-js';

const client = await KubeMQClient.create({ address: 'localhost:50000' });

// Subscribe
client.subscribeToEvents({
  channel: 'events.hello',
  onEvent: (msg) => console.log('Received:', new TextDecoder().decode(msg.body)),
  onError: (err) => console.error('Error:', err.message),
});

// Publish
await client.sendEvent(createEventMessage({ channel: 'events.hello', body: 'Hello KubeMQ!' }));

Queues (guaranteed delivery)

import { KubeMQClient, createQueueMessage } from 'kubemq-js';

const client = await KubeMQClient.create({ address: 'localhost:50000' });

// Send
await client.sendQueueMessage(
  createQueueMessage({ channel: 'queues.tasks', body: 'Process this' }),
);

// Receive
const messages = await client.receiveQueueMessages({
  channel: 'queues.tasks',
  waitTimeoutSeconds: 5,
});
for (const msg of messages) {
  console.log('Task:', new TextDecoder().decode(msg.body));
  await msg.ack();
}

RPC (request/reply)

import { KubeMQClient, createCommand } from 'kubemq-js';

const client = await KubeMQClient.create({ address: 'localhost:50000' });

// Handle commands
client.subscribeToCommands({
  channel: 'commands.greet',
  onCommand: (cmd) => client.sendCommandResponse({ requestId: cmd.id, isExecuted: true }),
  onError: (err) => console.error(err.message),
});

// Send command
const response = await client.sendCommand(
  createCommand({ channel: 'commands.greet', body: 'Hi', timeoutInSeconds: 5 }),
);
console.log('Executed:', response.isExecuted);

Expected output:

Received: Hello KubeMQ!
Task: Process this
Executed: true

Messaging Patterns

See the examples directory for 27 runnable examples covering all patterns and configuration options.

Configuration

The KubeMQClient.create() factory accepts a ClientOptions object:

import { KubeMQClient, createConsoleLogger } from 'kubemq-js';

const client = await KubeMQClient.create({
  address: 'kubemq-server:50000',
  credentials: 'my-auth-token',
  tls: { enabled: true, caCert: '/path/to/ca.pem' },
  retry: {
    maxRetries: 5,
    initialBackoffMs: 1000,
    maxBackoffMs: 30_000,
    multiplier: 2.0,
    jitter: 'full',
  },
  logger: createConsoleLogger('info'),
});

Error Handling

All SDK errors extend KubeMQError with a typed hierarchy of 19 subclasses. Every error carries an isRetryable flag, a machine-readable code, and an optional suggestion for the fix.

import { KubeMQError, ConnectionError, ValidationError } from 'kubemq-js';

try {
  await client.sendEvent(msg);
} catch (err) {
  if (err instanceof ConnectionError) {
    console.log('Server unreachable, will auto-retry');
  } else if (err instanceof ValidationError) {
    console.log('Fix the message:', err.suggestion);
  }
}

The SDK automatically retries transient errors (connection drops, timeouts, throttling) using exponential backoff with jitter. Permanent errors (validation, auth, not-found) are thrown immediately.

See the Error Handling Guide for the full error hierarchy, retry configuration, and best practices.

Troubleshooting

See the Troubleshooting Guide for 11 detailed problem/solution entries with exact error messages.

Requirements

• Node.js: ≥20.11.0 (20.x maintenance LTS, 22.x active LTS, or 24.x current)
• TypeScript: ≥ 5.0 (optional — the SDK ships compiled JS with .d.ts declarations)

Node.js 14, 16, and 18 are no longer supported in v3.x. See the migration guide for details.

Deprecation Policy

• Deprecated APIs are annotated with @deprecated TSDoc tags
• Each deprecation notice names the replacement API
• Deprecated APIs receive a minimum of 2 minor versions or 6 months notice before removal, whichever is longer
• Deprecated APIs continue to function until removal
• All deprecations are recorded in CHANGELOG.md
• Removed APIs are documented in migration guides (see docs/MIGRATION-v3.md)

Version Lifecycle

When a new major version of kubemq-js reaches General Availability (GA), the previous major version enters a security-only maintenance window:

Current Version Status

Security

See SECURITY.md for vulnerability reporting. The SDK supports TLS and mTLS connections — for configuration details, see How to Connect with TLS.

Additional Resources

• KubeMQ Documentation — Official KubeMQ documentation and guides
• Full Documentation Index — Complete SDK documentation index
• KubeMQ Concepts — Core KubeMQ messaging concepts
• SDK Feature Parity Matrix — Cross-SDK feature comparison
• CHANGELOG.md — Release history
• TROUBLESHOOTING.md — Common issues and solutions
• Examples — Runnable code examples for all patterns

Contributing

See CONTRIBUTING.md for development setup, coding standards, and PR guidelines.

License

Apache 2.0 — see LICENSE for details.