utils library

🧩 Jetleaf Utilities Subsystem

This library provides general-purpose helper utilities, text processors, configuration format parsers, and diagnostic decoding tools for the Jetleaf framework.

Key capabilities:

  • Recursive Placeholder Resolution: Dynamic resolution of ${key:default} patterns.
  • Multi-Format Parsers: Unified AST and object parsing for YAML, JSON, XML, Properties, and ENV.
  • Stack Trace Sanitization: Demangling and filtering internal VM frames for clear diagnostics.
  • Assertion & String Helpers: Defensive programming guards and casing utilities.

🔄 Placeholder Resolution Flow

┌─────────────────────────────────────────────────────────────┐
│                     Input Template String                   │
│              "https://${server.host:localhost}:${port}"     │
├─────────────────────────────────────────────────────────────┤
│ 1. Parse Token         Find prefix "${" and suffix "}"      │
│                               │                             │
│ 2. Extract Key/Default  key: "server.host", fallback: "..." │
│                               │                             │
│ 3. Query Resolver      Look up key in PropertyPlaceholder   │
│                               │                             │
│ 4. Recursive Replace   Substitute nested expressions        │
└─────────────────────────────────────────────────────────────┘

📦 Exports Categorization

🏷️ Placeholder Resolution

📄 Configuration Parsers

  • YamlParser — parses structured YAML documents into Dart Maps and Lists.
  • JsonParser — parses JSON streams and strings with strict type safety.
  • PropertiesParser — parses Java-style .properties key-value pairs.
  • EnvParser — parses .env files with quoted strings and variable expansion.

🩺 Stack Trace Utilities

🛡️ Guards & Defensiveness

  • Assert — defensive programming validation helpers (e.g. notNull, hasText, state).
  • StringUtils — high-performance string manipulation, casing, and collection joining.

🎯 Usage Example: Placeholders & Defensive Assertions

import 'package:jetleaf_core/utils.dart';

void main() {
  // 1. Validate preconditions with Assert
  final username = 'alice';
  Assert.hasText(username, 'Username must not be empty');

  // 2. Resolve placeholders dynamically
  final helper = PropertyPlaceholderHelper('\${', '}');
  final properties = {
    'api.host': 'api.jetleaf.dev',
    'api.version': 'v2',
  };

  final endpoint = helper.replacePlaceholders(
    'https://\${api.host}/\${api.version}/users/\${api.missing:current}',
    (key) => properties[key],
  );

  print('Resolved Endpoint: $endpoint');
  // Output: https://api.jetleaf.dev/v2/users/current
}

Classes

Assert
A utility class that provides static assertion methods for validating arguments and states in your application.
DartParser
A parser for Dart configuration files in Jetleaf.
EnvParser
Parses dotenv (.env) style files into a Map<String, dynamic>.
JsonParser
A parser for JSON configuration files.
NestedPlaceholderPart
A PlaceholderPart that represents a nested placeholder expression with optional fallback.
PackageUtils
Utility class for resolving and caching Dart packages at runtime.
Parser
A base interface for all configuration parsers in Jetleaf.
PlaceholderAbstractPart
Base class for all PlaceholderPart implementations that represent a segment of a parsed placeholder expression.
PlaceholderParsedSection
Represents a parsed section of a placeholder string, typically extracted from a raw placeholder like #{key:default}.
PlaceholderParsedValue
A container for a parsed text and its constituent Part objects.
PlaceholderParser
A utility class for parsing and resolving placeholders within a string.
PlaceholderPart
Represents a segment or fragment of a placeholder expression.
PlaceholderPartResolutionContext
A resolution context for placeholder expressions, providing configuration, resolution logic, and tracking for visited placeholders.
PlaceholderResolver
Strategy interface for resolving placeholder values in configuration strings.
PlaceholderTextPart
A PlaceholderPart implementation that represents literal, already-resolved text within a placeholder expression.
PropertiesParser
A parser for Java-style properties files.
PropertyPlaceholderHelper
A utility class for resolving string values that contain placeholders in the format #{name}.
SimplePlaceholderPart
A PlaceholderPart that represents a basic placeholder expression with an optional fallback.
StackTraceParser
A comprehensive stack trace parsing utility for Jetleaf applications.
StringUtils
🚀 StringUtils — A collection of common string manipulation utilities.
SystemPropertyPlaceholderResolver
A PlaceholderResolver implementation that resolves placeholders using system properties and environment variables.
SystemPropertyUtils
Utility class for resolving #{...}-style placeholders within strings using system properties or environment variables.
TraceFrame
Represents a single structured entry in a Jetleaf stack trace.
TraceMapping
A structured representation of a complete stack trace with analysis capabilities.
XmlParser
A parser for XML configuration files.
YamlParser
A parser for YAML configuration files.

Extensions

PlaceholderResolverExtension on PlaceholderResolverFn
Extension to provide a method-style interface on PlaceholderResolverFn functions.

Typedefs

PlaceholderResolverFn = String? Function(String placeholderName)

Exceptions / Errors

ParserException
Exception thrown when parsing fails.
PlaceholderResolutionException
Exception thrown when placeholder resolution fails.