env library

🌍 Jetleaf Environment & Configuration Subsystem

This library provides the runtime environment and configuration infrastructure for Jetleaf applications, managing:

  • Hierarchical Property Sources: Layered resolution with deterministic precedence.
  • Environment Profiles: Conditional property activation (dev, prod, test).
  • Command-Line Arguments: Parsing positional, option, and flag arguments.
  • Type-Safe Property Resolution: Type conversion and default value fallback.

📊 Property Resolution Precedence

Properties are resolved in order of decreasing precedence:

┌─────────────────────────────────────────────────────────────┐
│ 1. Command-Line Arguments        (--server.port=9090)       │
│                           │                                 │
│ 2. System Environment Variables   (SERVER_PORT=8080)        │
│                           │                                 │
│ 3. Profile-Specific Properties   (application-prod.yaml)   │
│                           │                                 │
│ 4. Default Application Config     (application.yaml)        │
│                           │                                 │
│ 5. Programmatic Defaults         (defaultValue: 3000)       │
└─────────────────────────────────────────────────────────────┘

📦 Exports Categorization

🌍 Environment Contracts

  • Environment — the primary interface for inspecting profiles and resolving properties.
  • AbstractEnvironment — extensible base environment orchestrating property sources.
  • GlobalEnvironment — process-wide singleton environment holding default system state.

🏷️ Profiles

  • Profiles — utility contract for querying and matching active and default profiles.

⚙️ Application Arguments


🎯 Usage Example: Layered Configuration & Profile Activation

import 'package:jetleaf_core/env.dart';
import 'package:jetleaf_core/lang.dart';
import 'package:jetleaf_core/property.dart';

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

  // 1. Activate environment profiles
  env.getActiveProfiles().addAll(['prod', 'cloud']);
  if (env.acceptsProfiles(Profiles.of(['prod']))) {
    print('Running in PRODUCTION profile.');
  }

  // 2. Add custom layered property sources
  env.getPropertySources().addLast(MapPropertySource('defaultConfig', {
    'server.host': '127.0.0.1',
    'server.port': 8080,
    'server.ssl': false,
  }));

  // 3. Resolve properties with type safety and fallback
  final host = env.getProperty('server.host', 'localhost');
  final port = env.getPropertyAs<int>('server.port', Class<int>(), 3000);
  final ssl = env.getPropertyAs<bool>('server.ssl', Class<bool>(), false);

  print('Server listening on: $host:$port (SSL: $ssl)');
}

Classes

AbstractEnvironment
Base class for creating environment implementations in Jetleaf.
ApplicationArguments
Defines the contract for accessing and parsing command-line arguments passed to an application.
ConfigurableEnvironment
A configurable extension of the Environment interface that allows mutation of environment internals such as active profiles and property sources.
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.
Profiles
A profile predicate used by Environment to determine if given profile expressions match the active/default profiles.

Mixins

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

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.