TaskChainBuilder class

Builder for creating task chains (A -> B -> C workflows).

Task chains allow you to define complex multi-step workflows where tasks execute in sequence or parallel. Perfect for data processing pipelines, ETL operations, or any multi-stage background work.

Sequential Chain (A → B → C)

await NativeWorkManager.beginWith(
  TaskRequest(
    id: 'download',
    worker: NativeWorker.httpDownload(
      url: 'https://cdn.example.com/video.mp4',
      savePath: '/tmp/video.mp4',
    ),
  ),
)
.then(TaskRequest(
  id: 'compress',
  worker: DartWorker(callbackId: 'compressVideo'),
))
.then(TaskRequest(
  id: 'upload',
  worker: NativeWorker.httpUpload(
    url: 'https://api.example.com/videos',
    filePath: '/tmp/compressed.mp4',
  ),
))
.named('video-pipeline')
.withConstraints(Constraints.heavyTask)
.enqueue();

Parallel Tasks (A → [B1, B2, B3])

await NativeWorkManager.beginWith(
  TaskRequest(
    id: 'prepare-data',
    worker: DartWorker(callbackId: 'prepareData'),
  ),
)
.thenAll([
  // These 3 uploads run in parallel
  TaskRequest(
    id: 'upload-server1',
    worker: NativeWorker.httpUpload(
      url: 'https://server1.example.com/backup',
      filePath: '/data/backup.zip',
    ),
  ),
  TaskRequest(
    id: 'upload-server2',
    worker: NativeWorker.httpUpload(
      url: 'https://server2.example.com/backup',
      filePath: '/data/backup.zip',
    ),
  ),
  TaskRequest(
    id: 'upload-cloud',
    worker: NativeWorker.httpUpload(
      url: 'https://cloud.example.com/backup',
      filePath: '/data/backup.zip',
    ),
  ),
])
.enqueue();

Complex Multi-Stage Pipeline

// Stage 1: Fetch metadata
// Stage 2: Download files in parallel
// Stage 3: Merge and process
// Stage 4: Upload result

await NativeWorkManager.beginWith(
  TaskRequest(
    id: 'fetch-metadata',
    worker: NativeWorker.httpRequest(
      url: 'https://api.example.com/metadata',
      method: HttpMethod.get,
    ),
  ),
)
.thenAll([
  TaskRequest(
    id: 'download-file1',
    worker: NativeWorker.httpDownload(
      url: 'https://cdn.example.com/file1.dat',
      savePath: '/tmp/file1.dat',
    ),
  ),
  TaskRequest(
    id: 'download-file2',
    worker: NativeWorker.httpDownload(
      url: 'https://cdn.example.com/file2.dat',
      savePath: '/tmp/file2.dat',
    ),
  ),
])
.then(TaskRequest(
  id: 'merge-process',
  worker: DartWorker(callbackId: 'mergeAndProcess'),
))
.then(TaskRequest(
  id: 'upload-result',
  worker: NativeWorker.httpUpload(
    url: 'https://api.example.com/results',
    filePath: '/tmp/result.json',
  ),
))
.named('etl-pipeline')
.withConstraints(Constraints.heavyTask)
.enqueue();

Chain Execution Rules

  • Sequential tasks: Execute one after another (A → B → C)
  • Parallel tasks: All start together, next step waits for ALL to complete
  • Failure handling: If ANY task fails, entire chain stops
  • Constraints: Applied to entire chain (use withConstraints)

Builder Methods

  • then - Add single task (sequential)
  • thenAll - Add multiple tasks (parallel)
  • named - Set chain name for debugging
  • withConstraints - Set constraints for entire chain
  • enqueue - Schedule the chain for execution

Common Pitfalls

❌ Don't make chains too long (increases failure risk) ❌ Don't use chains for independent tasks ❌ Don't forget to call enqueue() at the end ✅ Do handle failures gracefully ✅ Do keep chains focused on related tasks ✅ Do use constraints appropriately

See Also

Constructors

TaskChainBuilder.internal(List<TaskRequest> initialTasks)
Creates a new TaskChainBuilder with initial tasks.

Properties

constraints → Constraints
Get the chain constraints.
no setter
hashCode → int
The hash code for this object.
no setterinherited
name → String?
Get the chain name.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
steps → List<List<TaskRequest>>
Get all steps in the chain.
no setter

Methods

enqueue() → Future<ScheduleResult>
Schedule the chain for execution.
named(String name) → TaskChainBuilder
Set a name for this chain (for debugging/monitoring).
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
then(TaskRequest task) → TaskChainBuilder
Add a single task to run after the previous step completes.
thenAll(List<TaskRequest> tasks) → TaskChainBuilder
Add multiple tasks to run in parallel after the previous step completes.
toMap() → Map<String, dynamic>
Convert to map for platform channel.
toString() → String
A string representation of this object.
override
withConstraints(Constraints constraints) → TaskChainBuilder
Set constraints for the entire chain.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

enqueueCallback ↔ Future<ScheduleResult> Function(TaskChainBuilder)?
Internal: Callback to actually enqueue the chain. Set by NativeWorkManager during initialization.
getter/setter pair