@blokjs/trigger-worker 0.6.18 → 0.6.20

package/src/adapters/factory.ts

@@ -1,111 +0,0 @@
-/**
- * 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

@@ -1,130 +0,0 @@
-/**
- * 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

@@ -1,94 +0,0 @@
-/**
- * @blokjs/trigger-worker
- *
- * Worker-based trigger for Blok workflows.
- * Supports background job processing with:
- * - Configurable concurrency per queue
- * - Automatic retries with exponential backoff
- * - Job timeouts
- * - Priority-based job ordering
- * - Delayed job scheduling
- * - Queue statistics and monitoring
- *
- * 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
- * import { WorkerTrigger, BullMQAdapter } from "@blokjs/trigger-worker";
- *
- * class MyWorkerTrigger extends WorkerTrigger {
- *   protected adapter = new BullMQAdapter({
- *     host: "localhost",
- *     port: 6379,
- *   });
- *
- *   protected nodes = myNodes;
- *   protected workflows = myWorkflows;
- * }
- *
- * const trigger = new MyWorkerTrigger();
- * await trigger.listen();
- *
- * // Dispatch a job
- * await trigger.dispatch("background-jobs", { userId: "123" }, {
- *   priority: 10,
- *   retries: 3,
- *   delay: 5000, // delay 5 seconds
- * });
- * ```
- *
- * @example InMemory (development)
- * ```typescript
- * import { WorkerTrigger, InMemoryAdapter } from "@blokjs/trigger-worker";
- *
- * class DevWorkerTrigger extends WorkerTrigger {
- *   protected adapter = new InMemoryAdapter();
- *   protected nodes = myNodes;
- *   protected workflows = myWorkflows;
- * }
- * ```
- */
-
-// Core exports
-export {
-	WorkerTrigger,
-	type WorkerAdapter,
-	type WorkerJob,
-	type WorkerQueueStats,
-} from "./WorkerTrigger";
-
-// 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 { WorkerProvider, WorkerTriggerOpts } from "@blokjs/helper";

package/template/.env.example

@@ -1,13 +0,0 @@
-PROJECT_NAME=trigger-worker-server
-PROJECT_VERSION=0.0.1
-PORT=4008
-WORKFLOWS_PATH=PROJECT_PATH/workflows
-NODES_PATH=PROJECT_PATH/src/nodes
-CONSOLE_LOG_ACTIVE=true
-APP_NAME=blok-worker
-DISABLE_TRIGGER_RUN=false # Set to true to disable trigger run and use this project as a module
-
-# NATS JetStream Configuration
-NATS_SERVERS=localhost:4222
-NATS_STREAM_NAME=blok-worker
-# NATS_TOKEN=your-auth-token

package/template/package.json

@@ -1,45 +0,0 @@
-{
-	"name": "blok-worker-trigger",
-	"version": "0.1.0",
-	"description": "Worker trigger for Blok background job workflows",
-	"type": "module",
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"author": "",
-	"license": "MIT",
-	"scripts": {
-		"dev": "bun --watch run src/index.ts",
-		"start": "bun run dist/index.js",
-		"build": "rimraf ./dist && tsc",
-		"test": "vitest run",
-		"test:dev": "vitest"
-	},
-	"devDependencies": {
-		"@types/node": "^22.15.21",
-		"@types/uuid": "^11.0.0",
-		"rimraf": "^6.1.2",
-		"typescript": "^5.8.3",
-		"vitest": "^4.0.18"
-	},
-	"dependencies": {
-		"@blokjs/api-call": "^0.6.18",
-		"@blokjs/helper": "^0.6.18",
-		"@blokjs/if-else": "^0.6.18",
-		"@blokjs/runner": "^0.6.18",
-		"@blokjs/shared": "^0.6.18",
-		"@blokjs/trigger-worker": "^0.6.18",
-		"@opentelemetry/api": "^1.9.0",
-		"@opentelemetry/exporter-prometheus": "^0.57.2",
-		"@opentelemetry/resources": "^1.30.1",
-		"@opentelemetry/sdk-metrics": "^1.30.1",
-		"@opentelemetry/sdk-trace-base": "^1.30.1",
-		"@opentelemetry/semantic-conventions": "^1.39.0",
-		"nats": "^2.28.0",
-		"uuid": "^11.1.0",
-		"zod": "^3.24.2"
-	},
-	"private": true
-}

package/template/src/Nodes.ts

@@ -1,10 +0,0 @@
-import ApiCall from "@blokjs/api-call";
-import IfElse from "@blokjs/if-else";
-import type { BlokService } from "@blokjs/runner";
-
-const nodes: Record<string, BlokService<unknown>> = {
-	"@blokjs/api-call": ApiCall,
-	"@blokjs/if-else": IfElse,
-};
-
-export default nodes;

package/template/src/Workflows.ts

@@ -1,8 +0,0 @@
-import type Workflows from "./runner/types/Workflows";
-import processJob from "./workflows/jobs/process-job";
-
-const workflows: Workflows = {
-	"process-job": processJob,
-};
-
-export default workflows;

package/template/src/index.ts

@@ -1,41 +0,0 @@
-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/runner/WorkerServer.ts

@@ -1,34 +0,0 @@
-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;
-}

package/template/src/runner/types/Workflows.ts

@@ -1,7 +0,0 @@
-import type { HelperResponse } from "@blokjs/helper";
-
-type Workflows = {
-	[key: string]: HelperResponse;
-};
-
-export default Workflows;

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

@@ -1,47 +0,0 @@
-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: "js/ctx.request.params.attempt",
-				},
-			},
-		},
-	],
-});

package/template/tsconfig.json

@@ -1,31 +0,0 @@
-{
-	"ts-node": {
-		"transpileOnly": true
-	},
-	"compilerOptions": {
-		"target": "ES2022",
-		"module": "es2022",
-		"moduleResolution": "bundler",
-		"rootDir": "./src",
-		"baseUrl": ".",
-		"paths": {
-			"@nodes/*": ["./src/nodes/*"],
-			"@src/*": ["src/*"]
-		},
-		"allowJs": true,
-		"declaration": true,
-		"declarationMap": true,
-		"sourceMap": true,
-		"outDir": "./dist",
-		"esModuleInterop": true,
-		"forceConsistentCasingInFileNames": true,
-		"strict": true,
-		"noUnusedLocals": true,
-		"noImplicitReturns": true,
-		"skipLibCheck": true,
-		"resolveJsonModule": true
-	},
-	"compileOnSave": true,
-	"include": ["./src", "./src/nodes/**/*.json", "./src/nodes/**/*.md"],
-	"exclude": ["src/nodes/**/test/*.ts", "**/*.test.ts", "node_modules", "dist"]
-}

package/template/vitest.config.ts

@@ -1,39 +0,0 @@
-import path from "node:path";
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-	test: {
-		globals: true,
-		environment: "node",
-		coverage: {
-			provider: "istanbul",
-			reporter: ["text", "json", "html", "lcov"],
-			exclude: [
-				"node_modules/",
-				"dist/",
-				"**/*.d.ts",
-				"**/*.config.ts",
-				"__tests__/",
-				"src/nodes/",
-				"src/workflows/",
-				"src/runner/types/",
-				"src/runner/metrics/",
-			],
-			thresholds: {
-				lines: 90,
-				functions: 90,
-				branches: 85,
-				statements: 90,
-			},
-		},
-		include: ["__tests__/**/*.test.ts"],
-		exclude: ["node_modules", "dist"],
-		testTimeout: 10000,
-		hookTimeout: 10000,
-	},
-	resolve: {
-		alias: {
-			"@": path.resolve(__dirname, "./src"),
-		},
-	},
-});

package/tsconfig.json

@@ -1,32 +0,0 @@
-{
-	"ts-node": {
-		"transpileOnly": true
-	},
-	"compilerOptions": {
-		"target": "ES2022",
-		"module": "es2022",
-		"lib": ["ES2022"],
-		"declaration": true,
-		"strict": true,
-		"noImplicitAny": true,
-		"strictNullChecks": true,
-		"noImplicitThis": true,
-		"alwaysStrict": true,
-		"noUnusedLocals": false,
-		"noUnusedParameters": false,
-		"noImplicitReturns": true,
-		"noFallthroughCasesInSwitch": false,
-		"inlineSourceMap": true,
-		"inlineSources": true,
-		"experimentalDecorators": true,
-		"emitDecoratorMetadata": true,
-		"skipLibCheck": true,
-		"esModuleInterop": true,
-		"resolveJsonModule": true,
-		"outDir": "./dist",
-		"rootDir": "./src",
-		"moduleResolution": "bundler"
-	},
-	"include": ["src/**/*"],
-	"exclude": ["node_modules", "dist", "**/*.test.ts"]
-}