levit_dart_core

The foundational composition layer for the Levit ecosystem. Explicit. Reactive. Deterministic.

levit_dart_core orchestrates the relationship between levit_reactive primitives and levit_scope dependency management into a structured framework for building pure Dart business logic.

Purpose & Scope

levit_dart_core provides a predictable environment for managing application logic without UI dependencies. It is responsible for:

Lifecycle Orchestration: Defining how components are initialized, attached to scopes, and disposed.
Automated Resource Management: Ensuring all streams, timers, and reactive objects are cleaned up deterministically.
Composition Conventions: Providing both class-based (LevitController) and functional (LevitState) abstractions for logic.

It deliberately avoids UI or platform-specific logic, making it suitable for CLI tools, servers, and background services. For Flutter integration, use levit_flutter_core.

Conceptual Overview

Application Elements

LevitController: A managed component that encapsulates state and behavior. It participates in an explicit lifecycle and uses autoDispose for resource management.
LevitState: A functional provider that acts as a factory for state instances, offering a modern alternative to class-based controllers.
Levit: The central registry and entry point for managing scopes and resolving dependencies.

Key Mechanisms

Ambient Scoping: Uses Zone-based propagation via levit_scope to resolve dependencies implicitly without manual passing.
Auto-Linking: Automatically tracks reactive state created within a controller or state builder to ensure zero-leak disposal.

Getting Started

1. Define a Controller

class CounterController extends LevitController {
  // Logic is automatically registered for cleanup
  late final count = autoDispose(0.lx);

  void increment() => count.value++;
}

2. Register and Resolve

void main() {
  // Register the controller in the current scope
  Levit.put(() => CounterController());
  
  // Resolve and use
  final controller = Levit.find<CounterController>();
  controller.increment();
}

Design Principles

Explicit over Implicit

While Levit provides ambient scoping for ergonomics, every state transition and dependency link is trackable and deterministic.

Managed Lifecycle

Resources are never left to the garbage collector alone. The onClose hook and autoDispose mechanism ensure that all side effects are terminated as soon as a component is removed.

Functional Composition

The framework encourages composing logic via LevitState to reduce boilerplate and improve encapsulation, while providing LevitController for more complex or hierarchical logic.