macos_process_activity 0.1.0

A Flutter plugin that uses macOS ProcessInfo activities to prevent App Nap and idle system sleep from slowing user-initiated work.

Keep important macOS work responsive

Long-running exports, conversions, indexing, and file-processing tasks can be slowed when macOS applies App Nap or idle system sleep. This plugin wraps that work in a native ProcessInfo activity so macOS knows it should remain responsive until the operation finishes.

Why use it?

• Prevent App Nap and idle system sleep from slowing important work.
• Scope the native activity to a Future, Stream, or manually managed lifetime.
• Guarantee cleanup after success, failure, or stream cancellation.
• Safely run multiple overlapping activities without mixing their lifetimes.
• Keep application work running even when native integration is unavailable.
• Add no permissions, entitlements, or macOS setup steps.

Typical use cases include file exports, media conversion, archive creation, local indexing, data migration, and other finite tasks explicitly started by the user.

Installation

flutter pub add macos_process_activity

Then import the package:

import 'package:macos_process_activity/macos_process_activity.dart';

Run asynchronous work

run is the recommended API for a single asynchronous operation. The activity ends automatically whether the callback succeeds or throws.

final outputFile = await run(
  reason: 'Exporting photos',
  action: exportPhotos,
);

Run a stream

runStream starts its activity when the stream is listened to and keeps it alive until the stream completes or its subscription is cancelled.

await for (final progress in runStream(
  reason: 'Converting video',
  action: () => conversionProgress(),
)) {
  updateProgress(progress);
}

Control the lifetime manually

Use start when the lifetime cannot be represented by one callback. Calling end more than once is safe.

final activity = await start(reason: 'Building search index');
try {
  await rebuildSearchIndex();
} finally {
  await activity.end();
}

Prefer run or runStream whenever possible because their cleanup is scoped automatically.

Platform behavior

The native activity uses ProcessInfo.ActivityOptions.userInitiated. It is an energy-management hint for important work the user is waiting for; it does not keep the display on.

On platforms other than macOS, or when the native plugin is unavailable, all APIs remain safe no-ops and the wrapped application work continues normally.