@xmachines/play-router 1.0.0-beta.1

package/test/tree-query.test.js

@@ -0,0 +1,692 @@
+import { describe, test } from "vitest";
+import { expect } from "vitest";
+import {
+	buildRouteTree,
+	getNavigableRoutes,
+	routeExists,
+	findRouteById,
+	findRouteByPath,
+} from "../src/index.js";
+
+describe("buildRouteTree()", () => {
+	test("creates root with children for flat routes", () => {
+		const routes = [
+			{
+				stateId: "home",
+				statePath: ["home"],
+				routePath: "/home",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "about",
+				statePath: ["about"],
+				routePath: "/about",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+
+		// Root node exists with correct properties
+		expect(tree.root.id).toBe("__root__");
+		expect(tree.root.path).toBe("/");
+		expect(tree.root.fullPath).toBe("/");
+
+		// Two children attached to root
+		expect(tree.root.children.length).toBe(2);
+
+		// Children are linked to root as parent
+		expect(tree.root.children[0].parent).toBe(tree.root);
+		expect(tree.root.children[1].parent).toBe(tree.root);
+	});
+
+	test("builds nested hierarchy with parent-child relationships", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "overview",
+				statePath: ["dashboard", "overview"],
+				routePath: "/overview",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const dashboard = tree.byStateId.get("dashboard");
+		const overview = tree.byStateId.get("overview");
+
+		// Parent-child relationship correct
+		expect(overview.parent).toBe(dashboard);
+		expect(dashboard.children.includes(overview)).toBe(true);
+
+		// Relative path inherits from parent
+		expect(overview.fullPath).toBe("/dashboard/overview");
+	});
+
+	test("handles absolute child paths correctly", () => {
+		const routes = [
+			{
+				stateId: "parent",
+				statePath: ["parent"],
+				routePath: "/parent",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "child",
+				statePath: ["parent", "child"],
+				routePath: "/other",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const child = tree.byStateId.get("child");
+
+		// Absolute child path does not inherit from parent
+		expect(child.fullPath).toBe("/other");
+	});
+
+	test("populates byStateId map correctly", () => {
+		const routes = [
+			{
+				stateId: "home",
+				statePath: ["home"],
+				routePath: "/home",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+
+		// Root in map
+		expect(tree.byStateId.has("__root__")).toBe(true);
+		expect(tree.byStateId.get("__root__")).toBe(tree.root);
+
+		// Route in map
+		expect(tree.byStateId.has("home")).toBe(true);
+		expect(tree.byStateId.get("home")).toBe(tree.root.children[0]);
+	});
+
+	test("populates byPath map correctly", () => {
+		const routes = [
+			{
+				stateId: "home",
+				statePath: ["home"],
+				routePath: "/home",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+
+		// Root in map
+		expect(tree.byPath.has("/")).toBe(true);
+		expect(tree.byPath.get("/")).toBe(tree.root);
+
+		// Route in map
+		expect(tree.byPath.has("/home")).toBe(true);
+		expect(tree.byPath.get("/home")).toBe(tree.root.children[0]);
+	});
+
+	test("handles complex 3-level nesting", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "dashboard.settings",
+				statePath: ["dashboard", "settings"],
+				routePath: "/settings",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "dashboard.settings.profile",
+				statePath: ["dashboard", "settings", "profile"],
+				routePath: "/profile",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const dashboard = tree.byStateId.get("dashboard");
+		const settings = tree.byStateId.get("dashboard.settings");
+		const profile = tree.byStateId.get("dashboard.settings.profile");
+
+		// Grandparent-parent-child links
+		expect(settings.parent).toBe(dashboard);
+		expect(profile.parent).toBe(settings);
+
+		// Full path inheritance through 3 levels
+		expect(profile.fullPath).toBe("/dashboard/settings/profile");
+
+		// All children in parent arrays
+		expect(dashboard.children.includes(settings)).toBe(true);
+		expect(settings.children.includes(profile)).toBe(true);
+	});
+
+	test("handles multiple children per parent", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "overview",
+				statePath: ["dashboard", "overview"],
+				routePath: "/overview",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "settings",
+				statePath: ["dashboard", "settings"],
+				routePath: "/settings",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const dashboard = tree.byStateId.get("dashboard");
+
+		// Dashboard has both children
+		expect(dashboard.children.length).toBe(2);
+
+		// Both children reference dashboard as parent
+		expect(dashboard.children[0].parent).toBe(dashboard);
+		expect(dashboard.children[1].parent).toBe(dashboard);
+	});
+
+	test("handles mixed absolute and relative paths", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "relative",
+				statePath: ["dashboard", "relative"],
+				routePath: "/relative",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "absolute",
+				statePath: ["dashboard", "absolute"],
+				routePath: "/absolute",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const relative = tree.byStateId.get("relative");
+		const absolute = tree.byStateId.get("absolute");
+
+		// Relative inherits parent path
+		expect(relative.fullPath).toBe("/dashboard/relative");
+
+		// Absolute does not inherit
+		expect(absolute.fullPath).toBe("/absolute");
+	});
+});
+
+describe("getNavigableRoutes()", () => {
+	test("returns child routes for state with children", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "overview",
+				statePath: ["dashboard", "overview"],
+				routePath: "/overview",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "settings",
+				statePath: ["dashboard", "settings"],
+				routePath: "/settings",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const navigable = getNavigableRoutes(tree, "dashboard");
+
+		// Returns child routes
+		expect(navigable.length).toBe(2);
+
+		// Returned nodes match children
+		const overview = tree.byStateId.get("overview");
+		const settings = tree.byStateId.get("settings");
+		expect(navigable.includes(overview)).toBe(true);
+		expect(navigable.includes(settings)).toBe(true);
+	});
+
+	test("returns empty array for state with no children", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "overview",
+				statePath: ["dashboard", "overview"],
+				routePath: "/overview",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const navigable = getNavigableRoutes(tree, "overview");
+
+		// No children, returns empty
+		expect(navigable.length).toBe(0);
+	});
+
+	test("returns empty array for non-existent state", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const navigable = getNavigableRoutes(tree, "nonexistent");
+
+		// State doesn't exist, returns empty
+		expect(navigable.length).toBe(0);
+	});
+});
+
+describe("routeExists()", () => {
+	test("returns true for existing path", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "overview",
+				statePath: ["dashboard", "overview"],
+				routePath: "/overview",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+
+		// Existing paths return true
+		expect(routeExists(tree, "/dashboard")).toBe(true);
+		expect(routeExists(tree, "/dashboard/overview")).toBe(true);
+		expect(routeExists(tree, "/")).toBe(true); // Root exists
+	});
+
+	test("returns false for non-existent path", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+
+		// Non-existent paths return false
+		expect(routeExists(tree, "/nonexistent")).toBe(false);
+		expect(routeExists(tree, "/dashboard/fake")).toBe(false);
+	});
+
+	test("returns false for partial paths not in tree", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+
+		// Partial paths that aren't actual routes return false
+		expect(routeExists(tree, "/dash")).toBe(false);
+		expect(routeExists(tree, "/dashboard/")).toBe(false);
+	});
+});
+
+describe("findRouteById()", () => {
+	test("finds route by state ID", () => {
+		const routes = [
+			{
+				stateId: "home",
+				statePath: ["home"],
+				routePath: "/home",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const node = findRouteById(tree, "dashboard");
+
+		expect(node).not.toBe(undefined);
+		expect(node.id).toBe("dashboard");
+		expect(node.fullPath).toBe("/dashboard");
+		expect(node.routable).toBe(true);
+	});
+
+	test("returns undefined for non-existent ID", () => {
+		const routes = [
+			{
+				stateId: "home",
+				statePath: ["home"],
+				routePath: "/home",
+				isAbsolute: true,
+				routable: false,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const node = findRouteById(tree, "nonexistent");
+
+		expect(node).toBe(undefined);
+	});
+
+	test("finds nested route by state ID", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "settings",
+				statePath: ["dashboard", "settings"],
+				routePath: "/settings",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const node = findRouteById(tree, "settings");
+
+		expect(node).not.toBe(undefined);
+		expect(node.id).toBe("settings");
+		expect(node.fullPath).toBe("/dashboard/settings");
+	});
+
+	test("distinguishes between routable and non-routable states", () => {
+		const routes = [
+			{
+				stateId: "home",
+				statePath: ["home"],
+				routePath: "/home",
+				isAbsolute: true,
+				routable: true, // Has route: {} config
+				metadata: {},
+			},
+			{
+				stateId: "about",
+				statePath: ["about"],
+				routePath: "/about",
+				isAbsolute: true,
+				routable: false, // Only meta.route (legacy)
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const homeNode = findRouteById(tree, "home");
+		const aboutNode = findRouteById(tree, "about");
+
+		expect(homeNode.routable).toBe(true);
+		expect(aboutNode.routable).toBe(false);
+	});
+});
+
+describe("findRouteByPath()", () => {
+	test("finds route by URL path", () => {
+		const routes = [
+			{
+				stateId: "contact",
+				statePath: ["contact"],
+				routePath: "/contact",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const node = findRouteByPath(tree, "/contact");
+
+		expect(node).not.toBe(undefined);
+		expect(node.id).toBe("contact");
+		expect(node.stateId).toBe("contact");
+		expect(node.routable).toBe(true);
+	});
+
+	test("returns undefined for non-existent path", () => {
+		const routes = [
+			{
+				stateId: "home",
+				statePath: ["home"],
+				routePath: "/home",
+				isAbsolute: true,
+				routable: false,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const node = findRouteByPath(tree, "/nonexistent");
+
+		expect(node).toBe(undefined);
+	});
+
+	test("finds nested route by full path", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+			{
+				stateId: "profile",
+				statePath: ["dashboard", "profile"],
+				routePath: "/profile",
+				isAbsolute: false,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const node = findRouteByPath(tree, "/dashboard/profile");
+
+		expect(node).not.toBe(undefined);
+		expect(node.id).toBe("profile");
+		expect(node.fullPath).toBe("/dashboard/profile");
+	});
+
+	test("can be used to send play.route events", () => {
+		// Simulates browser navigation → play.route event flow
+		const routes = [
+			{
+				stateId: "settings",
+				statePath: ["settings"],
+				routePath: "/settings",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+		const pathname = "/settings";
+		const node = findRouteByPath(tree, pathname);
+
+		// Check if routable before sending play.route
+		if (node?.routable) {
+			const event = { type: "play.route", to: `#${node.id}` };
+			expect(event.to).toBe("#settings");
+		}
+	});
+});
+
+describe("bidirectional mapping", () => {
+	test("byId and byPath provide bidirectional lookup", () => {
+		const routes = [
+			{
+				stateId: "dashboard",
+				statePath: ["dashboard"],
+				routePath: "/dashboard",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+
+		// State ID → path
+		const nodeById = tree.byStateId.get("dashboard");
+		expect(nodeById.fullPath).toBe("/dashboard");
+
+		// Path → state ID
+		const nodeByPath = tree.byPath.get("/dashboard");
+		expect(nodeByPath.id).toBe("dashboard");
+
+		// Both references point to same node
+		expect(nodeById).toBe(nodeByPath);
+	});
+
+	test("supports URL sync workflow", () => {
+		// Simulates complete URL sync flow: actor → URL → actor
+		const routes = [
+			{
+				stateId: "profile",
+				statePath: ["profile"],
+				routePath: "/profile/:userId",
+				isAbsolute: true,
+				routable: true,
+				metadata: {},
+			},
+		];
+
+		const tree = buildRouteTree(routes);
+
+		// Actor transitioned to 'profile' state
+		const stateId = "profile";
+		const node = findRouteById(tree, stateId);
+
+		// Update browser URL with path
+		const urlPath = node.fullPath;
+		expect(urlPath).toBe("/profile/:userId");
+
+		// Browser navigated to /profile/123
+		// (Would need param matching in real implementation)
+		const browserPath = "/profile/:userId";
+		const targetNode = findRouteByPath(tree, browserPath);
+
+		// Send play.route event
+		if (targetNode?.routable) {
+			const event = { type: "play.route", to: `#${targetNode.id}` };
+			expect(event.to).toBe("#profile");
+		}
+	});
+});