introduce event system

[luxass]

The pipeline emits events during execution for logging, debugging, progress tracking, or building custom tooling on top.

Listening to Events

Pass an onEvent callback to the pipeline to receive events as they occur.

import { definePipeline } from "@ucdjs/pipelines";

const pipeline = definePipeline({
  versions: ["16.0.0"],
  source: mySource,
  routes: [myRoute],
  onEvent: (event) => {
    console.log(`[${event.type}]`, event.timestamp);
  },
});

Event Types

The pipeline emits events at various stages of execution.

const pipeline = definePipeline({
  versions: ["16.0.0"],
  source: mySource,
  routes: [myRoute],
  onEvent: (event) => {
    switch (event.type) {
      case "pipeline:start":
        console.log(`Processing ${event.versions.length} versions`);
        break;
      case "pipeline:end":
        console.log(`Completed in ${event.durationMs}ms`);
        break;
      case "version:start":
        console.log(`Starting version ${event.version}`);
        break;
      case "file:matched":
        console.log(`${event.file.name} matched route ${event.routeId}`);
        break;
      case "file:skipped":
        console.log(`${event.file.name} skipped: ${event.reason}`);
        break;
      case "cache:hit":
        console.log(`Cache hit for ${event.routeId}`);
        break;
      case "cache:miss":
        console.log(`Cache miss for ${event.routeId}`);
        break;
      case "artifact:produced":
        console.log(`Route ${event.routeId} emitted artifact ${event.artifactId}`);
        break;
      case "error":
        console.error(`Error in ${event.error.scope}: ${event.error.message}`);
        break;
    }
  },
});

Progress Tracking

Events can be used to build progress indicators for long-running pipelines.

let totalFiles = 0;
let processedFiles = 0;

const pipeline = definePipeline({
  versions: ["16.0.0"],
  source: mySource,
  routes: [myRoute],
  onEvent: (event) => {
    if (event.type === "version:start") {
      totalFiles = 0;
      processedFiles = 0;
    }
    if (event.type === "file:matched" || event.type === "file:skipped") {
      processedFiles++;
      console.log(`Progress: ${processedFiles}/${totalFiles}`);
    }
  },
});