Overview

@hanzo/mq is a message queue and job processing library for Node.js, built to work with Hanzo KV, Valkey, and Redis. It's part of the Hanzo AI infrastructure ecosystem.

This package is based on BullMQ and maintains full API compatibility.

Installation

npm install @hanzo/mq

Quick Start

Add jobs to the queue:

import { Queue } from '@hanzo/mq';

const queue = new Queue('Paint');

queue.add('cars', { color: 'blue' });

Process jobs with workers:

import { Worker } from '@hanzo/mq';

const worker = new Worker('Paint', async job => {
  if (job.name === 'cars') {
    await paintCar(job.data.color);
  }
});

Listen for job completion:

import { QueueEvents } from '@hanzo/mq';

const queueEvents = new QueueEvents('Paint');

queueEvents.on('completed', ({ jobId }) => {
  console.log('done painting');
});

queueEvents.on(
  'failed',
  ({ jobId, failedReason }: { jobId: string; failedReason: string }) => {
    console.error('error painting', failedReason);
  },
);

Parent-Child Job Dependencies

import { FlowProducer } from '@hanzo/mq';

const flow = new FlowProducer();

const originalTree = await flow.add({
  name: 'root-job',
  queueName: 'topQueueName',
  data: {},
  children: [
    {
      name: 'child-job',
      data: { idx: 0, foo: 'bar' },
      queueName: 'childrenQueueName',
      children: [
        {
          name: 'grandchild-job',
          data: { idx: 1, foo: 'bah' },
          queueName: 'grandChildrenQueueName',
        },
        {
          name: 'grandchild-job',
          data: { idx: 2, foo: 'baz' },
          queueName: 'grandChildrenQueueName',
        },
      ],
    },
    {
      name: 'child-job',
      data: { idx: 3, foo: 'foo' },
      queueName: 'childrenQueueName',
    },
  ],
});

Features

| Feature | @hanzo/mq | | :------------------------- | :-------: | | Backend | Hanzo KV / Valkey / Redis | | Parent/Child Dependencies | ✓ | | Deduplication (Debouncing) | ✓ | | Deduplication (Throttling) | ✓ | | Priorities | ✓ | | Concurrency | ✓ | | Delayed jobs | ✓ | | Global events | ✓ | | Rate Limiter | ✓ | | Pause/Resume | ✓ | | Sandboxed worker | ✓ | | Repeatable jobs | ✓ | | Atomic ops | ✓ | | Persistence | ✓ | | UI | ✓ |

Connection Options

@hanzo/mq connects to Hanzo KV, Valkey, or Redis:

import { Queue } from '@hanzo/mq';

// Default connection (localhost:6379)
const queue = new Queue('myqueue');

// Custom connection
const queue = new Queue('myqueue', {
  connection: {
    host: 'hanzo-kv.example.com',
    port: 6379,
    password: 'your-password',
  },
});

Hanzo Ecosystem

@hanzo/mq is part of the Hanzo AI infrastructure:

• Hanzo KV - High-performance key-value server (Valkey fork)
• @hanzo/kv-client - Node.js client for Hanzo KV
• Hanzo Auto - Workflow automation platform
• Hanzo Flow - Visual AI/LLM workflow builder

Documentation

For detailed documentation, see the BullMQ documentation as @hanzo/mq maintains API compatibility.

Contributing

Fork the repo, make some changes, submit a pull-request!

License

MIT

Credits

This package is based on BullMQ by Taskforce.sh.