@blokjs/trigger-pubsub 0.6.18 → 0.6.20

package/src/adapters/factory.ts

@@ -1,88 +0,0 @@
-/**
- * v0.7 PR 6 — pub/sub adapter factory.
- *
- * Resolves a `provider` string to a concrete `PubSubAdapter` instance.
- * Used by `PubSubTrigger` (per-workflow provider dispatch) and by the
- * `@blokjs/pubsub-publish` helper.
- *
- * Provider resolution order:
- *   1. Explicit `provider` field on the workflow.
- *   2. `BLOK_PUBSUB_ADAPTER` env var.
- *   3. `"nats"` fallback (cheapest infra; matches the v0.7 plan's
- *      "default for pub/sub" recommendation).
- *
- * Each adapter lazy-imports its broker SDK on first use; workflows
- * that don't use a given provider don't pay the install cost.
- */
-
-import type { PubSubProvider } from "@blokjs/helper";
-import type { PubSubAdapter } from "../PubSubTrigger";
-import { AWSSNSAdapter } from "./AWSSNSAdapter";
-import { AzureServiceBusAdapter } from "./AzureServiceBusAdapter";
-import { GCPPubSubAdapter } from "./GCPPubSubAdapter";
-import { KafkaPubSubAdapter } from "./KafkaPubSubAdapter";
-import { NATSPubSubAdapter } from "./NATSPubSubAdapter";
-import { RedisStreamsPubSubAdapter } from "./RedisStreamsPubSubAdapter";
-
-export function resolveProvider(provider?: PubSubProvider): PubSubProvider {
-	if (provider) return provider;
-	const envValue = process.env.BLOK_PUBSUB_ADAPTER;
-	if (envValue && isPubSubProvider(envValue)) return envValue;
-	return "nats";
-}
-
-function isPubSubProvider(value: string): value is PubSubProvider {
-	return (
-		value === "nats" ||
-		value === "redis-streams" ||
-		value === "kafka" ||
-		value === "gcp" ||
-		value === "aws" ||
-		value === "azure"
-	);
-}
-
-export function createPubSubAdapter(provider: PubSubProvider): PubSubAdapter {
-	switch (provider) {
-		case "nats":
-			return new NATSPubSubAdapter();
-		case "redis-streams":
-			return new RedisStreamsPubSubAdapter();
-		case "kafka":
-			return new KafkaPubSubAdapter();
-		case "gcp":
-			return new GCPPubSubAdapter();
-		case "aws":
-			return new AWSSNSAdapter();
-		case "azure":
-			return new AzureServiceBusAdapter();
-		default: {
-			const exhaustive: never = provider;
-			throw new Error(`[blok][pubsub] unknown provider "${exhaustive as string}". Check PubSubProviderSchema.`);
-		}
-	}
-}
-
-/**
- * Process-singleton adapter pool — one instance per provider. The
- * trigger calls `getOrCreateAdapter("nats")` once per workflow, and
- * subsequent workflows on the same provider share the broker
- * connection.
- */
-const pool: Map<PubSubProvider, PubSubAdapter> = new Map();
-
-export function getOrCreateAdapter(provider: PubSubProvider): PubSubAdapter {
-	let adapter = pool.get(provider);
-	if (!adapter) {
-		adapter = createPubSubAdapter(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,108 +0,0 @@
-/**
- * Smoke tests for the v0.7 PR 6 pub/sub adapters (NATS, Redis
- * Streams, Kafka) plus the v0.7 publish() backfill on the existing
- * 3 (GCP, AWS, Azure). Boundary-only — constructor, provider name,
- * initial state, `disconnect()` before connect.
- *
- * Live broker round-trips need docker-compose CI (see PR 6 plan,
- * deferred to follow-up).
- */
-
-import { describe, expect, it } from "vitest";
-
-import { AWSSNSAdapter } from "./AWSSNSAdapter";
-import { AzureServiceBusAdapter } from "./AzureServiceBusAdapter";
-import { GCPPubSubAdapter } from "./GCPPubSubAdapter";
-import { KafkaPubSubAdapter } from "./KafkaPubSubAdapter";
-import { NATSPubSubAdapter } from "./NATSPubSubAdapter";
-import { RedisStreamsPubSubAdapter } from "./RedisStreamsPubSubAdapter";
-
-describe("NATSPubSubAdapter — v0.7 PR 6", () => {
-	it("reports provider 'nats'", () => {
-		expect(new NATSPubSubAdapter().provider).toBe("nats");
-	});
-
-	it("is not connected before connect()", () => {
-		expect(new NATSPubSubAdapter().isConnected()).toBe(false);
-	});
-
-	it("disconnect() before connect is a no-op", async () => {
-		await expect(new NATSPubSubAdapter().disconnect()).resolves.toBeUndefined();
-	});
-
-	it("reads server list from NATS_SERVERS env var", () => {
-		process.env.NATS_SERVERS = "nats-a:4222,nats-b:4222";
-		const adapter = new NATSPubSubAdapter();
-		expect((adapter as unknown as { config: { servers: string[] } }).config.servers).toEqual([
-			"nats-a:4222",
-			"nats-b:4222",
-		]);
-		process.env.NATS_SERVERS = undefined;
-	});
-});
-
-describe("RedisStreamsPubSubAdapter — v0.7 PR 6", () => {
-	it("reports provider 'redis-streams'", () => {
-		expect(new RedisStreamsPubSubAdapter().provider).toBe("redis-streams");
-	});
-
-	it("is not connected before connect()", () => {
-		expect(new RedisStreamsPubSubAdapter().isConnected()).toBe(false);
-	});
-
-	it("disconnect() before connect is a no-op", async () => {
-		await expect(new RedisStreamsPubSubAdapter().disconnect()).resolves.toBeUndefined();
-	});
-
-	it("generates a unique consumer name per instance (fan-out isolation)", () => {
-		const a = new RedisStreamsPubSubAdapter();
-		const b = new RedisStreamsPubSubAdapter();
-		expect((a as unknown as { consumerName: string }).consumerName).not.toBe(
-			(b as unknown as { consumerName: string }).consumerName,
-		);
-	});
-});
-
-describe("KafkaPubSubAdapter — v0.7 PR 6", () => {
-	it("reports provider 'kafka'", () => {
-		expect(new KafkaPubSubAdapter().provider).toBe("kafka");
-	});
-
-	it("is not connected before connect()", () => {
-		expect(new KafkaPubSubAdapter().isConnected()).toBe(false);
-	});
-
-	it("disconnect() before connect is a no-op", async () => {
-		await expect(new KafkaPubSubAdapter().disconnect()).resolves.toBeUndefined();
-	});
-
-	it("honors the explicit broker list override", () => {
-		const adapter = new KafkaPubSubAdapter({ brokers: ["kafka-prod:9092"] });
-		expect((adapter as unknown as { config: { brokers: string[] } }).config.brokers).toEqual(["kafka-prod:9092"]);
-	});
-});
-
-describe("Existing adapters — provider names + publish() surface (v0.7 PR 6 backfill)", () => {
-	it("GCPPubSubAdapter reports provider 'gcp'", () => {
-		expect(new GCPPubSubAdapter().provider).toBe("gcp");
-	});
-
-	it("AWSSNSAdapter reports provider 'aws'", () => {
-		expect(new AWSSNSAdapter().provider).toBe("aws");
-	});
-
-	it("AzureServiceBusAdapter reports provider 'azure'", () => {
-		const adapter = new AzureServiceBusAdapter({
-			connectionString: "Endpoint=sb://example.servicebus.windows.net/;...",
-		});
-		expect(adapter.provider).toBe("azure");
-	});
-
-	it("all three now expose a publish() method (added in PR 6)", () => {
-		expect(typeof new GCPPubSubAdapter().publish).toBe("function");
-		expect(typeof new AWSSNSAdapter().publish).toBe("function");
-		expect(
-			typeof new AzureServiceBusAdapter({ connectionString: "Endpoint=sb://x.servicebus.windows.net/;Y" }).publish,
-		).toBe("function");
-	});
-});

package/src/index.ts

@@ -1,67 +0,0 @@
-/**
- * @blokjs/trigger-pubsub
- *
- * Pub/Sub-based trigger for Blok workflows. Supports 6 providers:
- *
- *   - **NATS** (Core + JetStream) — cheapest infra; subject wildcards.
- *   - **Redis Streams**           — when Redis is already in stack.
- *   - **Kafka**                   — high-throughput streaming.
- *   - **GCP Pub/Sub**             — Google Cloud-locked.
- *   - **AWS SNS+SQS**             — SNS fan-out → SQS queueing.
- *   - **Azure Service Bus**       — Azure Service Bus.
- *
- * v0.7+ — pick the adapter per workflow via `trigger.pubsub.provider`.
- * `BLOK_PUBSUB_ADAPTER` env var sets the default (falls back to NATS).
- * Subclasses can still set `protected adapter` directly for back-
- * compat with the pre-v0.7 single-adapter pattern.
- *
- * **Fan-out vs competing-consumer**: omit `consumerGroup` for fan-out
- * (every subscriber sees every message); set it for competing-consumer
- * (1 of N within group). One field disambiguates the two semantics.
- *
- * @example v0.7 — NATS subject hierarchy with JSON workflow
- * ```json
- * {
- *   "name": "audit-all-order-events",
- *   "trigger": {
- *     "pubsub": {
- *       "provider": "nats",
- *       "topic": "orders.>",
- *       "durable": true,
- *       "startFrom": "earliest"
- *     }
- *   },
- *   "steps": [...]
- * }
- * ```
- */
-
-// Core exports
-export {
-	PubSubTrigger,
-	type PubSubAdapter,
-	type PubSubMessage,
-} from "./PubSubTrigger";
-
-// Adapters
-export { AWSSNSAdapter, type AWSSNSConfig } from "./adapters/AWSSNSAdapter";
-export { AzureServiceBusAdapter, type AzureServiceBusConfig } from "./adapters/AzureServiceBusAdapter";
-export { GCPPubSubAdapter, type GCPPubSubConfig } from "./adapters/GCPPubSubAdapter";
-export { KafkaPubSubAdapter, type KafkaPubSubConfig } from "./adapters/KafkaPubSubAdapter";
-export { NATSPubSubAdapter, type NATSPubSubConfig } from "./adapters/NATSPubSubAdapter";
-export { RedisStreamsPubSubAdapter, type RedisStreamsPubSubConfig } from "./adapters/RedisStreamsPubSubAdapter";
-
-// v0.7 PR 6 — factory + pool used by PubSubTrigger and exposed for
-// helper nodes (`@blokjs/pubsub-publish`).
-export {
-	_resetAdapterPoolForTests,
-	createPubSubAdapter,
-	getOrCreateAdapter,
-	resolveProvider,
-} from "./adapters/factory";
-
-// Re-export types from helper for convenience
-export type {
-	PubSubProvider,
-	PubSubTriggerOpts,
-} from "@blokjs/helper";

package/template/.env.example

@@ -1,8 +0,0 @@
-PROJECT_NAME=trigger-pubsub-server
-PROJECT_VERSION=0.0.1
-PORT=4006
-WORKFLOWS_PATH=PROJECT_PATH/workflows
-NODES_PATH=PROJECT_PATH/src/nodes
-CONSOLE_LOG_ACTIVE=true
-APP_NAME=blok-pubsub
-DISABLE_TRIGGER_RUN=false # Set to true to disable trigger run and use this project as a module

package/template/package.json

@@ -1,44 +0,0 @@
-{
-	"name": "blok-pubsub-trigger",
-	"version": "0.1.0",
-	"description": "Pub/Sub trigger for Blok 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-pubsub": "^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",
-		"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 onMessage from "./workflows/messages/on-message";
-
-const workflows: Workflows = {
-	"on-message": onMessage,
-};
-
-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 PubSubServer from "./runner/PubSubServer";
-
-export default class App {
-	private pubsubServer: PubSubServer = <PubSubServer>{};
-	protected trigger_initializer = 0;
-	protected initializer = 0;
-	protected tracer = trace.getTracer(
-		process.env.PROJECT_NAME || "trigger-pubsub-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.pubsubServer = new PubSubServer();
-	}
-
-	async run() {
-		this.tracer.startActiveSpan("initialization", async (span: Span) => {
-			await this.pubsubServer.listen();
-			this.initializer = performance.now() - this.initializer;
-
-			this.logger.log(`Pub/Sub 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/PubSubServer.ts

@@ -1,39 +0,0 @@
-import { GCPPubSubAdapter, PubSubTrigger } from "@blokjs/trigger-pubsub";
-import nodes from "../Nodes";
-import workflows from "../Workflows";
-
-/**
- * PubSubServer - Concrete Pub/Sub trigger implementation
- *
- * This server extends the abstract PubSubTrigger and provides:
- * - A specific adapter (GCP Pub/Sub by default, can be changed to AWS or Azure)
- * - Node and workflow registries
- *
- * To change the provider, replace:
- * - GCPPubSubAdapter with AWSSNSAdapter or AzureServiceBusAdapter
- * - Update the adapter configuration accordingly
- *
- * @example AWS SNS/SQS
- * ```typescript
- * import { AWSSNSAdapter } from "@blokjs/trigger-pubsub";
- * protected adapter = new AWSSNSAdapter({
- *   region: process.env.AWS_REGION || "us-east-1",
- * });
- * ```
- *
- * @example Azure Service Bus
- * ```typescript
- * import { AzureServiceBusAdapter } from "@blokjs/trigger-pubsub";
- * protected adapter = new AzureServiceBusAdapter({
- *   connectionString: process.env.AZURE_SERVICE_BUS_CONNECTION_STRING || "",
- * });
- * ```
- */
-export default class PubSubServer extends PubSubTrigger {
-	protected adapter = new GCPPubSubAdapter({
-		projectId: process.env.GCP_PROJECT_ID || "my-project",
-	});
-
-	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/messages/on-message.ts

@@ -1,48 +0,0 @@
-import { workflow } from "@blokjs/helper";
-
-/**
- * Example Pub/Sub workflow — fires when a message arrives on a subscription.
- *
- * Message payload + metadata on ctx.request:
- *   - ctx.request.body                  — the message payload
- *   - ctx.request.headers               — message attributes
- *   - ctx.request.params.topic          — topic name
- *   - ctx.request.params.subscription   — subscription name
- *   - ctx.request.params.messageId      — unique message ID
- *   - ctx.vars._pubsub_message          — full broker metadata
- *
- * Pick a provider in the trigger config:
- *   provider: "gcp" | "aws" | "azure"
- *
- * v2 reliability knobs available on each step (uncomment to use):
- *   idempotencyKey: "$.req.params.messageId" — at-most-once delivery semantics
- *   retry: { maxAttempts: 3 }                 — retry on transient failures
- */
-export default workflow({
-	name: "On Pub/Sub Message",
-	version: "1.0.0",
-	description: "Handles incoming Pub/Sub messages",
-	trigger: {
-		pubsub: {
-			provider: "gcp",
-			topic: "my-topic",
-			subscription: "my-subscription",
-		},
-	},
-	steps: [
-		{
-			id: "log-message",
-			use: "@blokjs/api-call",
-			type: "module",
-			inputs: {
-				url: "https://httpbin.org/post",
-				method: "POST",
-				body: {
-					message: "js/ctx.request.body",
-					topic: "js/ctx.request.params.topic",
-					messageId: "js/ctx.request.params.messageId",
-				},
-			},
-		},
-	],
-});

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"]
-}