levit_scope 0.0.5

Pure Dart dependency injection and service locator. Part of the Levit framework.

levit_scope

Type-safe, hierarchical dependency injection for Dart. Explicit. Scoped. Deterministic.

levit_scope provides a robust, reflection-free dependency injection mechanism designed for applications requiring predictable lifecycles and explicit scoping. It serves as the core container engine for the Levit framework.

---

Purpose & Scope

levit_scope manages the lifecycle and resolution of dependencies. It is responsible for:

• Enforcing hierarchical isolation between different layers of an application.
• Orchestrating lifecycle hooks (onInit, onClose) for managed components.
• Providing a pure Dart, side-effect-free container that works across all platforms.

---

Conceptual Overview

Core Abstractions

• [LevitScope]: A container that holds dependency registrations. Scopes form a tree where children can inherit or override parent dependencies.
• [LevitScopeDisposable]: An interface that components implement to participate in the container's lifecycle.
• Ambient Scoping: Automatic detection of the active scope using [Zone]-based propagation, accessible via the [Ls] static interface.

---

Getting Started

Hierarchical Scoping

// Create a root scope
final root = LevitScope.root();

// Register a singleton
root.put(() => AuthService());

// Create a nested scope
final featureScope = root.createScope('feature');
featureScope.put(() => FeatureService());

// Resolve (falls back to parent if not found locally)
final auth = featureScope.find<AuthService>();

Lifecycle Hooks

class Database implements LevitScopeDisposable {
  @override
  void onInit() => print('Connecting...');

  @override
  void onClose() => print('Closing connection...');
}

---

Design Principles

Explicitness over Magic

No reflection or code generation. Every dependency is registered via typed builders, ensuring full type safety and transparency.

Deterministic Teardown

Disposing a scope guarantees that every owned dependency implementing [LevitScopeDisposable] has its onClose method called, preventing resource leaks.

Hierarchical Isolation

Scopes provide a strict hierarchy. This allows for powerful mocking and feature-specific resource allocation without global state pollution.