Model Observers

Organize model event handling with observer classes

What are Model Observers?

Model observers are dedicated classes that handle model events. Instead of putting all event logic directly in your models, observers provide a clean, organized way to separate concerns and make your code more maintainable.

Real-world analogy: Think of observers like specialized staff at a hotel. Instead of the front desk handling everything (check-in, luggage, room service, maintenance), you have dedicated staff for each area. The bellhop observes guest arrivals, the housekeeper observes checkouts, and the concierge observes special requests.

Creating Observers

Using the CLI

# Create an observer
npx ilana make:observer UserObserver

# Create observer for specific model
npx ilana make:observer UserObserver --model=User

Basic Observer Structure

// observers/UserObserver.js
class UserObserver {
  async creating(user) {
    // Logic before creating user
    user.email = user.email.toLowerCase().trim();
    
    if (!user.uuid) {
      user.uuid = this.generateUuid();
    }
  }
  
  async created(user) {
    // Logic after creating user
    await this.sendWelcomeEmail(user);
    await this.createUserProfile(user);
  }
  
  async updating(user) {
    // Logic before updating user
    if (user.isDirty('email')) {
      user.email_verified_at = null;
    }
  }
  
  async updated(user) {
    // Logic after updating user
    await this.clearUserCache(user);
    await this.syncUserData(user);
  }
  
  async deleting(user) {
    // Logic before deleting user
    await this.cleanupUserData(user);
  }
  
  async deleted(user) {
    // Logic after deleting user
    await this.removeUserFiles(user);
    await this.notifyAdmins(user);
  }
  
  // Helper methods
  generateUuid() {
    return require('crypto').randomUUID();
  }
  
  async sendWelcomeEmail(user) {
    const emailService = require('../services/EmailService');
    await emailService.sendWelcome(user.email, user.name);
  }
  
  async createUserProfile(user) {
    await user.profile().create({
      bio: '',
      avatar: null,
      preferences: {},
    });
  }
  
  async clearUserCache(user) {
    const cache = require('../services/CacheService');
    await cache.forget(`user:${user.id}`);
  }
  
  async syncUserData(user) {
    const syncService = require('../services/SyncService');
    await syncService.syncUser(user);
  }
  
  async cleanupUserData(user) {
    // Delete user's posts, comments, etc.
    await user.posts().delete();
    await user.comments().delete();
  }
  
  async removeUserFiles(user) {
    const fileService = require('../services/FileService');
    await fileService.removeUserFiles(user.id);
  }
  
  async notifyAdmins(user) {
    const notificationService = require('../services/NotificationService');
    await notificationService.notifyAdmins(`User ${user.email} deleted their account`);
  }
}

module.exports = UserObserver;

Registering Observers

Single Observer Registration

// In your model or bootstrap file
const User = require('./models/User');
const UserObserver = require('./observers/UserObserver');

// Register the observer
User.observe(UserObserver);

Multiple Observer Registration

// Register multiple observers for the same model
const User = require('./models/User');
const UserObserver = require('./observers/UserObserver');
const AuditObserver = require('./observers/AuditObserver');
const EmailObserver = require('./observers/EmailObserver');

User.observe(UserObserver);
User.observe(AuditObserver);
User.observe(EmailObserver);

Service Provider Pattern

// providers/ObserverServiceProvider.js
const User = require('../models/User');
const Post = require('../models/Post');
const Order = require('../models/Order');

const UserObserver = require('../observers/UserObserver');
const PostObserver = require('../observers/PostObserver');
const OrderObserver = require('../observers/OrderObserver');
const AuditObserver = require('../observers/AuditObserver');

class ObserverServiceProvider {
  static register() {
    // Register model-specific observers
    User.observe(UserObserver);
    Post.observe(PostObserver);
    Order.observe(OrderObserver);
    
    // Register cross-cutting observers
    User.observe(AuditObserver);
    Post.observe(AuditObserver);
    Order.observe(AuditObserver);
    
    console.log('All observers registered successfully');
  }
}

module.exports = ObserverServiceProvider;

// In your app.js or index.js
const ObserverServiceProvider = require('./providers/ObserverServiceProvider');
ObserverServiceProvider.register();

Advanced Observer Patterns

Conditional Observer Logic

// observers/PostObserver.js
class PostObserver {
  async updating(post) {
    // Only run logic if status changed
    if (post.isDirty('status')) {
      await this.handleStatusChange(post);
    }
    
    // Only run if content changed
    if (post.isDirty('content')) {
      post.reading_time = this.calculateReadingTime(post.content);
      post.word_count = this.countWords(post.content);
    }
    
    // Only run if title changed
    if (post.isDirty('title') && !post.slug) {
      post.slug = this.generateSlug(post.title);
    }
  }
  
  async updated(post) {
    // Handle different types of updates
    const changes = post.getChanges();
    
    if (changes.status) {
      await this.handleStatusUpdate(post, changes.status);
    }
    
    if (changes.featured_image) {
      await this.processImage(post.featured_image);
    }
    
    if (changes.category_id) {
      await this.updateCategoryStats(changes.category_id);
    }
  }
  
  async handleStatusChange(post) {
    switch (post.status) {
      case 'published':
        post.published_at = new Date();
        break;
      case 'draft':
        post.published_at = null;
        break;
      case 'archived':
        post.archived_at = new Date();
        break;
    }
  }
  
  async handleStatusUpdate(post, newStatus) {
    switch (newStatus) {
      case 'published':
        await this.notifySubscribers(post);
        await this.addToSearchIndex(post);
        break;
      case 'unpublished':
        await this.removeFromSearchIndex(post);
        break;
    }
  }
  
  calculateReadingTime(content) {
    const wordsPerMinute = 200;
    const wordCount = this.countWords(content);
    return Math.ceil(wordCount / wordsPerMinute);
  }
  
  countWords(content) {
    return content.trim().split(/\s+/).length;
  }
  
  generateSlug(title) {
    return title
      .toLowerCase()
      .replace(/[^a-z0-9]+/g, '-')
      .replace(/^-|-$/g, '');
  }
}

Cross-Model Observer

// observers/AuditObserver.js
class AuditObserver {
  async created(model) {
    await this.logActivity({
      model_type: model.constructor.name,
      model_id: model.id,
      action: 'created',
      data: this.sanitizeData(model.toJSON()),
      user_id: this.getCurrentUserId(),
    });
  }
  
  async updated(model) {
    const changes = model.getChanges();
    
    await this.logActivity({
      model_type: model.constructor.name,
      model_id: model.id,
      action: 'updated',
      changes: this.sanitizeData(changes),
      original: this.sanitizeData(model.getOriginal()),
      user_id: this.getCurrentUserId(),
    });
  }
  
  async deleted(model) {
    await this.logActivity({
      model_type: model.constructor.name,
      model_id: model.id,
      action: 'deleted',
      data: this.sanitizeData(model.toJSON()),
      user_id: this.getCurrentUserId(),
    });
  }
  
  async logActivity(data) {
    const AuditLog = require('../models/AuditLog');
    
    await AuditLog.create({
      ...data,
      ip_address: this.getCurrentIpAddress(),
      user_agent: this.getCurrentUserAgent(),
      timestamp: new Date(),
    });
  }
  
  sanitizeData(data) {
    // Remove sensitive fields
    const sensitiveFields = ['password', 'token', 'secret', 'key'];
    const sanitized = { ...data };
    
    sensitiveFields.forEach(field => {
      if (sanitized[field]) {
        sanitized[field] = '[REDACTED]';
      }
    });
    
    return sanitized;
  }
  
  getCurrentUserId() {
    // Get from request context or auth service
    const authService = require('../services/AuthService');
    return authService.getCurrentUserId();
  }
  
  getCurrentIpAddress() {
    const requestContext = require('../services/RequestContext');
    return requestContext.getIpAddress();
  }
  
  getCurrentUserAgent() {
    const requestContext = require('../services/RequestContext');
    return requestContext.getUserAgent();
  }
}

module.exports = AuditObserver;

Event-Specific Observers

// observers/EmailObserver.js
class EmailObserver {
  async created(model) {
    // Handle different model types
    switch (model.constructor.name) {
      case 'User':
        await this.sendWelcomeEmail(model);
        break;
      case 'Order':
        await this.sendOrderConfirmation(model);
        break;
      case 'Post':
        await this.notifyFollowers(model);
        break;
    }
  }
  
  async updated(model) {
    switch (model.constructor.name) {
      case 'Order':
        if (model.wasChanged('status')) {
          await this.sendOrderStatusUpdate(model);
        }
        break;
      case 'User':
        if (model.wasChanged('email')) {
          await this.sendEmailChangeNotification(model);
        }
        break;
    }
  }
  
  async sendWelcomeEmail(user) {
    const emailService = require('../services/EmailService');
    
    await emailService.send({
      to: user.email,
      subject: 'Welcome to our platform!',
      template: 'welcome',
      data: {
        name: user.name,
        login_url: process.env.APP_URL + '/login',
      },
    });
  }
  
  async sendOrderConfirmation(order) {
    await order.load('user', 'items.product');
    
    const emailService = require('../services/EmailService');
    
    await emailService.send({
      to: order.user.email,
      subject: `Order Confirmation #${order.id}`,
      template: 'order-confirmation',
      data: {
        order: order.toJSON(),
        customer_name: order.user.name,
      },
    });
  }
  
  async sendOrderStatusUpdate(order) {
    await order.load('user');
    
    const emailService = require('../services/EmailService');
    
    await emailService.send({
      to: order.user.email,
      subject: `Order #${order.id} Status Update`,
      template: 'order-status-update',
      data: {
        order_id: order.id,
        status: order.status,
        customer_name: order.user.name,
      },
    });
  }
}

Observer Dependencies and Services

Dependency Injection

// observers/UserObserver.js
class UserObserver {
  constructor(emailService, cacheService, auditService) {
    this.emailService = emailService;
    this.cacheService = cacheService;
    this.auditService = auditService;
  }
  
  async created(user) {
    await this.emailService.sendWelcome(user);
    await this.auditService.log('user_created', user);
  }
  
  async updated(user) {
    await this.cacheService.forget(`user:${user.id}`);
    await this.auditService.log('user_updated', user);
  }
}

// Register with dependencies
const EmailService = require('../services/EmailService');
const CacheService = require('../services/CacheService');
const AuditService = require('../services/AuditService');

const userObserver = new UserObserver(
  new EmailService(),
  new CacheService(),
  new AuditService()
);

User.observe(userObserver);

Service Locator Pattern

// services/ServiceContainer.js
class ServiceContainer {
  static services = new Map();
  
  static register(name, service) {
    this.services.set(name, service);
  }
  
  static get(name) {
    if (!this.services.has(name)) {
      throw new Error(`Service ${name} not found`);
    }
    return this.services.get(name);
  }
}

// Register services
ServiceContainer.register('email', new EmailService());
ServiceContainer.register('cache', new CacheService());
ServiceContainer.register('audit', new AuditService());

// observers/UserObserver.js
class UserObserver {
  get emailService() {
    return ServiceContainer.get('email');
  }
  
  get cacheService() {
    return ServiceContainer.get('cache');
  }
  
  get auditService() {
    return ServiceContainer.get('audit');
  }
  
  async created(user) {
    await this.emailService.sendWelcome(user);
    await this.auditService.log('user_created', user);
  }
  
  async updated(user) {
    await this.cacheService.forget(`user:${user.id}`);
    await this.auditService.log('user_updated', user);
  }
}

Testing Observers

Unit Testing Observers

// test/observers/UserObserver.test.js
const UserObserver = require('../../observers/UserObserver');
const User = require('../../models/User');

// Mock services
const mockEmailService = {
  sendWelcome: jest.fn(),
};

const mockCacheService = {
  forget: jest.fn(),
};

describe('UserObserver', () => {
  let observer;
  let user;
  
  beforeEach(() => {
    observer = new UserObserver(mockEmailService, mockCacheService);
    user = new User({
      id: 1,
      name: 'Test User',
      email: '[e-mail]',
    });
    
    // Clear mocks
    jest.clearAllMocks();
  });
  
  describe('created', () => {
    test('sends welcome email', async () => {
      await observer.created(user);
      
      expect(mockEmailService.sendWelcome).toHaveBeenCalledWith(user);
    });
  });
  
  describe('updated', () => {
    test('clears user cache', async () => {
      await observer.updated(user);
      
      expect(mockCacheService.forget).toHaveBeenCalledWith('user:1');
    });
  });
  
  describe('creating', () => {
    test('normalizes email', async () => {
      user.email = '  [e-mail]  ';
      
      await observer.creating(user);
      
      expect(user.email).toBe('[e-mail]');
    });
    
    test('generates UUID if not provided', async () => {
      expect(user.uuid).toBeUndefined();
      
      await observer.creating(user);
      
      expect(user.uuid).toBeDefined();
      expect(typeof user.uuid).toBe('string');
    });
  });
});

Integration Testing

// test/integration/UserObserver.integration.test.js
const User = require('../../models/User');
const UserObserver = require('../../observers/UserObserver');

describe('UserObserver Integration', () => {
  beforeEach(async () => {
    // Register observer
    User.observe(UserObserver);
    
    // Clear database
    await User.query().delete();
  });
  
  test('observer fires on user creation', async () => {
    const emailSpy = jest.spyOn(require('../../services/EmailService'), 'sendWelcome');
    
    const user = await User.create({
      name: 'Test User',
      email: '  [e-mail]  ',
    });
    
    // Check that observer normalized email
    expect(user.email).toBe('[e-mail]');
    
    // Check that observer generated UUID
    expect(user.uuid).toBeDefined();
    
    // Check that observer sent welcome email
    expect(emailSpy).toHaveBeenCalledWith(user);
    
    emailSpy.mockRestore();
  });
  
  test('observer fires on user update', async () => {
    const cacheSpy = jest.spyOn(require('../../services/CacheService'), 'forget');
    
    const user = await User.create({
      name: 'Test User',
      email: '[e-mail]',
    });
    
    await user.update({ name: 'Updated Name' });
    
    expect(cacheSpy).toHaveBeenCalledWith(`user:${user.id}`);
    
    cacheSpy.mockRestore();
  });
});

Observer Test Helpers

// test/helpers/ObserverTestHelper.js
class ObserverTestHelper {
  static observerCalls = [];
  
  static mockObserver(modelClass, methods = []) {
    const originalObservers = modelClass._observers || [];
    
    const mockObserver = {};
    methods.forEach(method => {
      mockObserver[method] = jest.fn(async (model) => {
        this.observerCalls.push({
          method,
          model: model.constructor.name,
          id: model.id,
          data: model.toJSON(),
        });
      });
    });
    
    modelClass.observe(mockObserver);
    
    return {
      restore: () => {
        modelClass._observers = originalObservers;
      },
      getCalls: (method = null) => {
        return this.observerCalls.filter(call => 
          !method || call.method === method
        );
      },
      clearCalls: () => {
        this.observerCalls = [];
      },
    };
  }
}

// Usage in tests
describe('User Model', () => {
  let observerMock;
  
  beforeEach(() => {
    observerMock = ObserverTestHelper.mockObserver(User, ['created', 'updated']);
    observerMock.clearCalls();
  });
  
  afterEach(() => {
    observerMock.restore();
  });
  
  test('fires created observer', async () => {
    await User.create({ name: 'Test', email: '[e-mail]' });
    
    const calls = observerMock.getCalls('created');
    expect(calls).toHaveLength(1);
    expect(calls[0].data.name).toBe('Test');
  });
});

Observer Best Practices

1. Single Responsibility

// ✅ Good - focused on email functionality
class EmailObserver {
  async created(user) {
    await this.sendWelcomeEmail(user);
  }
  
  async updated(user) {
    if (user.wasChanged('email')) {
      await this.sendEmailChangeNotification(user);
    }
  }
}

// ❌ Bad - doing too many things
class UserObserver {
  async created(user) {
    await this.sendWelcomeEmail(user);
    await this.createProfile(user);
    await this.updateAnalytics(user);
    await this.syncToExternalService(user);
    await this.generateReport(user);
  }
}

2. Error Handling

// ✅ Good - graceful error handling
class EmailObserver {
  async created(user) {
    try {
      await this.sendWelcomeEmail(user);
    } catch (error) {
      console.error('Failed to send welcome email:', error);
      // Don't throw - user creation should succeed
    }
  }
}

3. Async Operations

// ✅ Good - proper async handling
class UserObserver {
  async created(user) {
    // Critical operations (block if they fail)
    await this.createUserProfile(user);
    
    // Non-critical operations (run in background)
    setImmediate(async () => {
      try {
        await Promise.all([
          this.sendWelcomeEmail(user),
          this.updateAnalytics(user),
          this.syncToExternalService(user),
        ]);
      } catch (error) {
        console.error('Background tasks failed:', error);
      }
    });
  }
}

4. Environment Awareness

class EmailObserver {
  async created(user) {
    // Only send emails in production
    if (process.env.NODE_ENV === 'production') {
      await this.sendWelcomeEmail(user);
    } else {
      console.log(`Would send welcome email to ${user.email}`);
    }
  }
}

5. Documentation

/**
 * UserObserver
 * 
 * Handles user lifecycle events:
 * - creating: Normalizes data, sets defaults
 * - created: Sends welcome email, creates profile
 * - updating: Validates changes, tracks modifications
 * - updated: Clears cache, syncs external systems
 * - deleting: Cleans up related data
 * - deleted: Removes files, sends notifications
 */
class UserObserver {
  // ... implementation
}

Next Steps

Custom Casting

Transform data with custom cast classes

Query Scopes

Create reusable query constraints