get_it Documentation

In the Pragmatic Flutter Architecture (PFA), distinguish between data loading and UI interaction:

1. init(): Used for loading initial data via direct API calls. Do not use commands inside init().
2. Commands: The UI-facing reactive interface. Widgets watch isRunning, errors, and results.

Crucial Rule: Do not nest commands. If a command needs to refresh data after a mutation (e.g., after a delete), call the API directly inside the command body instead of calling another command's .run() method.

class MyManager {
  final items = ValueNotifier<List<Item>>([]);

  // Command for UI-triggered refresh (widget watches isRunning)
  late final loadCommand = Command.createAsyncNoParam<List<Item>>(
    () async {
      final result = await di<ApiClient>().getItems();
      items.value = result;
      return result;
    },
    initialValue: [],
  );

  // init() calls API directly — no command needed
  Future<MyManager> init() async {
    items.value = await di<ApiClient>().getItems();
    return this;
  }
}

// ✅ Direct API call inside command
late final deleteCommand = Command.createAsync<int, bool>((id) async {
  final result = await di<ApiClient>().delete(id);
  items.value = await di<ApiClient>().getItems(); // reload directly
  return result;
}, initialValue: false);

// ❌ Don't call another command from inside a command
late final deleteCommand = Command.createAsync<int, bool>((id) async {
  final result = await di<ApiClient>().delete(id);
  loadCommand.run(); // WRONG — nesting commands
  return result;
}, initialValue: false);

Scopes allow you to group related services and manage their lifecycle (e.g., for a user session).

Scope Shadowing: Scopes act as a stack. When you register a type in a new scope that already exists in a lower scope, the new registration shadows (hides) the original. getIt<T>() searches top-down, returning the first match. Popping the scope restores access to the original service.

Key Operations:

• pushNewScope(): Synchronous scope creation.
• pushNewScopeAsync(): Asynchronous scope creation (use for async initialization).
• popScope(): Asynchronous operation that removes the top scope and calls its dispose callbacks.
• popScopesTill(name, {inclusive: false}): Removes multiple scopes until a specific one is reached.
• dropScope(name): Removes a specific scope by name.

// Push scope (synchronous init)
getIt.pushNewScope(
  scopeName: 'user-session',
  init: (getIt) {
    getIt.registerSingleton<UserData>(currentUser);
    getIt.registerLazySingleton<UserPrefs>(() => UserPrefs(currentUser.id));
  },
);

// Push scope (async init)
await getIt.pushNewScopeAsync(
  scopeName: 'user-session',
  init: (getIt) async {
    final prefs = await UserPrefs.load(currentUser.id);
    getIt.registerSingleton<UserPrefs>(prefs);
  },
);

// Pop scope (always async - calls dispose callbacks)
await getIt.popScope();

// Pop multiple scopes
await getIt.popScopesTill('base-scope', inclusive: false);

// Drop specific scope by name
getIt.dropScope('user-session');

// Query scopes
getIt.hasScope('user-session');    // bool
getIt.currentScopeName;            // String?

When the same entity (e.g., a User or a Post) appears in multiple parts of the app (feeds, search results, detail pages), use a DataRepository to manage their lifecycle via Reference Counting. This prevents duplicate proxies for the same ID and ensures proxies are disposed of only when no longer needed.

The Reference Counting Flow:

1. Feed creates ChatProxy(id=1) $\rightarrow$ refCount=1.
2. Detail Page opens the same proxy $\rightarrow$ refCount=2.
3. Detail Page closes and releases the proxy $\rightarrow$ refCount=1 (proxy stays alive for the feed).
4. Feed refreshes and releases the proxy $\rightarrow$ refCount=0 (proxy is disposed).

Implementation Pattern:

• DataRepository maintains a map of active proxies by ID.
• createProxy(item): Returns an existing proxy (and updates it with fresh data) or creates a new one, then increments the _referenceCount.
• releaseProxy(proxy): Decrements the _referenceCount. If it reaches zero, the proxy is disposed and removed from the repository.

abstract class DataProxy<T> extends ChangeNotifier {
  DataProxy(this._target);
  T _target;
  int _referenceCount = 0;

  T get target => _target;
  set target(T value) { _target = value; notifyListeners(); }

  @override
  void dispose() {
    assert(_referenceCount == 0);
    super.dispose();
  }
}

abstract class DataRepository<T, TProxy extends DataProxy<T>, TId> {
  final _proxies = <TId, TProxy>{};

  TId identify(T item);
  TProxy makeProxy(T entry);

  // Returns existing proxy (updated) or creates new one
  TProxy createProxy(T item) {
    final id = identify(item);
    if (!_proxies.containsKey(id)) {
      _proxies[id] = makeProxy(item);
    } else {
      _proxies[id]!.target = item;  // Update with fresh data
    }
    _proxies[id]!._referenceCount++;
    return _proxies[id]!;
  }

  void releaseProxy(TProxy proxy) {
    proxy._referenceCount--;
    if (proxy._referenceCount == 0) {
      proxy.dispose();
      _proxies.remove(identify(proxy.target));
    }
  }
}

Error handling follows a hierarchy from local to global:

1. Local Error Listeners: In a Manager's init(), attach .errors.listen() to specific commands. This allows you to show user-friendly messages (via an InteractionManager) and suppresses the global handler for that specific error.
2. Global Exception Handler: A static method assigned to Command.globalExceptionHandler. This catches any command error that does not have a local listener.
3. InteractionManager: A sync singleton that abstracts user-facing feedback (toasts, dialogs). It uses an InteractionConnector widget to safely acquire a BuildContext for showing UI elements without passing context through business logic.

Error Flow: Command fails $\rightarrow$ ErrorFilter checks for local listeners $\rightarrow$ If local listeners exist, they fire $\rightarrow$ If no local listeners exist, the global handler fires.

// 1. Local Error Listeners in Manager
Future<MyManager> init() async {
  final interaction = di<InteractionManager>();
  startSessionCommand.errors.listen((error, _) {
    interaction.showToast('Could not start session', isError: true);
  });
  return this;
}

// 2. Global Error Handler
static void globalErrorHandler(CommandError error, StackTrace stackTrace) {
  di<InteractionManager>().showToast(error.error.toString(), isError: true);
}

// 3. InteractionManager Setup
// Register sync in base scope before async services
di.registerSingleton<InteractionManager>(InteractionManager());

Using get_it involves three main steps: defining your services, registering them at app startup, and accessing them from anywhere in your application without needing BuildContext.

1. Define services: Create your classes as usual.
2. Register services: Use a GetIt instance (e.g., GetIt.instance) to register your objects during the app's configuration phase.
3. Access services: Use the getIt<Type>() syntax to retrieve registered instances.

import 'package:get_it/get_it.dart';

// Create a global instance (or use GetIt.instance)
final getIt = GetIt.instance;

// 1. Define your services
class ApiClient {
  Future<void> fetchData() async { /* ... */ }
}

class UserRepository {
  final ApiClient apiClient;
  UserRepository(this.apiClient);
}

// 2. Register them at app startup
void configureDependencies() {
  getIt.registerSingleton<ApiClient>(ApiClient());
  getIt.registerLazySingleton<UserRepository>(
    () => UserRepository(getIt<ApiClient>())
  );
}

// 3. Access from anywhere in your app
class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        // No BuildContext passing needed!
        getIt<UserRepository>().apiClient.fetchData();
      },
      child: Text('Fetch Data'),
      )
    );
  }
}

Use getIt.register... methods to add services to the locator. Common registration types include:

• Singleton: Created immediately upon registration.
• Lazy Singleton: Created only when first accessed.
• Factory: Returns a new instance every time it is called.
• Factory with Parameters: Allows passing arguments during retrieval.
• Named Instances: Use instanceName to register multiple instances of the same type (e.g., different configurations).

Critical Rule: Register all services BEFORE calling runApp().

final getIt = GetIt.instance;

void configureDependencies() {
  // Singleton - created immediately
  getIt.registerSingleton<ApiClient>(ApiClient());

  // Singleton with dispose callback
  getIt.registerSingleton<StreamController>(
    StreamController(),
    dispose: (c) => c.close(),
  );

  // Lazy singleton - created on first access
  getIt.registerLazySingleton<Database>(() => Database());

  // Factory - new instance every call
  getIt.registerFactory<Logger>(() => Logger());

  // Factory with parameters
  getIt.registerFactoryParam<Logger, String, void>(
    (tag, _) => Logger(tag),
  );

  // Named instances
  getIt.registerSingleton<Config>(devConfig, instanceName: 'dev');
  getIt.registerSingleton<Config>(prodConfig, instanceName: 'prod');
}