platform-queue

Provider-agnostic queue infrastructure for NestJS. Exposes a unified IQueue contract with four ready-made implementations: in-memory FIFO (MemoryQueue), BullMQ/Redis (BullMqQueue), Azure Service Bus (AzureQueue), and Vercel Queues (VercelQueue). Jobs follow a lifecycle from pending through processing to completed or failed, with full metadata tracking.

Package: @breadstone/archipel-platform-queue

npm install @breadstone/archipel-platform-queue

Architecture

graph TD
    Core["@breadstone/archipel-platform-queue<br/><i>IQueue, models, errors, MemoryQueue</i>"]
    BullMQ["@breadstone/archipel-platform-queue/bullmq<br/><i>BullMqQueue</i>"]
    Azure["@breadstone/archipel-platform-queue/azure<br/><i>AzureQueue</i>"]
    Vercel["@breadstone/archipel-platform-queue/vercel<br/><i>VercelQueue</i>"]

    BullMQ -->|implements| Core
    Azure -->|implements| Core
    Vercel -->|implements| Core

    BullMQ -.-|requires| R["bullmq"]
    Azure -.-|requires| S["@azure/service-bus"]
    Vercel -.-|requires| V["@vercel/queue"]

Each provider SDK is an optional peer dependency. Install only the one you need. MemoryQueue ships with the core entry point and requires no additional dependencies.

---

Quick Start

1. Install the provider SDK (optional)

# Pick one (or use MemoryQueue without any extra SDK):
yarn add bullmq
yarn add @azure/service-bus
yarn add @vercel/queue

2. Register the queue

import { Module } from '@nestjs/common';
import { IQueue, MemoryQueue } from '@breadstone/archipel-platform-queue';

@Module({
  providers: [
    {
      provide: 'IQueue',
      useFactory: () => new MemoryQueue({ maxJobs: 5_000 }),
    },
  ],
  exports: ['IQueue'],
})
export class AppModule {}

Switching providers

Replace the imports — no other code change needed:

import { BullMqQueue } from '@breadstone/archipel-platform-queue/bullmq';

{
  provide: 'IQueue',
  useFactory: () => new BullMqQueue({ redisUrl: 'redis://localhost:6379' }),
}

---

Queue Providers

Memory (built-in)

Entry point: @breadstone/archipel-platform-queue

Variable	Required	Default	Description
QUEUE_MAX_JOBS	No	10000	Maximum jobs retained before eviction

BullMQ

Subpath: @breadstone/archipel-platform-queue/bullmqSDK: bullmq ≥ 5.0.0

Variable	Required	Default	Description
BULLMQ_REDIS_URL	Yes	—	Redis connection URL (e.g. redis://localhost:6379)
BULLMQ_PREFIX	No	""	Optional key prefix for all BullMQ queues

import { BullMqQueue, BULLMQ_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/bullmq';

Azure Service Bus

Subpath: @breadstone/archipel-platform-queue/azureSDK: @azure/service-bus ≥ 7.0.0

Variable	Required	Default	Description
AZURE_CONNECTION_STRING	Yes	—	Azure Service Bus connection string
AZURE_RECEIVE_WAIT_MS	No	5000	Max wait time (ms) when receiving messages

import { AzureQueue, AZURE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/azure';

Vercel Queues

Subpath: @breadstone/archipel-platform-queue/vercelSDK: @vercel/queue ≥ 0.1.0

Variable	Required	Default	Description
VERCEL_QUEUE_REGION	Yes	—	Vercel region code (e.g. iad1, fra1, sfo1)
VERCEL_QUEUE_CONSUMER_GROUP	Yes	—	Consumer group name for receiving messages
VERCEL_QUEUE_TOKEN	No	—	OIDC bearer token (auto-fetched when omitted)
VERCEL_QUEUE_DEPLOYMENT_ID	No	—	Deployment ID for per-deployment message isolation
VERCEL_QUEUE_VISIBILITY_TIMEOUT_SECONDS	No	300	Visibility timeout in seconds for received messages

import { VercelQueue, VERCEL_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/vercel';

---

Job Lifecycle

Status	Description
pending	Job is waiting to be picked up
processing	Job has been dequeued and is being processed
completed	Job finished successfully via markCompleted()
failed	Job finished with an error via markFailed()

---

Error Handling

Error Class	Base Class	When Thrown
QueueError	Error	Base class for all queue errors
QueueJobNotFoundError	QueueError	Job ID does not exist
QueueJobStateError	QueueError	Job is in wrong state for requested transition
QueueValidationError	QueueError	Empty queue name or error message

---

Health Check

The QueueHealthIndicator reports the queue subsystem as available. Import it from the /health subpath:

import { QueueHealthIndicator } from '@breadstone/archipel-platform-queue/health';
import { HealthModule } from '@breadstone/archipel-platform-health';

@Module({
  imports: [
    QueueModule.register({ /* ... */ }),
    HealthModule.withIndicators([QueueHealthIndicator]),
  ],
})
export class AppModule {}

Key	Check	Dependencies
queue	Always reports up	None

---

Peer Dependencies

Package	Required	Notes
@nestjs/common	Yes	NestJS core
bullmq	Optional	Required for BullMQ provider
@azure/service-bus	Optional	Required for Azure Service Bus
@vercel/queue	Optional	Required for Vercel Queues