simplest_service_locator #

simplest_service_locator is a lightweight and straightforward service locator for Dart, providing singleton, lazy singleton, and factory registration capabilities with support for named services and asynchronous initialization.

Table of Contents #

Features
Installation
Usage
API
Exceptions
Complete Example
License

Features #

Register and retrieve singletons, lazy singletons, and factory instances
Support for named services to register multiple instances of the same type
Asynchronous service registration and retrieval
Simple API for managing dependencies
Unregistration of services
Reset functionality for testing
Comprehensive exception handling

Installation #

Add simplest_service_locator to your pubspec.yaml file:

dependencies:
  simplest_service_locator: latest

Then, run dart pub get to install the package.

Usage #

Import the library:

import 'package:simplest_service_locator/simplest_service_locator.dart';

Basic Example #

void main() {
  final serviceLocator = SimplestServiceLocator.instance();

  // Register a singleton
  serviceLocator.registerSingleton<MyService>(MyService());

  // Register a lazy singleton
  serviceLocator.registerLazySingleton<MyLazyService>(() => MyLazyService());

  // Register a factory
  serviceLocator.registerFactory<MyFactoryService>(() => MyFactoryService());

  // Retrieve the singleton instance
  final myService = serviceLocator.get<MyService>();
  myService.doSomething();

  // Retrieve the lazy singleton instance
  final myLazyService = serviceLocator.get<MyLazyService>();
  myLazyService.doSomethingElse();

  // Retrieve a new instance from the factory
  final myFactoryService = serviceLocator.get<MyFactoryService>();
  myFactoryService.doAnotherThing();

  // Clear all registered services
  serviceLocator.clear();
}

Named Services #

You can register multiple services of the same type with different names:

// Register named services
serviceLocator.registerSingleton<ApiClient>(
  ApiClient(baseUrl: 'https://api.production.com'),
  name: 'production',
);

serviceLocator.registerSingleton<ApiClient>(
  ApiClient(baseUrl: 'https://api.staging.com'),
  name: 'staging',
);

// Retrieve named services
final productionApi = serviceLocator.get<ApiClient>(name: 'production');
final stagingApi = serviceLocator.get<ApiClient>(name: 'staging');

Asynchronous Services #

For services that require asynchronous initialization:

// Register an async lazy singleton
serviceLocator.registerLazySingletonAsync<DatabaseService>(() async {
  final db = DatabaseService();
  await db.initialize();
  return db;
});

// Register an async factory
serviceLocator.registerFactoryAsync<RemoteConfig>(() async {
  final config = RemoteConfig();
  await config.fetch();
  return config;
});

// Retrieve async services
final db = await serviceLocator.getAsync<DatabaseService>();
final config = await serviceLocator.getAsync<RemoteConfig>();

Unregistration #

You can unregister services when they're no longer needed:

// Check if a service is registered
if (serviceLocator.isRegistered<MyService>()) {
  // Unregister a service
  serviceLocator.unregister<MyService>();
}

// Unregister a named service
serviceLocator.unregister<ApiClient>(name: 'staging');

Reset for Testing #

The reset functionality is particularly useful for testing:

void setUp() {
  // Reset the service locator before each test
  SimplestServiceLocator.reset();
  
  // Register test mocks
  final locator = SimplestServiceLocator.instance();
  locator.registerSingleton<MyService>(MockMyService());
}

API #