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

| Pattern | Delivery Guarantee | Use When | Example Use Case | | -------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------ | -------------------------------------- | | Events | At-most-once | Fire-and-forget broadcasting to multiple subscribers | Real-time notifications, log streaming | | Events Store | At-least-once (persistent) | Subscribers must not miss messages, even if offline | Audit trails, event sourcing, replay | | Queues | At-least-once (with ack) | Work must be processed exactly by one consumer with acknowledgment | Job processing, task distribution | | Commands | At-most-once (request/reply) | You need a response confirming the action was executed | Device control, configuration changes | | Queries | At-most-once (request/reply) | You need to retrieve data from a responder | Data lookups, service-to-service reads |

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

Configuration

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

| Option | Type | Default | Description | | -------------------------- | ------------------------------ | ------------------------ | -------------------------------------------------- | | address | string | (required) | KubeMQ server address (host:port) | | clientId | string | Auto-generated UUID | Unique client identifier | | credentials | CredentialProvider \| string | undefined | Authentication token or provider | | tls | TlsOptions \| boolean | Smart default | TLS configuration (auto-enabled for non-localhost) | | retry | RetryPolicy | 3 retries, 500ms initial | Auto-retry policy for transient errors | | reconnect | ReconnectionPolicy | Unlimited, 500ms initial | Auto-reconnection policy | | connectionTimeoutSeconds | number | 10 | Connection establishment timeout (seconds) | | logger | Logger | noopLogger | Structured logging interface | | tracerProvider | TracerProvider | No-op | OpenTelemetry tracer for distributed tracing |

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

| Problem | Solution | | ---------------------------------- | ----------------------------------------------------------------- | | Connection refused | Verify KubeMQ server is running on the configured address | | Authentication failed | Check your auth token or TLS certificates | | Message too large | Default limit is 100 MB; configure maxSendMessageSize | | No messages received | Ensure subscriber is connected before publisher sends | | Queue message not acknowledged | Messages reappear when not acknowledged — always call msg.ack() |

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:

| Phase | Duration | What's Included | | ------------- | ----------------------------- | ------------------------------------- | | Active | Until next major GA | Features, bug fixes, security patches | | Security-only | 12 months after next major GA | Critical security patches only | | End of Life | After security-only window | No updates; upgrade recommended |

Current Version Status

| Version | Status | Security Support Until | | ------- | ------------- | ----------------------- | | v3.x | Active | — | | v2.x | Security-only | 12 months after v3.0 GA | | v1.x | End of Life | No longer supported |

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.