# @imqueue is a message-queue RPC framework for Node.js and TypeScript back-ends

Source: https://imqueue.org/intro/

Services describe themselves at runtime, so their typed clients are generated, not
written. The name is short for **I**ntercommunication **M**essaging **Queue** — @imqueue,
imqueue and IMQ all refer to this framework. It is built with Node.js and
TypeScript for service-oriented back-ends (microservices being a special case of
SOA), works well behind an API layer such as GraphQL or a REST gateway, and lets you
write only the functionality while @imqueue handles the low-level messaging.

## @imqueue at a glance

| | |
|---|---|
| @imqueue/core | 3.3.2 |
| @imqueue/rpc | 3.5.3 |
| Licence | GPL-3.0-only, or a commercial licence for closed-source distribution |
| Node.js | 22.12 or newer |
| Redis | 3.2 or newer (6.2+ for safe delivery) |
| Transport | Redis only — the vendor option defaults to Redis and is its only supported value |
| Addressing | the queue name, which is the service class name — no discovery |
| Load balancing | competing consumers — no balancer, no weighting, no canaries |
| Delivery | at-least-once in both modes, so exposed methods should be idempotent |
| Streaming | none — request/response only |
| Languages | Node.js and TypeScript only |
| Contract source | the service class plus its JSDoc; clients are generated from a running service |


## Key capabilities

- **@imqueue/core** — messaging queue as the base communication protocol between services. [Reference](https://imqueue.org/api/core/latest/)
- **@imqueue/rpc** — an RPC-like programming interface over the messaging queue. [Reference](https://imqueue.org/api/rpc/latest/)
- **@imqueue/cli** — a rapid application development command line interface. [Manual](https://imqueue.org/cli/)

Thirteen more packages cover caching, observability, API composition, background
work and hardening — all with generated references under [/api/](https://imqueue.org/api/).

## Key principles

- **Reliable.** Safe-delivery messaging re-queues a message a dying worker never
  started, rather than losing it with the process. The guarantee covers that
  hand-off: delivery is
  [at-least-once](https://imqueue.org/api/core/latest/core.imqoptions.safedelivery/), so
  handlers should be idempotent.
- **Scalable.** Cluster the backend engine, fork across a machine's cores, and scale
  horizontally across servers — throughput grows with the workers you add, and
  [what that looks like on one rig is measured here](https://imqueue.org/blog/benchmarking-imqueue-throughput/).
- **Simple (KISS).** Low entry for JS/TypeScript developers — minutes to your first
  service. No hidden knowledge, a clean JSON-based protocol, and familiar patterns
  (Messaging Queue and RPC).
- **Self-describing.** Every service describes itself, so clients are generated
  dynamically on the fly or pre-generated to files. You focus only on the service.

## How it works

### A centralized broker

IMQ implements a messaging queue over a broker (Redis today, adapters are
pluggable) that routes messages between services and their clients. All messages
flow through a single point, so monitoring and debugging use the tooling the broker
already gives you.

No service discovery to implement — instances compete for their messages. If one is
busy or down, another consumes the message and delivers the response anyway.
Load-balancing happens naturally, with good distribution across nodes.

### Service & client model

From a development point of view a service is as simple as a class with exposed
methods. A client is a local representation of that remote service's interface.

Call a client method and it takes care of delivering the message to the queue,
invoking the matching service method, and returning the result. At development level
it simply looks like remote procedure calls — and clients are generated for you, so
you focus only on the service.

## Next

- [Get started in a few minutes](https://imqueue.org/get-started/)
- [Tutorial](https://imqueue.org/tutorial/) — a complete example application
- [Documentation](https://imqueue.org/docs/) — every section