# carrotmq

> easy way to use rabbitmq

Latest version **8.0.3** (published 2025-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install carrotmq
pnpm add carrotmq
yarn add carrotmq
bun add carrotmq
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 8.0.3 |
| Published | 2025-07-10 |
| First published | 2016-03-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=16 |
| Dependencies | 8 |
| Unpacked size | 57.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | bangbang93 |
| Maintainers | bangbang93 |
| Keywords | rabbitmq, amqp, amqplib |

## Links

- npm: https://www.npmjs.com/package/carrotmq
- Repository: https://github.com/bangbang93/carrotmq
- Homepage: https://github.com/bangbang93/carrotmq#readme
- Issues: https://github.com/bangbang93/carrotmq/issues
- npm.io page: https://npm.io/package/carrotmq

## Dependencies (8)

- [nanoid](https://npm.io/package/nanoid.md) ^3.3.1
- [verror](https://npm.io/package/verror.md) ^1.10.1
- [amqplib](https://npm.io/package/amqplib.md) ^0.8.0
- [bluebird](https://npm.io/package/bluebird.md) ^3.7.2
- [@types/node](https://npm.io/package/@types/node.md) ^14.14.25
- [@types/amqplib](https://npm.io/package/@types/amqplib.md) ^0.8.2
- [@types/bluebird](https://npm.io/package/@types/bluebird.md) ^3.5.36
- [@sindresorhus/is](https://npm.io/package/@sindresorhus/is.md) ^4.6.0

## Recent versions

- 8.0.3 (latest) — 2025-07-10
- 8.0.2 — 2022-06-10
- 8.0.1 — 2022-03-23
- 8.0.0 — 2022-03-04
- 7.0.1 — 2021-10-15
- 7.0.0 — 2021-05-18
- 6.2.7 — 2021-03-10
- 6.2.6 — 2019-12-31
- 6.2.5 — 2019-12-31
- 6.2.4 — 2019-12-31
- 6.2.3 — 2019-12-31
- 6.2.2 — 2019-05-15
- 6.2.1 — 2019-03-13
- 6.2.0 — 2019-03-11
- 6.1.4 — 2019-03-06
- … 80 more at https://npm.io/package/carrotmq/versions

## README

# carrotmq

a much easy way to use rabbitmq

[中文文档](https://blog.bangbang93.com/2016/03/29/carrotmq%e4%b8%ad%e6%96%87%e6%96%87%e6%a1%a3.moe)

[![Build Status](https://travis-ci.org/bangbang93/carrotmq.svg?branch=master)](https://travis-ci.org/bangbang93/carrotmq)
[![Version npm](https://img.shields.io/npm/v/carrotmq.svg?style=flat-square)](https://www.npmjs.com/package/carrotmq)
[![NPM Downloads](https://img.shields.io/npm/dm/carrotmq.svg?style=flat-square)](https://www.npmjs.com/package/carrotmq)
[![Dependencies](https://img.shields.io/david/bangbang93/carrotmq.svg?style=flat-square)](https://david-dm.org/bangbang93/carrotmq)
[![NPM](https://nodei.co/npm/carrotmq.png?downloads=true&downloadRank=true)](https://nodei.co/npm/carrotmq/)


## APIDOC

[documentation](https://bangbang93.github.io/carrotmq)

## usage
```typescript
const {CarrotMQ} = require('carrotmq');

const mq = new CarrotMQ('amqp://localhost');
await mq.connect()

const publisher = new CarrotMQ('amqp://localhost'); //also can use without schema
await publisher.connect()

mq.queue('fooQueue', async (data, ctx) => {
    console.log(data);
    ctx.ack();
    //ctx.nack();
    //ctx.reject();
    //ctx.cancel(); cancel this consumer;
    ctx.reply({date: new Date}); //reply to message.properties.relyTo
    ctx.carrotmq //carrotmq instrance
    ctx.channel  //current channel
    return Promise.reject(); // or throw new Error('some thing happened') will execute `this.reject()` if this message hadn't been ack
});

mq.sendToQueue('queue', {msg: 'message'});
mq.publish('exchange', 'foo.bar.key', {msg: 'hello world!'});
```

## RPC
```javascript
mq.rpc('queue', {data: new Date})
.then((reply)=>{
  reply.ack();
  console.log(reply.data); //some reply result
});
```
If you prefer to use named queue rather than temp queue, you can set in config like 
```javascript
const mq = new CarrotMQ('amqp://localhost', {
  callbackQueue: {
    queue: 'carrotmq.rpc.callback'
  }
})
```
Or 
```javascript 
mq.rpc('carrotmq.rpc', {data: 'foo'}, 'carrotmq.rpc.callback') 
```

## RPC Over Exchange
```javascript

app.queue('rpcQueue', async (data, ctx) => {
  await ctx.reply(data);
  await ctx.ack();
});

let time = new Date();
app.rpcExchange('exchange0', 'rpc.rpc', {time})
.then(function (reply){
  reply.ack();
  console.log(reply.data)//{time: time}
}) // if target exchange is an topic or fanout exchange, only the first reply will be accepted.
```

## events
### ready
emit after connection established
```javascript
mq.on('ready', function(){});
```

### error
emit when something happened
```javascript
mq.on('error', function (err){});
```

### message
emit when message come
```javascript
mq.on('message', function (data){
  data.channel; //channel object
  data.queue   //queue name
  data.message  //message object
})
```

### close
emit when connection close
```js
mq.on('close', () => setTimeout(mq.connect(), 1000));
```

## upgrade
### V4 to V5

Because of rewritten in TypeScript, some export has changed
before:
```javascript
const CarrotMQ = require('carrotmq')
```
after:
```javascript
const {CarrotMQ} = require('carrotmq')
```
### V2 to V3
#### breaking change
  - mq.rpc() and mq.rpcExchange() method remove the 4th consumer argument.And using Promise
  
  used to
  ```js
    mq.rpc('someQueue', {data}, function(data) {
      const that = this;
      // or some data async logic
      doSomeThingAsync(data)
      .then(() => that.ack())
      .catch(() => that.nack());
      return data;
    }).then((data) => console.log(data));
```
now can replaced by
```js
    let reply = await mq.rpc('someQueue', {data});
    try {
      await doSomeThingAsync(reply.data);
      reply.ack();
    } catch (e) {
      reply.nack();
    }
```

---
_Source: https://npm.io/package/carrotmq · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._