@blokjs/trigger-worker 0.4.0 → 0.6.2

package/src/adapters/factory.ts

@@ -0,0 +1,111 @@
+/**
+ * v0.7 PR 5 — adapter factory.
+ *
+ * Resolves a `provider` string to a concrete `WorkerAdapter` instance.
+ * Used by the `WorkerTrigger` (to pick the right adapter per workflow
+ * based on `trigger.worker.provider`) and by the `@blokjs/worker-publish`
+ * helper node (to enqueue jobs from any workflow without bundling all
+ * broker clients).
+ *
+ * Provider resolution order:
+ *   1. Explicit `provider` field on the workflow (highest priority).
+ *   2. `BLOK_WORKER_ADAPTER` env var (per Q7 resolution in the plan).
+ *   3. `"in-memory"` fallback (zero-infra default for dev/tests).
+ *
+ * Each adapter beyond `in-memory` lazy-imports its broker SDK on first
+ * use (BullMQ does this today). Workflows that don't use a given
+ * provider don't pay the install or import cost.
+ */
+
+import type { WorkerProvider } from "@blokjs/helper";
+import type { WorkerAdapter } from "../WorkerTrigger";
+import { BullMQAdapter } from "./BullMQAdapter";
+import { InMemoryAdapter } from "./InMemoryAdapter";
+import { KafkaAdapter } from "./KafkaAdapter";
+import { NATSWorkerAdapter } from "./NATSAdapter";
+import { PgBossAdapter } from "./PgBossAdapter";
+import { RabbitMQAdapter } from "./RabbitMQAdapter";
+import { RedisStreamsAdapter } from "./RedisStreamsAdapter";
+import { SQSAdapter } from "./SQSAdapter";
+
+/**
+ * Resolve the effective provider for a workflow. The trigger's
+ * `provider` field always wins; otherwise fall back to the
+ * `BLOK_WORKER_ADAPTER` env var; otherwise `"in-memory"`.
+ */
+export function resolveProvider(provider?: WorkerProvider): WorkerProvider {
+	if (provider) return provider;
+	const envValue = process.env.BLOK_WORKER_ADAPTER;
+	if (envValue && isWorkerProvider(envValue)) return envValue;
+	return "in-memory";
+}
+
+function isWorkerProvider(value: string): value is WorkerProvider {
+	return (
+		value === "in-memory" ||
+		value === "nats" ||
+		value === "bullmq" ||
+		value === "kafka" ||
+		value === "rabbitmq" ||
+		value === "sqs" ||
+		value === "redis" ||
+		value === "pg-boss"
+	);
+}
+
+/**
+ * Construct an adapter for the named provider. Throws a clear error
+ * for unknown names — keeps the schema validation and runtime
+ * behaviour in sync (the Zod enum catches typos at workflow load).
+ */
+export function createWorkerAdapter(provider: WorkerProvider): WorkerAdapter {
+	switch (provider) {
+		case "in-memory":
+			return new InMemoryAdapter();
+		case "nats":
+			return new NATSWorkerAdapter();
+		case "bullmq":
+			return new BullMQAdapter();
+		case "kafka":
+			return new KafkaAdapter();
+		case "rabbitmq":
+			return new RabbitMQAdapter();
+		case "sqs":
+			return new SQSAdapter();
+		case "redis":
+			return new RedisStreamsAdapter();
+		case "pg-boss":
+			return new PgBossAdapter();
+		default: {
+			const exhaustive: never = provider;
+			throw new Error(`[blok][worker] unknown provider "${exhaustive as string}". Check WorkerProviderSchema.`);
+		}
+	}
+}
+
+/**
+ * Process-singleton adapter pool — one instance per provider. The
+ * trigger calls `getOrCreateAdapter("kafka")` once per workflow, and
+ * subsequent workflows on the same provider share the broker
+ * connection. Adapters are connected lazily — `getOrCreateAdapter`
+ * never connects on its own; the caller calls `adapter.connect()`.
+ *
+ * Reset via `_resetAdapterPoolForTests()` between vitest suites.
+ */
+const pool: Map<WorkerProvider, WorkerAdapter> = new Map();
+
+export function getOrCreateAdapter(provider: WorkerProvider): WorkerAdapter {
+	let adapter = pool.get(provider);
+	if (!adapter) {
+		adapter = createWorkerAdapter(provider);
+		pool.set(provider, adapter);
+	}
+	return adapter;
+}
+
+export function _resetAdapterPoolForTests(): void {
+	for (const adapter of pool.values()) {
+		void adapter.disconnect?.().catch(() => {});
+	}
+	pool.clear();
+}

package/src/adapters/new-adapters.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Smoke tests for the v0.7 PR 5 adapters (Kafka, RabbitMQ, SQS, Redis
+ * Streams, pg-boss). Each adapter is exercised at the boundaries
+ * that don't require a live broker connection:
+ *
+ *   - Constructor + provider name + initial connected state.
+ *   - `disconnect()` is a no-op before connect.
+ *
+ * The peer-dep error paths and the broker round-trips need real
+ * brokers — those live in the docker-compose integration suite that
+ * we'll wire up as a follow-up (see PR 5 plan, "Out of scope:
+ * docker-compose CI").
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { KafkaAdapter } from "./KafkaAdapter";
+import { PgBossAdapter } from "./PgBossAdapter";
+import { RabbitMQAdapter } from "./RabbitMQAdapter";
+import { RedisStreamsAdapter } from "./RedisStreamsAdapter";
+import { SQSAdapter } from "./SQSAdapter";
+
+describe("KafkaAdapter — v0.7 PR 5", () => {
+	it("reports provider 'kafka'", () => {
+		expect(new KafkaAdapter().provider).toBe("kafka");
+	});
+
+	it("is not connected before connect()", () => {
+		expect(new KafkaAdapter().isConnected()).toBe(false);
+	});
+
+	it("disconnect() before connect is a no-op", async () => {
+		await expect(new KafkaAdapter().disconnect()).resolves.toBeUndefined();
+	});
+
+	it("reads broker list from KAFKA_BROKERS env var", () => {
+		process.env.KAFKA_BROKERS = "broker-a:9092,broker-b:9092";
+		const adapter = new KafkaAdapter();
+		expect((adapter as unknown as { config: { brokers: string[] } }).config.brokers).toEqual([
+			"broker-a:9092",
+			"broker-b:9092",
+		]);
+		process.env.KAFKA_BROKERS = undefined;
+	});
+});
+
+describe("RabbitMQAdapter — v0.7 PR 5", () => {
+	it("reports provider 'rabbitmq'", () => {
+		expect(new RabbitMQAdapter().provider).toBe("rabbitmq");
+	});
+
+	it("is not connected before connect()", () => {
+		expect(new RabbitMQAdapter().isConnected()).toBe(false);
+	});
+
+	it("disconnect() before connect is a no-op", async () => {
+		await expect(new RabbitMQAdapter().disconnect()).resolves.toBeUndefined();
+	});
+
+	it("reads AMQP_URL from env var", () => {
+		process.env.AMQP_URL = "amqp://prod.example:5672";
+		const adapter = new RabbitMQAdapter();
+		expect((adapter as unknown as { config: { url: string } }).config.url).toBe("amqp://prod.example:5672");
+		process.env.AMQP_URL = undefined;
+	});
+});
+
+describe("SQSAdapter — v0.7 PR 5", () => {
+	it("reports provider 'sqs'", () => {
+		expect(new SQSAdapter().provider).toBe("sqs");
+	});
+
+	it("is not connected before connect()", () => {
+		expect(new SQSAdapter().isConnected()).toBe(false);
+	});
+
+	it("disconnect() before connect is a no-op", async () => {
+		await expect(new SQSAdapter().disconnect()).resolves.toBeUndefined();
+	});
+
+	it("honors the explicit region override", () => {
+		const adapter = new SQSAdapter({ region: "eu-west-2" });
+		expect((adapter as unknown as { config: { region: string } }).config.region).toBe("eu-west-2");
+	});
+});
+
+describe("RedisStreamsAdapter — v0.7 PR 5", () => {
+	it("reports provider 'redis'", () => {
+		expect(new RedisStreamsAdapter().provider).toBe("redis");
+	});
+
+	it("is not connected before connect()", () => {
+		expect(new RedisStreamsAdapter().isConnected()).toBe(false);
+	});
+
+	it("disconnect() before connect is a no-op", async () => {
+		await expect(new RedisStreamsAdapter().disconnect()).resolves.toBeUndefined();
+	});
+
+	it("generates a unique consumer name per instance", () => {
+		const a = new RedisStreamsAdapter();
+		const b = new RedisStreamsAdapter();
+		expect((a as unknown as { consumerName: string }).consumerName).not.toBe(
+			(b as unknown as { consumerName: string }).consumerName,
+		);
+	});
+});
+
+describe("PgBossAdapter — v0.7 PR 5", () => {
+	it("reports provider 'pg-boss'", () => {
+		expect(new PgBossAdapter().provider).toBe("pg-boss");
+	});
+
+	it("is not connected before connect()", () => {
+		expect(new PgBossAdapter().isConnected()).toBe(false);
+	});
+
+	it("disconnect() before connect is a no-op", async () => {
+		await expect(new PgBossAdapter().disconnect()).resolves.toBeUndefined();
+	});
+
+	it("connect() throws a clear peer-dep error when pg-boss is absent", async () => {
+		// pg-boss is the only adapter SDK NOT pre-installed in this monorepo,
+		// so the lazy-import path actually throws here. The other adapters'
+		// SDKs ARE installed (other workspaces use them) — their peer-dep
+		// error paths get exercised in the docker-compose integration suite.
+		const adapter = new PgBossAdapter();
+		await expect(adapter.connect()).rejects.toThrow(/pg-boss/);
+	});
+});

package/src/index.ts

@@ -10,9 +10,20 @@
  * - Delayed job scheduling
  * - Queue statistics and monitoring
  *
- * Adapters:
- * - BullMQ (Redis-backed, production)
- * - InMemory (development/testing)
+ * Adapters (v0.7+):
+ * - BullMQ        — Redis-backed, ops-style queues (`bullmq` peer dep)
+ * - InMemory      — development / tests (no peer deps)
+ * - NATS          — JetStream durable streams (`nats` peer dep)
+ * - Kafka         — high-throughput streaming (`kafkajs` peer dep)
+ * - RabbitMQ      — reliable enterprise queues (`amqplib` peer dep)
+ * - SQS           — AWS cloud queues (`@aws-sdk/client-sqs` peer dep)
+ * - Redis Streams — when Redis is already in stack (`ioredis` peer dep)
+ * - pg-boss       — no extra infra (`pg-boss` peer dep)
+ *
+ * v0.7+ — pick the adapter per workflow via `trigger.worker.provider`.
+ * `BLOK_WORKER_ADAPTER` env var sets the default. Subclasses can still
+ * set `protected adapter` directly for back-compat with the pre-v0.7
+ * single-adapter pattern.
  *
  * @example BullMQ
  * ```typescript
@@ -62,7 +73,22 @@ export {
 // Adapters
 export { BullMQAdapter, type BullMQConfig } from "./adapters/BullMQAdapter";
 export { InMemoryAdapter } from "./adapters/InMemoryAdapter";
+export { KafkaAdapter, type KafkaConfig } from "./adapters/KafkaAdapter";
 export { NATSWorkerAdapter, type NATSWorkerConfig } from "./adapters/NATSAdapter";
+export { PgBossAdapter, type PgBossConfig } from "./adapters/PgBossAdapter";
+export { RabbitMQAdapter, type RabbitMQConfig } from "./adapters/RabbitMQAdapter";
+export { RedisStreamsAdapter, type RedisStreamsConfig } from "./adapters/RedisStreamsAdapter";
+export { SQSAdapter, type SQSConfig } from "./adapters/SQSAdapter";
+
+// v0.7 PR 5 — factory + pool. Used by WorkerTrigger and exposed for
+// helper nodes (`@blokjs/worker-publish`) that need to enqueue jobs
+// from any workflow without bundling all broker SDKs.
+export {
+	_resetAdapterPoolForTests,
+	createWorkerAdapter,
+	getOrCreateAdapter,
+	resolveProvider,
+} from "./adapters/factory";
 
 // Re-export types from helper for convenience
-export type { WorkerTriggerOpts } from "@blokjs/helper";
+export type { WorkerProvider, WorkerTriggerOpts } from "@blokjs/helper";

package/template/package.json

@@ -25,12 +25,12 @@
 		"vitest": "^4.0.18"
 	},
 	"dependencies": {
-		"@blokjs/api-call": "^0.4.0",
-		"@blokjs/helper": "^0.4.0",
-		"@blokjs/if-else": "^0.4.0",
-		"@blokjs/runner": "^0.4.0",
-		"@blokjs/shared": "^0.4.0",
-		"@blokjs/trigger-worker": "^0.4.0",
+		"@blokjs/api-call": "^0.6.2",
+		"@blokjs/helper": "^0.6.2",
+		"@blokjs/if-else": "^0.6.2",
+		"@blokjs/runner": "^0.6.2",
+		"@blokjs/shared": "^0.6.2",
+		"@blokjs/trigger-worker": "^0.6.2",
 		"@opentelemetry/api": "^1.9.0",
 		"@opentelemetry/exporter-prometheus": "^0.57.2",
 		"@opentelemetry/resources": "^1.30.1",

package/template/src/workflows/jobs/process-job.ts

@@ -1,45 +1,47 @@
-import { type Step, Workflow } from "@blokjs/helper";
+import { workflow } from "@blokjs/helper";
 
 /**
- * Example Worker workflow - triggered when a job is received from the queue
+ * Example Worker workflow — fires when a job is received from the queue.
  *
- * The job data is available in ctx.request:
- * - ctx.request.body: The job payload
- * - ctx.request.headers: Job headers/metadata
- * - ctx.request.params.queue: The queue name
- * - ctx.request.params.jobId: Unique job ID
- * - ctx.request.params.attempt: Current attempt number (0-based)
+ * 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
  *
- * Additional metadata is available in ctx.vars._worker_job:
- * - id: Unique job ID
- * - queue: Queue name
- * - attempts: Current attempt number
- * - maxRetries: Maximum retry count
- * - priority: Job priority (if set)
- * - createdAt: When the job was created (ISO string)
+ * 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
  */
-const step: Step = Workflow({
+export default workflow({
 	name: "Process Background Job",
 	version: "1.0.0",
 	description: "Handles incoming worker jobs from the queue",
-})
-	.addTrigger("worker", {
-		queue: "background-jobs",
-	})
-	.addStep({
-		name: "process-job",
-		node: "@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: "js/ctx.request.params.attempt",
+	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: "js/ctx.request.params.attempt",
+				},
 			},
 		},
-	});
-
-export default step;
+	],
+});