Skip to content

feat: add typed API for flamegraph and collapse#358

Open
jonhoo wants to merge 1 commit intomainfrom
api-v2
Open

feat: add typed API for flamegraph and collapse#358
jonhoo wants to merge 1 commit intomainfrom
api-v2

Conversation

@jonhoo
Copy link
Owner

@jonhoo jonhoo commented Mar 2, 2026

Inferno's library API was purely text-based: collapsers produce "stack;frames count\n" lines, and flamegraph parses them back. Downstream tools with structured stack data had to round-trip through text, causing escaping issues, wasted work, and loss of type safety (issues #30, #164, #270).

This commit adds a typed API alongside the existing text path. The core type is Sample<S>, generic over the stack iterator, which replaces the text line "main;foo;bar 42". Three new entry points accept iterators of Sample: from_sorted_stacks (requires pre-sorted input), from_stacks (sorts internally), and flame_chart_from_stacks (preserves time ordering). On the collapse side,
Collapse::collapse_to_stacks returns a FoldedStacks wrapper whose samples() method yields typed Sample values for direct rendering without text serialization. CollapsePrivate implementors get an efficient override that skips text entirely; other Collapse implementors get a default that round-trips through text that they can override if able.

Options is now Clone and has no lifetime parameter. The mutable palette_map reference moves to a separate parameter on all public functions, and text-processing fields (no_sort, reverse_stack_order, flame_chart, base) move to a new PreProcessingOptions struct that is only needed by the text-based entry points.

This is a breaking API change, hence the version bump to 1.0.0-rc.1.

@codecov
Copy link

codecov bot commented Mar 2, 2026

Codecov Report

❌ Patch coverage is 70.60932% with 82 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.84%. Comparing base (51423f4) to head (7dd0e67).

Files with missing lines Patch % Lines
src/collapse/mod.rs 0.00% 62 Missing ⚠️
src/collapse/common.rs 30.76% 18 Missing ⚠️
src/flamegraph/merge.rs 96.66% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #358      +/-   ##
==========================================
- Coverage   91.22%   89.84%   -1.38%     
==========================================
  Files          21       21              
  Lines        4272     4481     +209     
==========================================
+ Hits         3897     4026     +129     
- Misses        375      455      +80     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jonhoo
Copy link
Owner Author

jonhoo commented Mar 2, 2026

This took me forever to get around to, but here's finally a first draft of a more reasonable crate API for inferno.

Would love to get input from the various people interested in #30, #164, and #270, like @koute, @Licenser, @Kixiron, @itamarst, and @stepancheg.

I also figure that once we land this, we're probably ready to mark inferno as 1.0 👀

Inferno's library API was purely text-based: collapsers produce
`"stack;frames count\n"` lines, and flamegraph parses them back.
Downstream tools with structured stack data had to round-trip through
text, causing escaping issues, wasted work, and loss of type safety
(issues #30, #164, #270).

This commit adds a typed API alongside the existing text path. The core
type is `Sample<S>`, generic over the stack iterator, which replaces the
text line `"main;foo;bar 42"`. Three new entry points accept iterators
of `Sample`: `from_sorted_stacks` (requires pre-sorted input),
`from_stacks` (sorts internally), and `flame_chart_from_stacks`
(preserves time ordering). On the collapse side,
`Collapse::collapse_to_stacks` returns a `FoldedStacks` wrapper whose
`samples()` method yields typed `Sample` values for direct rendering
without text serialization. `CollapsePrivate` implementors get an
efficient override that skips text entirely; other `Collapse`
implementors get a default that round-trips through text that they can
override if able.

`Options` is now `Clone` and has no lifetime parameter. The mutable
`palette_map` reference moves to a separate parameter on all public
functions, and text-processing fields (`no_sort`, `reverse_stack_order`,
`flame_chart`, `base`) move to a new `PreProcessingOptions` struct that
is only needed by the text-based entry points.

This is a breaking API change, hence the version bump to `1.0.0-rc.1`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant