Day 23: Deep Link Navigation with Date Parameters
Lesson 23: Deep Link Navigation with Date Parameters
Module 3 — Data Modeling, Persistence & ConnectivityPart 5 of 12
What Changed Since Lesson 13
Lesson 13 established nomadair://search?from=BOM&to=DXB — a deep link that pre-fills the Search form's origin and destination. That was a single-responsibility handler: parse two IATA codes, set two fields, open the Search tab.
Lesson 23 introduces three new requirements that push the design further:
Date parameter:
date=2025-08-15adds a third field. Now the full search criteria — origin, destination, and date — can arrive via deep link.Cache-first routing: When all three parameters are present and a fresh cache entry exists for that search, the deep link should skip the form entirely and navigate directly to the results screen. The user never sees the search form.
Error handling: Unknown IATA codes, malformed dates, or self-loops (BOM→BOM) should produce a visible error rather than silently misrouting.
These three requirements reveal that the existing approach — a few lines of query parameter reading in AppRouter — needs to become a proper service with its own model, logic, and test coverage.
DeepLinkIntent: A Sealed Union
The parser's output is a sealed union with three variants:
A sealed union makes the handling exhaustive. Every switch on DeepLinkIntent must handle all three variants — the compiler enforces it. There's no else branch that could silently swallow an InvalidIntent.
DeepLinkResolver: Pure Dart
DeepLinkResolver is a value object with a single resolve(Uri) method. It has no Flutter dependencies, no BuildContext, no Provider. This is the key design decision:
Because there's no Flutter in this class, 18 tests can run in milliseconds with zero setup:
No widget pump, no BuildContext, no Provider setup. The parser is just a function.
Date Parsing
DateTime.parse() would accept 2025-08-15T00:00:00 — too permissive for a URL parameter that should be exactly YYYY-MM-DD. The manual split validates the format explicitly. Out-of-range values (month 13, day 32) and non-numeric strings both return null, which becomes an InvalidIntent in the caller.
DeepLinkHandler: The Router
DeepLinkHandler is where BuildContext appears — it needs to read providers and call context.go(). It receives a resolved DeepLinkIntent and dispatches to the correct screen:
The switch is exhaustive because DeepLinkIntent is sealed — no default case needed.
Cache-First Search Routing
For a SearchIntent, the handler checks whether the cache already has a fresh entry before navigating:
The notifier is pre-loaded before navigating to results so SearchResultsScreen can trigger notifier.search(criteria) in its initState as usual — the cache will serve it instantly on the first call.
Pre-Fill via GoRouter Extra
PreFillIntent navigates to the Search tab passing an extra map:
AppRouter reads both uri.queryParameters (for incoming deep links) and state.extra (for handler-initiated navigation) when building SearchScreen:
Keep going with the full lesson
The rest of this lesson — plus its implementation guide, runnable scripts and source code — is included with the course or an All Access plan. Create a free account to start the free lessons in every course.
Already a member? Sign in