Better return type for Resolver().resolve

Author: Archmonger

CHANGELOG.md

@@ -25,6 +25,7 @@ Don't forget to remove deprecated code on each major release!
 -   Set minimum ReactPy version to `1.1.0`.
 -   `link` element now calculates URL changes using the client.
 -   Refactoring related to `reactpy>=1.1.0` changes.
+-   Determination of the browser's initial URL is now deterministic.
 
 ### Fixed
 

src/reactpy_router/resolvers.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from reactpy_router.converters import CONVERTERS
+from reactpy_router.types import MatchedRoute
 
 if TYPE_CHECKING:
     from reactpy_router.types import ConversionInfo, ConverterMapping, Route
@@ -70,7 +71,7 @@ def parse_path(self, path: str) -> re.Pattern[str]:
 
         return re.compile(pattern)
 
-    def resolve(self, path: str) -> tuple[Any, dict[str, Any]] | None:
+    def resolve(self, path: str) -> MatchedRoute | None:
         match = self.pattern.match(path)
         if match:
             # Convert the matched groups to the correct types
@@ -80,5 +81,5 @@ def resolve(self, path: str) -> tuple[Any, dict[str, Any]] | None:
                 else parameter_name: self.converter_mapping[parameter_name](value)
                 for parameter_name, value in match.groupdict().items()
             }
-            return (self.element, params)
+            return MatchedRoute(self.element, params, path)
         return None

src/reactpy_router/routers.py

@@ -4,7 +4,7 @@
 
 from dataclasses import replace
 from logging import getLogger
-from typing import TYPE_CHECKING, Any, Literal, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from reactpy import component, use_memo, use_state
 from reactpy.backend.types import Connection, Location
@@ -14,6 +14,7 @@
 from reactpy_router.components import History
 from reactpy_router.hooks import RouteState, _route_state_context
 from reactpy_router.resolvers import StarletteResolver
+from reactpy_router.types import MatchedRoute
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence
@@ -57,36 +58,27 @@ def router(
     *routes: Route,
     resolver: Resolver[Route],
 ) -> VdomDict | None:
-    """A component that renders matching route(s) using the given resolver.
+    """A component that renders matching route using the given resolver.
 
-    This typically should never be used by a user. Instead, use `create_router` if creating
+    User notice: This component typically should never be used. Instead, use `create_router` if creating
     a custom routing engine."""
 
-    old_conn = use_connection()
-    location, set_location = use_state(old_conn.location)
-    first_load, set_first_load = use_state(True)
-
+    old_connection = use_connection()
+    location, set_location = use_state(cast(Location | None, None))
     resolvers = use_memo(
         lambda: tuple(map(resolver, _iter_routes(routes))),
         dependencies=(resolver, hash(routes)),
     )
-
-    match = use_memo(lambda: _match_route(resolvers, location, select="first"))
+    route_element = None
+    match = use_memo(lambda: _match_route(resolvers, location or old_connection.location))
 
     if match:
-        if first_load:
-            # We need skip rendering the application on 'first_load' to avoid
-            # rendering it twice. The second render follows the on_history_change event
-            route_elements = []
-            set_first_load(False)
-        else:
-            route_elements = [
-                _route_state_context(
-                    element,
-                    value=RouteState(set_location, params),
-                )
-                for element, params in match
-            ]
+        # Skip rendering until ReactPy-Router knows what URL the page is on.
+        if location:
+            route_element = _route_state_context(
+                match.element,
+                value=RouteState(set_location, match.params),
+            )
 
         def on_history_change(event: dict[str, Any]) -> None:
             """Callback function used within the JavaScript `History` component."""
@@ -96,8 +88,8 @@ def on_history_change(event: dict[str, Any]) -> None:
 
         return ConnectionContext(
             History({"onHistoryChangeCallback": on_history_change}),  # type: ignore[return-value]
-            *route_elements,
-            value=Connection(old_conn.scope, location, old_conn.carrier),
+            route_element,
+            value=Connection(old_connection.scope, location or old_connection.location, old_connection.carrier),
         )
 
     return None
@@ -110,9 +102,9 @@ def _iter_routes(routes: Sequence[Route]) -> Iterator[Route]:
         yield parent
 
 
-def _add_route_key(match: tuple[Any, dict[str, Any]], key: str | int) -> Any:
+def _add_route_key(match: MatchedRoute, key: str | int) -> Any:
     """Add a key to the VDOM or component on the current route, if it doesn't already have one."""
-    element, _params = match
+    element = match.element
     if hasattr(element, "render") and not element.key:
         element = cast(ComponentType, element)
         element.key = key
@@ -125,24 +117,12 @@ def _add_route_key(match: tuple[Any, dict[str, Any]], key: str | int) -> Any:
 def _match_route(
     compiled_routes: Sequence[CompiledRoute],
     location: Location,
-    select: Literal["first", "all"],
-) -> list[tuple[Any, dict[str, Any]]]:
-    matches = []
-
+) -> MatchedRoute | None:
     for resolver in compiled_routes:
         match = resolver.resolve(location.pathname)
         if match is not None:
-            if select == "first":
-                return [_add_route_key(match, resolver.key)]
+            return _add_route_key(match, resolver.key)
 
-            # Matching multiple routes is disabled since `react-router` no longer supports multiple
-            # matches via the `Route` component. However, it's kept here to support future changes
-            # or third-party routers.
-            # TODO: The `resolver.key` value has edge cases where it is not unique enough to use as
-            # a key here. We can potentially fix this by throwing errors for duplicate identical routes.
-            matches.append(_add_route_key(match, resolver.key))  # pragma: no cover
+    _logger.debug("No matching route found for %s", location.pathname)
 
-    if not matches:
-        _logger.debug("No matching route found for %s", location.pathname)
-
-    return matches
+    return None

src/reactpy_router/types.py

@@ -67,11 +67,11 @@ def __call__(self, *routes: RouteType_contra) -> Component:
 
 
 class Resolver(Protocol[RouteType_contra]):
-    """Compile a route into a resolver that can be matched against a given path."""
+    """A class, that when instantiated, can match routes against a given path."""
 
     def __call__(self, route: RouteType_contra) -> CompiledRoute:
         """
-        Compile a route into a resolver that can be matched against a given path.
+        Compile a route into a resolver that can be match routes against a given path.
 
         Args:
             route: The route to compile.
@@ -87,13 +87,13 @@ class CompiledRoute(Protocol):
     A protocol for a compiled route that can be matched against a path.
 
     Attributes:
-        key (Key): A property that uniquely identifies this resolver.
+        key: A property that uniquely identifies this resolver.
     """
 
     @property
     def key(self) -> Key: ...
 
-    def resolve(self, path: str) -> tuple[Any, dict[str, Any]] | None:
+    def resolve(self, path: str) -> MatchedRoute | None:
         """
         Return the path's associated element and path parameters or None.
 
@@ -106,6 +106,22 @@ def resolve(self, path: str) -> tuple[Any, dict[str, Any]] | None:
         ...
 
 
+@dataclass(frozen=True)
+class MatchedRoute:
+    """
+    Represents a matched route.
+
+    Attributes:
+        element (Any): The element to render.
+        params (dict[str, Any]): The parameters extracted from the path.
+        path (str): The path that was matched.
+    """
+
+    element: Any
+    params: dict[str, Any]
+    path: str
+
+
 class ConversionInfo(TypedDict):
     """
     A TypedDict that holds information about a conversion type.

tests/test_resolver.py

@@ -5,13 +5,16 @@
 
 from reactpy_router import route
 from reactpy_router.resolvers import StarletteResolver
+from reactpy_router.types import MatchedRoute
 
 
 def test_resolve_any():
     resolver = StarletteResolver(route("{404:any}", "Hello World"))
     assert resolver.parse_path("{404:any}") == re.compile("^(?P<_numeric_404>.*)$")
     assert resolver.converter_mapping == {"_numeric_404": str}
-    assert resolver.resolve("/hello/world") == ("Hello World", {"404": "/hello/world"})
+    assert resolver.resolve("/hello/world") == MatchedRoute(
+        element="Hello World", params={"404": "/hello/world"}, path="/hello/world"
+    )
 
 
 def test_parse_path():