@xmachines/play-router 1.0.0-beta.1

package/test/router-bridge-base-edge.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it, vi } from "vitest";
+import { Signal } from "@xmachines/play-signals";
+import { RouterBridgeBase } from "../src/router-bridge-base.js";
+
+class TestBridge extends RouterBridgeBase {
+	protected navigateRouter(_path: string): void {}
+	protected watchRouterChanges(): void {}
+	protected unwatchRouterChanges(): void {}
+}
+
+class InitialPathBridge extends RouterBridgeBase {
+	protected navigateRouter(_path: string): void {}
+	protected watchRouterChanges(): void {}
+	protected unwatchRouterChanges(): void {}
+	protected getInitialRouterPath(): string | null {
+		return "/dashboard/main";
+	}
+}
+
+function makeBridge(overrides?: {
+	getStateIdByPath?: (path: string) => string | undefined;
+	getPathByStateId?: (id: string) => string | undefined;
+	actorSend?: (event: unknown) => void;
+}) {
+	const actor = {
+		currentRoute: new Signal.State<string | null>("/"),
+		send: overrides?.actorSend ?? vi.fn(),
+	};
+	const routeMap = {
+		getStateIdByPath:
+			overrides?.getStateIdByPath ??
+			((path: string) => (path === "/dashboard" ? "dashboard" : undefined)),
+		getPathByStateId:
+			overrides?.getPathByStateId ??
+			((id: string) => (id === "dashboard" ? "/dashboard/:tab" : undefined)),
+	};
+	return {
+		bridge: new TestBridge(actor as any, routeMap),
+		actor,
+	};
+}
+
+describe("RouterBridgeBase edge branches", () => {
+	it("initializes lastSyncedPath to empty string when actor route is null", () => {
+		const actor = {
+			currentRoute: new Signal.State<string | null>(null),
+			send: vi.fn(),
+		};
+		const routeMap = {
+			getStateIdByPath: vi.fn(),
+			getPathByStateId: vi.fn(),
+		};
+
+		const bridge = new TestBridge(actor as any, routeMap);
+		expect((bridge as any).lastSyncedPath).toBe("");
+	});
+
+	it("connect prefers initial router path over actor route", () => {
+		const actor = {
+			currentRoute: new Signal.State<string | null>("/"),
+			send: vi.fn(),
+		};
+		const routeMap = {
+			getStateIdByPath: (path: string) =>
+				path === "/dashboard/main" ? "dashboard" : undefined,
+			getPathByStateId: () => "/dashboard/:tab",
+		};
+
+		const bridge = new InitialPathBridge(actor as any, routeMap);
+		bridge.connect();
+
+		expect(actor.send).toHaveBeenCalledWith(
+			expect.objectContaining({
+				type: "play.route",
+				to: "#dashboard",
+			}),
+		);
+
+		bridge.disconnect();
+	});
+
+	it("prefixes event target when routeMap stateId has no #", () => {
+		const { bridge, actor } = makeBridge({
+			getStateIdByPath: (path: string) =>
+				path === "/dashboard/main" ? "dashboard" : undefined,
+			getPathByStateId: () => "/dashboard/:tab",
+		});
+
+		(bridge as any).syncActorFromRouter("/dashboard/main", "?tab=profile");
+
+		expect(actor.send).toHaveBeenCalledWith(
+			expect.objectContaining({
+				type: "play.route",
+				to: "#dashboard",
+				query: { tab: "profile" },
+			}),
+		);
+	});
+
+	it("extractParams returns empty object when no pattern or invalid pattern", () => {
+		const noPattern = makeBridge({ getPathByStateId: () => undefined }).bridge;
+		expect((noPattern as any).extractParams("/x", "x")).toEqual({});
+
+		const invalidPattern = makeBridge({ getPathByStateId: () => "(" }).bridge;
+		expect((invalidPattern as any).extractParams("/x", "x")).toEqual({});
+	});
+
+	it("extractQuery returns {} when URLSearchParams throws", () => {
+		const { bridge } = makeBridge();
+		expect((bridge as any).extractQuery(Symbol("bad") as any)).toEqual({});
+	});
+
+	it("syncRouterFromActor returns early for invalid or blocked routes", () => {
+		const { bridge } = makeBridge();
+
+		(bridge as any).syncRouterFromActor(null);
+		expect((bridge as any).isProcessingNavigation).toBe(false);
+
+		(bridge as any).lastSyncedPath = "/same";
+		(bridge as any).syncRouterFromActor("/same");
+		expect((bridge as any).isProcessingNavigation).toBe(false);
+
+		(bridge as any).isProcessingNavigation = true;
+		(bridge as any).syncRouterFromActor("/dashboard");
+		expect((bridge as any).isProcessingNavigation).toBe(true);
+	});
+
+	it("syncActorFromRouter returns early for invalid pathname or processing flag", () => {
+		const { bridge, actor } = makeBridge();
+
+		(bridge as any).syncActorFromRouter(123 as any, "");
+		expect(actor.send).not.toHaveBeenCalled();
+
+		(bridge as any).isProcessingNavigation = true;
+		(bridge as any).syncActorFromRouter("/dashboard/main", "");
+		expect(actor.send).not.toHaveBeenCalled();
+	});
+
+	it("extractParams returns {} when URLPattern has no match", () => {
+		const { bridge } = makeBridge({ getPathByStateId: () => "/dashboard/:tab" });
+		expect((bridge as any).extractParams("/other/path", "dashboard")).toEqual({});
+	});
+
+	it("syncActorFromRouter catches actor.send errors and clears processing flag", () => {
+		const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+		const throwingSend = vi.fn(() => {
+			throw new Error("send failed");
+		});
+		const { bridge } = makeBridge({
+			getStateIdByPath: () => "dashboard",
+			getPathByStateId: () => "/dashboard/:tab",
+			actorSend: throwingSend,
+		});
+
+		(bridge as any).syncActorFromRouter("/dashboard", "");
+
+		expect(errorSpy).toHaveBeenCalledWith(
+			"[RouterBridgeBase] Error sending event:",
+			expect.any(Error),
+		);
+		expect((bridge as any).isProcessingNavigation).toBe(false);
+
+		errorSpy.mockRestore();
+	});
+});

package/test/router-bridge-base.test.ts

@@ -0,0 +1,119 @@
+/**
+ * RouterBridgeBase Unit Tests — Wave 0 Stub (RED phase)
+ *
+ * These tests MUST FAIL until Task 2 creates RouterBridgeBase.
+ * They define the full contract for the base class.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Signal } from "@xmachines/play-signals";
+import { RouterBridgeBase } from "../src/router-bridge-base.js";
+
+// Minimal concrete implementation for testing (only abstract methods)
+class TestBridge extends RouterBridgeBase {
+	public navigateCalls: string[] = [];
+	public watchCalled = false;
+	public unwatchCalled = false;
+
+	protected navigateRouter(path: string): void {
+		this.navigateCalls.push(path);
+	}
+	protected watchRouterChanges(): void {
+		this.watchCalled = true;
+	}
+	protected unwatchRouterChanges(): void {
+		this.unwatchCalled = true;
+	}
+}
+
+describe("RouterBridgeBase", () => {
+	let mockActor: any;
+	let mockRouteMap: any;
+	let bridge: TestBridge;
+
+	beforeEach(() => {
+		const currentRoute = new Signal.State<string | null>("/");
+		mockActor = { currentRoute, send: vi.fn() };
+		mockRouteMap = {
+			getStateIdByPath: vi.fn((path: string) =>
+				path === "/" ? "#home" : path === "/dashboard" ? "#dashboard" : undefined,
+			),
+			getPathByStateId: vi.fn((id: string) =>
+				id === "#home" ? "/" : id === "#dashboard" ? "/dashboard" : undefined,
+			),
+		};
+		bridge = new TestBridge(mockActor, mockRouteMap);
+	});
+
+	describe("RouterBridge protocol compliance", () => {
+		it("should implement connect() method", () => {
+			expect(typeof bridge.connect).toBe("function");
+		});
+		it("should implement disconnect() method", () => {
+			expect(typeof bridge.disconnect).toBe("function");
+		});
+		it("should not throw when calling connect()", () => {
+			expect(() => bridge.connect()).not.toThrow();
+		});
+		it("should not throw when calling disconnect()", () => {
+			bridge.connect();
+			expect(() => bridge.disconnect()).not.toThrow();
+		});
+	});
+
+	describe("connect() sets up framework-specific watcher", () => {
+		it("should call watchRouterChanges() on connect", () => {
+			bridge.connect();
+			expect(bridge.watchCalled).toBe(true);
+		});
+		it("should call unwatchRouterChanges() on disconnect", () => {
+			bridge.connect();
+			bridge.disconnect();
+			expect(bridge.unwatchCalled).toBe(true);
+		});
+	});
+
+	describe("actor → router sync", () => {
+		it("should call navigateRouter when actor route changes", async () => {
+			bridge.connect();
+			bridge.navigateCalls = []; // Clear initial sync
+			mockActor.currentRoute.set("/dashboard");
+			await new Promise<void>((r) => queueMicrotask(r));
+			expect(bridge.navigateCalls).toContain("/dashboard");
+		});
+		it("should not navigate when route is unchanged (circular prevention)", async () => {
+			bridge.connect();
+			bridge.navigateCalls = [];
+			mockActor.currentRoute.set("/"); // Same as initial
+			await new Promise<void>((r) => queueMicrotask(r));
+			expect(bridge.navigateCalls).toHaveLength(0);
+		});
+	});
+
+	describe("router → actor sync", () => {
+		it("should send play.route event when router navigates to known path", () => {
+			bridge.connect();
+			// Access protected method via type cast for testing
+			(bridge as any).syncActorFromRouter("/dashboard", "");
+			expect(mockActor.send).toHaveBeenCalledWith(
+				expect.objectContaining({ type: "play.route", to: "#dashboard" }),
+			);
+		});
+		it("should not send event for unknown path", () => {
+			bridge.connect();
+			(bridge as any).syncActorFromRouter("/unknown", "");
+			expect(mockActor.send).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("circular update prevention", () => {
+		it("should not double-navigate when both syncs fire", async () => {
+			bridge.connect();
+			bridge.navigateCalls = [];
+			// Simulate actor→router direction; flag prevents router→actor echo
+			(bridge as any).syncRouterFromActor("/dashboard");
+			(bridge as any).syncActorFromRouter("/dashboard", ""); // Should be blocked
+			expect(mockActor.send).not.toHaveBeenCalled();
+			await new Promise<void>((r) => queueMicrotask(r));
+		});
+	});
+});