pod library

🫘 A lightweight, modular dependency injection (DI) and inversion-of-control (IoC) library.

The jetleaf_pod library provides a flexible set of factories, registries, definitions, and lifecycle hooks to manage object creation, dependency resolution, and application startup in a structured way.

🫘 Overview

Alias Registry – Manage alternative names for pods (objects).
Core Factories – Define and resolve object creation strategies.
Pod Definitions – Represent metadata and configuration for pods.
Expressions – Evaluate or transform pod references.
Helpers – Utilities for nullable handling, enums, and object wrapping.
Instantiation – Strategies for creating pod instances.
Lifecycle – Hooks and processors for object lifecycle events.
Name Generators – Strategies for naming pods consistently.
Scopes – Contextual lifetimes (e.g., singleton, prototype).
Singleton Registry – Manage global singleton instances.
Startup – Application bootstrap and initialization.
Exceptions – Common error types for the DI container.

🫘 Example

import 'package:jetleaf_pod/jetleaf_pod.dart';

void main() {
  final factory = DefaultListablePodFactory();

  factory.registerDefinition(
    PodDefinition(
      name: 'service',
      create: () => MyService(),
    ),
  );

  final service = factory.getPod<MyService>('service');
  service.run();
}

🫘 Key Benefits

Lightweight and modular.
Flexible factories, scopes, and lifecycle processors.
Extensible with custom implementations.
Application-ready with startup orchestration.

See the individual sub-libraries for detailed API documentation.

Classes

AbstractAutowirePodFactory: Abstract base class for pod factories that support autowiring capabilities.
AbstractPodDefinition: An abstract base class for pod definitions that extends PodDefinition.
AbstractPodFactory: Abstract base implementation of PodFactory that provides core functionality for pod creation, management, and lifecycle handling in the Jetleaf framework.
AbstractPodProviderFactory: Retrieves the PodProvider backing a pod.
AliasRegistry: An abstract interface for managing name aliases in a registry system.
AliasRegistryAware: Contract for objects that support alias registration.
ApplicationStartup: Instruments the application startup phase using StartupSteps.
ApplicationStartupAware: Defines a contract for components that are aware of and can interact with an ApplicationStartup strategy.
ArgumentValue: Holder for a constructor argument value, including its optional type and name metadata.
ArgumentValueHolder: Argument Value Holder
AutowireCandidateDescriptor: Describes whether a component is eligible for autowiring.
AutowirePodFactory: Extends PodFactory with automatic dependency injection capabilities.
ConfigurableListablePodFactory: The most comprehensive pod factory interface combining listing and configuration capabilities.
ConfigurablePodFactory: A comprehensive pod factory interface with configuration capabilities.
ConstructorArgumentValues: Holder for constructor argument values used when instantiating a pod.
ConvertibleValue: Abstraction for holding a raw value and its converted state.
DefaultApplicationStartup: A no-op implementation of ApplicationStartup that always returns a singleton DefaultStartupStep for any startup operation.
DefaultListablePodFactory: Default implementation of ConfigurableListablePodFactory that provides comprehensive pod management capabilities in the Jetleaf framework.
DefaultObjectProvider<T>: Default implementation of ObjectProvider in Jetleaf.
DefaultStartupStep: A no-op implementation of StartupStep used by DefaultApplicationStartup.
DefaultStartupStepTags: A no-op, empty tag collection returned by DefaultStartupStep.
DependencyDescriptor: Describes a dependency required by a component or pod.
DependencyDesign: Describes a dependency required by a component or pod.
DesignDescriptor: Describes the design role configuration of a component.
DisposablePod: Interface to be implemented by pods that need to release resources or perform cleanup when being removed from the container or shut down.
ExecutableHolder: Executable Holder
ExecutableStrategy: Executable Strategy
FactoryAwareOrderSourceProvider: An OrderSourceProvider implementation that is aware of the container’s DefaultListablePodFactory.
FactoryMethodDesign: Describes a factory method used to create a pod (component).
HierarchicalPodFactory: Extends PodFactory with hierarchical capabilities for parent-child relationships.
InitializingPod: Interface to be implemented by pods that require initialization logic after their properties have been set by the container.
LifecycleDesign: Describes lifecycle behavior of a component, such as initialization and destruction methods.
ListablePodDefinitionRegistry: Interface for registries that provides additional functionality for listing and enumeration.
ListablePodFactory: Extends PodFactory with capabilities to list and query pods.
Mergeable: Interface for objects that can merge with other objects of the same type.
MutablePropertyValues: Mutable implementation of PropertyValues interface.
NullablePod: A special marker pod instance that represents a nullable or absent pod value.
ObjectFactory<T>: A generic factory interface for producing instances of a given type T.
ObjectHolder<T>: A generic container that holds an object along with optional metadata such as its package name and qualified name.
ObjectProvider<T>: A flexible, functional-style provider interface for retrieving and interacting with pods or objects of a particular type.
PodDefinition: Defines the blueprint of a pod (component) in the dependency injection system.
PodDefinitionRegistry: Interface for registries that hold PodDefinition instances.
PodDestructionProcessor: Processor that provides hooks into the pod destruction and cleanup lifecycle.
PodExpression<T>: Pod Expression Contract
PodExpressionContext: Context for evaluating expressions in a pod environment.
PodExpressionResolver: Strategy interface for resolving pod definition values and expressions.
PodFactory: The core factory interface for managing and retrieving pods (components) in Jetleaf.
PodInitializationProcessor: Processor that provides hooks into the pod initialization lifecycle phases.
PodInstantiationProcessor: Processor that provides hooks into the pod instantiation and property population lifecycle.
PodNameGenerator: Strategy interface for generating pod names for PodDefinitions.
PodProcessor: Abstract interface for processors that handle or manipulate pods in the JetLeaf framework.
PodProvider<T>: Interface for objects that are themselves factories for other objects.
PodScope: Interface for pod scopes that manage object lifecycle and contextual storage.
PodSmartInstantiationProcessor: Advanced processor that provides sophisticated control over pod instantiation.
PropertyValue: Represents a property with a _name and its associated _value.
PropertyValues: Interface for accessing a collection of PropertyValue objects.
RootPodDefinition: A concrete implementation of AbstractPodDefinition that serves as the default pod definition in the system.
ScopeDesign: Describes the scope configuration of a component.
ScopedObjectFactory<T>: An ObjectFactory implementation that retrieves objects from a specific PodScope.
SimpleAliasRegistry: A thread-safe implementation of AliasRegistry using LocalThread storage.
SimpleObjectFactory<T>: Default implementation of the ObjectFactory interface that uses a creator function.
SimplePodDefinitionRegistry: A basic registry for managing pod definitions.
SimplePodNameGenerator: Default implementation of the PodNameGenerator interface.
SingletonPodRegistry: Interface for registries that hold singleton pod instances.
SmartInitializingSingleton: Callback interface triggered at the end of the singleton pre-instantiation phase.
StandardStartupTracker: Standard implementation of the {@macro startup} interface.
StartupStep: Step recording metrics about a particular phase or action happening during the ApplicationStartup.
StartupStepTag: Attaches a static key/value tag to this step.
StartupStepTags: Returns the complete list of StartupStepTags associated with this step.
StartupTracker: Represents a startup lifecycle monitor for JetLeaf-based applications.
StringValueResolver: Interface for resolving string values to their actual values.

Enums

AutowireMode: Defines strategies for automatically wiring dependencies in a system.
DependencyCheck: Defines the type of dependency validation to be performed when initializing a component or system.
DesignRole: Defines the architectural role of a component within a system.
ScopeType: Defines the lifecycle scope of a component within a dependency injection container.

Typedefs

CreatedPodHolder = (String, PodDefinition, Object): The holder for created pods
ObjectFactoryFunction<T> = FutureOr<ObjectHolder<T>> Function([List<ArgumentValue>? args]): A function that creates an instance of type T.
PodDefinitionHolder = (String, PodDefinition, List<String>): Type definition for a pod definition holder tuple.
PodHolder = (Object, Class): A tuple representing a pod and its class.

Exceptions / Errors

FatalPodException: Base class for fatal pod-related exceptions that indicate unrecoverable errors.
NoSuchPodDefinitionException: Exception thrown when a PodFactory is asked for a pod instance by name, and no definition for that pod name exists.
NoUniquePodDefinitionException: Exception thrown when multiple pod definitions are found for a given type in the application context.
PodCreationException: Exception thrown when a pod cannot be created.
PodCreationNotAllowedException: Exception thrown when a pod creation is not allowed in the current context.
PodCurrentlyInCreationException: Exception thrown when a pod is currently in the process of being created.
PodDefinitionOverrideException: Exception thrown when a pod definition is overridden.
PodDefinitionStoreException: Exception thrown when a pod definition store error occurs.
PodDefinitionValidationException: Exception thrown when a pod definition is invalid during validation.
PodException: Base exception type for all pod-related errors in JetLeaf.
PodIsAbstractException: Exception thrown when attempting to instantiate a pod that is marked as abstract.
PodIsNotAProviderException: Exception thrown when a pod is expected to be a PodProvider but is not.
PodNotOfRequiredTypeException: Exception thrown when a pod retrieved from the context is not of the expected type.
PodProviderNotInitializedException: Exception thrown when attempting to use a PodProvider that hasn't been fully initialized.
ScopeNotActiveException: Exception thrown when a pod is requested from a scope that is not active.
UnsatisfiedDependencyException: Exception thrown when a dependency is not satisfied for a pod.

pod library

🫘 Overview

🫘 Example

🫘 Key Benefits

Classes

Enums

Typedefs

Exceptions / Errors

jetleaf_pod package

pod library