run_off_main #

A lightweight isolate execution engine for Dart and Flutter applications that offloads heavy parsing, JSON decoding, cryptography, and computation off the UI isolate with Dart DevTools Timeline tracing and graceful Web fallbacks.

Why run_off_main? #

Running expensive operations (e.g. 50KB+ JSON parsing, M3U playlist transformations, image processing) directly on the main isolate causes UI frame drops and jank.

run_off_main provides a safe isolate boundary that:

• Spawns worker isolates via Isolate.run.
• Traces task microsecond performance in Dart DevTools via TimelineTask.
• Gracefully degrades to inline execution on Web without runtime exceptions.
• Supports deterministic inline overrides for unit testing.

Installation #

Add run_off_main to your pubspec.yaml:

dependencies:
  run_off_main: ^1.0.0

Usage #

1. Functional Helper (runOffMain) #

import 'package:run_off_main/run_off_main.dart';

void main() async {
  final largeJsonString = fetchHeavyPayload();

  // Offload heavy JSON parsing to a background worker isolate
  final parsedData = await runOffMain(() {
    return jsonDecode(largeJsonString) as Map<String, dynamic>;
  }, debugName: 'parse_heavy_json');

  print('Parsed payload off main isolate!');
}

2. Class-Based Executor (OffMainWorkerExecutor) #

Use OffMainWorkerExecutor for dependency injection and testing overrides:

import 'package:run_off_main/run_off_main.dart';

class DataRepository {
  final OffMainWorkerExecutor workerExecutor;

  DataRepository({this.workerExecutor = const OffMainWorkerExecutor()});

  Future<List<Item>> processItems(List<String> rawLines) {
    return workerExecutor.run(
      debugName: 'process_items',
      computation: () {
        return rawLines.map((line) => Item.parse(line)).toList();
      },
    );
  }
}

Testing #

Force inline execution during unit tests:

final testExecutor = const OffMainWorkerExecutor(forceInline: true);

License #

MIT License - see LICENSE for details.