Topics

Topics provide a general-purpose messaging layer on top of Ironflow’s NATS infrastructure. Use them for service-to-service communication, analytics, or notifications — without triggering workflows.

Topics vs Events

Feature	emit()	publish()
Namespace	events:	topic:
Triggers Functions?	Yes	No
Use Case	Business logic triggers.	Real-time messages / broadcasting.

---

Publishing to Topics

From Application Code

TypeScript

import { createClient } from "@ironflow/node";

const ironflow = createClient({ apiKey: process.env.IRONFLOW_API_KEY });

await ironflow.publish("notifications.email", {
  to: "user@example.com",
  body: "Welcome to Ironflow!",
});

Go

client := ironflow.NewClient(ironflow.ClientConfig{
    APIKey: os.Getenv("IRONFLOW_API_KEY"),
})

client.Publish(ctx, "notifications.email", map[string]string{
    "to": "user@example.com",
})

Python

import os
from ironflow import IronflowRPC
from ironflow.rpc.v1 import PublishRequest
from protobuf.wkt import Struct

with IronflowRPC(api_key=os.environ["IRONFLOW_API_KEY"]) as rpc:
    res = rpc.pubsub.publish(PublishRequest(
        topic="notifications.email",
        data=Struct.from_python({"to": "user@example.com", "body": "Welcome to Ironflow!"}),
    ))
    print(res.event_id, res.sequence)

rpc.pubsub also exposes subscriptions, topic queries and consumer-group operations.

From Within a Workflow

Use step.publish() to emit a message as a durable step. This ensures that if the workflow retries, the message is not published more than once.

import { ironflow } from "@ironflow/node";

export const myFn = ironflow.createFunction(config, async ({ step }) => {
  // Durable publish — memoized and observable
  await step.publish("analytics.workflow_step", { status: "reached" });
});

---

Subscribing to Topics

Topics use the topic: prefix for subscriptions.

TypeScript

import { ironflow } from "@ironflow/browser";

await ironflow.subscribe("topic:notifications.>", {
  onEvent: (event) => console.log("Broadcasting:", event.data),
});

CLI

# Listen to all developer topics
ironflow subscribe "topic:>"

Clean Patterns

Use topic:notifications.* to listen to specific categories, or topic:> to listen to all custom messages in the system.