Cron job

Quark ERP supports two cron styles: process-local @CronJob (in-process timer via the cron package) and distributed CronJobService (BullMQ + Redis + Postgres). Use BullMQ for shared / multi-instance schedules; use @CronJob for simple single-process ticks.

Two types

Pick the style that matches how the work must run.

Process cron (@CronJob) — in-process schedule started when the @Service is resolved; uses the Node cron package (timer in this process only)
BullMQ cron (CronJobService) — queue-backed schedule on Redis with metadata in Postgres (cron_jobs); retries, repeat limits, multi-instance safe

When to use which

BullMQ CronJobService — domain sweeps, reminders, reconciles, anything that must survive restart and stay correct with multiple app instances
Process @CronJob — lightweight housekeeping on a single process, or when you explicitly want an in-memory tick with no Redis
Do not use @quan-erp-plugins/cron-schedular-backend for new work — the same Redis APIs live in core as CronJobService

1. Process cron (@CronJob)

Mark a method on a DI-resolved @Service. When the class is resolved, the core starts a process-local CronJob from the expression. No DB row, no Redis queue, no retries — each process that loads the service ticks independently.

expression (required) — cron pattern, e.g. 0 * * * *
name (optional) — label for logs
Class must be @Service() (or otherwise DI-resolved) and registered on the module providers

TSX@CronJob

import { CronJob, Module, Service } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class LocalHousekeepingService {
  @CronJob({ expression: "0 * * * *", name: "HourlyLocalCleanup" })
  async cleanup() {
    // runs on this Node process only
  }
}

@Module({
  name: metadata.name,
  providers: [LocalHousekeepingService],
  controllers: [],
  entities: [],
})
export class MyPluginModule {}

2. BullMQ cron (CronJobService)

Jobs are enqueued through BullMQ on Redis. Schedule metadata is persisted in Postgres (cron_jobs). On boot, active schedules reload into Redis. Handlers run when the BullMQ worker fires — re-attach listeners every boot because callbacks are in-memory only.

Inject CronJobService

Inject the builtin core service with ContainerRegistryManager.BUILTIN_PLUGIN.

TSXinject

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  Service,
} from "@quan-erp/shared-backend-core";

@Service()
export class MaturedSweepService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;
}

Register a BullMQ job

Call register with a unique (pluginName, jobName) pair. Use metadata.name as pluginName. register upserts the DB row and (re)creates the Redis scheduler.

TSXregister

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class MaturedSweepService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;

  async registerJob() {
    await this.cronJobService.register({
      cronExpression: "0 2 * * *",
      pluginName: metadata.name,
      jobName: "matured-daily-sweep",
      status: "active",
      startDate: new Date(),
      data: { reason: "daily-sweep" },
      retry: { attempt: 3, delay: 5_000, type: "exponential" },
      callback: async (job) => {
        await this.runSweep(job.data);
      },
    });
  }

  private async runSweep(data: unknown) { /* … */ }
}

Re-attach listeners after restart

Schedules reload from Postgres into Redis on boot. Callbacks are not persisted — always re-register on @OnAllModuleLoaded (or pass callback again via register).

TSXlistener

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  OnAllModuleLoaded,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class MaturedSweepService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;

  @OnAllModuleLoaded()
  async onAllModuleLoaded() {
    this.cronJobService.addEventListener(
      metadata.name,
      "matured-daily-sweep",
      async (job) => { await this.runSweep(job.data); },
    );
  }

  private async runSweep(data: unknown) { /* … */ }
}

Stop / remove (BullMQ)

stop(pluginName, jobName) — pause scheduler + mark inactive
remove(pluginName, jobName) — delete Redis scheduler, DB row, and listeners
stopAllByPluginName / removeAllByPluginName — bulk helpers on uninstall

Query helpers

TSXquery

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class MaturedSweepService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;

  async listJobs() {
    const job = await this.cronJobService.getByPluginNameWithJobName(
      metadata.name,
      "matured-daily-sweep",
    );

    const jobs = await this.cronJobService.getByPluginName({
      pluginName: metadata.name,
      skip: 0,
      limit: 50,
      status: "active",
    });

    return { job, jobs };
  }
}

CreateCronJobDTO

cronExpression (required) — e.g. 0 2 * * *
pluginName / jobName (required) — key is `${pluginName}/${jobName}`
status — active | inactive
data — payload on BullMQ job.data
startDate — earliest start (initial delay)
repeat.limit — max executions
retry.attempt / delay / type (fixed | exponential)
callback — optional in-memory listener at register time

Recommended BullMQ pattern

01
Inject
CronJobService with ContainerRegistryManager.BUILTIN_PLUGIN.
02
Register on boot
On @OnAllModuleLoaded, register({ pluginName: metadata.name, jobName, cronExpression, … }).
03
Attach listener every boot
callback on register and/or addEventListener — schedules survive restart; handlers do not.
04
Cleanup
On uninstall / disable, stop or remove to avoid orphan Redis schedulers.

TSXend-to-end

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  OnAllModuleLoaded,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

const JOB_NAME = "inventory-nightly-reconcile";

@Service()
export class InventoryReconcileCronService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;

  @OnAllModuleLoaded()
  async onAllModuleLoaded() {
    await this.cronJobService.register({
      cronExpression: "0 3 * * *",
      pluginName: metadata.name,
      jobName: JOB_NAME,
      startDate: new Date(),
      callback: async () => { await this.reconcile(); },
    });
  }

  private async reconcile() { /* domain work */ }
}