Queues & Background Jobs

While building web applications, you may encounter tasks that take too long to complete during a typical web request, such as sending emails, generating reports, or hitting slow external APIs.

Archery provides an exceptional Background Job system powered by Dart Isolates that allows you to offload these tasks without blocking your main application thread.

Creating a Job

A Job is simply a class that mixes in Queueable and implements two methods: handle() to perform the work, and toJson() to serialize the job's payload.

import 'package:archery/archery/archery.dart';

class SendWelcomeEmail with Queueable {
  final String emailAddress;

  SendWelcomeEmail(this.emailAddress);

  @override
  Map<String, dynamic> toJson() => {
    'emailAddress': emailAddress
  };

  @override
  Future<dynamic> handle() async {
    // Heavy lifting goes here!
    // Example: await sesClient.sendEmail(to: emailAddress);
    return 'Email sent successfully';
  }
}

Dispatching Jobs

Once you have written your job, you can dispatch it from anywhere in your application, such as a controller route:

router.post('/register', (request) async {
  // 1. Create the user
  
  // 2. Dispatch the background job
  await SendWelcomeEmail('jane@example.com').dispatch();
  
  // 3. Quickly return a response to the user
  return request.redirectHome();
});

When you call dispatch(), Archery automatically:

1. Serializes the job into a hashed database record (using the QueueJob model) ensuring the task persists.
2. Deduplicates pending jobs having identical payloads.
3. Spawns an isolated worker thread specifically for this job type.
4. Executes the job safely outside the main event loop.
5. Updates the database status to complete or failed.

Inline Isolates

If you have a quick closure of heavy work and don't want to define an entirely new Queueable class, you can use QueueJob.inline:

router.get('/heavy-math', (request) async {
  // Execute heavy computation without freezing the HTTP server
  final result = await QueueJob.inline(() async {
    return calculatePrimes();
  });
  
  return request.json({'result': result});
});