mizchi/ailab

Domain Events represent something significant that has happened within the domain. They are used to notify other parts of the system about state changes.

Rules for Domain Events:

• Naming: Use past tense (e.g., OrderPlaced, OrderPaid).
• Immutability: Events represent facts that occurred in the past and cannot be changed.
• Integration with Aggregates: An AggregateRoot can collect events during its lifecycle and provide a mechanism to clearEvents() after they are published.

Core Components:

• DomainEvent: Base interface with occurredAt: Date.
• DomainEventPublisher: Interface for publishing and subscribing to events.
• AggregateRoot: Abstract class to manage the collection of events within an aggregate.

interface DomainEvent {
  readonly occurredAt: Date;
}

class OrderPlaced implements DomainEvent {
  readonly occurredAt: Date;
  constructor(
    readonly orderId: OrderId,
    readonly customerId: CustomerId,
    readonly orderTotal: number,
  ) {
    this.occurredAt = new Date();
  }
}

abstract class AggregateRoot {
  private _domainEvents: DomainEvent[] = [];

  protected addDomainEvent(event: DomainEvent): void {
    this._domainEvents.push(event);
  }

  clearEvents(): DomainEvent[] {
    const events = [...this._domainEvents];
    this._domainEvents = [];
    return events;
  }
}

class OrderWithEvents extends AggregateRoot {
  // ... implementation ...
  markAsPaid(): void {
    // ... logic ...
    this._status = "paid";
    this.addDomainEvent(new OrderPaid(this.id, this.total));
  }
}

You can run specific parts of the Lighthouse lifecycle using the --gather-mode (-G) and --audit-mode (-A) flags. This is useful for separating the browser interaction/artifact collection phase from the report generation phase.

• Gather Mode (-G): Launches the browser, collects artifacts (like traces and screenshots), and saves them to disk (defaulting to ./latest-run/), then quits.
• Audit Mode (-A): Skips browser interaction, loads artifacts from disk, runs audits on them, and generates a report.
• Gather + Audit (-GA): Performs both steps and saves artifacts to disk.

You can provide a custom directory for artifacts by appending a path to the flag.

Examples:

# Collect artifacts and quit
lighthouse http://example.com -G

# Run audits using previously collected artifacts
lighthouse http://example.com -A

# Collect and save to a specific directory
lighthouse -GA=./my-artifacts https://example.com

lighthouse http://example.com -GA

The Infrastructure Layer handles technical details required by the application, such as persistence, messaging, and external integrations. This layer implements the interfaces defined in the domain or application layers.

Common implementations include:

• Repositories: Concrete implementations for database access (e.g., InMemoryCustomerRepository, SqlOrderRepository).
• Event Publishers: Implementations for broadcasting domain events (e.g., SimpleDomainEventPublisher).
• External Clients: API clients for third-party services.

// Example: In-memory Repository implementation
class InMemoryCustomerRepository implements CustomerRepository {
  private customers: Map<string, Customer> = new Map();

  async findById(id: CustomerId): Promise<Customer | null> {
    const customer = this.customers.get(id.toString());
    return customer || null;
  }

  async save(customer: Customer): Promise<void> {
    this.customers.set(customer.customerId.toString(), customer);
  }
}

// Example: Simple Domain Event Publisher
class SimpleDomainEventPublisher implements DomainEventPublisher {
  private handlers: Map<string, Array<(event: DomainEvent) => void>> = new Map();

  publish<T extends DomainEvent>(event: T): void {
    const eventType = event.constructor.name;
    const eventHandlers = this.handlers.get(eventType) || [];
    for (const handler of eventHandlers) {
      try {
        handler(event);
      } catch (error) {
        console.error(`Error handling event ${eventType}:`, error);
      }
    }
  }

  subscribe<T extends DomainEvent>(
    eventType: new (...args: any[]) => T,
    handler: (event: T) => void,
  ): void {
    const eventName = eventType.name;
    if (!this.handlers.has(eventName)) {
      this.handlers.set(eventName, []);
    }
    this.handlers.get(eventName)!.push(handler as any);
  }
}

The system relies on two core interfaces to represent the structure and metadata of JSON data during analysis:

PathSegment

Represents a single step in a JSON path (e.g., a key in an object or an index in an array).

• type: Either "key", "index", or "wildcard".
• value: The actual key name or index.
• arrayAccess: Boolean indicating if this segment is part of an array access.
• arrayInfo: Contains isTuple (boolean) and itemTypes (an array of PathInfo) if the segment is an array.

PathInfo

Represents a complete path to a value, including its type and metadata.

• segments: An array of PathSegment objects.
• value: The actual value found at this path.
• type: The primitive type ("string", "number", "boolean", "null", "object", or "array").
• isNullable: Boolean indicating if the value can be null.
• metadata: Advanced information used for prediction, such as occurrences (count), patterns (for enum prediction), or recordPattern (for Record<string, T> detection).

interface PathSegment {
  type: "key" | "index" | "wildcard";
  value: string;
  arrayAccess?: boolean;
  arrayInfo?: {
    isTuple: boolean;
    itemTypes: PathInfo[];
  };
}

interface PathInfo {
  segments: PathSegment[];
  value: unknown;
  type: "string" | "number" | "boolean" | "null" | "object" | "array";
  isNullable: boolean;
  metadata?: {
    occurrences: number;
    patterns?: string[];
    recordPattern?: {
      keyPattern: string;
      valueType: PathInfo;
    };
  };
}