events

Every mutation emits an immutable event. Build reactive systems, audit trails, and event-driven workflows.

Import

import { DB } from 'ai-database'

const { db, events } = DB({
  Post: { title: 'string' },
})

Automatic Events

All mutations emit events automatically:

await db.Post.create({ title: 'Hello' })
// Emits: Post.created

await db.Post.update('hello', { published: true })
// Emits: Post.updated

await db.Post.delete('hello')
// Emits: Post.deleted

Operations

on

Subscribe to events:

events.on('Post.created', async (event) => {
  console.log(`New post: ${event.data.title}`)
})

// Pattern matching
events.on('Post.*', handler)      // all Post events
events.on('*.created', handler)   // all creation events

off

Unsubscribe:

events.off('Post.created', handler)

emit

Emit custom events:

await events.emit('Post.published', {
  url: post.$id,
  data: { title: post.title },
})

list

Query the event log:

const changes = await events.list({
  type: 'Post.*',
  since: lastWeek,
  limit: 100,
})

replay

Replay events for recovery:

await events.replay({
  type: 'Post.*',
  since: checkpoint,
  handler: async (event) => {
    // Process each event
  },
})

Event Types

Event	Emitted When
`{Type}.created`	Entity created
`{Type}.updated`	Entity updated
`{Type}.deleted`	Entity deleted
`{Type}.generated`	Entity AI-generated
`Relation.created`	Relationship created
`Relation.deleted`	Relationship deleted
`Action.started`	Action began
`Action.completed`	Action succeeded
`Action.failed`	Action failed

Event Structure

interface Event {
  id: string
  type: string          // 'Post.created'
  url: string           // entity URL
  data: unknown         // entity data or changes
  timestamp: Date
  actor?: string        // who triggered it
}

Use Cases

// Generate social posts on creation
events.on('Post.created', async (event) => {
  await db.generate({
    type: 'SocialPost',
    data: { post: event.url },
  })
})

// Send notifications
events.on('Post.published', async (event) => {
  await notify(event.data)
})

// Audit trail
events.on('*', async (event) => {
  await auditLog.append(event)
})

Was this page helpful?

On this page