utils library Jetleaf

🛠️ Jetleaf Utilities & Helper Subsystem

This library provides the reusable algorithmic primitives, assertion helpers, string formatters, collection utilities, and hashing contracts used across the Jetleaf framework:

  • String Manipulation: StringUtils (camelCase, kebab-case, snake_case, uncapitalize, cleanPath).
  • Equality & Hashing: EqualsAndHashCode, ObjectUtils.
  • Defensive Checks: Assert, preconditions, and parameter validation.
  • Collection Tools: CollectionUtils, array and list slicing, deduplication.
  • Optional Values: Optional monad for expressive nullable value handling.

📦 Exports Categorization

🔤 String & Path Utilities

  • StringUtils — high-performance string operations: capitalization, substring splitting, token replacement, path normalization.

🛡️ Preconditions & Assertions

📦 Optional Monad

  • Optional — container object which may or may not contain a non-null value (isPresent, ifPresent, orElse, map).

⚖️ Equality & Hashing

  • EqualsAndHashCode — mixin providing deep equality and deterministic hash code computation.
  • ObjectUtils — safe null-handling, identity comparisons, and string representations.

🎯 Usage Example: Defensive Assertions & Optional Handling

import 'package:jetleaf/utils.dart';

class AccountService {
  void deposit(String accountId, double amount) {
    Assert.hasText(accountId, 'Account ID must not be blank');
    Assert.isTrue(amount > 0, 'Deposit amount must be strictly positive');

    print('Deposited \$$amount into $accountId');
  }

  Optional<String> findDiscountCode(String tier) {
    if (tier == 'VIP') {
      return Optional.of('VIP-DISCOUNT-50');
    }
    return Optional.empty();
  }
}

void main() {
  final service = AccountService();
  service.deposit('ACC-4001', 150.0);

  final discount = service.findDiscountCode('VIP');
  print('Discount: ${discount.orElse('NO_DISCOUNT')}');
}

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.