Skip to main content

async

@webda/async

Durable asynchronous job orchestration for Webda — queue a service method call, track its status, and optionally schedule it for later execution.

When to use it​

  • You need to offload long-running work (report generation, data imports) to a background worker without blocking the HTTP response.
  • You want to schedule a recurring or time-delayed operation (cron-based or timestamp-based).
  • You need a persistent audit trail of job executions with status, logs, and results stored in a Webda Store.

Install​

pnpm add @webda/async

Configuration​

{
  "services": {
    "AsyncActionsQueue": {
      "type": "MemoryQueue"
    },
    "asyncJobService": {
      "type": "AsyncJobService",
      "queue": "AsyncActionsQueue",
      "url": "/async",
      "runners": ["serviceRunner"],
      "includeCron": true,
      "logsLimit": 500
    },
    "serviceRunner": {
      "type": "ServiceRunner"
    }
  }
}
ParameterTypeDefaultRequiredDescription
queuestring"AsyncActionsQueue"YesName of the Queue service to dispatch jobs through
urlstring"/async"NoURL prefix for the status hook endpoint
runnersstring[][]YesList of Runner service names to execute jobs
localLaunchbooleanfalseNoExecute jobs inline (no queue) — useful for development
fallbackOnFirstbooleanfalseNoUse first runner if no runner matches the job type
concurrencyLimitnumber—NoMaximum number of jobs running concurrently
includeCronbooleantrueNoAuto-schedule @Cron-annotated methods as async actions
logsLimitnumber500NoMax log lines retained per job in the store
asyncOperationDefinitionstring—NoPath to a JSON file of operation definitions generated by webda operations
schedulerResolutionnumber60000NoScheduler tick interval in milliseconds

Usage​

import { Service } from "@webda/core";
import { Bean, Inject } from "@webda/core";
import AsyncJobService from "@webda/async/services/asyncjobservice";

@Bean
export class ReportService extends Service {
  @Inject("asyncJobService")
  asyncJobService: AsyncJobService;

  // Expose an HTTP endpoint that queues a job and returns immediately
  async generateReport(ctx: any): Promise<void> {
    const action = await this.asyncJobService.launchAsAsyncAction(
      "ReportService",   // service name
      "runReport",       // method name
      ctx.getParameters().reportId
    );
    ctx.write({ jobId: action.getUuid(), status: action.status });
  }

  // This method runs inside the worker process
  async runReport(reportId: string): Promise<void> {
    // ... long-running work here
  }
}

// Start the worker (typically in a separate process)
// asyncJobService.worker().then(() => console.log("worker stopped"));

Reference​

CoreServices​

Other​