CEL Filtering

CEL (Common Expression Language) allows you to perform server-side filtering on event payloads. This significantly reduces bandwidth by only sending matching events to your client.

Basic Syntax

TypeScript

Browser (Singleton):

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

await ironflow.subscribe("events:order.*", {
  filter: 'data.total > 100.00',
  onEvent: (e) => console.log("High-value order:", e.data),
});

Node.js (Instance):

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

const subClient = createSubscriptionClient({
  serverUrl: "http://localhost:9123",
  apiKey: "...",
});
await subClient.connect();
await subClient.subscribe("events:payment.*", {
  filter: 'data.status == "failed"',
  onEvent: (e) => notifyOps(e.data),
});

Go

sub, _ := client.Subscribe(ctx, "events:order.*", &ironflow.SubscribeOptions{
    Filter: `data.status == "completed"`,
})

---

String & Logic Operators

CEL supports standard string methods and logical operators for complex filtering.

• Contains: data.email.contains("@company.com")
• Regex: data.id.matches("^[0-9]+$")
• Logic: data.priority == "high" && data.urgent == true
• Lists: data.category in ["billing", "auth"]

---

Available Variables

Variable	Description
data	The event payload (JSON object).
topic	The full event topic string.
name	The event name.
timestamp	The event creation time.

For pub/sub subscriptions, only the variables above are populated by the server. CEL fields like event, metadata, source, and eventNamespace apply only in the event-trigger matching path and are unavailable here.

Performance

Because filtering happens before the event is serialized for the network, using CEL filters is highly recommended for high-throughput streams (like system.run.>).