https://github.com/stefalda/inject_x
A lightweight, easy-to-use service locator implementation for Dart applications. This package provides a simple dependency injection container that helps manage application dependencies with minimal setup.
https://github.com/stefalda/inject_x
dart dartlang dependency-injection flutter library
Last synced: 3 months ago
JSON representation
A lightweight, easy-to-use service locator implementation for Dart applications. This package provides a simple dependency injection container that helps manage application dependencies with minimal setup.
- Host: GitHub
- URL: https://github.com/stefalda/inject_x
- Owner: stefalda
- License: mit
- Created: 2025-02-11T14:27:19.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-08T13:46:12.000Z (about 1 year ago)
- Last Synced: 2025-06-08T14:30:48.909Z (about 1 year ago)
- Topics: dart, dartlang, dependency-injection, flutter, library
- Language: Dart
- Homepage:
- Size: 11.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# InjectX
A lightweight, easy-to-use service locator implementation for Dart applications. This package provides a simple dependency injection container that helps manage application dependencies with minimal setup.
## Features
- Simple registration and retrieval of dependencies
- Singleton instance management
- Automatic disposal of services
- Type-safe dependency injection
- Angular-style `inject` function
- Zero external dependencies
## Installation
Add this to your package's `pubspec.yaml` file:
```yaml
dependencies:
inject_x: ^0.0.5
```
## Usage
### Basic Usage
```dart
// Register your dependencies
InjectX.add(UserService());
InjectX.add(AuthService());
// Retrieve instances
final userService = InjectX.get();
final authService = InjectX.get();
// Alternatively, use Angular-style injection
final userService = inject();
```
### Init Method
If your class defines an `init()` method, it will be called automatically **before the first injection**. This is useful when your service depends on other services that need to be resolved after construction — particularly in cases of circular dependencies.
```dart
class UserService {
late AuthService authService;
void init() {
authService = inject();
}
}
```
The `init()` method is called **only once**, just before the first access via `get()` or `inject()`.
### Async Init Method
If your class has an `async` `init()` method (returning a `Future`), you can use `injectAsync()` or `InjectX.getAsync()` to ensure initialization is awaited before use.
```dart
class ConfigService {
String? config;
Future init() async {
await Future.delayed(Duration(milliseconds: 100));
config = 'loaded';
}
}
void main() async {
InjectX.add(ConfigService());
final config = await injectAsync();
}
```
### Automatic Disposal
InjectX automatically calls a service’s `dispose()` method if it exists when the service is removed:
```dart
class DatabaseService {
void dispose() {
// Cleanup resources
}
}
// Register the service
InjectX.add(DatabaseService());
// Later, remove it
InjectX.remove(); // dispose() will be called automatically
```
## API Reference
### Methods
- `add(T instance)`: Register a new dependency
- `get()`: Retrieve a registered dependency, calling `init()` if defined
- `getAsync()`: Retrieve a registered dependency, awaiting `init()` if it's async
- `remove()`: Remove a registered dependency and call `dispose()` if defined
- `length`: The number of registered dependencies
- `clear()`: Remove all dependencies and dispose each (if supported)
### Helper Functions
- `inject()`: Angular-style helper to call `InjectX.get()`
- `injectAsync()`: Angular-style helper for services with async `init()`
## Error Handling
The package includes error handling for common scenarios:
```dart
// Attempting to retrieve a non-existent dependency
try {
final service = InjectX.get();
} catch (e) {
// Throws StateError: No instance registered for type UnregisteredService
}
```
## Best Practices
1. Register all dependencies early in your app lifecycle
2. Use meaningful type parameters for clarity
3. Implement `dispose()` for services that require cleanup
4. Remove services when no longer needed (e.g., on module unload)
## Example
```dart
class UserService {
void dispose() {
// Cleanup
}
}
class AuthService {
final UserService userService;
AuthService(this.userService);
}
void main() {
// Register services
InjectX.add(UserService());
// Register a dependent service
InjectX.add(AuthService(inject()));
// Use services
final userService = inject();
final authService = inject();
// Cleanup
InjectX.remove();
InjectX.remove();
}
```
## Contributing
Contributions are welcome! Please feel free to submit a pull request.
For major changes, open an issue first to discuss what you'd like to propose.
## License
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.