Event handlers

A handler subscribes to a resource’s mutation events and runs a side effect when the data changes. Handlers live next to the resource that owns the data, in apps/api/src/resources/<name>/handlers/*.ts. Each file calls eventBus.on(...) at module scope — importing the file registers the subscription.

resources/users/
  handlers/
    sync-analytics.ts   # users.insert → track in analytics
    to-sockets.ts       # users.update → push to the browser

Anatomy of a handler

A handler file imports eventBus, subscribes to one `${table}.${type}` key, iterates docs, and wraps the work in a try/catch so a side-effect failure never takes down the request that triggered it:

import { eventBus } from '@/event-bus';
import logger from '@/logger';
import { analyticsService } from '@/services';

eventBus.on('users.insert', (data) => {
  try {
    for (const user of data.docs) {
      analyticsService.track('New user created', {
        fullName: user.fullName,
      });
    }
  } catch (err) {
    logger.error(`users.insert handler error: ${err}`);
  }
});

data is the typed MutationEvent for the users table, so user is a fully-typed User row — user.fullName, user.email and user.id are all known to the compiler.

Reacting to updates

users.update events carry both the new rows (docs) and the rows as they were (prevDocs). Here Ship pushes every updated user to their own browser over Socket.IO:

import { eventBus } from '@/event-bus';
import ioEmitter from '@/io-emitter';
import logger from '@/logger';

eventBus.on('users.update', (data) => {
  try {
    for (const user of data.docs) {
      logger.debug(`Emitting user:updated to user ${user.id} (${user.email})`);
      ioEmitter.publishToUser(user.id, 'user:updated', user);
    }
  } catch (err) {
    logger.error(`users.update handler error: ${err}`);
  }
});

Need to act only when a specific field changed? Compare against prevDocs (same order as docs):

eventBus.on('users.update', ({ docs, prevDocs }) => {
  for (const [i, user] of docs.entries()) {
    const before = prevDocs?.[i];
    if (before && !before.isEmailVerified && user.isEmailVerified) {
      analyticsService.track('Email verified', { userId: user.id });
    }
  }
});

Opt a table into events

A table only emits events when its DbService is constructed with the event-bus hook. This is wired in the generated src/db.ts:

users: new DbService<typeof users>(users, db, 'users', eventBus.hook('users')),

eventBus.hook('users') returns the onMutation callback DbService calls after every write — it re-emits the mutation as users.insert / users.update / users.delete. A table created without the fourth argument (e.g. sessions, verifications) writes silently and fires no events. Add the hook when you want a table to be observable.

src/db.ts is generated by codegen-db.ts. Re-run pnpm --filter api codegen after adding a schema; then add eventBus.hook('<table>') to that table’s DbService if it should emit events.

Registration is automatic

You never wire handlers up by hand. codegen-router.ts scans every resources/<name>/handlers/ folder and emits a side-effect import at the top of the generated src/router.ts:

// Auto-generated by codegen-router.ts — do not edit manually

import './resources/users/handlers/sync-analytics';
import './resources/users/handlers/to-sockets';

Importing the module runs its top-level eventBus.on(...), registering the subscription. So the workflow is:

Add the file

Create resources/<name>/handlers/<what-it-does>.ts and call eventBus.on('<table>.<type>', ...).

Run codegen

pnpm --filter api codegen regenerates router.ts with the new side-effect import.

Done

The handler is live — no registry, no manual import.

Name handlers for the effect, not the event: sync-analytics.ts, to-sockets.ts, denormalise-counts.ts. One file per side effect keeps each reaction independent and easy for an agent to find.

Keep handlers safe

Always try/catch. A handler runs in the same process as the write; an unguarded throw shouldn’t surface as a request error. Log and move on.
Iterate docs. Bulk mutations (insertMany, updateMany, deleteMany) deliver one event with many rows.
Stay idempotent where you can. Treat handlers as best-effort reactions, not part of the transaction.

Next steps

The event shape and types: Mutation events.
Cross-resource patterns: Using events.

Getting Started

Ship Components

Plugins

Event handlers

Anatomy of a handler

Reacting to updates

Opt a table into events

Registration is automatic

Keep handlers safe

Next steps

​Anatomy of a handler

​Reacting to updates

​Opt a table into events

​Registration is automatic

​Keep handlers safe

​Next steps

Anatomy of a handler

Reacting to updates

Opt a table into events

Registration is automatic

Keep handlers safe

Next steps