PubSub Module

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iii-hq/iii/llms.txt

Use this file to discover all available pages before exploring further.

​

Configuration

modules:
  - class: modules::pubsub::PubSubModule
    config:
      adapter:
        class: modules::pubsub::RedisAdapter
        config:
          redis_url: redis://localhost:6379

​

Available Adapters

adapter:
  class: modules::pubsub::LocalAdapter

adapter:
  class: modules::pubsub::RedisAdapter
  config:
    redis_url: redis://localhost:6379

​

Publishing Events

await client.call('pubsub.publish', {
  topic: 'user.login',
  data: {
    userId: 123,
    timestamp: new Date().toISOString(),
  },
});

​

Subscribing to Topics

export default iii({
  triggers: {
    'on-user-login': {
      type: 'subscribe',
      config: {
        topic: 'user.login',
      },
    },
    'on-order-created': {
      type: 'subscribe',
      config: {
        topic: 'order.created',
      },
    },
  },
});

export async function onUserLogin(data: any) {
  console.log('User logged in:', data.userId);
  // Track login analytics
  await trackEvent('login', data);
}

export async function onOrderCreated(data: any) {
  console.log('New order:', data.orderId);
  // Send confirmation email
  await sendConfirmation(data);
}

​

Trigger Configuration

​

Use Cases

​

Real-time Notifications

// Publisher
await client.call('pubsub.publish', {
  topic: 'notifications',
  data: {
    userId: 456,
    message: 'Your order has shipped!',
  },
});

// Subscriber
export async function onNotification(data: any) {
  await sendPushNotification(data.userId, data.message);
}

​

Event Broadcasting

// Broadcast to multiple subscribers
await client.call('pubsub.publish', {
  topic: 'cache.invalidate',
  data: { key: 'products' },
});

// Multiple functions can subscribe to the same topic
export async function onCacheInvalidate(data: any) {
  await clearCache(data.key);
}

​

Cross-Service Communication

// Service A publishes events
await client.call('pubsub.publish', {
  topic: 'payment.processed',
  data: {
    orderId: '123',
    amount: 99.99,
  },
});

// Service B reacts to events
export async function onPaymentProcessed(data: any) {
  await fulfillOrder(data.orderId);
}

​

LocalAdapter vs RedisAdapter

​

LocalAdapter

• Use for: Development, single-instance deployments
• Storage: In-memory HashMap
• Scope: Single process instance only
• Performance: Extremely fast (no network overhead)
• Persistence: None (events lost on restart)

​

RedisAdapter

• Use for: Production, multi-instance deployments
• Storage: Redis pub/sub channels
• Scope: All connected instances
• Performance: Fast with minimal network latency
• Persistence: None (Redis pub/sub is ephemeral)

​

Error Handling

// Empty topic returns an error
const result = await client.call('pubsub.publish', {
  topic: '',
  data: { test: true },
});
// Returns: { code: 'topic_not_set', message: 'Topic is not set' }

​

Best Practices

1. Use descriptive topic names - Use namespaced topics like user.created, order.shipped
2. Keep payloads small - PubSub is optimized for real-time events, not large data transfers
3. Handle failures gracefully - Subscribers should not throw errors that affect other subscribers
4. Use Redis in production - RedisAdapter enables horizontal scaling across multiple instances
5. Don’t rely on delivery guarantees - Use the Queue module if you need guaranteed delivery

​

Comparison with Queue Module

​

API Reference

​

pubsub.publish

{
  topic: string;  // Topic name (required, non-empty)
  data: any;      // Event payload (required)
}

• topic_not_set - Topic is empty or not provided