@blokjs/trigger-pubsub 0.2.2 → 0.6.1

package/src/adapters/factory.ts

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

@@ -0,0 +1,108 @@
+/**
+ * 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,50 +1,37 @@
 /**
  * @blokjs/trigger-pubsub
  *
- * Pub/Sub-based trigger for Blok workflows.
- * Supports multiple pub/sub providers:
- * - Google Cloud Pub/Sub
- * - AWS SNS/SQS
- * - Azure Service Bus
+ * Pub/Sub-based trigger for Blok workflows. Supports 6 providers:
  *
- * @example GCP Pub/Sub
- * ```typescript
- * import { PubSubTrigger, GCPPubSubAdapter } from "@blokjs/trigger-pubsub";
+ *   - **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.
  *
- * class MyPubSubTrigger extends PubSubTrigger {
- *   protected adapter = new GCPPubSubAdapter({
- *     projectId: "my-project",
- *   });
+ * 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.
  *
- *   protected nodes = myNodes;
- *   protected workflows = myWorkflows;
- * }
- *
- * const trigger = new MyPubSubTrigger();
- * await trigger.listen();
- * ```
- *
- * @example AWS SNS/SQS
- * ```typescript
- * import { PubSubTrigger, AWSSNSAdapter } from "@blokjs/trigger-pubsub";
- *
- * class MyPubSubTrigger extends PubSubTrigger {
- *   protected adapter = new AWSSNSAdapter({
- *     region: "us-east-1",
- *   });
- *   // ...
- * }
- * ```
- *
- * @example Azure Service Bus
- * ```typescript
- * import { PubSubTrigger, AzureServiceBusAdapter } from "@blokjs/trigger-pubsub";
+ * **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.
  *
- * class MyPubSubTrigger extends PubSubTrigger {
- *   protected adapter = new AzureServiceBusAdapter({
- *     connectionString: process.env.AZURE_SERVICE_BUS_CONNECTION_STRING,
- *   });
- *   // ...
+ * @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": [...]
  * }
  * ```
  */
@@ -57,9 +44,21 @@ export {
 } from "./PubSubTrigger";
 
 // Adapters
-export { GCPPubSubAdapter, type GCPPubSubConfig } from "./adapters/GCPPubSubAdapter";
 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 {

package/template/package.json

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

package/template/src/runner/PubSubServer.ts

@@ -34,6 +34,6 @@ export default class PubSubServer extends PubSubTrigger {
 		projectId: process.env.GCP_PROJECT_ID || "my-project",
 	});
 
-	protected nodes = nodes;
-	protected workflows = workflows;
+	protected nodes: Record<string, import("@blokjs/runner").BlokService<unknown>> = nodes;
+	protected workflows: Record<string, import("@blokjs/helper").HelperResponse> = workflows;
 }

package/template/src/workflows/messages/on-message.ts

@@ -1,44 +1,48 @@
-import { type Step, Workflow } from "@blokjs/helper";
+import { workflow } from "@blokjs/helper";
 
 /**
- * Example Pub/Sub workflow - triggered when a message is received
+ * Example Pub/Sub workflow — fires when a message arrives on a subscription.
  *
- * The message data is available in ctx.request:
- * - ctx.request.body: The message payload
- * - ctx.request.headers: Message attributes
- * - ctx.request.params.topic: The topic name
- * - ctx.request.params.subscription: The subscription name
- * - ctx.request.params.messageId: Unique message ID
+ * 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
  *
- * Additional metadata is available in ctx.vars._pubsub_message:
- * - topic: Topic name
- * - subscription: Subscription name
- * - publishTime: When the message was published (ISO string)
- * - attributes: JSON string of message attributes
+ * 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
  */
-const step: Step = Workflow({
+export default workflow({
 	name: "On Pub/Sub Message",
 	version: "1.0.0",
 	description: "Handles incoming Pub/Sub messages",
-})
-	.addTrigger("pubsub", {
-		provider: "gcp",
-		topic: "my-topic",
-		subscription: "my-subscription",
-	})
-	.addStep({
-		name: "log-message",
-		node: "@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",
+	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",
+				},
 			},
 		},
-	});
-
-export default step;
+	],
+});