@modern-admin/queue 0.1.0

package/dist/queue.module.js

@@ -0,0 +1,93 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var QueueModule_1;
+import { Module } from '@nestjs/common';
+import { BullModule } from '@nestjs/bullmq';
+/**
+ * BullMQ integration module for modern-admin NestJS applications.
+ *
+ * 1. Call `QueueModule.forRoot()` once in the root AppModule to configure the
+ *    Redis connection globally.
+ * 2. Call `QueueModule.register({ queues: [...] })` in any feature module to
+ *    register named queues and make their injection tokens available.
+ *
+ * @example
+ * // AppModule
+ * imports: [
+ *   QueueModule.forRoot({ connection: { host: 'localhost', port: 6379 } }),
+ *   QueueModule.register({ queues: ['emails', 'exports'] }),
+ *   CronModule,
+ * ]
+ */
+let QueueModule = QueueModule_1 = class QueueModule {
+    /**
+     * Configure the BullMQ Redis connection for the whole application.
+     * Must be imported once at the root level before any `register()` call.
+     */
+    static forRoot(options) {
+        return {
+            module: QueueModule_1,
+            global: true,
+            imports: [
+                BullModule.forRoot({
+                    connection: options.connection,
+                    defaultJobOptions: options.defaultJobOptions,
+                }),
+            ],
+        };
+    }
+    /**
+     * Async variant of `forRoot` — useful when the Redis URL comes from a
+     * config service or environment variable loaded at runtime.
+     *
+     * @example
+     * QueueModule.forRootAsync({
+     *   imports: [ConfigModule],
+     *   inject: [ConfigService],
+     *   useFactory: (cfg: ConfigService) => ({
+     *     connection: cfg.get('REDIS_URL'),
+     *   }),
+     * })
+     */
+    static forRootAsync(opts) {
+        return {
+            module: QueueModule_1,
+            global: true,
+            imports: [
+                BullModule.forRootAsync({
+                    imports: opts.imports,
+                    inject: opts.inject,
+                    useFactory: async (...args) => {
+                        const resolved = await opts.useFactory(...args);
+                        return {
+                            connection: resolved.connection,
+                            defaultJobOptions: resolved.defaultJobOptions,
+                        };
+                    },
+                }),
+            ],
+        };
+    }
+    /**
+     * Register named queues (and optional flow producers) in the current module.
+     * Exports the BullMQ tokens so they can be injected via `@InjectQueue(name)`.
+     */
+    static register(options) {
+        const queueModules = options.queues.map((name) => BullModule.registerQueue({ name }));
+        const flowModules = (options.flows ?? []).map((name) => BullModule.registerFlowProducer({ name }));
+        return {
+            module: QueueModule_1,
+            imports: [...queueModules, ...flowModules],
+            exports: [...queueModules, ...flowModules],
+        };
+    }
+};
+QueueModule = QueueModule_1 = __decorate([
+    Module({})
+], QueueModule);
+export { QueueModule };
+//# sourceMappingURL=queue.module.js.map

package/dist/queue.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.module.js","sourceRoot":"","sources":["../src/queue.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAsB,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAG3C;;;;;;;;;;;;;;;GAeG;AAEI,IAAM,WAAW,mBAAjB,MAAM,WAAW;IACtB;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,OAAyB;QACtC,OAAO;YACL,MAAM,EAAE,aAAW;YACnB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE;gBACP,UAAU,CAAC,OAAO,CAAC;oBACjB,UAAU,EAAE,OAAO,CAAC,UAAoB;oBACxC,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;iBAC7C,CAAC;aACH;SACF,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CAAC,IAInB;QACC,OAAO;YACL,MAAM,EAAE,aAAW;YACnB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE;gBACP,UAAU,CAAC,YAAY,CAAC;oBACtB,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,MAAM,EAAE,IAAI,CAAC,MAAiB;oBAC9B,UAAU,EAAE,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;wBACvC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAA;wBAC/C,OAAO;4BACL,UAAU,EAAE,QAAQ,CAAC,UAAoB;4BACzC,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;yBAC9C,CAAA;oBACH,CAAC;iBACF,CAAC;aACH;SACF,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,OAA2B;QACzC,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAC/C,UAAU,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC,CACnC,CAAA;QACD,MAAM,WAAW,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACrD,UAAU,CAAC,oBAAoB,CAAC,EAAE,IAAI,EAAE,CAAC,CAC1C,CAAA;QACD,OAAO;YACL,MAAM,EAAE,aAAW;YACnB,OAAO,EAAE,CAAC,GAAG,YAAY,EAAE,GAAG,WAAW,CAAC;YAC1C,OAAO,EAAE,CAAC,GAAG,YAAY,EAAE,GAAG,WAAW,CAAC;SAC3C,CAAA;IACH,CAAC;CACF,CAAA;AAxEY,WAAW;IADvB,MAAM,CAAC,EAAE,CAAC;GACE,WAAW,CAwEvB"}

package/dist/queue.types.d.ts

@@ -0,0 +1,20 @@
+import type { DefaultJobOptions } from 'bullmq';
+export interface QueueModuleOptions {
+    queues: string[];
+    flows?: string[];
+}
+export interface QueueRootOptions {
+    /**
+     * ioredis-compatible connection. Accepts a connection string
+     * (`redis://...`) or a plain options object.
+     */
+    connection: {
+        host?: string;
+        port?: number;
+        password?: string;
+        db?: number;
+    } | string;
+    /** Default job options applied to every queue in this process. */
+    defaultJobOptions?: DefaultJobOptions;
+}
+//# sourceMappingURL=queue.types.d.ts.map

package/dist/queue.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.types.d.ts","sourceRoot":"","sources":["../src/queue.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AAE/C,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,UAAU,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAA;IACrF,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CACtC"}

package/dist/queue.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=queue.types.js.map

package/dist/queue.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.types.js","sourceRoot":"","sources":["../src/queue.types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@modern-admin/queue",
+  "version": "0.1.0",
+  "description": "BullMQ-based queue + cron module for Modern Admin (NestJS).",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modern-admin/modern-admin.git",
+    "directory": "packages/queue"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "devDependencies": {
+    "@modern-admin/tsconfig": "0.1.0",
+    "@nestjs/bullmq": "^11.0.4",
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/core": "^11.1.19",
+    "@nestjs/testing": "^11.1.19",
+    "@types/bun": "^1.3.13",
+    "bullmq": "^5.77.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@nestjs/bullmq": "^11.0.4",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "bullmq": "^5.0.0"
+  }
+}

package/src/cron/cron-task.decorator.ts

@@ -0,0 +1,34 @@
+import { SetMetadata } from '@nestjs/common'
+import type { JobsOptions } from 'bullmq'
+
+export const CRON_TASK_META = 'MODERN_ADMIN_CRON_TASK_META'
+
+export interface CronTaskOptions {
+  /** Unique task name — used as the BullMQ job scheduler key. */
+  name: string
+  /** Cron expression, e.g. `"0 8 * * *"` for every day at 08:00 UTC. */
+  cron: string
+  /**
+   * When `true`, a distributed Redis lock is acquired before the handler runs.
+   * If the previous execution is still active, the new invocation is skipped.
+   */
+  skipIfRunning?: boolean
+  /** Extra BullMQ job options (excluding `repeat` which is controlled by `cron`). */
+  opts?: Omit<JobsOptions, 'repeat'>
+}
+
+/**
+ * Marks a service method as a BullMQ-backed cron task.
+ * The `CronService` discovers all decorated methods automatically on module init.
+ *
+ * @example
+ * @Injectable()
+ * export class ReportService {
+ *   @CronTask({ name: 'daily-report', cron: '0 8 * * *' })
+ *   async run(job: Job) {
+ *     // ...
+ *   }
+ * }
+ */
+export const CronTask = (options: CronTaskOptions): MethodDecorator =>
+  SetMetadata(CRON_TASK_META, options)

package/src/cron/cron.constants.ts

@@ -0,0 +1,4 @@
+export const CRON_QUEUE = 'ma:cron'
+export const DEFAULT_CRON_WORKER_CONCURRENCY = 4
+export const CRON_LOCK_PREFIX = 'ma:cron-lock:'
+export const DEFAULT_CRON_LOCK_TTL = 300

package/src/cron/cron.module.ts

@@ -0,0 +1,33 @@
+import { Global, Module } from '@nestjs/common'
+import { DiscoveryModule } from '@nestjs/core'
+import { QueueModule } from '../queue.module.js'
+import { CRON_QUEUE } from './cron.constants.js'
+import { CronService } from './cron.service.js'
+import { CronProcessor } from './cron.processor.js'
+
+/**
+ * Global module that enables BullMQ-backed cron scheduling.
+ *
+ * Provides:
+ * - `CronService` — register tasks imperatively or via `@CronTask` decorator
+ * - `CronProcessor` — BullMQ worker that dispatches jobs to their handlers
+ *
+ * Requires `QueueModule.forRoot()` to be imported in the root module.
+ *
+ * @example
+ * // AppModule
+ * imports: [
+ *   QueueModule.forRoot({ connection: { host: 'localhost', port: 6379 } }),
+ *   CronModule,
+ * ]
+ */
+@Global()
+@Module({
+  imports: [
+    DiscoveryModule,
+    QueueModule.register({ queues: [CRON_QUEUE] }),
+  ],
+  providers: [CronService, CronProcessor],
+  exports: [CronService],
+})
+export class CronModule {}

package/src/cron/cron.processor.ts

@@ -0,0 +1,86 @@
+import { InjectQueue, Processor, WorkerHost } from '@nestjs/bullmq'
+import { Logger } from '@nestjs/common'
+import type { Job, Queue } from 'bullmq'
+import {
+  CRON_LOCK_PREFIX,
+  CRON_QUEUE,
+  DEFAULT_CRON_LOCK_TTL,
+  DEFAULT_CRON_WORKER_CONCURRENCY,
+} from './cron.constants.js'
+import type { CronService } from './cron.service.js'
+
+@Processor(CRON_QUEUE, { concurrency: DEFAULT_CRON_WORKER_CONCURRENCY })
+export class CronProcessor extends WorkerHost {
+  private readonly logger = new Logger(CronProcessor.name)
+
+  constructor(
+    private readonly cronService: CronService,
+    @InjectQueue(CRON_QUEUE) private readonly cronQueue: Queue,
+  ) {
+    super()
+  }
+
+  async process(job: Job<unknown, unknown, string>): Promise<unknown> {
+    const handler = this.cronService.getHandler(job.name)
+    if (!handler) {
+      const msg = `No cron handler registered for "${job.name}"`
+      this.logger.error(msg)
+      throw new Error(msg)
+    }
+
+    return this.cronService.shouldSkipIfRunning(job.name)
+      ? this.processWithLock(job, handler)
+      : this.executeHandler(job, handler)
+  }
+
+  private async processWithLock(
+    job: Job<unknown, unknown, string>,
+    handler: (job: Job) => unknown,
+  ): Promise<unknown> {
+    const lockKey = `${CRON_LOCK_PREFIX}${job.name}`
+    const client = await this.cronQueue.client
+
+    // Atomic SET NX EX via the generic `runCommand` escape hatch on
+    // bullmq's `IRedisClient`. We can't use `client.set(..., { EX, NX })`
+    // because bullmq 5.77+ abstracted the client surface and dropped the
+    // `NX` option from `set`'s typed overloads (it now only accepts
+    // `{ PX?, EX? }`). `runCommand` is the documented portable way to
+    // reach any Redis command across ioredis / node-redis / bun-redis
+    // adapters. Returns the raw bulk-string reply ("OK") or nil.
+    const acquired = (await client.runCommand('set', [
+      lockKey,
+      job.id!,
+      'EX',
+      DEFAULT_CRON_LOCK_TTL,
+      'NX',
+    ])) as string | null
+    if (!acquired) {
+      this.logger.warn(
+        `Skipping "${job.name}" (jobId=${job.id}) — previous instance still running`,
+      )
+      return
+    }
+
+    try {
+      return await this.executeHandler(job, handler)
+    } finally {
+      await client.del(lockKey)
+    }
+  }
+
+  private async executeHandler(
+    job: Job<unknown, unknown, string>,
+    handler: (job: Job) => unknown,
+  ): Promise<unknown> {
+    const start = Date.now()
+    this.logger.log(`Cron task "${job.name}" started (jobId=${job.id})`)
+    try {
+      const result = await handler(job)
+      this.logger.log(`Cron task "${job.name}" completed in ${Date.now() - start}ms`)
+      return result
+    } catch (err: unknown) {
+      this.logger.error(`Cron task "${job.name}" failed after ${Date.now() - start}ms`, err)
+      throw err
+    }
+  }
+}

package/src/cron/cron.service.ts

@@ -0,0 +1,178 @@
+import {
+  Injectable,
+  Logger,
+  type OnModuleDestroy,
+  type OnModuleInit,
+} from '@nestjs/common'
+import { DiscoveryService, Reflector } from '@nestjs/core'
+import { InjectQueue } from '@nestjs/bullmq'
+import type { Job, Queue } from 'bullmq'
+import { CRON_QUEUE } from './cron.constants.js'
+import type { CronHandler, CronTaskDefinition } from './cron.types.js'
+import { CRON_TASK_META, type CronTaskOptions } from './cron-task.decorator.js'
+
+@Injectable()
+export class CronService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(CronService.name)
+  private readonly handlers = new Map<string, CronHandler>()
+  private readonly skipIfRunningSet = new Set<string>()
+  private readonly definitions: CronTaskDefinition[] = []
+  private initialized = false
+
+  constructor(
+    @InjectQueue(CRON_QUEUE) private readonly cronQueue: Queue,
+    private readonly discoveryService: DiscoveryService,
+    private readonly reflector: Reflector,
+  ) {}
+
+  /**
+   * Register a cron task imperatively.
+   * If called before `onModuleInit`, it is picked up by `syncSchedulers`.
+   * If called after `onModuleInit`, the scheduler is upserted in BullMQ immediately.
+   */
+  register<TData = unknown, TResult = unknown>(
+    definition: CronTaskDefinition<TData, TResult>,
+  ): void {
+    if (this.handlers.has(definition.name)) {
+      throw new Error(`Cron task "${definition.name}" is already registered`)
+    }
+    this.handlers.set(definition.name, definition.handler as CronHandler)
+    if (definition.skipIfRunning) this.skipIfRunningSet.add(definition.name)
+    this.definitions.push(definition as CronTaskDefinition)
+
+    if (this.initialized) {
+      void this.upsertScheduler(definition as CronTaskDefinition)
+    }
+  }
+
+  getHandler<TData = unknown, TResult = unknown>(
+    name: string,
+  ): CronHandler<TData, TResult> | undefined {
+    return this.handlers.get(name) as CronHandler<TData, TResult> | undefined
+  }
+
+  shouldSkipIfRunning(name: string): boolean {
+    return this.skipIfRunningSet.has(name)
+  }
+
+  async onModuleInit(): Promise<void> {
+    this.discoverCronTasks()
+    try {
+      await this.syncSchedulers()
+    } catch (err: unknown) {
+      this.logger.error('Failed to sync cron schedulers on init', err)
+    } finally {
+      this.initialized = true
+    }
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.cronQueue.close()
+  }
+
+  /**
+   * Remove specific cron tasks by name — deletes their schedulers and any
+   * waiting/delayed jobs from Redis.
+   */
+  async purgeTasks(names: string[]): Promise<void> {
+    const schedulers = await this.cronQueue.getJobSchedulers()
+    for (const s of schedulers) {
+      if (names.includes(s.name)) {
+        try {
+          await this.cronQueue.removeJobScheduler(s.key)
+          this.logger.log(`Purged scheduler: ${s.name}`)
+        } catch (err: unknown) {
+          this.logger.error(`Failed to purge scheduler ${s.name}`, err)
+        }
+      }
+    }
+
+    const jobs = (await this.cronQueue.getJobs(['waiting', 'delayed'])) as Job[]
+    for (const j of jobs) {
+      if (!j) continue
+      if (names.includes(j.name)) {
+        try {
+          await j.remove()
+          this.logger.log(`Purged job: ${j.name} (id=${j.id})`)
+        } catch (err: unknown) {
+          this.logger.error(`Failed to purge job ${j.name}`, err)
+        }
+      }
+    }
+  }
+
+  private discoverCronTasks(): void {
+    const providers = this.discoveryService.getProviders()
+    for (const wrapper of providers) {
+      const instance: unknown = wrapper.instance
+      if (!instance || typeof instance !== 'object') continue
+
+      const prototype = Object.getPrototypeOf(instance) as Record<string, unknown>
+      for (const key of Object.getOwnPropertyNames(prototype)) {
+        if (key === 'constructor') continue
+
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, key)
+        if (!descriptor || typeof descriptor.value !== 'function') continue
+
+        const meta = this.reflector.get<CronTaskOptions>(CRON_TASK_META, descriptor.value)
+        if (!meta) continue
+
+        const method = (instance as Record<string, unknown>)[key]
+        if (typeof method !== 'function') continue
+        this.register({
+          name: meta.name,
+          cron: meta.cron,
+          handler: (job) => method.call(instance, job),
+          skipIfRunning: meta.skipIfRunning,
+          opts: meta.opts,
+        })
+      }
+    }
+  }
+
+  /**
+   * Synchronise repeatable job schedulers in Redis with the current definitions.
+   * Removes stale schedulers no longer defined in code, then upserts all current ones.
+   */
+  private async syncSchedulers(): Promise<void> {
+    const registeredNames = new Set(this.definitions.map((d) => d.name))
+
+    const existing = await this.cronQueue.getJobSchedulers()
+    for (const scheduler of existing) {
+      if (!registeredNames.has(scheduler.name)) {
+        try {
+          await this.cronQueue.removeJobScheduler(scheduler.key)
+          this.logger.log(
+            `Removed stale cron scheduler: ${scheduler.name} (key=${scheduler.key})`,
+          )
+        } catch (err: unknown) {
+          this.logger.error(`Failed to remove stale scheduler ${scheduler.name}`, err)
+        }
+      }
+    }
+
+    for (const def of this.definitions) {
+      await this.upsertScheduler(def)
+    }
+  }
+
+  private async upsertScheduler(def: CronTaskDefinition): Promise<void> {
+    try {
+      await this.cronQueue.upsertJobScheduler(
+        def.name,
+        { pattern: def.cron },
+        {
+          name: def.name,
+          opts: {
+            removeOnComplete: { count: 100 },
+            removeOnFail: { count: 100 },
+            ...def.opts,
+          },
+        },
+      )
+      this.logger.log(`Cron task scheduled: "${def.name}" [${def.cron}]`)
+    } catch (err: unknown) {
+      this.logger.error(`Failed to schedule cron task "${def.name}"`, err)
+    }
+  }
+}

package/src/cron/cron.types.ts

@@ -0,0 +1,13 @@
+import type { Job, JobsOptions } from 'bullmq'
+
+export type CronHandler<TData = unknown, TResult = unknown> = (
+  job: Job<TData, TResult, string>,
+) => Promise<TResult> | TResult
+
+export interface CronTaskDefinition<TData = unknown, TResult = unknown> {
+  name: string
+  cron: string
+  handler: CronHandler<TData, TResult>
+  skipIfRunning?: boolean
+  opts?: Omit<JobsOptions, 'repeat'>
+}

package/src/cron/index.ts

@@ -0,0 +1,11 @@
+export { CronModule } from './cron.module.js'
+export { CronService } from './cron.service.js'
+export { CronProcessor } from './cron.processor.js'
+export { CronTask, CRON_TASK_META, type CronTaskOptions } from './cron-task.decorator.js'
+export type { CronHandler, CronTaskDefinition } from './cron.types.js'
+export {
+  CRON_QUEUE,
+  CRON_LOCK_PREFIX,
+  DEFAULT_CRON_WORKER_CONCURRENCY,
+  DEFAULT_CRON_LOCK_TTL,
+} from './cron.constants.js'

package/src/index.ts

@@ -0,0 +1,19 @@
+// @modern-admin/queue — BullMQ queue + cron scheduling for NestJS.
+
+export { QueueModule } from './queue.module.js'
+export type { QueueModuleOptions, QueueRootOptions } from './queue.types.js'
+
+export {
+  CronModule,
+  CronService,
+  CronProcessor,
+  CronTask,
+  CRON_TASK_META,
+  CRON_QUEUE,
+  CRON_LOCK_PREFIX,
+  DEFAULT_CRON_WORKER_CONCURRENCY,
+  DEFAULT_CRON_LOCK_TTL,
+  type CronTaskOptions,
+  type CronHandler,
+  type CronTaskDefinition,
+} from './cron'

package/src/queue.module.ts

@@ -0,0 +1,94 @@
+import { type DynamicModule, Module } from '@nestjs/common'
+import { BullModule } from '@nestjs/bullmq'
+import type { QueueModuleOptions, QueueRootOptions } from './queue.types.js'
+
+/**
+ * BullMQ integration module for modern-admin NestJS applications.
+ *
+ * 1. Call `QueueModule.forRoot()` once in the root AppModule to configure the
+ *    Redis connection globally.
+ * 2. Call `QueueModule.register({ queues: [...] })` in any feature module to
+ *    register named queues and make their injection tokens available.
+ *
+ * @example
+ * // AppModule
+ * imports: [
+ *   QueueModule.forRoot({ connection: { host: 'localhost', port: 6379 } }),
+ *   QueueModule.register({ queues: ['emails', 'exports'] }),
+ *   CronModule,
+ * ]
+ */
+@Module({})
+export class QueueModule {
+  /**
+   * Configure the BullMQ Redis connection for the whole application.
+   * Must be imported once at the root level before any `register()` call.
+   */
+  static forRoot(options: QueueRootOptions): DynamicModule {
+    return {
+      module: QueueModule,
+      global: true,
+      imports: [
+        BullModule.forRoot({
+          connection: options.connection as object,
+          defaultJobOptions: options.defaultJobOptions,
+        }),
+      ],
+    }
+  }
+
+  /**
+   * Async variant of `forRoot` — useful when the Redis URL comes from a
+   * config service or environment variable loaded at runtime.
+   *
+   * @example
+   * QueueModule.forRootAsync({
+   *   imports: [ConfigModule],
+   *   inject: [ConfigService],
+   *   useFactory: (cfg: ConfigService) => ({
+   *     connection: cfg.get('REDIS_URL'),
+   *   }),
+   * })
+   */
+  static forRootAsync(opts: {
+    imports?: DynamicModule['imports']
+    inject?: unknown[]
+    useFactory: (...args: unknown[]) => QueueRootOptions | Promise<QueueRootOptions>
+  }): DynamicModule {
+    return {
+      module: QueueModule,
+      global: true,
+      imports: [
+        BullModule.forRootAsync({
+          imports: opts.imports,
+          inject: opts.inject as never[],
+          useFactory: async (...args: unknown[]) => {
+            const resolved = await opts.useFactory(...args)
+            return {
+              connection: resolved.connection as object,
+              defaultJobOptions: resolved.defaultJobOptions,
+            }
+          },
+        }),
+      ],
+    }
+  }
+
+  /**
+   * Register named queues (and optional flow producers) in the current module.
+   * Exports the BullMQ tokens so they can be injected via `@InjectQueue(name)`.
+   */
+  static register(options: QueueModuleOptions): DynamicModule {
+    const queueModules = options.queues.map((name) =>
+      BullModule.registerQueue({ name }),
+    )
+    const flowModules = (options.flows ?? []).map((name) =>
+      BullModule.registerFlowProducer({ name }),
+    )
+    return {
+      module: QueueModule,
+      imports: [...queueModules, ...flowModules],
+      exports: [...queueModules, ...flowModules],
+    }
+  }
+}

package/src/queue.types.ts

@@ -0,0 +1,16 @@
+import type { DefaultJobOptions } from 'bullmq'
+
+export interface QueueModuleOptions {
+  queues: string[]
+  flows?: string[]
+}
+
+export interface QueueRootOptions {
+  /**
+   * ioredis-compatible connection. Accepts a connection string
+   * (`redis://...`) or a plain options object.
+   */
+  connection: { host?: string; port?: number; password?: string; db?: number } | string
+  /** Default job options applied to every queue in this process. */
+  defaultJobOptions?: DefaultJobOptions
+}