kubemq-js
Version:
KubeMQ SDK for Node.js — gRPC-based messaging client for Events, Queues, Commands, and Queries
251 lines (189 loc) • 12.2 kB
Markdown
# KubeMQ SDK for Node.js / TypeScript
[](https://www.npmjs.com/package/kubemq-js)
[](https://github.com/kubemq-io/kubemq-js/actions/workflows/ci.yml)
[](https://codecov.io/gh/kubemq-io/kubemq-js)
[](https://opensource.org/licenses/Apache-2.0)
The official TypeScript/JavaScript client for [KubeMQ](https://kubemq.io/) — 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](#installation)
- [Quick Start](#quick-start)
- [Events (fire-and-forget)](#events-fire-and-forget)
- [Queues (guaranteed delivery)](#queues-guaranteed-delivery)
- [RPC (request/reply)](#rpc-requestreply)
- [Messaging Patterns](#messaging-patterns)
- [Configuration](#configuration)
- [Error Handling](#error-handling)
- [Troubleshooting](#troubleshooting)
- [Requirements](#requirements)
- [Deprecation Policy](#deprecation-policy)
- [Version Lifecycle](#version-lifecycle)
- [Current Version Status](#current-version-status)
- [Security](#security)
- [Additional Resources](#additional-resources)
- [Contributing](#contributing)
- [License](#license)
## Installation
```bash
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)
```typescript
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)
```typescript
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)
```typescript
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](https://github.com/kubemq-io/kubemq-js/tree/main/examples/events) | At-most-once | Fire-and-forget broadcasting to multiple subscribers | Real-time notifications, log streaming |
| [Events Store](https://github.com/kubemq-io/kubemq-js/tree/main/examples/events-store) | At-least-once (persistent) | Subscribers must not miss messages, even if offline | Audit trails, event sourcing, replay |
| [Queues](https://github.com/kubemq-io/kubemq-js/tree/main/examples/queues) | At-least-once (with ack) | Work must be processed exactly by one consumer with acknowledgment | Job processing, task distribution |
| [Commands](https://github.com/kubemq-io/kubemq-js/tree/main/examples/rpc) | At-most-once (request/reply) | You need a response confirming the action was executed | Device control, configuration changes |
| [Queries](https://github.com/kubemq-io/kubemq-js/tree/main/examples/rpc) | At-most-once (request/reply) | You need to retrieve data from a responder | Data lookups, service-to-service reads |
See the [examples directory](https://github.com/kubemq-io/kubemq-js/tree/main/examples) 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 |
```typescript
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.
```typescript
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](https://github.com/kubemq-io/kubemq-js/blob/main/docs/ERROR-HANDLING.md) 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](https://github.com/kubemq-io/kubemq-js/blob/main/docs/TROUBLESHOOTING.md) 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](./docs/MIGRATION-v3.md) 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](./CHANGELOG.md)
- Removed APIs are documented in migration guides (see [docs/MIGRATION-v3.md](./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](SECURITY.md) for vulnerability reporting. The SDK supports TLS and mTLS connections — for configuration details, see [How to Connect with TLS](docs/how-to/connect-with-tls.md).
## Additional Resources
- [KubeMQ Documentation](https://docs.kubemq.io/) — Official KubeMQ documentation and guides
- [Full Documentation Index](docs/INDEX.md) — Complete SDK documentation index
- [KubeMQ Concepts](docs/CONCEPTS.md) — Core KubeMQ messaging concepts
- [SDK Feature Parity Matrix](../sdk-feature-parity-matrix.md) — Cross-SDK feature comparison
- [CHANGELOG.md](./CHANGELOG.md) — Release history
- [TROUBLESHOOTING.md](https://github.com/kubemq-io/kubemq-js/blob/main/docs/TROUBLESHOOTING.md) — Common issues and solutions
- [Examples](https://github.com/kubemq-io/kubemq-js/tree/main/examples) — Runnable code examples for all patterns
## Contributing
See [CONTRIBUTING.md](https://github.com/kubemq-io/kubemq-js/blob/main/CONTRIBUTING.md) for development setup, coding standards, and PR guidelines.
## License
Apache 2.0 — see [LICENSE](https://github.com/kubemq-io/kubemq-js/blob/main/LICENSE) for details.