@xmachines/play-router 1.0.0-beta.1

package/test/crawl-extract.test.js

@@ -0,0 +1,473 @@
+import { describe, test } from "vitest";
+import { expect } from "vitest";
+import { createMachine } from "xstate";
+import { crawlMachine } from "../src/crawl-machine.js";
+import { extractRoute } from "../src/extract-route.js";
+
+describe("crawlMachine()", () => {
+	describe("nested states", () => {
+		test("simple machine with 2 states", () => {
+			const machine = createMachine({
+				initial: "home",
+				states: {
+					home: {},
+					about: {},
+				},
+			});
+
+			const visits = crawlMachine(machine);
+
+			// Should visit root + 2 states = 3 visits
+			expect(visits.length).toBe(3);
+
+			// Root visit
+			expect(visits[0].path).toEqual([]);
+			expect(visits[0].parent).toBe(null);
+
+			// Child visits
+			expect(visits[1].path).toEqual(["home"]);
+			expect(visits[1].parent).toBe(machine.root);
+			expect(visits[2].path).toEqual(["about"]);
+			expect(visits[2].parent).toBe(machine.root);
+		});
+
+		test("nested machine (parent + child)", () => {
+			const machine = createMachine({
+				initial: "home",
+				states: {
+					home: {
+						initial: "dashboard",
+						states: {
+							dashboard: {},
+						},
+					},
+				},
+			});
+
+			const visits = crawlMachine(machine);
+
+			// Should visit root + home + dashboard = 3 visits
+			expect(visits.length).toBe(3);
+
+			// BFS order: root, home, dashboard
+			expect(visits[0].path).toEqual([]);
+			expect(visits[1].path).toEqual(["home"]);
+			expect(visits[2].path).toEqual(["home", "dashboard"]);
+		});
+
+		test("deeply nested (3 levels)", () => {
+			const machine = createMachine({
+				initial: "a",
+				states: {
+					a: {
+						initial: "b",
+						states: {
+							b: {
+								initial: "c",
+								states: {
+									c: {},
+								},
+							},
+						},
+					},
+				},
+			});
+
+			const visits = crawlMachine(machine);
+
+			// Should visit root + a + b + c = 4 visits
+			expect(visits.length).toBe(4);
+
+			expect(visits[0].path).toEqual([]);
+			expect(visits[1].path).toEqual(["a"]);
+			expect(visits[2].path).toEqual(["a", "b"]);
+			expect(visits[3].path).toEqual(["a", "b", "c"]);
+		});
+	});
+
+	describe("parallel states", () => {
+		test("parallel region with 2 children", () => {
+			const machine = createMachine({
+				type: "parallel",
+				states: {
+					sidebar: {},
+					content: {},
+				},
+			});
+
+			const visits = crawlMachine(machine);
+
+			// Should visit root + sidebar + content = 3 visits
+			expect(visits.length).toBe(3);
+
+			expect(visits[0].path).toEqual([]);
+			expect(visits[1].path).toEqual(["sidebar"]);
+			expect(visits[2].path).toEqual(["content"]);
+		});
+
+		test("mixed nested + parallel", () => {
+			const machine = createMachine({
+				initial: "app",
+				states: {
+					app: {
+						type: "parallel",
+						states: {
+							sidebar: {
+								initial: "collapsed",
+								states: {
+									collapsed: {},
+									expanded: {},
+								},
+							},
+							main: {},
+						},
+					},
+				},
+			});
+
+			const visits = crawlMachine(machine);
+
+			// Should visit: root, app, sidebar, main, collapsed, expanded = 6 visits
+			expect(visits.length).toBe(6);
+
+			// BFS order
+			expect(visits[0].path).toEqual([]);
+			expect(visits[1].path).toEqual(["app"]);
+			expect(visits[2].path).toEqual(["app", "sidebar"]);
+			expect(visits[3].path).toEqual(["app", "main"]);
+			expect(visits[4].path).toEqual(["app", "sidebar", "collapsed"]);
+			expect(visits[5].path).toEqual(["app", "sidebar", "expanded"]);
+		});
+	});
+
+	describe("edge cases", () => {
+		test("empty machine (root only)", () => {
+			const machine = createMachine({
+				// No states defined
+			});
+
+			const visits = crawlMachine(machine);
+
+			// Should visit only root = 1 visit
+			expect(visits.length).toBe(1);
+			expect(visits[0].path).toEqual([]);
+		});
+
+		test("machine with empty states object", () => {
+			const machine = createMachine({
+				states: {},
+			});
+
+			const visits = crawlMachine(machine);
+
+			// Should visit only root = 1 visit
+			expect(visits.length).toBe(1);
+			expect(visits[0].path).toEqual([]);
+		});
+	});
+});
+
+describe("extractRoute()", () => {
+	describe("valid metadata", () => {
+		test("string format meta.route", () => {
+			const machine = createMachine({
+				id: "home",
+				meta: {
+					route: "/home",
+				},
+			});
+
+			const stateMap = new Map([["home", machine.root]]);
+			const route = extractRoute(machine.root, ["home"], stateMap);
+
+			expect(route).not.toBe(null);
+			expect(route.routePath).toBe("/home");
+			expect(route.stateId).toBe("home");
+			expect(route.isAbsolute).toBe(true);
+		});
+
+		test("object format meta.route with path property", () => {
+			const machine = createMachine({
+				id: "dashboard",
+				meta: {
+					route: {
+						path: "/dashboard",
+						title: "Dashboard",
+					},
+				},
+			});
+
+			const stateMap = new Map([["dashboard", machine.root]]);
+			const route = extractRoute(machine.root, ["dashboard"], stateMap);
+
+			expect(route).not.toBe(null);
+			expect(route.routePath).toBe("/dashboard");
+			expect(route.stateId).toBe("dashboard");
+			expect(route.metadata).toEqual({
+				path: "/dashboard",
+				title: "Dashboard",
+			});
+		});
+
+		test("absolute path (starts with /)", () => {
+			const machine = createMachine({
+				id: "settings",
+				meta: {
+					route: "/settings",
+				},
+			});
+
+			const stateMap = new Map([["settings", machine.root]]);
+			const route = extractRoute(machine.root, ["settings"], stateMap);
+
+			expect(route.isAbsolute).toBe(true);
+		});
+
+		test("child route with leading /", () => {
+			const machine = createMachine({
+				id: "overview",
+				meta: {
+					route: "/overview",
+				},
+			});
+
+			const stateMap = new Map([["overview", machine.root]]);
+			const route = extractRoute(machine.root, ["overview"], stateMap);
+
+			// Even child routes require leading / per validation
+			expect(route.routePath).toBe("/overview");
+			expect(route.isAbsolute).toBe(true);
+		});
+	});
+
+	describe("state ID logic", () => {
+		test("falls back to path.join('.') when node.id is missing", () => {
+			const route = extractRoute(
+				{
+					meta: {
+						route: "/from-path",
+					},
+				},
+				["parent", "child"],
+				new Map(),
+			);
+
+			expect(route.stateId).toBe("parent.child");
+		});
+
+		test("uses node.id when available", () => {
+			const machine = createMachine({
+				id: "explicit-id",
+				meta: {
+					route: "/test",
+				},
+			});
+
+			const stateMap = new Map([["explicit-id", machine.root]]);
+			const route = extractRoute(machine.root, ["some", "path"], stateMap);
+
+			expect(route.stateId).toBe("explicit-id");
+		});
+
+		test("uses path.join('.') when no explicit id (XState auto-generates id)", () => {
+			const machine = createMachine({
+				meta: {
+					route: "/test",
+				},
+			});
+
+			// XState auto-generates '(machine)' id, so include it in stateMap
+			const stateMap = new Map([["(machine)", machine.root]]);
+			const route = extractRoute(machine.root, ["dashboard", "overview"], stateMap);
+
+			// extractRoute uses node.id when present (even auto-generated ones)
+			expect(route.stateId).toBe("(machine)");
+		});
+
+		test("includes full path in statePath property", () => {
+			const machine = createMachine({
+				id: "nested",
+				meta: {
+					route: "/nested",
+				},
+			});
+
+			const stateMap = new Map([["nested", machine.root]]);
+			const route = extractRoute(machine.root, ["parent", "child", "nested"], stateMap);
+
+			expect(route.statePath).toEqual(["parent", "child", "nested"]);
+		});
+
+		test("captures pattern when route contains parameters", () => {
+			const machine = createMachine({
+				id: "profile",
+				meta: {
+					route: "/profile/:userId",
+				},
+			});
+
+			const stateMap = new Map([["profile", machine.root]]);
+			const route = extractRoute(machine.root, ["profile"], stateMap);
+
+			expect(route.pattern).toBe("/profile/:userId");
+		});
+	});
+
+	describe("non-routable states", () => {
+		test("returns null when no meta", () => {
+			const machine = createMachine({
+				id: "loading",
+			});
+
+			const stateMap = new Map();
+			const route = extractRoute(machine.root, ["loading"], stateMap);
+
+			expect(route).toBe(null);
+		});
+
+		test("returns null when meta has no route property", () => {
+			const machine = createMachine({
+				id: "other",
+				meta: {
+					title: "Other",
+					description: "Some other state",
+				},
+			});
+
+			const stateMap = new Map();
+			const route = extractRoute(machine.root, ["other"], stateMap);
+
+			expect(route).toBe(null);
+		});
+
+		test("returns null when meta.route is undefined", () => {
+			const machine = createMachine({
+				id: "undefined-route",
+				meta: {
+					route: undefined,
+				},
+			});
+
+			const stateMap = new Map();
+			const route = extractRoute(machine.root, ["undefined-route"], stateMap);
+
+			expect(route).toBe(null);
+		});
+	});
+
+	describe("route: {} config (Stately pattern)", () => {
+		test("detects route: {} config with meta.route", () => {
+			// Simulate a state node with route: {} config
+			const machine = createMachine({
+				id: "dashboard",
+				initial: "overview",
+				states: {
+					overview: {
+						id: "overview",
+						meta: {
+							route: "/overview",
+						},
+					},
+				},
+			});
+
+			// Get the overview state node
+			const overviewNode = machine.states.overview;
+			// Manually add route: {} to simulate Stately pattern
+			overviewNode.route = {};
+
+			const stateMap = new Map([["overview", overviewNode]]);
+			const route = extractRoute(overviewNode, ["overview"], stateMap);
+
+			expect(route).not.toBe(null);
+			expect(route.routePath).toBe("/overview");
+			expect(route.stateId).toBe("overview");
+			expect(route.routable).toBe(true); // Has route: {} config
+		});
+
+		test("route: {} config with meta.route falls back correctly", () => {
+			const machine = createMachine({
+				id: "settings",
+				initial: "profile",
+				states: {
+					profile: {
+						id: "profile",
+						meta: {
+							route: "/profile",
+						},
+					},
+				},
+			});
+
+			const profileNode = machine.states.profile;
+			profileNode.route = {};
+
+			const stateMap = new Map([["profile", profileNode]]);
+			const route = extractRoute(profileNode, ["profile"], stateMap);
+
+			expect(route.routePath).toBe("/profile");
+			expect(route.routable).toBe(true);
+		});
+
+		test("returns null when no meta.route or meta.path", () => {
+			const machine = createMachine({
+				initial: "invalid",
+				states: {
+					invalid: {
+						id: "invalid",
+						meta: {}, // No route metadata
+					},
+				},
+			});
+
+			const invalidNode = machine.states.invalid;
+			const stateMap = new Map([["invalid", invalidNode]]);
+
+			// Should return null for states without route metadata
+			const result = extractRoute(invalidNode, ["invalid"], stateMap);
+			expect(result).toBe(null);
+		});
+
+		test("meta.route makes state routable (no route: {} required)", () => {
+			const machine = createMachine({
+				id: "home",
+				meta: {
+					route: "/home",
+				},
+			});
+
+			const stateMap = new Map([["home", machine.root]]);
+			const route = extractRoute(machine.root, ["home"], stateMap);
+
+			expect(route).not.toBe(null);
+			expect(route.routePath).toBe("/home");
+			expect(route.routable).toBe(true); // meta.route makes state routable
+		});
+
+		test("meta.route takes precedence over meta.path when route: {} exists", () => {
+			const machine = createMachine({
+				id: "priority",
+				initial: "test",
+				states: {
+					test: {
+						id: "test",
+						meta: {
+							route: "/new-path",
+							path: "/old-path",
+						},
+					},
+				},
+			});
+
+			const testNode = machine.states.test;
+			testNode.route = {};
+
+			const stateMap = new Map([["test", testNode]]);
+			const route = extractRoute(testNode, ["test"], stateMap);
+
+			// meta.route should win (NEW pattern)
+			expect(route.routePath).toBe("/new-path");
+			expect(route.routable).toBe(true);
+		});
+	});
+});

package/test/create-browser-history.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test, vi } from "vitest";
+import { createBrowserHistory } from "../src/create-browser-history.js";
+
+function createMockWindow() {
+	const listeners = new Map<string, Set<() => void>>();
+	const location = {
+		pathname: "/",
+		search: "",
+		hash: "",
+	};
+
+	const history = {
+		state: null as unknown,
+		pushState: vi.fn((state: unknown, _title: string, url?: string | URL | null) => {
+			history.state = state;
+			if (typeof url === "string") {
+				location.pathname = url;
+			}
+		}),
+		replaceState: vi.fn((state: unknown, _title: string, url?: string | URL | null) => {
+			history.state = state;
+			if (typeof url === "string") {
+				location.pathname = url;
+			}
+		}),
+		go: vi.fn(),
+		back: vi.fn(),
+		forward: vi.fn(),
+	};
+
+	const win = {
+		history,
+		location,
+		addEventListener: vi.fn((event: string, cb: () => void) => {
+			if (!listeners.has(event)) {
+				listeners.set(event, new Set());
+			}
+			listeners.get(event)!.add(cb);
+		}),
+		removeEventListener: vi.fn((event: string, cb: () => void) => {
+			listeners.get(event)?.delete(cb);
+		}),
+	};
+
+	return {
+		win,
+		emit(event: string) {
+			listeners.get(event)?.forEach((listener) => listener());
+		},
+	};
+}
+
+describe("createBrowserHistory", () => {
+	test("notifies subscribers for push/replace/popstate and restores on destroy", () => {
+		const { win, emit } = createMockWindow();
+		const browserHistory = createBrowserHistory({ window: win as any });
+		const listener = vi.fn();
+		const unsubscribe = browserHistory.subscribe(listener);
+
+		browserHistory.push("/dashboard", { from: "push" });
+		expect(listener).toHaveBeenLastCalledWith(
+			expect.objectContaining({ pathname: "/dashboard", state: { from: "push" } }),
+		);
+
+		browserHistory.replace("/settings", { from: "replace" });
+		expect(listener).toHaveBeenLastCalledWith(
+			expect.objectContaining({ pathname: "/settings", state: { from: "replace" } }),
+		);
+
+		emit("popstate");
+		expect(listener).toHaveBeenCalledTimes(3);
+
+		unsubscribe();
+		browserHistory.push("/ignored");
+		expect(listener).toHaveBeenCalledTimes(3);
+
+		browserHistory.destroy();
+		expect(win.removeEventListener).toHaveBeenCalledWith("popstate", expect.any(Function));
+	});
+
+	test("exposes location and navigation helpers", () => {
+		const { win } = createMockWindow();
+		const browserHistory = createBrowserHistory({ window: win as any });
+
+		win.location.pathname = "/profile";
+		win.location.search = "?tab=security";
+		win.location.hash = "#anchor";
+		win.history.state = { from: "state" };
+
+		expect(browserHistory.location).toEqual({
+			pathname: "/profile",
+			search: "?tab=security",
+			hash: "#anchor",
+			state: { from: "state" },
+		});
+
+		expect(browserHistory.createHref("/settings")).toBe("/settings");
+
+		browserHistory.go(-1);
+		browserHistory.back();
+		browserHistory.forward();
+
+		expect(win.history.go).toHaveBeenCalledWith(-1);
+		expect(win.history.back).toHaveBeenCalledTimes(1);
+		expect(win.history.forward).toHaveBeenCalledTimes(1);
+
+		browserHistory.destroy();
+	});
+
+	test("restores original history methods on destroy", () => {
+		const { win } = createMockWindow();
+		const browserHistory = createBrowserHistory({ window: win as any });
+		const listener = vi.fn();
+		browserHistory.subscribe(listener);
+
+		browserHistory.destroy();
+		win.history.pushState({ from: "destroy" }, "", "/after-destroy");
+		win.history.replaceState({ from: "destroy" }, "", "/after-destroy-2");
+
+		expect(listener).not.toHaveBeenCalled();
+		expect(win.location.pathname).toBe("/after-destroy-2");
+	});
+});

package/test/create-router.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test, vi } from "vitest";
+import { createRouter } from "../src/create-router.js";
+
+describe("createRouter", () => {
+	test("returns history/routeTree and delegates destroy", () => {
+		const routeTree = {
+			root: { id: "root" },
+			byPath: new Map(),
+			byStateId: new Map(),
+		} as any;
+		const history = {
+			destroy: vi.fn(),
+		} as any;
+
+		const router = createRouter({ routeTree, history });
+
+		expect(router.routeTree).toBe(routeTree);
+		expect(router.history).toBe(history);
+
+		router.destroy();
+		expect(history.destroy).toHaveBeenCalledTimes(1);
+	});
+});

package/test/extract-routes.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test, vi } from "vitest";
+import type { RouteInfo } from "../src/types.js";
+
+const mocks = vi.hoisted(() => ({
+	crawlMachine: vi.fn(),
+	extractRoute: vi.fn(),
+	detectDuplicateRoutes: vi.fn(),
+	buildRouteTree: vi.fn(),
+}));
+
+vi.mock("../src/crawl-machine.js", () => ({
+	crawlMachine: mocks.crawlMachine,
+}));
+
+vi.mock("../src/extract-route.js", () => ({
+	extractRoute: mocks.extractRoute,
+}));
+
+vi.mock("../src/validate-routes.js", () => ({
+	detectDuplicateRoutes: mocks.detectDuplicateRoutes,
+}));
+
+vi.mock("../src/build-tree.js", () => ({
+	buildRouteTree: mocks.buildRouteTree,
+}));
+
+import { extractMachineRoutes } from "../src/extract-routes.js";
+
+describe("extractMachineRoutes", () => {
+	test("builds state map only for nodes with ids and filters null routes", () => {
+		const visitWithId = {
+			node: { id: "known", meta: { route: "/known" } },
+			path: ["known"],
+			parent: null,
+		};
+		const visitWithoutId = {
+			node: { meta: { route: "/anonymous" } },
+			path: ["anonymous"],
+			parent: null,
+		};
+
+		mocks.crawlMachine.mockReturnValue([visitWithId, visitWithoutId]);
+
+		const routeInfo: RouteInfo = {
+			stateId: "known",
+			statePath: ["known"],
+			routePath: "/known",
+			isAbsolute: true,
+			routable: true,
+			metadata: { path: "/known" },
+		};
+
+		mocks.extractRoute
+			.mockImplementationOnce(
+				(_node: unknown, _path: string[], stateMap: Map<string, unknown>) => {
+					expect(stateMap.has("known")).toBe(true);
+					return routeInfo;
+				},
+			)
+			.mockImplementationOnce(
+				(_node: unknown, _path: string[], stateMap: Map<string, unknown>) => {
+					expect(stateMap.has("known")).toBe(true);
+					return null;
+				},
+			);
+
+		const expectedTree = {
+			root: { id: "root" },
+			byPath: new Map(),
+			byStateId: new Map(),
+		};
+		mocks.buildRouteTree.mockReturnValue(expectedTree);
+
+		const tree = extractMachineRoutes({} as any);
+
+		expect(mocks.detectDuplicateRoutes).toHaveBeenCalledWith([routeInfo]);
+		expect(mocks.buildRouteTree).toHaveBeenCalledWith([routeInfo]);
+		expect(tree).toBe(expectedTree);
+	});
+});