orbital_core 0.1.0

Core contracts and lifecycle primitives for the Orbital ecosystem.

orbital_core

Core contracts and shared primitives for the Orbital ecosystem.

What this package contains

orbital_core defines the low-level building blocks used by the injector, router and aggregate package:

• OrbitalBinding and OrbitalBindingType
• OrbitalDependencyRef and OrbitalKey
• OrbitalResolver and OrbitalScope
• OrbitalLifecycle
• OrbitalLogEvent and OrbitalLogger
• framework exceptions such as OrbitalMissingDependencyException

This package is intentionally framework-agnostic and does not depend on Flutter.

Binding model

Orbital supports six binding kinds:

• singleton
• singletonAsync
• lazySingleton
• lazySingletonAsync
• factory
• factoryAsync

Use async bindings only when that binding's own factory needs await.

factoryAsync is intended for one-shot async production and should be consumed through getAsync<T>(). Unlike singleton variants, it does not establish a stable ready instance inside the scope.

Use dependsOn to describe readiness and creation order, not constructor injection. Factories still read dependencies through OrbitalResolver.

OrbitalBinding.singletonAsync<ApiClient>((resolver) async {
  return ApiClient.connect();
}),
OrbitalBinding.singleton<HomeController>(
  (resolver) => HomeController(resolver.get<ApiClient>()),
  dependsOn: [OrbitalDependencyRef.of<ApiClient>()],
),

Resolver and scope contracts

• get<T>() reads a ready dependency synchronously
• getAsync<T>() waits for async completion
• getOrNull<T>() returns null when missing or not ready
• isRegistered<T>() checks scope-tree registration
• isReady<T>() reports async readiness

OrbitalScope extends OrbitalResolver with mutation and lifecycle methods:

• createChild(...)
• register(...)
• initialize()
• dispose()

Logging

OrbitalLogger provides:

• named domains such as route, module, injector and asyncResolution
• stable event names for tests and filtering
• presets (minimal, normal, verbose)
• configurable formatting and writer output

The formatter is optimized for readable console output, while OrbitalLogEvent.details keeps structured metadata for assertions and custom writers.

More detail

See doc.md for the package architecture, lifecycle semantics, readiness rules, logger behavior and extension points.