Interface: PlayRouteEvent

Documentation / @xmachines/play-react-router / PlayRouteEvent

Defined in: play-router/dist/types.d.ts:182

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

Merged path + query parameters (path parameters win conflicts)

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" }, // Merged: path + query
  query: { tab: "security" }, // Query-only
};
actor.send(event);
// Resolves to route: /settings/profile?tab=security

See

RFC Play v1

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/dist/types.d.ts:187
params?	readonly	Record<string, string>	play-router/dist/types.d.ts:185
query?	readonly	Record<string, string>	play-router/dist/types.d.ts:186
to	readonly	string	play-router/dist/types.d.ts:184
type	readonly	"play.route"	play-router/dist/types.d.ts:183