jetleaf_core

The unified core runtime powering dependency injection, lifecycle management, environment configuration, logging, and type conversion for the Jetleaf framework.

pub package tests pure AOT license platform

Features • Installation • Quick Start • Architecture & Subsystems • Dependency Injection • Environment & Config • Type Conversion • Logging • Language Primitives • Utilities • AOT Compilation • Testing


jetleaf_core is the enterprise-grade foundation of the Jetleaf application framework. It brings robust dependency injection, hierarchical configuration resolution, declarative metadata, event-driven decoupling, structured logging, and extensible type conversion to Dart — engineered from the ground up for pure AOT compilation (dart compile exe) with zero reflection runtime performance penalties.

// Import the complete unified framework
import 'package:jetleaf_core/jetleaf_core.dart';

// Or import specific modular entry points
import 'package:jetleaf_core/core.dart';
import 'package:jetleaf_core/pod.dart';
import 'package:jetleaf_core/env.dart';
import 'package:jetleaf_core/logging.dart';
import 'package:jetleaf_core/convert.dart';
import 'package:jetleaf_core/utils.dart';
import 'package:jetleaf_core/lang.dart';

✨ Features

  • Unified 7-in-1 Architecture — Consolidates the complete Jetleaf runtime (core context, pods/IoC, environment, logging, conversion, utilities, and language extensions) into a single cohesive package.
  • Declarative Inversion of Control (IoC) — Full container lifecycle management (GenericApplicationContext, AnnotationConfigApplicationContext, DefaultListablePodFactory) supporting singleton and prototype scopes, eager/lazy initialization, constructor/property autowiring, and circular dependency resolution.
  • Hierarchical Environment & Properties — Type-safe configuration binding (@ConfigurationProperties), multi-profile support (dev, prod, test), and hierarchical property resolution across environment variables, CLI options, YAML/JSON/Properties files, and custom property sources.
  • Pure AOT Native Compilation — Completely mirror-free (dart:mirrors free). Generates deterministic dispatch registries at build time that survive Dart's aggressive tree-shaker without reflection compromises.
  • Decoupled Event Bus — Synchronous and asynchronous application event dispatching (ApplicationEvent, @EventListener, SimpleApplicationEventBus) with ordering and payload validation.
  • Extensible Type Conversion Service — Robust conversion pipeline (ConversionService, ConverterRegistry) covering primitives, collections, custom objects, enums, dates, and localized strings with bidirectional adapters.
  • Structured Leveled Logging — Pluggable ANSI-formatted console logging with customizable log levels (TRACE through FATAL), formatters (PrettyPrinter, FlatStructuredPrinter, FmtPrinter), and filter pipelines.
  • High-Performance Collections & Functional Streams — Low-overhead linear data structures (ArrayList, LinkedList, Stack, Queue, HashMap, CaseInsensitiveMap) and functional streams (GenericStream, IntStream, DoubleStream, Collector).
  • Cross-Cutting Method Interception — Method interception hooks (@Intercept, Interceptable, MethodInterceptor) for declarative caching, audit trails, transactions, and metrics.

📦 Installation

Add jetleaf_core to your pubspec.yaml:

dependencies:
  jetleaf_core: ^2.0.0

dev_dependencies:
  jetleaf_tools: ^1.0.1

Fetch dependencies:

dart pub get

🚀 Quick Start

Here is a complete, runnable example showcasing configuration classes, pods, dependency injection, and environment property resolution in under 40 lines of code:

import 'package:jetleaf_core/jetleaf_core.dart';

// 1. Define a domain service
@Service()
class UserService {
  final DatabaseClient _db;
  
  UserService(this._db);

  Future<void> createUser(String name) async {
    console.info('Creating user: $name via ${_db.url}');
  }
}

// 2. Define a dependency pod
class DatabaseClient {
  final String url;
  DatabaseClient(this.url);
}

// 3. Define an application configuration module
@Configuration()
class AppConfig {
  @Pod()
  DatabaseClient databaseClient(@Value('\${app.database.url:memory://default}') String url) {
    return DatabaseClient(url);
  }
}

void main() async {
  // 4. Initialize the application context
  final context = AnnotationConfigApplicationContext();
  context.register(AppConfig);
  context.register(UserService);
  await context.refresh();

  // 5. Retrieve and execute the managed pod
  final userService = context.getPod<UserService>();
  await userService.createUser('Alice');

  // 6. Gracefully shut down
  await context.close();
}

🏛 Architectural Subsystems

jetleaf_core is organized into 7 distinct, cohesive subsystems under lib/src/:

┌────────────────────────────────────────────────────────────────────────┐
│                          jetleaf_core (2.0.0)                          │
├──────────────┬──────────────┬──────────────┬──────────────┬────────────┤
│  src/core/   │   src/pod/   │   src/env/   │ src/logging/ │src/convert/│
│ Context,     │ IoC Container│ Environment, │ Structured   │ Type       │
│ Events,      │ Factories,   │ Profiles,    │ Loggers,     │ Conversion │
│ Lifecycle    │ Scopes       │ Properties   │ Printers     │ Pipeline   │
├──────────────┴──────────────┴──────────────┴──────────────┴────────────┤
│                src/lang/                │          src/utils/          │
│ Metaprogramming, Collections, I/O       │ Placeholders, Parsers, Assert│
└─────────────────────────────────────────┴──────────────────────────────┘

🫘 Dependency Injection (Pods)

The IoC container in jetleaf_core is built around the concept of Pods — lightweight, managed components that participate in dependency injection, lifecycle callbacks, and scoping.

Registering Pods

Pods can be declared using annotations or registered programmatically:

// Declarative stereotype annotations
@Component()
class EmailNotifier implements Notifier {}

@Repository()
class OrderRepository {}

// Programmatic pod registration
final context = GenericApplicationContext();
context.registerPod<OrderRepository>();
context.registerPod<EmailNotifier>(name: 'primaryNotifier');

Autowiring & Injection

Constructor injection is the recommended pattern:

@Service()
class OrderService {
  final OrderRepository repository;
  final Notifier notifier;

  // Dependencies are automatically resolved by type and qualifier
  OrderService(this.repository, @Qualifier('primaryNotifier') this.notifier);
}

Pod Lifecycles & Callbacks

Components can hook into the container lifecycle via interfaces or annotations:

@Service()
class CacheService implements InitializingPod, DisposablePod {
  @override
  Future<void> onReady() async {
    console.info('Cache warmed up.');
  }

  @override
  Future<void> onDestroy() async {
    console.info('Cache flushed to disk.');
  }
}

🌍 Environment & Properties

The environment abstraction (Environment) provides unified access to runtime configuration, active profiles, and hierarchical property resolution.

Hierarchical Resolution Order

Properties are resolved across multiple layered sources with deterministic precedence:

  1. Command Line Arguments (--server.port=8080)
  2. System Environment Variables (SERVER_PORT=8080)
  3. Profile-Specific Configuration (application-prod.yaml)
  4. Default Configuration (application.yaml)
final env = StandardEnvironment();
env.setActiveProfiles(['prod']);

// Placeholder resolution with default fallback syntax
final port = env.resolvePlaceholders('\${server.port:8080}');
final dbHost = env.getProperty<String>('database.host', defaultValue: 'localhost');

Strongly-Typed Configuration Binding

Bind structured configuration maps directly into immutable classes:

@ConfigurationProperties(prefix: 'server')
class ServerConfig {
  final int port;
  final String host;
  final Duration timeout;

  const ServerConfig({
    required this.port,
    this.host = '0.0.0.0',
    this.timeout = const Duration(seconds: 30),
  });
}

🔄 Type Conversion

jetleaf_core includes a comprehensive type conversion service (DefaultConversionService) capable of converting between primitives, collections, complex objects, and dates:

import 'package:jetleaf_core/convert.dart';

final conversionService = DefaultConversionService();

// Primitives and numbers
final intVal = conversionService.convert<int>('42'); // 42
final boolVal = conversionService.convert<bool>('true'); // true

// Dates and durations
final duration = conversionService.convert<Duration>('5s'); // Duration(seconds: 5)
final dateTime = conversionService.convert<DateTime>('2026-11-08T07:00:00Z');

// Custom Converter Registration
conversionService.addConverter<String, GeoLocation>(
  Converter.from((source) => GeoLocation.parse(source)),
);

📝 Structured Logging

The logging engine (package:jetleaf_core/logging.dart) provides structured, leveled, colorized output with zero external dependencies:

import 'package:jetleaf_core/logging.dart';

// Quick global console logger
console.info('Application started successfully.');
console.warn('Cache hit ratio below 80%');
console.error('Database connection timeout', error: err, stackTrace: st);

// Custom scoped logger with formatted output
final logger = Logger(
  name: 'HTTP-Worker',
  level: LogLevel.DEBUG,
  printer: PrettyPrinter(),
);

logger.debug('Handled request in 12ms', tag: 'perf');

📚 Language Primitives & Collections

jetleaf_core bundles low-overhead, deterministic data structures and streaming pipelines:

Structure Access / Peek Mutation Memory Alignment
ArrayList<T> $\mathcal{O}(1)$ Amortized $\mathcal{O}(1)$ Contiguous flat memory buffer
LinkedList<T> $\mathcal{O}(n)$ $\mathcal{O}(1)$ Doubly linked node chain
Stack<T> / LinkedStack<T> $\mathcal{O}(1)$ $\mathcal{O}(1)$ LIFO ring / node sequence
Queue<T> / LinkedQueue<T> $\mathcal{O}(1)$ $\mathcal{O}(1)$ FIFO ring buffer
CaseInsensitiveMap<V> $\mathcal{O}(1)$ avg $\mathcal{O}(1)$ avg Normalized header/key lookup

Functional Streams

import 'package:jetleaf_core/lang.dart';

final totalOrderAmount = GenericStream.of(orders)
    .filter((order) => order.isPaid)
    .mapToDouble((order) => order.total)
    .sum();

🧩 Utilities

  • PropertyPlaceholderHelper: Fast, recursive ${placeholder:default} resolution.
  • Parsers: Native parsers for YAML, JSON, XML, .env, and .properties.
  • Assert: Framework assertion preconditions (Assert.notNull, Assert.hasText, Assert.state).
  • StackTraceParser: Clean stack trace parsing, frame mapping, and sanitization.

⚙️ AOT Compilation

jetleaf_core is architected for Dart's ahead-of-time (AOT) compiler:

  1. Zero usage of dart:mirrors.
  2. Static dispatch registries generated via jetleaf_tools.
  3. Fully compatible with dart compile exe producing standalone, native OS binaries without external VM dependencies.
# Compile to a standalone binary
dart compile exe bin/main.dart -o build/server.exe

# Execute native binary
./build/server.exe

🧪 Testing

The repository includes over 3,600 automated tests exercising the container, factories, converters, logging formats, environment resolution, and collections:

# Run the test suite
dart test test/all_tests.dart

📄 License

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Libraries

annotation
🏷️ Jetleaf Core Annotations Subsystem
collections
📚 Jetleaf Collections, Linear Topologies & Accumulators Subsystem
context
🌱 Jetleaf Application Context Subsystem
convert
🔄 Jetleaf Type Conversion Subsystem
core
🌱 Jetleaf Core Subsystem
design
Jetleaf Standard Library
env
🌍 Jetleaf Environment & Configuration Subsystem
extensions
Architecture Ecosystem: Fluent Primitives & Object Lifecycle Extensions
format
intercept
🔄 Jetleaf Core Interception (AOP) Subsystem
io
💾 Jetleaf I/O Subsystem: Streams, Buffers & Functional Topologies
jetleaf_core
🍃 Jetleaf Core Framework
lang
Core Language Architecture: Metaprogramming Runtime, Reflection & System Topologies
logging
📝 Jetleaf Logging System
message
🌐 Jetleaf Internationalization (i18n) & Message Subsystem
pod
🫘 Jetleaf Pod Dependency Injection & IoC Subsystem
printers
🖨️ Jetleaf Logging Printers
property
📑 Jetleaf Property Source & Resolution Subsystem
utils
🧩 Jetleaf Utilities Subsystem