Scalable Event-Driven Task System with TypeScript

The biggest mistake in an event-driven TypeScript project is treating events as simple strings and payloads as flexible objects. This makes the system look event-driven, but it removes the safety that TypeScript should provide. If one handler expects taskId and another publishes id, the event will still be emitted, but the workflow may fail silently or create inconsistent task state.

Problematic approach:

          type EventPayload = Record<string, unknown>;

          function publish(eventName: string, payload: EventPayload): void {
            handlers[eventName]?.forEach((handler) => {
              handler(payload);
            });
          }

          publish("task.completed", {
            id: "task_123",
            user: "user_1"
          });

This code allows any event name and any payload shape. The compiler cannot warn you when required fields are missing or incorrectly named.

Better typed event map:

          type TaskStatus = "todo" | "in-progress" | "blocked" | "completed";

          interface DomainEvents {
            "task.created": {
              taskId: string;
              title: string;
              createdBy: string;
              createdAt: string;
            };

            "task.assigned": {
              taskId: string;
              assigneeId: string;
              assignedBy: string;
              assignedAt: string;
            };

            "task.status.changed": {
              taskId: string;
              previousStatus: TaskStatus;
              nextStatus: TaskStatus;
              changedBy: string;
              changedAt: string;
            };

            "task.completed": {
              taskId: string;
              completedBy: string;
              completedAt: string;
            };
          }

Typed publish function:

          type EventName = keyof DomainEvents;

          function publish<Name extends EventName>(
            eventName: Name,
            payload: DomainEvents[Name]
          ): void {
            const eventHandlers = handlers[eventName] || [];

            eventHandlers.forEach((handler) => {
              handler(payload);
            });
          }

          publish("task.completed", {
            taskId: "task_123",
            completedBy: "user_1",
            completedAt: new Date().toISOString()
          });

Pay attention to: Define an event contract before building handlers. Event names and payloads should be typed together so invalid events cannot move through the system unnoticed.

Event-driven systems can become messy when every handler is allowed to update any part of the application state. For example, a notification handler should not also update task status, write analytics, and modify assignment history. If handlers have unclear responsibilities, the system becomes hard to debug because one event can trigger many hidden side effects.

Problematic handler:

          async function onTaskAssigned(payload: any) {
            await db.task.update({
              where: { id: payload.taskId },
              data: { assigneeId: payload.assigneeId }
            });

            await db.notification.create({
              data: {
                userId: payload.assigneeId,
                message: "You have a new task."
              }
            });

            await db.analytics.create({
              data: {
                type: "assignment",
                taskId: payload.taskId
              }
            });

            await db.activityLog.create({
              data: {
                message: "Task was assigned."
              }
            });
          }

This handler does too many things. It mixes task mutation, notifications, analytics, and activity tracking in one place.

Better separation of handlers:

          type EventHandler<Name extends EventName> = (
            payload: DomainEvents[Name]
          ) => Promise<void> | void;

          const updateTaskAssignment: EventHandler<"task.assigned"> = async (payload) => {
            await taskRepository.assignTask({
              taskId: payload.taskId,
              assigneeId: payload.assigneeId
            });
          };

          const notifyAssignee: EventHandler<"task.assigned"> = async (payload) => {
            await notificationService.createNotification({
              userId: payload.assigneeId,
              message: "You have been assigned a new task."
            });
          };

          const recordAssignmentActivity: EventHandler<"task.assigned"> = async (payload) => {
            await activityService.record({
              type: "task.assigned",
              taskId: payload.taskId,
              actorId: payload.assignedBy,
              createdAt: payload.assignedAt
            });
          };

Registration example:

          eventBus.subscribe("task.assigned", updateTaskAssignment);
          eventBus.subscribe("task.assigned", notifyAssignee);
          eventBus.subscribe("task.assigned", recordAssignmentActivity);

Pay attention to: Handlers should be small and focused. One handler should own one reaction. This keeps workflows traceable and makes it easier to add, remove, or test system behavior.

Events should describe something that has happened, not something that might happen. A common mistake is publishing task.created before the task is actually saved. If the database operation fails, other handlers may still send notifications, update activity streams, or trigger follow-up workflows for a task that does not exist.

Problematic flow:

          async function createTask(input: CreateTaskInput): Promise<Task> {
            eventBus.publish("task.created", {
              taskId: input.id,
              title: input.title,
              createdBy: input.userId,
              createdAt: new Date().toISOString()
            });

            const task = await taskRepository.create(input);

            return task;
          }

This publishes the event too early. The event stream now claims a task was created even if the repository call fails.

Better command flow:

          async function createTask(input: CreateTaskInput): Promise<Task> {
            const task = await taskRepository.create({
              title: input.title,
              description: input.description,
              status: "todo",
              createdBy: input.userId
            });

            eventBus.publish("task.created", {
              taskId: task.id,
              title: task.title,
              createdBy: task.createdBy,
              createdAt: task.createdAt
            });

            return task;
          }

Safer outbox-style idea:

          async function createTask(input: CreateTaskInput): Promise<Task> {
            return db.transaction(async (tx) => {
              const task = await tx.task.create({
                data: {
                  title: input.title,
                  description: input.description,
                  status: "todo",
                  createdBy: input.userId
                }
              });

              await tx.eventOutbox.create({
                data: {
                  eventName: "task.created",
                  payload: {
                    taskId: task.id,
                    title: task.title,
                    createdBy: task.createdBy,
                    createdAt: task.createdAt
                  },
                  status: "pending"
                }
              });

              return task;
            });
          }

Pay attention to: Publish events only after the source operation is successful. For more reliable systems, store events in an outbox table and process them separately so task state and event history cannot drift apart.

Event handlers may run more than once. Retries, queue redelivery, browser refreshes, network interruptions, and worker restarts can all cause duplicate processing. If a handler sends the same notification twice, creates duplicate activity logs, or applies the same task transition repeatedly, users lose trust in the system.

Problematic handler:

          async function onTaskCompleted(payload: DomainEvents["task.completed"]) {
            await activityService.record({
              type: "task.completed",
              taskId: payload.taskId,
              actorId: payload.completedBy,
              createdAt: payload.completedAt
            });

            await notificationService.notifyManager({
              taskId: payload.taskId,
              message: "A task was completed."
            });
          }

If the same event is delivered twice, this handler records two activities and sends two notifications.

Better event envelope:

          interface EventEnvelope<Name extends EventName> {
            eventId: string;
            eventName: Name;
            payload: DomainEvents[Name];
            occurredAt: string;
          }

          type EnvelopeHandler<Name extends EventName> = (
            event: EventEnvelope<Name>
          ) => Promise<void>;

Idempotent processing:

          async function processOnce<Name extends EventName>(
            event: EventEnvelope<Name>,
            handler: () => Promise<void>
          ): Promise<void> {
            const existing = await processedEventRepository.findById(event.eventId);

            if (existing) {
              return;
            }

            await handler();

            await processedEventRepository.save({
              eventId: event.eventId,
              eventName: event.eventName,
              processedAt: new Date().toISOString()
            });
          }

          const onTaskCompleted: EnvelopeHandler<"task.completed"> = async (event) => {
            await processOnce(event, async () => {
              await activityService.record({
                type: event.eventName,
                taskId: event.payload.taskId,
                actorId: event.payload.completedBy,
                createdAt: event.payload.completedAt
              });
            });
          };

Pay attention to: Every event should have a unique event ID. Handlers that create side effects should be safe to retry without duplicating work.

An activity stream is useful, but the UI should not depend on raw internal event objects. Internal events may contain technical fields, sensitive data, or payload shapes that change as the system evolves. Beginners often render the event payload directly in a table, which creates a dashboard that is difficult to understand and easy to break.

Problematic Ant Design table:

          <Table
            dataSource={events}
            columns={[
              {
                title: "Event",
                dataIndex: "eventName"
              },
              {
                title: "Payload",
                render: (_, event) => JSON.stringify(event.payload)
              }
            ]}
          />

This exposes raw technical data instead of useful product information. Users should see meaningful activity such as “Task assigned to Maria,” not a JSON object.

Better view model:

          interface ActivityItem {
            id: string;
            title: string;
            description: string;
            taskId: string;
            actorId: string;
            createdAt: string;
            severity: "info" | "success" | "warning";
          }

          function eventToActivityItem(
            event: EventEnvelope<EventName>
          ): ActivityItem {
            switch (event.eventName) {
              case "task.created":
                return {
                  id: event.eventId,
                  title: "Task created",
                  description: event.payload.title,
                  taskId: event.payload.taskId,
                  actorId: event.payload.createdBy,
                  createdAt: event.occurredAt,
                  severity: "info"
                };

              case "task.completed":
                return {
                  id: event.eventId,
                  title: "Task completed",
                  description: "A task was marked as completed.",
                  taskId: event.payload.taskId,
                  actorId: event.payload.completedBy,
                  createdAt: event.occurredAt,
                  severity: "success"
                };
            }
          }

Cleaner Ant Design rendering:

          <Table
            rowKey="id"
            dataSource={activityItems}
            columns={[
              {
                title: "Activity",
                dataIndex: "title"
              },
              {
                title: "Description",
                dataIndex: "description"
              },
              {
                title: "Time",
                dataIndex: "createdAt",
                render: (value) => formatDateTime(value)
              }
            ]}
          />

Pay attention to: Convert internal events into UI-specific activity items before rendering. The dashboard should show clear workflow history, not raw system internals.