Events

Events are timestamped actions with a type tag and a payload. The TEventMap generic maps each event type to its payload shape.

Defining Event Types


type MyEvents = {
  'order:placed': { orderId: string; items: number };
  'order:completed': { orderId: string };
};

The SimEvent interface:


interface SimEvent<TType extends string, TPayload> {
  readonly id: string;           // auto-generated unique ID
  readonly time: number;         // scheduled simulation time
  readonly type: TType;          // event type tag
  readonly payload: TPayload;    // user-defined event data
  readonly createdAt: number;    // simulation time when scheduled
  cancelled: boolean;            // set to true to skip processing
}

Scheduling Events

Inside any handler, use ctx.schedule() to create new events:


sim.on('customer:arrive', (event, ctx) => {
  // Schedule a future event
  ctx.schedule('customer:serve', ctx.clock + 5, {
    customerId: event.payload.customerId,
  });
});

The scheduled event’s time must be >= ctx.clock. Scheduling an event in the past throws a SimulationError.

Event Cancellation

schedule() returns the event object. Pass it to cancelEvent() to prevent it from being processed:


const timeout = ctx.schedule('timeout', ctx.clock + 10, {});
// later...
ctx.cancelEvent(timeout);

Cancelled events remain in the queue but are skipped during processing (lazy deletion). This avoids the cost of removing from the heap.

Event Processing Order

The internal event queue is a binary min-heap sorted by:

time (ascending)
insertionOrder (ascending, FIFO — ensures determinism for simultaneous events)