orbital_core 0.1.1

Core contracts and lifecycle primitives for the Orbital ecosystem.

orbital_core

Core contracts, debug primitives and lifecycle vocabulary for the Orbital ecosystem.

What this package contains

orbital_core is the framework-agnostic layer shared by every other Orbital package. It exports:

• OrbitalBinding, OrbitalBindingType, OrbitalDependencyRef and OrbitalKey
• OrbitalResolver and OrbitalScope
• OrbitalLifecycle
• OrbitalLogger, OrbitalLogEvent and logger presets/config
• debug snapshots, OrbitalDebugBridge and service-extension contracts
• deterministic runtime exceptions such as duplicate, missing, cycle and not-ready failures

This package contains no concrete dependency graph implementation and no Flutter routing runtime.

Binding model

Orbital supports six creation strategies:

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

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

Use dependsOn to describe readiness order, not constructor injection:

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

The factory still reads values through OrbitalResolver.

Resolver, scope and lifecycle contracts

OrbitalResolver exposes:

• get<T>()
• getAsync<T>()
• getOrNull<T>()
• isRegistered<T>()
• isReady<T>()

OrbitalScope extends that contract with:

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

OrbitalLifecycle is optional and gives framework-managed objects three hooks:

• onInit()
• onReady()
• onDispose()

The execution order and recovery semantics are implemented by the concrete runtime, typically orbital_injector.

Logging and debug contracts

OrbitalLogger provides stable event names plus readable formatted output. orbital_core also owns the runtime debug model consumed by orbital_devtools:

• scope snapshots
• router snapshots
• health summaries
• service-extension names
• OrbitalDebugBridge.enable(...)

This split keeps runtime packages independent from the DevTools UI while still sharing one debug protocol.

More detail

See doc.md for binding semantics, readiness rules, lifecycle contracts, logger behavior and debug integration.