orbital_core 0.2.0

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.

Sensitive data in logs

The default logger preset is normal, which omits dependency read/register tracing. Verbose logging can include route URIs, query parameters, error messages and stack traces. Treat verbose output and debug snapshots as development diagnostics: do not forward them to remote logging services without reviewing or redacting application-specific secrets such as tokens, emails or customer identifiers.

For production telemetry, provide a custom OrbitalLoggerAdapter and redact event.details before export. Keep OrbitalLoggerConfig.minimal() or a category-limited custom config for environments where URLs or query strings may contain sensitive data.

More detail

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