HiveGrid-Wireframes/hivegrid-cloud/packages/queue/README.md

@toolctrl/queue

BullMQ-oriented queue contracts and producer helpers for web/API enqueue paths and the opt-in worker runtime.

This package defines stable queue names, typed payloads, job descriptors, producer helpers and small BullMQ factory helpers. Processors live in apps/worker; queues only run when the worker is enabled and the related runtime flags/services are configured.

Queues

Queue	Purpose
toolctrl.email	Transactional email and webhook delivery jobs.
toolctrl.notifications	User notification delivery jobs.
toolctrl.maintenance	Background cleanup and retention jobs.
toolctrl.ai-chatbot	Contract for admin-managed AI chat completion jobs.
toolctrl.browser-automation	Contract for browser session run, cleanup and usage flush jobs.
toolctrl.file-scan	Storage file scan jobs.
toolctrl.exports	Export job execution.
toolctrl.imports	Import job execution.
toolctrl.plugin-invoke	Isolated third-party plugin invocation jobs.

AI/Browser Jobs

Stable job names:

• chat-completion
• browser-session-run
• browser-session-cleanup
• usage-flush
• scan-file
• run-export
• run-import

These are typed contracts and descriptors. Concrete processing is owned by apps/worker handlers and may still be disabled until the matching service flag or provider configuration is present.

Redis

Queue workers resolve Redis from BULLMQ_REDIS_URL first. REDIS_URL is fallback only when BULLMQ_REDIS_URL is absent, so new deployments should prefer the BullMQ-specific variable and keep generic platform Redis bindings optional.

Supported URL schemes:

• redis://localhost:6379/0
• rediss://user:password@example.redis:6379/0

Usage

import { createQueue, queueNames, resolveRedisConnectionOptions } from "@toolctrl/queue";

const emailQueue = createQueue(queueNames.email, {
  connection: resolveRedisConnectionOptions({ required: true }),
});

await emailQueue.add("send-email", {
  kind: "mail.transactional",
  recipientEmail: "user@example.com",
  templateId: "welcome",
});