utils library

🧩 JetLeaf Utilities Library

This library provides a collection of general-purpose utilities for JetLeaf applications, including:

  • placeholder resolution
  • configuration file parsing (JSON, YAML, XML, Dart, env, properties)
  • stack trace parsing and mapping
  • string, package, and system property helpers

It is designed to streamline common framework-level operations and provide a consistent set of tools for application development.

🔑 Key Concepts

🔧 Placeholder Resolution

  • PlaceholderParser — parses placeholders in strings (e.g., ${value})
  • PlaceholderResolver — resolves placeholders to actual values
  • PropertyPlaceholderHelper — utility methods for working with placeholders

📄 Configuration File Parsers

Support multiple file formats for configuration:

  • JsonParser — parses JSON configuration
  • YamlParser — parses YAML configuration
  • XmlParser — parses XML configuration
  • PropertiesParser — parses .properties files
  • DartParser — parses Dart code as configuration
  • EnvParser — parses environment variables
  • Parser — base interface for custom parsers

🧾 Stack Trace Parsing

  • StackTraceParser — parses raw stack traces
  • TraceFrame — represents a single frame in the stack trace
  • TraceMapping — maps frames for better readability

Useful for debugging, logging, and error reporting.

🛠 General Utilities

  • assert.dart — extended assertion helpers
  • exceptions.dart — common exception types
  • package_utils.dart — helpers for package management
  • string_utils.dart — string manipulation utilities
  • system_property_utils.dart — helpers for accessing system properties

🎯 Intended Usage

Import this library when you need:

  • robust placeholder resolution
  • configuration parsing from multiple formats
  • stack trace analysis and formatting
  • helper utilities for strings, packages, and system properties

Example:

import 'package:jetleaf_utils/utils.dart';

final parser = JsonParser();
final config = parser.parse(jsonString);

final resolved = PropertyPlaceholderHelper.replacePlaceholders(
  'Hello ${name}', {'name': 'JetLeaf'}
);

© 2025 Hapnium & JetLeaf Contributors

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.