feat(trie): Add support for setting up mappings of values on lookup trie.use(path, map)

[nielsenko]

Description

Adds PathTrie.use() method to apply transformation functions to values on lookup. When a mapping is registered at a path, it transforms the value at that path and all descendant paths during lookup. Multiple mappings along a path compose from leaf to root.

Key changes:

• Added map field to _TrieNode to store transformation functions
• Implemented use() method to register mappings at specific paths
• Updated lookup() to compose and apply mappings during traversal
• Added conflict detection in attach() for overlapping maps
• Added test

The higher purpose for this change is to allow for setup of middleware at various points in the routing tree. PRs to update Router<T> as well as exposing in Serverpod will follow.

Related Issues

• Fixes: #

Pre-Launch Checklist

• This update focuses on a single feature or bug fix.
• I have read and followed the Dart Style Guide and formatted the code using dart format.
• I have referenced at least one issue this PR fixes or is related to.
• I have updated/added relevant documentation.
• I have added new tests to verify the changes.
• All existing and new tests pass successfully.
• I have documented any breaking changes below.

Breaking Changes

• No breaking changes.

Summary by CodeRabbit

• New Features
  • Added per-path value transformation during route lookup, composing mappers along the matched path to modify returned values without changing routes.
• Refactor
  • Tightened generic bounds to non-nullable Object across routing types, requiring non-nullable type parameters in consumer code.
• Tests
  • Added comprehensive tests covering mapping on root, wildcards, parameters, and composition order.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

Introduces per-subpath value mapping to PathTrie with a new use(...) API and composed map application during lookup. Tightens generic bounds to T extends Object across Router, PathTrie, and routing middleware. Adds tests validating mapping behavior across path patterns.

Changes

Cohort / File(s)	Summary of Changes
PathTrie mapping and lookup updates lib/src/router/path_trie.dart	Added per-subpath mapper registration via use(NormalizedPath, T Function(T)). Composes node-level mapping functions during traversal and applies to final value in lookup. Tightened generic to PathTrie. Added validation for non-existent/conflicting mappings.
Type bound tightening across router and middleware lib/src/router/router.dart, lib/src/middleware/routing_middleware.dart	Constrained generics to T extends Object for Router, RouteEx, _RouterEntry, and routing middleware routeWith/_RoutingMiddlewareBuilder. _RouterEntry now implements Iterable<T?>. No control-flow or runtime logic change beyond type constraints.
Tests for mapping behavior test/router/path_trie_test.dart	Added test group “Use mapping” covering root, wildcard, parameterized paths, composition order, and selective descendant transformation. Imported dart:math.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Client
  participant Router
  participant PathTrie
  participant Node as Trie Node(s)

  Client->>Router: handle(request)
  Router->>PathTrie: lookup(normalizedPath)
  rect rgba(217,235,255,0.4)
    note right of PathTrie: Traverse segments (literal/param/wildcard)
    loop for each segment
      PathTrie->>Node: descend(segment)
      Node-->>PathTrie: child node + optional mapper
      note right of PathTrie: Compose mapping if present
    end
  end
  PathTrie-->>Router: TrieMatch(value [, composedMap])
  alt composedMap present
    note right of Router: Apply composedMap to value
  end
  Router-->>Client: route match (final value)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat: Support Router.attach #62 — Modifies PathTrie and Router lookup; overlaps with this PR’s PathTrie traversal and Router generic/type usage.
• feat: Router class #52 — Touches the same router and path_trie APIs; related to added use(...) and tightened generics.
• feat: The routeWith middleware builder function is now generic. #78 — Adjusts routing_middleware generics; directly related to this PR’s T extends Object constraint changes.

Pre-merge checks and finishing touches and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The PR description is well structured and documents the feature and checklist progress, but the Related Issues section lacks a specific issue reference and the corresponding checklist item remains unchecked, indicating incomplete required information.	Please add the actual issue number in the Related Issues section using the Closes/Fixes: #<issue_number> syntax and check the corresponding checklist item to reference the issue this PR addresses.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly and concisely summarizes the main feature added by this PR, namely support for setting up value mappings on lookup via the trie.use(path, map) method, and follows the project’s conventional commit format.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.84%. Comparing base (113d136) to head (ba1d6ec).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #185      +/-   ##
==========================================
+ Coverage   91.79%   91.84%   +0.04%     
==========================================
  Files          85       85              
  Lines        3133     3150      +17     
  Branches     1620     1627       +7     
==========================================
+ Hits         2876     2893      +17     
  Misses        257      257              

☔ 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.

[nielsenko]

@CodeRabbit review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nielsenko]

The test coverage could be improved, but mostly for some error situations, such as setting up mappings on the same node twice, or attaching nodes to each other with conflicting mappings.

[SandPod]

Changes looks good!

Have one question regarding the order of operations. Would be good to get your thoughts on that.

[nielsenko]

Changed semantics slightly in 24462c2. You are now allowed to call use on a hitherto non-existing path. Ie to call use before add.

Also extended test coverage a bit.

[nielsenko]

Found a bug in attach that could cause a previously use call to be ignored (/map to be dropped). This is addressed in 4016835

[nielsenko]

Changed semantics in 7e6e34a to allow use to be called multiple times for the same path. This is also impacts attach.

[SandPod]

LGTM! 👍