@flatfile/implementations-utils-job-worker

Provides a class abstraction for easily implementing Flatfile Jobs. This package simplifies the process of creating, running, and managing background jobs within the Flatfile ecosystem.

Features

• Abstract Worker Classes: Provides JobWorker, WorkbookJobWorker, and SheetJobWorker to structure your job logic with easy access to event context.
• Decorator-based Triggers: Use the @TriggeredBy decorator to link your worker class to a specific job operation.
• Progress Tracking: Built-in ProgressTracker to report progress back to the Flatfile UI.
• Simplified Error Handling: JobError class for standardized error reporting.

Usage

Here is an example of a simple job worker that processes records in a sheet.

import {
  SheetJobWorker,
  TriggeredBy,
  worker,
} from "@flatfile/implementations-utils-job-worker";
import { FlatfileListener } from "@flatfile/listener";

// 1. Define your worker class
@TriggeredBy("processRecords", "sheet")
class ProcessRecordsJob extends SheetJobWorker {
  // `execute` is the main method where your job logic lives.
  async execute() {
    const { sheetId } = this;
    const sheet = await this.sheet();

    // Start progress tracking
    this.progress.add("Processing", { size: "l" });

    // Your business logic here...
    // For example, fetching records and processing them.
    await this.progress.report("Processing", 50, "Halfway there!");

    // ... more logic ...

    // Complete the progress
    await this.progress.complete("Processing", "Done!");

    return {
      outcome: {
        message: `Processing complete for sheet: ${sheet.name}.`,
      },
    };
  }
}

// 2. Register the worker with the listener
export default function (listener: FlatfileListener) {
  listener.use(worker(ProcessRecordsJob));
}

Progress Tracking

The ProgressTracker helps you provide feedback to the user during long-running jobs.

• progress.add(name, { size }): Adds a new task to track. size can be 's', 'm', or 'l'.
• progress.report(name, percentage, message): Updates the progress of a task.
• progress.complete(name, message): Marks a task as 100% complete.