utils/format/format_utils
library
Functions
-
addItemToJSONCArray(String content, dynamic newItem)
→ String
-
Add an item to a JSON array string, preserving formatting.
-
coerceDescriptionToString(dynamic value, {String? componentName, String? pluginName})
→ String?
-
Coerce a description value from frontmatter to a string.
-
expandBraces(String pattern)
→ List<String>
-
Expand brace patterns in a glob string.
-
formatDuration(int ms, {bool hideTrailingZeros = false, bool mostSignificantOnly = false})
→ String
-
Formats a duration in milliseconds to a human-readable string.
-
formatFileSize(int sizeInBytes)
→ String
-
Formats a byte count to a human-readable string (KB, MB, GB).
Example:
formatFileSize(1536) returns "1.5KB".
-
formatLogMetadata({required DateTime modified, required int messageCount, int? fileSize, String? gitBranch, String? tag, String? agentSetting, int? prNumber, String? prRepository})
→ String
-
Formats log metadata for display.
-
formatNumber(int number)
→ String
-
Formats a number using compact notation.
Example:
formatNumber(1321) returns "1.3k".
-
formatRelativeTime(DateTime date, {RelativeTimeStyle style = RelativeTimeStyle.narrow, DateTime? now})
→ String
-
Format a date as a relative time string.
-
formatRelativeTimeAgo(DateTime date, {RelativeTimeStyle style = RelativeTimeStyle.narrow, DateTime? now})
→ String
-
Format a past date as relative time ago.
-
formatResetText(String resetsAt, {bool showTimezone = false, bool showTime = true})
→ String
-
Format a reset time from an ISO 8601 string.
-
formatResetTime(int? timestampInSeconds, {bool showTimezone = false, bool showTime = true})
→ String?
-
Formats a reset timestamp for display.
-
formatSecondsShort(int ms)
→ String
-
Formats milliseconds as seconds with 1 decimal place.
Example:
formatSecondsShort(1234) returns "1.2s".
-
formatTokens(int count)
→ String
-
Formats a token count, removing trailing
.0.
-
parseBooleanFrontmatter(dynamic value)
→ bool
-
Parse a boolean frontmatter value.
-
parseFrontmatter(String markdown, {String? sourcePath})
→ ParsedMarkdown
-
Parse markdown content to extract frontmatter and body.
-
parseJSONL<T>(String data)
→ List<T>
-
Parse JSONL data from a string, skipping malformed lines.
-
parsePositiveIntFromFrontmatter(dynamic value)
→ int?
-
Parse a positive integer from frontmatter.
-
parseShellFrontmatter(dynamic value, {required String source})
→ FrontmatterShell?
-
Parse and validate the
shell: frontmatter field.
-
readJSONLFile<T>(String filePath)
→ Future<List<T>>
-
Read and parse a JSONL file.
-
safeParseJSON(String? jsonStr, {bool shouldLogError = true})
→ dynamic
-
Safely parse a JSON string, returning null on failure.
-
splitPathInFrontmatter(dynamic input)
→ List<String>
-
Split paths in frontmatter, respecting brace patterns.
-
stringWidth(String text)
→ int
-
Returns the visual width of a string (simple approximation).
For full CJK/emoji awareness, integrate a proper stringWidth package.
-
treeify(TreeNode obj, {TreeifyOptions options = const TreeifyOptions()})
→ String
-
Render a tree node as a string.
-
truncate(String str, int maxWidth, {bool singleLine = false})
→ String
-
Truncates a string with optional single-line mode.
-
truncatePathMiddle(String path, int maxLength)
→ String
-
Truncates a file path in the middle to preserve directory context and filename.
-
truncateStartToWidth(String text, int maxWidth)
→ String
-
Truncates from the start of a string, keeping the tail end.
Prepends '\u2026' when truncation occurs.
-
truncateToWidth(String text, int maxWidth)
→ String
-
Truncates a string to fit within a maximum display width.
Appends '\u2026' (ellipsis) when truncation occurs.
-
truncateToWidthNoEllipsis(String text, int maxWidth)
→ String
-
Truncates a string without appending an ellipsis.
-
wrapText(String text, int width)
→ List<String>
-
Wraps text to the given width, splitting on grapheme boundaries.
