Interface: PlayRouteEvent

API / @xmachines/play-tanstack-react-router / PlayRouteEvent

Defined in: play-router/src/types.ts:225

Enhanced routing event with parameter and query support

Unified routing event used throughout the Play architecture. Supports parameter-aware navigation patterns (e.g., /profile/:userId) for dynamic route segments.

Architectural Context: Implements Passive Infrastructure (INV-04) by representing user navigation intent that the Actor evaluates through guards. Infrastructure proposes via play.route events, Actor decides via state machine transitions.

Browser Navigation Flow:

1. Browser fires popstate
2. Router adapter resolves URL to route target
3. Adapter sends PlayRouteEvent to Actor
4. Actor validates transition via state machine guards

Param

Event discriminator (always “play.route”)

Param

Target state ID with # prefix (e.g., ‘#home’, ‘#profile’)

Param

Path-only route parameters extracted from the URL path (e.g., { userId: '123' } from /profile/123). Query parameters are kept separate in query.

Param

Query parameters only (isolated from path params)

Param

Full URLPattern match result for debugging/observability (optional)

Examples

Combining base and routing events

import type { PlayEvent } from "@xmachines/play";
import type { PlayRouteEvent } from "@xmachines/play-router";

type AppEvent = PlayEvent | PlayRouteEvent;

Basic navigation to a route

import type { PlayRouteEvent } from "@xmachines/play-router";

const event: PlayRouteEvent = {
  type: "play.route",
  to: "#home",
};
actor.send(event);

Navigation with route parameters

import type { PlayRouteEvent } from "@xmachines/play-router";

const event: PlayRouteEvent = {
  type: "play.route",
  to: "#profile",
  params: { userId: "123" },
};
actor.send(event);
// Resolves to route: /profile/123

Navigation with query parameters

import type { PlayRouteEvent } from "@xmachines/play-router";

const event: PlayRouteEvent = {
  type: "play.route",
  to: "#settings",
  params: { section: "profile" }, // Path-only route parameter
  query: { tab: "security" }, // Query-only
};
actor.send(event);
// Resolves to route: /settings/profile?tab=security

See

Play RFC

Remarks

Use play.route when you need parameter-aware navigation with the route: {} config pattern on your state machine nodes. The match field exposes the full URLPatternResult for advanced use cases (debugging, pattern analysis).

Indexable

[key: string]: unknown

Properties

Property	Modifier	Type	Defined in
match?	readonly	unknown	play-router/src/types.ts:230
params?	readonly	Record<string, string>	play-router/src/types.ts:228
query?	readonly	Record<string, string>	play-router/src/types.ts:229
to	readonly	string	play-router/src/types.ts:227
type	readonly	"play.route"	play-router/src/types.ts:226