@blokjs/trigger-worker

--- package/template/src/index.ts (excerpt) ---
import { DefaultLogger } from "@blokjs/runner";
import { type Span, metrics, trace } from "@opentelemetry/api";
import WorkerServer from "./runner/WorkerServer";

export default class App {
	private workerServer: WorkerServer = <WorkerServer>{};
	protected trigger_initializer = 0;
	protected initializer = 0;
	protected tracer = trace.getTracer(
		process.env.PROJECT_NAME || "trigger-worker-server",
		process.env.PROJECT_VERSION || "0.0.1",
	);
	private logger = new DefaultLogger();
	protected app_cold_start = metrics.getMeter("default").createGauge("initialization", {
		description: "Application cold start",
	});

	constructor() {
		this.initializer = performance.now();
		this.workerServer = new WorkerServer();
	}

	async run() {
		this.tracer.startActiveSpan("initialization", async (span: Span) => {
			await this.workerServer.listen();
			this.initializer = performance.now() - this.initializer;

			this.logger.log(`Worker trigger initialized in ${this.initializer.toFixed(2)}ms`);
			this.app_cold_start.record(this.initializer, {
				pid: process.pid,
				env: process.env.NODE_ENV,
				app: process.env.APP_NAME,
			});
			span.end();
		});
	}
}

if (process.env.DISABLE_TRIGGER_RUN !== "true") {
	new App().run();
}


--- package/template/src/workflows/jobs/process-job.ts (excerpt) ---
import { workflow } from "@blokjs/helper";

/**
 * Example Worker workflow — fires when a job is received from the queue.
 *
 * The job payload + metadata land on ctx.request:
 *   - ctx.request.body                 — the job payload as posted
 *   - ctx.request.headers              — job headers
 *   - ctx.request.params.queue         — queue name
 *   - ctx.request.params.jobId         — unique job ID
 *   - ctx.request.params.attempt       — retry attempt (0-based)
 *   - ctx.vars._worker_job             — full job metadata
 *
 * v2 reliability knobs available on each step (uncomment to use):
 *   idempotencyKey: "$.req.params.jobId"    — skip re-runs of the same job
 *   retry: { maxAttempts: 3 }                — retry on transient failures
 *   maxDuration: "30s"                       — fail the step if it hangs
 *
 * Trigger-level reliability:
 *   concurrencyKey: "$.req.body.tenantId"    — per-tenant fairness
 *   onLimit: "queue"                          — defer instead of reject
 */
export default workflow({
	name: "Process Background Job",
	version: "1.0.0",
	description: "Handles incoming worker jobs from the queue",
	trigger: {
		worker: { queue: "background-jobs" },
	},
	steps: [
		{
			id: "process-job",
			use: "@blokjs/api-call",
			type: "module",
			inputs: {
				url: "https://httpbin.org/post",
				method: "POST",
				body: {
					job: "js/ctx.request.body",
					queue: "js/ctx.request.params.queue",
					jobId: "js/ctx.request.params.jobId",
					attempt: 

--- package/template/src/runner/WorkerServer.ts (excerpt) ---
import { NATSWorkerAdapter, WorkerTrigger } from "@blokjs/trigger-worker";
import nodes from "../Nodes";
import workflows from "../Workflows";

/**
 * WorkerServer - Concrete Worker trigger implementation using NATS JetStream
 *
 * This server extends the abstract WorkerTrigger and provides:
 * - NATS JetStream adapter for persistent job queues
 * - Node and workflow registries
 * - Configurable concurrency, retries, and timeouts
 *
 * Environment variables:
 * - NATS_SERVERS: Comma-separated NATS server URLs (default: localhost:4222)
 * - NATS_STREAM_NAME: JetStream stream name (default: blok-worker)
 * - NATS_TOKEN: Authentication token (optional)
 *
 * @example BullMQ (Redis) alternative
 * ```typescript
 * import { BullMQAdapter } from "@blokjs/trigger-worker";
 * protected adapter = new BullMQAdapter({
 *   host: process.env.REDIS_HOST || "localhost",
 *   port: Number(process.env.REDIS_PORT) || 6379,
 * });
 * ```
 */
export default class WorkerServer extends WorkerTrigger {
	protected adapter = new NATSWorkerAdapter({
		servers: (process.env.NATS_SERVERS || "localhost:4222").split(","),
	});

	protected nodes: Record<string, import("@blokjs/runner").BlokService<unknown>> = nodes;
	protected workflows: Record<string, import("@blokjs/helper").HelperResponse> = workflows;
}