env library Jetleaf

🌍 Jetleaf Environment, Profiles & Property Resolution Subsystem

This library provides the centralized environment abstraction, multi-profile management, and hierarchical property resolution engine for the Jetleaf framework.

It encapsulates:


πŸ›οΈ Hierarchical Property Resolution Cascade

Jetleaf resolves configuration properties by cascading through ordered property sources:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                 Hierarchical Property Sources (Highest to Lowest)      β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ 1. Command-Line Arguments   (--server.port=9090, -Dcustom=val)         β”‚
β”‚                                    β”‚                                   β”‚
β”‚ 2. Environment Variables    (SERVER_PORT=8080, JETLEAF_ACTIVE_PROFILES)β”‚
β”‚                                    β”‚                                   β”‚
β”‚ 3. Profile-Specific Files   (application-prod.properties / .yaml)      β”‚
β”‚                                    β”‚                                   β”‚
β”‚ 4. Default Application File (application.properties / .yaml / .json)   β”‚
β”‚                                    β”‚                                   β”‚
β”‚ 5. Programmatic Defaults    (DefaultPropertiesPropertySource)          β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ“¦ Exports Categorization

🌍 Environment Management

  • Environment β€” read-only access to active profiles and configuration properties.
  • ConfigurableEnvironment β€” allows mutation of active profiles and property sources.
  • StandardEnvironment β€” standard production environment incorporating system env and properties.
  • Profiles β€” utility for profile predicate evaluation (e.g. dev & !cloud).

πŸ” Property Resolvers & Sources


🎯 Usage Example: Configuring Profiles & Reading Typed Properties

import 'package:jetleaf/env.dart';

void main() {
  final env = StandardEnvironment();

  // 1. Configure active environment profiles
  env.setActiveProfiles(['production', 'eu-west']);

  // 2. Add an in-memory property source
  env.getPropertySources().addFirst(
    MapPropertySource('customConfig', {
      'server.host': '0.0.0.0',
      'server.port': 8080,
      'cache.enabled': true,
    }),
  );

  // 3. Resolve properties with defaults
  final host = env.getProperty<String>('server.host', 'localhost');
  final port = env.getProperty<int>('server.port', 3000);
  final isCache = env.getProperty<bool>('cache.enabled', false);

  print('Server listening on: $host:$port (Cache: $isCache)');
  print('Active profiles: ${env.getActiveProfiles()}');
}

Classes

AbstractEnvironment
Base class for creating environment implementations in Jetleaf.
AbstractPropertyResolver
An abstract base implementation of ConfigurablePropertyResolver that provides common functionality for resolving property placeholders, type conversion, and required property validation.
AlphabeticalRule
A property source ordering rule that sorts sources alphabetically by name.
ApplicationArguments
Defines the contract for accessing and parsing command-line arguments passed to an application.
ApplicationConfigurationProperties
ConfigurationProperties is a class for defining application configuration in a typed and expressive way, similar to defining settings in application.yaml, but directly in Dart.
ApplicationConfigurationProperty
A base class for defining structured and strongly typed configuration classes in the Jetleaf framework.
BeforeRule
Represents a reordering rule for property sources that ensures one source appears before another within a list of PropertySources.
CommandLinePropertySource<T>
A base class for property sources that are backed by command line arguments.
ComparatorRule
A property source ordering rule that sorts sources using a custom OrderComparator.
CompositePropertySource
A composite implementation of ListablePropertySource that aggregates multiple PropertySource instances.
ConfigurableEnvironment
A configurable extension of the Environment interface that allows mutation of environment internals such as active profiles and property sources.
ConfigurablePropertyResolver
A specialized PropertyResolver that allows full control over property placeholder behavior and type conversion logic using a configurable ConfigurableConversionService.
DefaultApplicationArguments
Default implementation of ApplicationArguments that wraps command-line arguments and exposes them via a PropertySource-based backing system.
Env<T>
A generic configuration property accessor for environment variables.
Environment
Environment Contract
GlobalEnvironment
A concrete implementation of AbstractEnvironment that represents the default runtime environment for most applications.
JetleafProperty
Base class for all Jetleaf framework configuration properties.
ListablePropertySource<T>
A specialized PropertySource capable of enumerating all available property keys, allowing efficient lookup operations.
MapPropertySource
A PropertySource implementation backed by a Map of key-value pairs.
MutablePropertySources
A mutable container for managing an ordered list of PropertySource objects.
PriorityRule
A reordering rule for property sources based on explicit numeric priorities.
Profiles
A profile predicate used by Environment to determine if given profile expressions match the active/default profiles.
PropertyResolver
A service abstraction for resolving application properties and configuration values.
PropertySource<T>
A base abstraction representing a source of key-value properties, such as maps, environment variables, or configuration files.
PropertySourceOrderRule
Defines a user-supplied rule that determines the ordering of `PropertySource` objects within Jetleaf’s configuration system.
PropertySources
A collection of PropertySources that provides lookup and stream support.
PropertySourcesPropertyResolver
A concrete implementation of AbstractPropertyResolver that retrieves property values from a collection of PropertySources managed by a MutablePropertySources container.
SimpleCommandLinePropertySource
A CommandLinePropertySource that adapts CommandLineArgs into a resolvable PropertySource.
SystemEnvironmentPropertySource
A MapPropertySource that exposes system environment variables as a property source.

Mixins

ConfigurationPropertySource
A mixin that provides access to a globally attached Environment.

Properties

environmentLoggingListener β†’ Obs<Map<LogLevel, String>>
A reactive listener that holds environment-specific logging configuration.
final

Exceptions / Errors

DartLoadingException
Exception thrown when Dart file loading fails.
EnvironmentParsingException
An Exception thrown when an error occurs during environment property parsing.
MissingRequiredEnvironmentException
Exception thrown when a required environment variable is not found.
MissingRequiredPropertiesException
Exception thrown when required properties are not found.