events-default

Fire-and-Forget

Send an event to the first registered listener. The sender doesn't wait for a response.

// Sender - emits and continues immediately
await this.events.emitEvent("order.created", {
  orderId: "12345",
  items: [{ sku: "ABC", qty: 2 }]
});

// Listener - handles the event
await this.events.onEvent(
  "order.created",
  async (data) => {
    await processOrder(data.orderId, data.items);
  }
);

Request-Response

Send an event and wait for a response from the handler.

// Sender - waits for response
const result = await this.events.emitEventAndReturn(
  "user.validate",
  { email: "user@example.com" },
  5000  // timeout in milliseconds
);
console.log(result.valid); // true or false

// Handler - returns response
await this.events.onReturnableEvent(
  "user.validate",
  async (data) => {
    const isValid = await checkEmail(data.email);
    return { valid: isValid };
  }
);

Broadcast

Send an event to ALL registered listeners.

// Sender - broadcasts to all listeners
await this.events.emitBroadcast("cache.invalidate", {
  keys: ["user:123", "session:abc"]
});

// Listeners - all instances receive the event
await this.events.onBroadcast(
  "cache.invalidate",
  async (data) => {
    for (const key of data.keys) {
      await localCache.delete(key);
    }
  }
);

Type-Safe Events with Zod

Define event schemas for compile-time and runtime type safety:

import { z } from "zod";

// Define event schemas
const OrderCreatedSchema = z.object({
  orderId: z.string(),
  userId: z.string(),
  items: z.array(z.object({
    sku: z.string(),
    quantity: z.number()
  }))
});

const OrderResultSchema = z.object({
  success: z.boolean(),
  orderId: z.string()
});

// Type-safe event handling
await this.events.onReturnableEvent(
  "order.create",
  OrderCreatedSchema,   // input validation
  OrderResultSchema,    // output validation
  async (data) => {
    // data is fully typed as z.infer<typeof OrderCreatedSchema>
    return {
      success: true,
      orderId: data.orderId
    };
  }
);