orbital_injector 0.1.0

Default dependency injection container implementation for Orbital.

orbital_injector

Default dependency injection container for Orbital.

Core concepts

OrbitalContainer resolves OrbitalBindings inside a scope tree. Bindings can be sync or async, eager or lazy, singleton or factory.

• singleton and singletonAsync are created during initialize()
• lazySingleton and lazySingletonAsync are created on first access
• factory and factoryAsync create a new instance every time

dependsOn vs resolver

dependsOn declares a readiness graph. It tells the container which dependencies must already be registered and ready before this binding is created.

It does not inject values into the factory signature.

Factories always read dependencies through OrbitalResolver.

container.register(
  OrbitalBinding.singletonAsync<ApiClient>((resolver) async {
    return ApiClient.connect();
  }),
);

container.register(
  OrbitalBinding.singleton<DashboardController>(
    (resolver) => DashboardController(
      resolver.get<ApiClient>(),
    ),
    dependsOn: [OrbitalDependencyRef.of<ApiClient>()],
  ),
);

await container.initialize();
final controller = container.get<DashboardController>();

In the example above, DashboardController is sync even though it consumes an async dependency. The controller does not need to be async because the async work happened in ApiClient creation, and dependsOn guaranteed readiness.

OrbitalDependencyRef

Use OrbitalDependencyRef to describe the dependency edge declared by dependsOn.

OrbitalDependencyRef.of<ApiClient>()
OrbitalDependencyRef.of<ApiClient>(key: OrbitalKey('admin'))
const OrbitalDependencyRef(ApiClient, key: OrbitalKey('admin'))

Use a key when more than one binding of the same type exists.

get, getAsync and isReady

• get<T>() returns a ready sync instance, or a ready async instance
• getAsync<T>() waits for async creation when needed
• isReady<T>() reports whether an async binding is already available

For factoryAsync, use getAsync<T>() only. It is intentionally ephemeral and does not become a cached "ready" instance inside the scope.

If a binding tries to synchronously read an async dependency before it is ready, the container throws OrbitalNotReadyException.