@mantiq/events 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/events
+
+Event dispatcher, broadcasting, and model observers for MantiqJS.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/events
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@mantiq/events",
+  "version": "0.0.1",
+  "description": "Event dispatcher, listeners, observers, and broadcasting for MantiqJS",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/events",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/events"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "events"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@mantiq/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@mantiq/database": "workspace:*",
+    "@mantiq/auth": "workspace:*",
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "@mantiq/database": "workspace:*",
+    "@mantiq/auth": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@mantiq/database": {
+      "optional": true
+    },
+    "@mantiq/auth": {
+      "optional": true
+    }
+  }
+}

package/src/Dispatcher.ts

@@ -0,0 +1,151 @@
+import type { Constructor, EventDispatcher, EventHandler } from '@mantiq/core'
+import { Event, Listener } from '@mantiq/core'
+import type { Subscriber } from './Subscriber.ts'
+import type { ShouldBroadcast } from './contracts/ShouldBroadcast.ts'
+import type { BroadcastManager } from './broadcast/BroadcastManager.ts'
+import { ListenerError } from './errors/EventError.ts'
+
+type RegisteredListener = Constructor<Listener> | EventHandler
+
+/**
+ * Concrete implementation of the EventDispatcher contract.
+ *
+ * Supports class-based listeners, closure listeners, subscribers,
+ * wildcard listeners, and broadcasting integration.
+ */
+export class Dispatcher implements EventDispatcher {
+  private readonly listeners = new Map<Constructor<Event>, RegisteredListener[]>()
+  private readonly wildcardListeners: EventHandler[] = []
+  private broadcaster: BroadcastManager | null = null
+
+  // ── Registration ─────────────────────────────────────────────────────
+
+  on(eventClass: Constructor<Event>, listener: RegisteredListener): void {
+    const existing = this.listeners.get(eventClass) ?? []
+    existing.push(listener)
+    this.listeners.set(eventClass, existing)
+  }
+
+  /**
+   * Register a listener that fires for every event.
+   */
+  onAny(handler: EventHandler): void {
+    this.wildcardListeners.push(handler)
+  }
+
+  /**
+   * Register a listener that fires only once, then auto-removes.
+   */
+  once(eventClass: Constructor<Event>, handler: EventHandler): void {
+    const wrapper: EventHandler = async (event) => {
+      this.off(eventClass, wrapper)
+      await handler(event)
+    }
+    this.on(eventClass, wrapper)
+  }
+
+  /**
+   * Remove a specific listener for an event class.
+   */
+  off(eventClass: Constructor<Event>, listener: RegisteredListener): void {
+    const existing = this.listeners.get(eventClass)
+    if (!existing) return
+    const index = existing.indexOf(listener)
+    if (index !== -1) existing.splice(index, 1)
+  }
+
+  /**
+   * Remove all listeners for an event class.
+   */
+  forget(eventClass: Constructor<Event>): void {
+    this.listeners.delete(eventClass)
+  }
+
+  /**
+   * Remove all listeners for all events.
+   */
+  flush(): void {
+    this.listeners.clear()
+    this.wildcardListeners.length = 0
+  }
+
+  /**
+   * Register a subscriber that can listen to multiple events.
+   */
+  subscribe(subscriber: Subscriber): void {
+    subscriber.subscribe(this)
+  }
+
+  /**
+   * Check whether an event class has any listeners registered.
+   */
+  hasListeners(eventClass: Constructor<Event>): boolean {
+    const registered = this.listeners.get(eventClass)
+    return (registered !== undefined && registered.length > 0) || this.wildcardListeners.length > 0
+  }
+
+  /**
+   * Get all listeners for an event class.
+   */
+  getListeners(eventClass: Constructor<Event>): RegisteredListener[] {
+    return [...(this.listeners.get(eventClass) ?? []), ...this.wildcardListeners]
+  }
+
+  // ── Broadcasting ─────────────────────────────────────────────────────
+
+  /**
+   * Set the broadcast manager for broadcasting ShouldBroadcast events.
+   */
+  setBroadcaster(broadcaster: BroadcastManager): void {
+    this.broadcaster = broadcaster
+  }
+
+  // ── Dispatch ─────────────────────────────────────────────────────────
+
+  async emit(event: Event): Promise<void> {
+    const eventClass = event.constructor as Constructor<Event>
+    const registered = this.listeners.get(eventClass) ?? []
+
+    // Fire class-based and closure listeners
+    for (const listener of registered) {
+      await this.callListener(listener, event)
+    }
+
+    // Fire wildcard listeners
+    for (const handler of this.wildcardListeners) {
+      await handler(event)
+    }
+
+    // Broadcast if the event implements ShouldBroadcast
+    if (this.broadcaster && isBroadcastable(event)) {
+      await this.broadcaster.broadcast(event as Event & ShouldBroadcast)
+    }
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────
+
+  private async callListener(listener: RegisteredListener, event: Event): Promise<void> {
+    try {
+      if (isListenerClass(listener)) {
+        const instance = new listener()
+        await instance.handle(event)
+      } else {
+        await (listener as EventHandler)(event)
+      }
+    } catch (error) {
+      const eventName = event.constructor.name
+      const listenerName = isListenerClass(listener) ? listener.name : listener.name || '(anonymous)'
+      throw new ListenerError(eventName, listenerName, error instanceof Error ? error : new Error(String(error)))
+    }
+  }
+}
+
+// ── Type guards ────────────────────────────────────────────────────────────
+
+function isListenerClass(listener: RegisteredListener): listener is Constructor<Listener> {
+  return typeof listener === 'function' && listener.prototype instanceof Listener
+}
+
+function isBroadcastable(event: Event): event is Event & ShouldBroadcast {
+  return typeof (event as any).broadcastOn === 'function'
+}

package/src/EventServiceProvider.ts

@@ -0,0 +1,79 @@
+import { ServiceProvider, ConfigRepository, CacheManager, RouterImpl } from '@mantiq/core'
+import { Dispatcher } from './Dispatcher.ts'
+import { BroadcastManager } from './broadcast/BroadcastManager.ts'
+import type { BroadcastConfig } from './broadcast/BroadcastManager.ts'
+import { EVENT_DISPATCHER } from './helpers/emit.ts'
+import { BROADCAST_MANAGER } from './helpers/broadcast.ts'
+import { fireModelEvent, bootModelEvents } from './model/HasEvents.ts'
+
+const DEFAULT_BROADCAST_CONFIG: BroadcastConfig = {
+  default: 'null',
+  connections: {
+    null: { driver: 'null' },
+  },
+}
+
+/**
+ * Registers the event dispatcher and broadcast manager in the container.
+ *
+ * Also hooks events into other framework packages when they are installed:
+ * - @mantiq/database — Model lifecycle events, query events, migration events
+ * - @mantiq/auth — Authentication events (Login, Logout, Failed, etc.)
+ * - @mantiq/core — Cache events, RouteMatched event
+ */
+export class EventServiceProvider extends ServiceProvider {
+  override register(): void {
+    // Register the event dispatcher as a singleton
+    this.app.singleton(Dispatcher, () => new Dispatcher())
+    this.app.alias(Dispatcher, EVENT_DISPATCHER)
+
+    // Register the broadcast manager as a singleton
+    this.app.singleton(BroadcastManager, (c) => {
+      let config = DEFAULT_BROADCAST_CONFIG
+      try {
+        config = c.make(ConfigRepository).get<BroadcastConfig>('broadcasting', DEFAULT_BROADCAST_CONFIG)
+      } catch {
+        // ConfigRepository not yet registered — use defaults
+      }
+      return new BroadcastManager(config)
+    })
+    this.app.alias(BroadcastManager, BROADCAST_MANAGER)
+  }
+
+  override boot(): void {
+    const dispatcher = this.app.make<Dispatcher>(EVENT_DISPATCHER)
+    const broadcaster = this.app.make<BroadcastManager>(BROADCAST_MANAGER)
+    dispatcher.setBroadcaster(broadcaster)
+
+    // ── Hook into @mantiq/database ─────────────────────────────────────
+    try {
+      const db = require('@mantiq/database') as any
+      if (db.Model) {
+        db.Model._fireEvent = fireModelEvent
+        bootModelEvents(db.Model)
+      }
+      if (db.SQLiteConnection) {
+        db.SQLiteConnection._dispatcher = dispatcher
+      }
+      if (db.Migrator) {
+        db.Migrator._dispatcher = dispatcher
+      }
+    } catch {
+      // @mantiq/database not installed
+    }
+
+    // ── Hook into @mantiq/auth ─────────────────────────────────────────
+    try {
+      const auth = require('@mantiq/auth') as any
+      if (auth.SessionGuard) {
+        auth.SessionGuard._dispatcher = dispatcher
+      }
+    } catch {
+      // @mantiq/auth not installed
+    }
+
+    // ── Hook into @mantiq/core (cache + routing) ────────────────────────
+    CacheManager._dispatcher = dispatcher
+    RouterImpl._dispatcher = dispatcher
+  }
+}

package/src/Subscriber.ts

@@ -0,0 +1,23 @@
+import type { EventDispatcher } from '@mantiq/core'
+
+/**
+ * Base class for event subscribers.
+ *
+ * A subscriber can listen to multiple events by registering them
+ * inside the `subscribe()` method.
+ *
+ * ```typescript
+ * class UserEventSubscriber extends Subscriber {
+ *   override subscribe(events: EventDispatcher): void {
+ *     events.on(UserRegistered, this.onRegistered.bind(this))
+ *     events.on(UserDeleted, this.onDeleted.bind(this))
+ *   }
+ *
+ *   private async onRegistered(event: UserRegistered) { ... }
+ *   private async onDeleted(event: UserDeleted) { ... }
+ * }
+ * ```
+ */
+export abstract class Subscriber {
+  abstract subscribe(events: EventDispatcher): void
+}

package/src/broadcast/BroadcastManager.ts

@@ -0,0 +1,103 @@
+import type { Event } from '@mantiq/core'
+import type { ShouldBroadcast } from '../contracts/ShouldBroadcast.ts'
+import type { Broadcaster } from './Broadcaster.ts'
+import { NullBroadcaster } from './NullBroadcaster.ts'
+import { LogBroadcaster } from './LogBroadcaster.ts'
+import { BroadcastError } from '../errors/EventError.ts'
+
+export interface BroadcastConfig {
+  default: string
+  connections: Record<string, { driver: string; [key: string]: any }>
+}
+
+/**
+ * Manages broadcast drivers and dispatches broadcastable events.
+ *
+ * Supports multiple named connections with pluggable drivers.
+ */
+export class BroadcastManager {
+  private readonly drivers = new Map<string, Broadcaster>()
+  private readonly customCreators = new Map<string, (config: any) => Broadcaster>()
+  private readonly defaultDriver: string
+
+  constructor(private readonly config: BroadcastConfig) {
+    this.defaultDriver = config.default ?? 'null'
+  }
+
+  // ── Driver resolution ────────────────────────────────────────────────
+
+  /**
+   * Get a broadcaster by connection name.
+   */
+  connection(name?: string): Broadcaster {
+    const driverName = name ?? this.defaultDriver
+    if (!this.drivers.has(driverName)) {
+      this.drivers.set(driverName, this.resolve(driverName))
+    }
+    return this.drivers.get(driverName)!
+  }
+
+  /**
+   * Register a custom broadcast driver creator.
+   */
+  extend(name: string, creator: (config: any) => Broadcaster): void {
+    this.customCreators.set(name, creator)
+  }
+
+  // ── Broadcasting ─────────────────────────────────────────────────────
+
+  /**
+   * Broadcast a ShouldBroadcast event through the configured driver.
+   */
+  async broadcast(event: Event & ShouldBroadcast): Promise<void> {
+    const channels = normalizeChannels(event.broadcastOn())
+    const eventName = event.broadcastAs?.() ?? event.constructor.name
+    const data = event.broadcastWith?.() ?? extractPublicProperties(event)
+    const driver = this.connection()
+    await driver.broadcast(channels, eventName, data)
+  }
+
+  /**
+   * Broadcast directly to channels without an event class.
+   */
+  async send(channels: string | string[], event: string, data: Record<string, any>): Promise<void> {
+    const driver = this.connection()
+    await driver.broadcast(normalizeChannels(channels), event, data)
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────
+
+  private resolve(name: string): Broadcaster {
+    const connectionConfig = this.config.connections?.[name]
+    const driverName = connectionConfig?.driver ?? name
+
+    // Check for custom creator
+    const creator = this.customCreators.get(driverName)
+    if (creator) return creator(connectionConfig ?? {})
+
+    // Built-in drivers
+    switch (driverName) {
+      case 'null':
+        return new NullBroadcaster()
+      case 'log':
+        return new LogBroadcaster()
+      default:
+        throw new BroadcastError(`Broadcast driver "${driverName}" is not supported.`, { driver: driverName })
+    }
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function normalizeChannels(channels: string | string[]): string[] {
+  return Array.isArray(channels) ? channels : [channels]
+}
+
+function extractPublicProperties(event: any): Record<string, any> {
+  const data: Record<string, any> = {}
+  for (const key of Object.keys(event)) {
+    if (key === 'timestamp') continue
+    data[key] = event[key]
+  }
+  return data
+}

package/src/broadcast/Broadcaster.ts

@@ -0,0 +1,12 @@
+/**
+ * Contract for broadcast drivers.
+ *
+ * Each driver handles pushing event data to connected clients
+ * through a specific transport (WebSocket, SSE, log, etc.).
+ */
+export interface Broadcaster {
+  /**
+   * Broadcast an event to the given channels.
+   */
+  broadcast(channels: string[], event: string, data: Record<string, any>): Promise<void>
+}

package/src/broadcast/LogBroadcaster.ts

@@ -0,0 +1,10 @@
+import type { Broadcaster } from './Broadcaster.ts'
+
+/**
+ * Logs broadcasts to the console. Useful for development and debugging.
+ */
+export class LogBroadcaster implements Broadcaster {
+  async broadcast(channels: string[], event: string, data: Record<string, any>): Promise<void> {
+    console.log(`[broadcast] ${event} → ${channels.join(', ')}`, data)
+  }
+}

package/src/broadcast/NullBroadcaster.ts

@@ -0,0 +1,10 @@
+import type { Broadcaster } from './Broadcaster.ts'
+
+/**
+ * No-op broadcaster. Used when broadcasting is not configured.
+ */
+export class NullBroadcaster implements Broadcaster {
+  async broadcast(_channels: string[], _event: string, _data: Record<string, any>): Promise<void> {
+    // Intentionally empty — events are silently discarded.
+  }
+}

package/src/contracts/ShouldBroadcast.ts

@@ -0,0 +1,43 @@
+/**
+ * Implement this interface on an Event class to mark it as broadcastable.
+ *
+ * When the event is dispatched via `emit()`, the broadcast manager
+ * will push the event data to all clients subscribed to the channels
+ * returned by `broadcastOn()`.
+ *
+ * ```typescript
+ * class OrderShipped extends Event implements ShouldBroadcast {
+ *   constructor(public order: Order) { super() }
+ *
+ *   broadcastOn() {
+ *     return ['private:orders.' + this.order.id]
+ *   }
+ *
+ *   broadcastWith() {
+ *     return { orderId: this.order.id, status: 'shipped' }
+ *   }
+ * }
+ * ```
+ */
+export interface ShouldBroadcast {
+  /**
+   * The channel(s) the event should broadcast on.
+   */
+  broadcastOn(): string | string[]
+
+  /**
+   * Custom event name for the broadcast. Defaults to the class name.
+   */
+  broadcastAs?(): string
+
+  /**
+   * Custom payload for the broadcast. Defaults to all public properties.
+   */
+  broadcastWith?(): Record<string, any>
+}
+
+/**
+ * Implement this interface to broadcast synchronously (skip the queue).
+ * Identical to ShouldBroadcast but signals the system to bypass queuing.
+ */
+export interface ShouldBroadcastNow extends ShouldBroadcast {}

package/src/errors/EventError.ts

@@ -0,0 +1,29 @@
+import { MantiqError } from '@mantiq/core'
+
+export class EventError extends MantiqError {
+  constructor(message: string, context?: Record<string, any>) {
+    super(message, context)
+    this.name = 'EventError'
+  }
+}
+
+export class ListenerError extends MantiqError {
+  constructor(
+    public readonly eventName: string,
+    public readonly listenerName: string,
+    public override readonly cause?: Error,
+  ) {
+    super(`Listener "${listenerName}" failed while handling "${eventName}": ${cause?.message ?? 'unknown error'}`, {
+      event: eventName,
+      listener: listenerName,
+    })
+    this.name = 'ListenerError'
+  }
+}
+
+export class BroadcastError extends MantiqError {
+  constructor(message: string, context?: Record<string, any>) {
+    super(message, context)
+    this.name = 'BroadcastError'
+  }
+}

package/src/helpers/broadcast.ts

@@ -0,0 +1,24 @@
+import { Application } from '@mantiq/core'
+import type { BroadcastManager } from '../broadcast/BroadcastManager.ts'
+
+export const BROADCAST_MANAGER = Symbol('BroadcastManager')
+
+/**
+ * Broadcast data directly to channels without an event class.
+ *
+ * ```typescript
+ * import { broadcast } from '@mantiq/events'
+ *
+ * await broadcast('private:orders.' + order.id, 'status-updated', {
+ *   status: 'shipped',
+ * })
+ * ```
+ */
+export async function broadcast(
+  channels: string | string[],
+  event: string,
+  data: Record<string, any>,
+): Promise<void> {
+  const manager = Application.getInstance().make<BroadcastManager>(BROADCAST_MANAGER)
+  return manager.send(channels, event, data)
+}

package/src/helpers/emit.ts

@@ -0,0 +1,32 @@
+import { Application, Event } from '@mantiq/core'
+import type { Dispatcher } from '../Dispatcher.ts'
+
+export const EVENT_DISPATCHER = Symbol('EventDispatcher')
+
+/**
+ * Dispatch an event through the global event dispatcher.
+ *
+ * ```typescript
+ * import { emit } from '@mantiq/events'
+ *
+ * await emit(new UserRegistered(user))
+ * ```
+ */
+export async function emit(event: Event): Promise<void> {
+  const dispatcher = Application.getInstance().make<Dispatcher>(EVENT_DISPATCHER)
+  return dispatcher.emit(event)
+}
+
+/**
+ * Get the event dispatcher instance.
+ *
+ * ```typescript
+ * import { events } from '@mantiq/events'
+ *
+ * const dispatcher = events()
+ * dispatcher.on(UserRegistered, SendWelcomeEmail)
+ * ```
+ */
+export function events(): Dispatcher {
+  return Application.getInstance().make<Dispatcher>(EVENT_DISPATCHER)
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// @mantiq/events — public API exports
+
+// ── Re-exports from @mantiq/core (convenience) ────────────────────────────
+export { Event, Listener } from '@mantiq/core'
+export type { EventDispatcher, EventHandler } from '@mantiq/core'
+
+// ── Dispatcher ────────────────────────────────────────────────────────────
+export { Dispatcher } from './Dispatcher.ts'
+
+// ── Subscriber ────────────────────────────────────────────────────────────
+export { Subscriber } from './Subscriber.ts'
+
+// ── Contracts ─────────────────────────────────────────────────────────────
+export type { ShouldBroadcast, ShouldBroadcastNow } from './contracts/ShouldBroadcast.ts'
+export type { Broadcaster } from './broadcast/Broadcaster.ts'
+
+// ── Broadcasting ──────────────────────────────────────────────────────────
+export { BroadcastManager } from './broadcast/BroadcastManager.ts'
+export type { BroadcastConfig } from './broadcast/BroadcastManager.ts'
+export { NullBroadcaster } from './broadcast/NullBroadcaster.ts'
+export { LogBroadcaster } from './broadcast/LogBroadcaster.ts'
+
+// ── Model Events ──────────────────────────────────────────────────────────
+export type { ModelObserver } from './model/Observer.ts'
+export type { ModelEventName } from './model/ModelEvents.ts'
+export { ModelEventDispatcher } from './model/ModelEventDispatcher.ts'
+export {
+  fireModelEvent,
+  observe,
+  onModelEvent,
+  flushModelEvents,
+  bootModelEvents,
+  getModelDispatcher,
+} from './model/HasEvents.ts'
+
+// ── Errors ────────────────────────────────────────────────────────────────
+export { EventError, ListenerError, BroadcastError } from './errors/EventError.ts'
+
+// ── Service Provider ──────────────────────────────────────────────────────
+export { EventServiceProvider } from './EventServiceProvider.ts'
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+export { emit, events, EVENT_DISPATCHER } from './helpers/emit.ts'
+export { broadcast, BROADCAST_MANAGER } from './helpers/broadcast.ts'
+
+// ── Testing ───────────────────────────────────────────────────────────────
+export { EventFake } from './testing/EventFake.ts'
+export { BroadcastFake } from './testing/BroadcastFake.ts'

package/src/model/HasEvents.ts

@@ -0,0 +1,107 @@
+import { ModelEventDispatcher } from './ModelEventDispatcher.ts'
+import type { ModelObserver } from './Observer.ts'
+import type { ModelEventName } from './ModelEvents.ts'
+
+type ModelEventCallback = (model: any) => boolean | void | Promise<boolean | void>
+
+/**
+ * Adds model event support to a Model class.
+ *
+ * Call `bootModelEvents(ModelClass)` to set up event methods on a model constructor.
+ * This adds `observe()`, `creating()`, `created()`, etc. as static methods,
+ * and provides `fireModelEvent()` as an instance method.
+ *
+ * This is designed to be called from the EventServiceProvider's boot()
+ * to augment the Model class from `@mantiq/database`.
+ */
+
+const dispatchers = new WeakMap<Function, ModelEventDispatcher>()
+
+/**
+ * Get or create the event dispatcher for a model constructor.
+ */
+export function getModelDispatcher(modelClass: Function): ModelEventDispatcher {
+  if (!dispatchers.has(modelClass)) {
+    dispatchers.set(modelClass, new ModelEventDispatcher())
+  }
+  return dispatchers.get(modelClass)!
+}
+
+/**
+ * Fire a model event. Returns `false` if a cancellable event was cancelled.
+ */
+export async function fireModelEvent(model: any, event: ModelEventName): Promise<boolean> {
+  const ctor = model.constructor
+  const dispatcher = dispatchers.get(ctor)
+  if (!dispatcher) return true
+  return dispatcher.fire(event, model)
+}
+
+/**
+ * Register an observer for a model class.
+ */
+export function observe(modelClass: Function, observer: ModelObserver | (new () => ModelObserver)): void {
+  const instance = typeof observer === 'function' ? new observer() : observer
+  getModelDispatcher(modelClass).addObserver(instance)
+}
+
+/**
+ * Register a callback for a model event.
+ */
+export function onModelEvent(modelClass: Function, event: ModelEventName, callback: ModelEventCallback): void {
+  getModelDispatcher(modelClass).addCallback(event, callback)
+}
+
+/**
+ * Flush all event listeners for a model class.
+ */
+export function flushModelEvents(modelClass: Function): void {
+  const dispatcher = dispatchers.get(modelClass)
+  if (dispatcher) dispatcher.flush()
+}
+
+/**
+ * Boot model event support on a Model class by adding static methods.
+ *
+ * After calling this, the model class gains:
+ * - `Model.observe(ObserverClass)`
+ * - `Model.creating(callback)`
+ * - `Model.created(callback)`
+ * - `Model.updating(callback)` / `Model.updated(callback)`
+ * - `Model.saving(callback)` / `Model.saved(callback)`
+ * - `Model.deleting(callback)` / `Model.deleted(callback)`
+ * - `Model.restoring(callback)` / `Model.restored(callback)`
+ * - `Model.forceDeleting(callback)` / `Model.forceDeleted(callback)`
+ * - `Model.trashed(callback)`
+ * - `Model.retrieved(callback)`
+ * - `Model.flushEventListeners()`
+ */
+export function bootModelEvents(ModelClass: any): void {
+  // observe()
+  ModelClass.observe = function (observer: ModelObserver | (new () => ModelObserver)): void {
+    observe(this, observer)
+  }
+
+  // flushEventListeners()
+  ModelClass.flushEventListeners = function (): void {
+    flushModelEvents(this)
+  }
+
+  // Event shortcut methods
+  const events: ModelEventName[] = [
+    'retrieved',
+    'creating', 'created',
+    'updating', 'updated',
+    'saving', 'saved',
+    'deleting', 'deleted',
+    'forceDeleting', 'forceDeleted',
+    'restoring', 'restored',
+    'trashed',
+  ]
+
+  for (const event of events) {
+    ModelClass[event] = function (callback: ModelEventCallback): void {
+      onModelEvent(this, event, callback)
+    }
+  }
+}

package/src/model/ModelEventDispatcher.ts

@@ -0,0 +1,98 @@
+import type { ModelObserver } from './Observer.ts'
+import type { ModelEventName } from './ModelEvents.ts'
+import { isCancellable } from './ModelEvents.ts'
+
+type ModelEventCallback = (model: any) => boolean | void | Promise<boolean | void>
+
+/**
+ * Per-model event dispatcher.
+ *
+ * Manages observers and callbacks for a single model class.
+ * Each model class gets its own instance stored on the model constructor.
+ *
+ * ```typescript
+ * // Register an observer
+ * User.observe(UserObserver)
+ *
+ * // Register an inline callback
+ * User.creating((user) => {
+ *   user.set('slug', slugify(user.get('name')))
+ * })
+ * ```
+ */
+export class ModelEventDispatcher {
+  private readonly observers: ModelObserver[] = []
+  private readonly callbacks = new Map<ModelEventName, ModelEventCallback[]>()
+
+  // ── Registration ─────────────────────────────────────────────────────
+
+  /**
+   * Register an observer class instance.
+   */
+  addObserver(observer: ModelObserver): void {
+    this.observers.push(observer)
+  }
+
+  /**
+   * Register a callback for a specific event.
+   */
+  addCallback(event: ModelEventName, callback: ModelEventCallback): void {
+    const existing = this.callbacks.get(event) ?? []
+    existing.push(callback)
+    this.callbacks.set(event, existing)
+  }
+
+  /**
+   * Check if any observers or callbacks are registered for an event.
+   */
+  hasListeners(event: ModelEventName): boolean {
+    const hasCallbacks = (this.callbacks.get(event)?.length ?? 0) > 0
+    const hasObservers = this.observers.some((o) => typeof (o as any)[event] === 'function')
+    return hasCallbacks || hasObservers
+  }
+
+  // ── Dispatching ──────────────────────────────────────────────────────
+
+  /**
+   * Fire a model event. For cancellable events, returns `false` if
+   * any listener returns `false` (which cancels the operation).
+   */
+  async fire(event: ModelEventName, model: any): Promise<boolean> {
+    const cancellable = isCancellable(event)
+
+    // Fire observer methods
+    for (const observer of this.observers) {
+      const method = (observer as any)[event]
+      if (typeof method === 'function') {
+        const result = await method.call(observer, model)
+        if (cancellable && result === false) return false
+      }
+    }
+
+    // Fire registered callbacks
+    const callbacks = this.callbacks.get(event) ?? []
+    for (const callback of callbacks) {
+      const result = await callback(model)
+      if (cancellable && result === false) return false
+    }
+
+    return true
+  }
+
+  // ── Cleanup ──────────────────────────────────────────────────────────
+
+  /**
+   * Remove all observers and callbacks.
+   */
+  flush(): void {
+    this.observers.length = 0
+    this.callbacks.clear()
+  }
+
+  /**
+   * Remove callbacks for a specific event.
+   */
+  forgetEvent(event: ModelEventName): void {
+    this.callbacks.delete(event)
+  }
+}

package/src/model/ModelEvents.ts

@@ -0,0 +1,38 @@
+/**
+ * All supported model lifecycle event names.
+ *
+ * "Before" events (creating, updating, saving, deleting, restoring)
+ * can return `false` from a listener to cancel the operation.
+ *
+ * "After" events (created, updated, saved, deleted, restored, retrieved)
+ * are informational and cannot cancel anything.
+ */
+export type ModelEventName =
+  | 'retrieved'
+  | 'creating'
+  | 'created'
+  | 'updating'
+  | 'updated'
+  | 'saving'
+  | 'saved'
+  | 'deleting'
+  | 'deleted'
+  | 'forceDeleting'
+  | 'forceDeleted'
+  | 'restoring'
+  | 'restored'
+  | 'trashed'
+
+/** "Before" events that can be cancelled by returning false. */
+export const CANCELLABLE_EVENTS: ModelEventName[] = [
+  'creating',
+  'updating',
+  'saving',
+  'deleting',
+  'forceDeleting',
+  'restoring',
+]
+
+export function isCancellable(event: ModelEventName): boolean {
+  return CANCELLABLE_EVENTS.includes(event)
+}

package/src/model/Observer.ts

@@ -0,0 +1,41 @@
+/**
+ * A model observer handles lifecycle events for a model.
+ *
+ * Implement any subset of these methods. Methods matching "before" events
+ * (creating, updating, saving, deleting, restoring, forceDeleting) can
+ * return `false` to cancel the operation.
+ *
+ * ```typescript
+ * class UserObserver implements ModelObserver {
+ *   creating(model: User): boolean | void {
+ *     // Normalize email before saving
+ *     model.set('email', model.get('email').toLowerCase())
+ *   }
+ *
+ *   created(model: User): void {
+ *     // Send welcome email
+ *   }
+ *
+ *   deleting(model: User): boolean | void {
+ *     // Prevent deletion of admin users
+ *     if (model.get('role') === 'admin') return false
+ *   }
+ * }
+ * ```
+ */
+export interface ModelObserver {
+  retrieved?(model: any): void | Promise<void>
+  creating?(model: any): boolean | void | Promise<boolean | void>
+  created?(model: any): void | Promise<void>
+  updating?(model: any): boolean | void | Promise<boolean | void>
+  updated?(model: any): void | Promise<void>
+  saving?(model: any): boolean | void | Promise<boolean | void>
+  saved?(model: any): void | Promise<void>
+  deleting?(model: any): boolean | void | Promise<boolean | void>
+  deleted?(model: any): void | Promise<void>
+  forceDeleting?(model: any): boolean | void | Promise<boolean | void>
+  forceDeleted?(model: any): void | Promise<void>
+  restoring?(model: any): boolean | void | Promise<boolean | void>
+  restored?(model: any): void | Promise<void>
+  trashed?(model: any): void | Promise<void>
+}

package/src/testing/BroadcastFake.ts

@@ -0,0 +1,107 @@
+import type { Event } from '@mantiq/core'
+import type { ShouldBroadcast } from '../contracts/ShouldBroadcast.ts'
+import type { BroadcastManager } from '../broadcast/BroadcastManager.ts'
+
+interface BroadcastRecord {
+  channels: string[]
+  event: string
+  data: Record<string, any>
+}
+
+/**
+ * A fake broadcast manager for testing.
+ *
+ * Records all broadcasts without actually sending them.
+ * Provides assertion methods for verifying broadcasts.
+ *
+ * ```typescript
+ * const fake = new BroadcastFake()
+ * dispatcher.setBroadcaster(fake as any)
+ *
+ * await emit(new OrderShipped(order))
+ *
+ * fake.assertBroadcast('OrderShipped')
+ * fake.assertBroadcastOn('private:orders.1', 'OrderShipped')
+ * ```
+ */
+export class BroadcastFake {
+  private readonly broadcasts: BroadcastRecord[] = []
+
+  // ── BroadcastManager-compatible methods ──────────────────────────────
+
+  async broadcast(event: Event & ShouldBroadcast): Promise<void> {
+    const channels = normalizeChannels(event.broadcastOn())
+    const eventName = event.broadcastAs?.() ?? event.constructor.name
+    const data = event.broadcastWith?.() ?? extractPublicProperties(event)
+    this.broadcasts.push({ channels, event: eventName, data })
+  }
+
+  async send(channels: string | string[], event: string, data: Record<string, any>): Promise<void> {
+    this.broadcasts.push({ channels: normalizeChannels(channels), event, data })
+  }
+
+  // ── Assertions ───────────────────────────────────────────────────────
+
+  assertBroadcast(eventName: string, predicate?: (data: Record<string, any>) => boolean): void {
+    const matched = this.broadcasts.filter(
+      (b) => b.event === eventName && (!predicate || predicate(b.data)),
+    )
+    if (matched.length === 0) {
+      throw new Error(`Expected [${eventName}] to be broadcast, but it was not.`)
+    }
+  }
+
+  assertBroadcastOn(channel: string, eventName: string): void {
+    const matched = this.broadcasts.filter(
+      (b) => b.event === eventName && b.channels.includes(channel),
+    )
+    if (matched.length === 0) {
+      throw new Error(
+        `Expected [${eventName}] to be broadcast on channel "${channel}", but it was not.`,
+      )
+    }
+  }
+
+  assertNotBroadcast(eventName: string): void {
+    const matched = this.broadcasts.filter((b) => b.event === eventName)
+    if (matched.length > 0) {
+      throw new Error(`Unexpected [${eventName}] was broadcast.`)
+    }
+  }
+
+  assertNothingBroadcast(): void {
+    if (this.broadcasts.length > 0) {
+      const names = [...new Set(this.broadcasts.map((b) => b.event))]
+      throw new Error(`Expected no broadcasts, but the following were broadcast: ${names.join(', ')}`)
+    }
+  }
+
+  /**
+   * Get all recorded broadcasts.
+   */
+  all(): BroadcastRecord[] {
+    return [...this.broadcasts]
+  }
+
+  /**
+   * Clear the recorded broadcasts.
+   */
+  reset(): void {
+    this.broadcasts.length = 0
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function normalizeChannels(channels: string | string[]): string[] {
+  return Array.isArray(channels) ? channels : [channels]
+}
+
+function extractPublicProperties(event: any): Record<string, any> {
+  const data: Record<string, any> = {}
+  for (const key of Object.keys(event)) {
+    if (key === 'timestamp') continue
+    data[key] = event[key]
+  }
+  return data
+}

package/src/testing/EventFake.ts

@@ -0,0 +1,158 @@
+import type { Constructor, EventDispatcher, EventHandler } from '@mantiq/core'
+import { Event, Listener } from '@mantiq/core'
+
+type RegisteredListener = Constructor<Listener> | EventHandler
+
+/**
+ * A fake event dispatcher for testing.
+ *
+ * Replaces the real dispatcher to record all emitted events
+ * without executing any listeners. Provides assertion methods
+ * for verifying that events were (or were not) dispatched.
+ *
+ * ```typescript
+ * const fake = EventFake.create()
+ *
+ * await someService.doWork()
+ *
+ * fake.assertEmitted(UserCreated)
+ * fake.assertEmittedTimes(UserCreated, 1)
+ * fake.assertNotEmitted(UserDeleted)
+ * ```
+ */
+export class EventFake implements EventDispatcher {
+  private readonly emitted: Event[] = []
+  private readonly eventsToFake: Set<Constructor<Event>> | null
+  private readonly original: EventDispatcher | null
+
+  constructor(original?: EventDispatcher, eventsToFake?: Constructor<Event>[]) {
+    this.original = original ?? null
+    this.eventsToFake = eventsToFake ? new Set(eventsToFake) : null
+  }
+
+  /**
+   * Create a new EventFake, optionally wrapping an existing dispatcher.
+   * If `eventsToFake` is provided, only those events are faked — all
+   * others pass through to the original dispatcher.
+   */
+  static create(original?: EventDispatcher, eventsToFake?: Constructor<Event>[]): EventFake {
+    return new EventFake(original, eventsToFake)
+  }
+
+  // ── EventDispatcher interface ────────────────────────────────────────
+
+  on(eventClass: Constructor<Event>, listener: RegisteredListener): void {
+    // When faking, listener registration is ignored for faked events.
+    if (this.shouldFake(eventClass)) return
+    this.original?.on(eventClass, listener)
+  }
+
+  forget(eventClass: Constructor<Event>): void {
+    this.original?.forget(eventClass)
+  }
+
+  async emit(event: Event): Promise<void> {
+    const eventClass = event.constructor as Constructor<Event>
+
+    if (this.shouldFake(eventClass)) {
+      this.emitted.push(event)
+      return
+    }
+
+    // Pass through to original if not faking this event
+    if (this.original) {
+      await this.original.emit(event)
+    }
+  }
+
+  // ── Assertions ───────────────────────────────────────────────────────
+
+  /**
+   * Assert that an event was emitted at least once.
+   * Optionally pass a predicate to check specific event data.
+   */
+  assertEmitted<T extends Event>(
+    eventClass: Constructor<T>,
+    predicate?: (event: T) => boolean,
+  ): void {
+    const matched = this.getEmitted(eventClass).filter((e) => !predicate || predicate(e))
+    if (matched.length === 0) {
+      const msg = predicate
+        ? `Expected [${eventClass.name}] to be emitted matching the given predicate, but it was not.`
+        : `Expected [${eventClass.name}] to be emitted, but it was not.`
+      throw new Error(msg)
+    }
+  }
+
+  /**
+   * Assert that an event was emitted exactly N times.
+   */
+  assertEmittedTimes<T extends Event>(eventClass: Constructor<T>, count: number): void {
+    const actual = this.getEmitted(eventClass).length
+    if (actual !== count) {
+      throw new Error(
+        `Expected [${eventClass.name}] to be emitted ${count} time(s), but it was emitted ${actual} time(s).`,
+      )
+    }
+  }
+
+  /**
+   * Assert that an event was NOT emitted.
+   */
+  assertNotEmitted<T extends Event>(
+    eventClass: Constructor<T>,
+    predicate?: (event: T) => boolean,
+  ): void {
+    const matched = this.getEmitted(eventClass).filter((e) => !predicate || predicate(e))
+    if (matched.length > 0) {
+      throw new Error(`Unexpected [${eventClass.name}] was emitted.`)
+    }
+  }
+
+  /**
+   * Assert that no events were emitted at all.
+   */
+  assertNothingEmitted(): void {
+    if (this.emitted.length > 0) {
+      const names = [...new Set(this.emitted.map((e) => e.constructor.name))]
+      throw new Error(`Expected no events to be emitted, but the following were: ${names.join(', ')}`)
+    }
+  }
+
+  // ── Querying ─────────────────────────────────────────────────────────
+
+  /**
+   * Get all emitted instances of a given event class.
+   */
+  getEmitted<T extends Event>(eventClass: Constructor<T>): T[] {
+    return this.emitted.filter((e) => e instanceof eventClass) as T[]
+  }
+
+  /**
+   * Check if an event was emitted.
+   */
+  hasEmitted<T extends Event>(eventClass: Constructor<T>): boolean {
+    return this.getEmitted(eventClass).length > 0
+  }
+
+  /**
+   * Get all emitted events.
+   */
+  all(): Event[] {
+    return [...this.emitted]
+  }
+
+  /**
+   * Clear the recorded events.
+   */
+  reset(): void {
+    this.emitted.length = 0
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────
+
+  private shouldFake(eventClass: Constructor<Event>): boolean {
+    if (this.eventsToFake === null) return true
+    return this.eventsToFake.has(eventClass)
+  }
+}