Route/Transition

/**
 * Builds the Transition for a cold load (a direct visit, a
 *  bookmark, a reload). There is no previous route, so isEntering
 *  counts the transition as an entry.
 */
<Route>(nextRoute: Route): Transition<Route>

/**
 * The route a transition entered, narrowed to the given tag: `Some` of
 *  the entered route when this transition entered it, and `None`
 *  otherwise. The entry Command for a detail route usually needs the
 *  route's payload, and this returns it typed. enteredAny is the
 *  form that answers for every route at once.
 */
<Route extends Readonly<{
  _tag: string
}>, Tag extends string>(
  transition: Transition<Route>,
  routeTag: Tag
): Option<Extract<Route, {
  _tag: Tag
}>>

/**
 * The route a transition entered, whichever route that was:
 *  `Some(nextRoute)` when the next route's tag differs from the previous
 *  route's (a cold load counts as an entry), `None` when the transition
 *  stayed within one route, for example between two ids of one detail
 *  route. Match on the result to dispatch entry Commands for many routes
 *  in one place. For a single named route, entered narrows to its
 *  tag and isEntering is the plain predicate form.
 */
<Route extends Readonly<{
  _tag: string
}>>(__namedParameters: Transition<Route>): Option<Route>

/**
 * The route a transition left, narrowed to the given tag: `Some` of the
 *  exited route when this transition left it, and `None` otherwise.
 *  exitedAny is the form that answers for every route at once.
 */
<Route extends Readonly<{
  _tag: string
}>, Tag extends string>(
  transition: Transition<Route>,
  routeTag: Tag
): Option<Extract<Route, {
  _tag: Tag
}>>

/**
 * The route a transition left, whichever route that was:
 *  `Some(previousRoute)` when the previous route's tag differs from the
 *  next route's, `None` on a cold load or when the transition stayed
 *  within one route. For one-shot Commands on the way out, saving a
 *  draft, recording that a visit ended. Things that live while a route is
 *  active, listeners, timers, handles, belong to a Subscription or
 *  ManagedResource condition on the Model instead, which also ends them
 *  when the route state disappears for reasons other than navigation.
 *  exited narrows to a single tag.
 */
<Route extends Readonly<{
  _tag: string
}>>(__namedParameters: Transition<Route>): Option<Route>

/**
 * Predicate for "this transition entered the given route": the next
 *  route carries the tag and the previous route did not (a cold load
 *  counts as an entry). Navigating within the same route, for example
 *  between two ids of one detail route, is not an entry. The boolean
 *  view of entered: when the entry Command needs the route's
 *  payload, use that instead. The route union is inferred from the
 *  transition argument, so the tag is checked against the union's
 *  tags.
 */
<Route extends Readonly<{
  _tag: string
}>, Tag extends string>(
  transition: Transition<Route>,
  routeTag: Tag
): boolean

/**
 * Whether the transition left the selected route. A cold load never exits.
 *  Use exited when its payload is needed.
 */
<Route extends Readonly<{
  _tag: string
}>, Tag extends string>(
  transition: Transition<Route>,
  routeTag: Tag
): boolean

/**
 * Whether both routes have the selected tag. A cold load never stays. Use
 *  stayed for both payloads.
 */
<Route extends Readonly<{
  _tag: string
}>, Tag extends string>(
  transition: Transition<Route>,
  routeTag: Tag
): boolean

/**
 * Builds the Transition for an in-app navigation, from the route
 *  the Model still holds to the route the new URL parsed to. Arguments
 *  read in travel order: previous first, next second.
 */
<Route>(
  previousRoute: Route,
  nextRoute: Route
): Transition<Route>

/**
 * Runs exactly one handler for the selected route tag. A cold load is
 *  `Entered` or `Unrelated`. When both routes have the selected tag, the case
 *  is `Stayed`, even when their payloads differ. Handler routes are narrowed
 *  to the tag. The direct form infers a union of handler returns.
 *  `match<Output>()(...)` constrains every handler to `Output` while inferring
 *  the Route and tag.
 */
<Output>(): (transition: Transition<Route>, routeTag: Tag, handlers: MatchHandlers<Extract<Route, {
  _tag: Tag
}>, Output, Output, Output, Output>) => Output

<Route extends Readonly<{
  _tag: string
}>, Tag extends string, Entered, Exited, Stayed, Unrelated>(
  transition: Transition<Route>,
  routeTag: Tag,
  handlers: MatchHandlers<Extract<Route, {
    _tag: Tag
  }>, Entered, Exited, Stayed, Unrelated>
): Entered | Exited | Stayed | Unrelated

/**
 * Runs the matching handler, or the fallback when that handler is omitted.
 *  A handler that returns `undefined` has handled the case. The direct form
 *  infers a union of callback returns. `matchOrElse<Output>()(...)` constrains
 *  every callback to `Output` while inferring the Route and tag.
 */
<Output>(): (transition: Transition<Route>, routeTag: Tag, handlers: Partial<MatchHandlers<Extract<Route, {
  _tag: Tag
}>, Output, Output, Output, Output>>, fallback: () => Output) => Output

<Route extends Readonly<{
  _tag: string
}>, Tag extends string, Entered = never, Exited = never, Stayed = never, Unrelated = never, Fallback = never>(
  transition: Transition<Route>,
  routeTag: Tag,
  handlers: Partial<MatchHandlers<Extract<Route, {
    _tag: Tag
  }>, Entered, Exited, Stayed, Unrelated>>,
  fallback: () => Fallback
): Entered | Exited | Stayed | Unrelated | Fallback

/**
 * Both sides of a within-route navigation: `Some` of the previous and
 *  next routes, narrowed to the given tag, when the transition stayed on
 *  that route, and `None` when it entered it, left it, or never touched
 *  it. A cold load stays nowhere. For reacting to payload changes within
 *  one route, a detail id, a search text, when the previous value
 *  matters; when it does not, the ChangedUrl handler already has the next
 *  route. There is no tagless counterpart to this the way
 *  enteredAny answers for entered: without a tag the two
 *  sides of a stay could not narrow to the same route variant together,
 *  so matching on one would leave the other typed as the whole union.
 */
<Route extends Readonly<{
  _tag: string
}>, Tag extends string>(
  transition: Transition<Route>,
  routeTag: Tag
): Option<Readonly<{
  nextRoute: Extract<Route, {
    _tag: Tag
  }>
  previousRoute: Extract<Route, {
    _tag: Tag
  }>
}>>