capture static method

Future<Snapshot> capture({
  1. String? appVersion,
  2. Map<String, dynamic>? metadata,
  3. List<String>? keys,
})

Captures a snapshot of the current application state.

This method collects state from all registered state contributors and creates an immutable snapshot containing:

  • Timestamp (UTC)
  • App version
  • Schema version
  • All registered state data
  • Optional metadata

Example:

final snapshot = await StateSnapshot.capture();
// Or with metadata:
final snapshot = await StateSnapshot.capture(
  appVersion: '1.0.0',
  metadata: {'bug_id': 'BUG-123', 'reporter': 'John'},
);

Requirements:

  • Checkpoint must be enabled (see enable)
  • At least one state contributor must be registered (see register)

Parameters:

  • appVersion: Optional version string of the application (e.g., "1.2.3"). If not provided, defaults to "0.0.0". Consider using package_info_plus to get the actual app version automatically.
  • metadata: Optional map of custom metadata to attach to the snapshot. Must be JSON-serializable. Useful for tagging snapshots with bug IDs, reporter names, or other contextual information.
  • keys: Optional list of keys to capture. If provided, only the specified state contributors will be included in the snapshot. If null, all registered contributors are captured.

Returns: A Future that completes with an immutable Snapshot containing all captured state from registered contributors.

Throws:

  • StateError if checkpoint is not enabled
  • StateError if no state contributors are registered
  • ArgumentError if keys contains a key that is not registered
  • Any exception thrown by an exporter function (propagated)

Deterministic Behavior: State is collected in alphabetical order of keys, ensuring deterministic snapshot creation regardless of registration order.

Implementation

static Future<Snapshot> capture({
  String? appVersion,
  Map<String, dynamic>? metadata,
  List<String>? keys,
}) async {
  ensureEnabled();

  final version = appVersion ?? '0.0.0';
  return SnapshotManager.instance.capture(
    version,
    metadata: metadata,
    keys: keys,
  );
}