@btst/stack 3.0.0-rc.2 → 3.0.0-rc.4

package/src/__tests__/plugin-registration.test.tsx

@@ -0,0 +1,183 @@
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import { defineDb } from "@btst/db";
+import { QueryClient } from "@tanstack/react-query";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import { createBackendStack } from "../api";
+import { createClientStack } from "../client";
+import { StackProvider, usePluginOverrides, useStack } from "../context";
+import { createDbPlugin, defineBackendPlugin } from "../plugins/api";
+import { createRoute, defineClientPlugin } from "../plugins/client";
+import { generateRouteDocsSchema } from "../plugins/route-docs/generator";
+
+function runtimeConfig<TPlugins extends Record<string, any>>(
+	plugins: TPlugins,
+) {
+	return {
+		api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+		site: { baseURL: "https://app.example.com", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		plugins,
+	};
+}
+
+function identifiedClient(id: string) {
+	return defineClientPlugin({
+		id,
+		resolve: (runtime) => ({
+			routes: () => ({
+				probe: createRoute(`/${id}`, () => ({ PageComponent: () => null })),
+			}),
+			sitemap: () => [
+				{ url: `${runtime.site.baseURL}${runtime.site.basePath}/${id}` },
+			],
+		}),
+	});
+}
+
+function identifiedBackend(id: string) {
+	return defineBackendPlugin({
+		id,
+		dbPlugin: createDbPlugin(`${id}-db`, {}),
+		routes: () => ({}),
+	});
+}
+
+describe("canonical plugin registration IDs", () => {
+	it("rejects client aliases and duplicate resolved IDs before resolution", () => {
+		expect(() =>
+			createClientStack(
+				runtimeConfig({ alias: identifiedClient("actual") }) as any,
+			),
+		).toThrowError(/client.*key.*alias.*ID.*actual/i);
+
+		expect(() =>
+			createClientStack(
+				runtimeConfig({
+					first: identifiedClient("duplicate"),
+					second: identifiedClient("duplicate"),
+				}) as any,
+			),
+		).toThrowError(/client.*ID.*duplicate.*first.*second/i);
+	});
+
+	it("requires plugins to be an own client configuration property", () => {
+		const inheritedConfig = Object.assign(
+			Object.create({ plugins: { probe: identifiedClient("probe") } }),
+			{
+				api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+				site: { baseURL: "https://app.example.com", basePath: "/pages" },
+				queryClient: new QueryClient(),
+			},
+		);
+
+		expect(() => createClientStack(inheritedConfig as any)).toThrowError(
+			/plugins.*registration map/i,
+		);
+	});
+
+	it("rejects backend aliases and duplicate resolved IDs before adapter creation", () => {
+		const adapter = vi.fn(() => createMemoryAdapter(defineDb({}))({}));
+		expect(() =>
+			createBackendStack({
+				basePath: "/api/data",
+				plugins: { alias: identifiedBackend("actual") },
+				adapter,
+			} as any),
+		).toThrowError(/backend.*key.*alias.*ID.*actual/i);
+		expect(adapter).not.toHaveBeenCalled();
+
+		expect(() =>
+			createBackendStack({
+				basePath: "/api/data",
+				plugins: {
+					first: identifiedBackend("duplicate"),
+					second: identifiedBackend("duplicate"),
+				},
+				adapter,
+			} as any),
+		).toThrowError(/backend.*ID.*duplicate.*first.*second/i);
+		expect(adapter).not.toHaveBeenCalled();
+	});
+
+	it("binds provider runtime and overrides to the resolved client stack", async () => {
+		const plugin = defineClientPlugin<{ label: string }>()({
+			id: "probe",
+			resolve: (runtime) => ({
+				routes: () => ({
+					probe: createRoute("/probe", () => ({ PageComponent: () => null })),
+				}),
+				sitemap: () => [
+					{ url: `${runtime.site.baseURL}${runtime.site.basePath}/probe` },
+				],
+			}),
+		});
+		const stack = createClientStack({
+			...runtimeConfig({ probe: plugin }),
+			endpoints: { probe: { api: { basePath: "/api/probe" } } },
+		});
+		let observed:
+			| {
+					basePath: string;
+					apiBasePath?: string;
+					pluginBasePath?: string;
+					label: string;
+			  }
+			| undefined;
+
+		function Probe() {
+			const context = useStack();
+			const overrides = usePluginOverrides<{ label: string }>("probe");
+			observed = {
+				basePath: context.basePath,
+				apiBasePath: context.api?.basePath,
+				pluginBasePath: context.plugins?.probe?.api.basePath,
+				label: overrides.label,
+			};
+			return null;
+		}
+
+		renderToString(
+			<StackProvider stack={stack} overrides={{ probe: { label: "Resolved" } }}>
+				<Probe />
+			</StackProvider>,
+		);
+
+		expect(observed).toEqual({
+			basePath: "/pages",
+			apiBasePath: "/api/data",
+			pluginBasePath: "/api/probe",
+			label: "Resolved",
+		});
+		await expect(stack.generateSitemap()).resolves.toEqual([
+			{ url: "https://app.example.com/pages/probe" },
+		]);
+	});
+
+	it("uses the canonical ID in client context and route diagnostics", () => {
+		let contextPluginId: string | undefined;
+		const canonicalDefinition = defineClientPlugin({
+			id: "canonical",
+			resolve: () => ({
+				routes: (context) => {
+					contextPluginId = context?.plugins.canonical?.id;
+					return {
+						canonical: createRoute("/canonical", () => ({
+							PageComponent: () => null,
+						})),
+					};
+				},
+			}),
+		});
+
+		const stack = createClientStack(
+			runtimeConfig({ canonical: canonicalDefinition }),
+		);
+
+		expect(contextPluginId).toBe("canonical");
+		const schema = generateRouteDocsSchema(stack.context);
+		expect(schema.plugins).toMatchObject([
+			{ key: "canonical", name: "canonical" },
+		]);
+	});
+});

package/src/__tests__/plugin-registration.typecheck.tsx

@@ -0,0 +1,139 @@
+import type { DatabaseDefinition, DBAdapter } from "@btst/db";
+import { QueryClient } from "@tanstack/react-query";
+import { createBackendStack } from "../api";
+import { createClientStack } from "../client";
+import { StackProvider } from "../context";
+import {
+	createDbPlugin,
+	createEndpoint,
+	defineBackendPlugin,
+} from "../plugins/api";
+import { createRoute, defineClientPlugin } from "../plugins/client";
+
+interface ConsumerOverrides {
+	label: string;
+	format?: "short" | "long";
+}
+
+function consumerClientPlugin() {
+	return defineClientPlugin<ConsumerOverrides>()({
+		id: "consumerProbe",
+		resolve: () => ({
+			routes: () => ({
+				consumerProbe: createRoute("/consumer-probe", () => ({
+					PageComponent: () => null,
+				})),
+			}),
+		}),
+	});
+}
+
+function routeOnlyClientPlugin() {
+	return defineClientPlugin({
+		id: "routeOnly",
+		resolve: () => ({
+			routes: () => ({
+				routeOnly: createRoute("/route-only", () => ({
+					PageComponent: () => null,
+				})),
+			}),
+		}),
+	});
+}
+
+consumerClientPlugin().id satisfies "consumerProbe";
+routeOnlyClientPlugin().id satisfies "routeOnly";
+
+const queryClient = new QueryClient();
+const clientStack = createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: {
+		consumerProbe: consumerClientPlugin(),
+		routeOnly: routeOnlyClientPlugin(),
+	},
+});
+
+const routeOnlyStack = createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: { routeOnly: routeOnlyClientPlugin() },
+});
+
+<StackProvider
+	stack={clientStack}
+	router={{ navigate: () => undefined }}
+	overrides={{
+		consumerProbe: { label: "Probe", format: "short" },
+	}}
+/>;
+
+<StackProvider stack={clientStack} />;
+
+<StackProvider stack={routeOnlyStack} />;
+
+// @ts-expect-error No-override stacks do not accept activation-style empty blocks.
+<StackProvider stack={routeOnlyStack} overrides={{ routeOnly: {} }} />;
+
+<StackProvider
+	stack={clientStack}
+	overrides={{
+		consumerProbe: {
+			label: "Probe",
+			// @ts-expect-error Override values are inferred from the registered definition.
+			format: "wide",
+		},
+	}}
+/>;
+
+<StackProvider
+	stack={clientStack}
+	overrides={{
+		// @ts-expect-error Plugins without configurable fields are absent from overrides.
+		routeOnly: {},
+	}}
+/>;
+
+// @ts-expect-error Canonical providers consume API/site paths from the resolved stack.
+<StackProvider stack={clientStack} basePath="/other-pages" />;
+
+createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: {
+		// @ts-expect-error Registration keys must equal a canonical client plugin ID.
+		alias: consumerClientPlugin(),
+	},
+});
+
+function consumerBackendPlugin() {
+	return defineBackendPlugin({
+		id: "consumerProbe",
+		dbPlugin: createDbPlugin("consumer-probe-db", {}),
+		routes: () => ({
+			probe: createEndpoint("/probe", { method: "GET" }, async () => ({
+				ok: true,
+			})),
+		}),
+	});
+}
+
+consumerBackendPlugin().id satisfies "consumerProbe";
+
+createBackendStack({
+	basePath: "/api/data",
+	plugins: { consumerProbe: consumerBackendPlugin() },
+	adapter: (_db: DatabaseDefinition) => null as unknown as DBAdapter,
+});
+
+createBackendStack({
+	basePath: "/api/data",
+	plugins: {
+		// @ts-expect-error Registration keys must equal a canonical backend plugin ID.
+		alias: consumerBackendPlugin(),
+	},
+	adapter: (_db: DatabaseDefinition) => null as unknown as DBAdapter,
+});

package/src/__tests__/plugins.test.tsx

@@ -1,9 +1,14 @@
 import { describe, it, expect } from "vitest";
-import { stack } from "../api";
-import { createStackClient } from "../client";
+import { createBackendStack } from "../api";
+import { createClientStack } from "../client";
 import { defineBackendPlugin } from "../plugins/api";
 import { defineClientPlugin } from "../plugins/client";
-import type { BackendPlugin, ClientPlugin } from "../types";
+import type {
+	BackendPlugin,
+	ClientPlugin,
+	ClientPluginRegistration,
+	MatchingPluginRegistrations,
+} from "../types";
 import type {
 	BetterAuthDBSchema,
 	DatabaseDefinition,
@@ -14,6 +19,7 @@ import { createMemoryAdapter } from "@btst/adapter-memory";
 import { createEndpoint as endpoint } from "better-call";
 import { z } from "zod";
 import { createRoute } from "@btst/yar";
+import { QueryClient } from "@tanstack/react-query";
 
 /**
  * Adapter wrapper for testing
@@ -23,6 +29,20 @@ const testAdapter = (db: DatabaseDefinition): Adapter => {
 	return createMemoryAdapter(db)({});
 };
 
+function createThirdPartyClient<
+	const TPlugins extends Record<
+		string,
+		ClientPluginRegistration<any, any, any, any, any>
+	>,
+>(config: { plugins: TPlugins & MatchingPluginRegistrations<TPlugins> }) {
+	return createClientStack<TPlugins>({
+		api: { baseURL: "https://example.com", basePath: "/api" },
+		site: { baseURL: "https://example.com", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		...config,
+	});
+}
+
 /**
  * Test schema for messages plugin
  * Using BetterAuthDBSchema format
@@ -58,7 +78,7 @@ const messagesSchema: BetterAuthDBSchema = {
  * Now using defineBackendPlugin for full type inference - no casts needed!
  */
 const messagesBackendPlugin = defineBackendPlugin({
-	name: "messages",
+	id: "messages",
 	dbPlugin: createDbPlugin("messages", messagesSchema),
 	routes: (adapter) => ({
 		list: endpoint(
@@ -152,23 +172,29 @@ const messageDetailLoader = async ({ params }: { params: { id: string } }) => {
  * Using Yar's createRoute() to create proper route handlers.
  */
 const messagesClientPlugin = defineClientPlugin({
-	name: "messages",
-	routes: () => ({
-		messagesList: createRoute("/messages", () => ({
-			PageComponent: MessagesListComponent,
-			loader: messagesListLoader,
-		})),
-		messageDetail: createRoute("/messages/:id", ({ params }) => ({
-			PageComponent: MessageDetailComponent,
-			loader: () => messageDetailLoader({ params }),
-		})),
+	id: "messages",
+	resolve: () => ({
+		routes: () => ({
+			messagesList: createRoute("/messages", () => ({
+				PageComponent: MessagesListComponent,
+				loader: messagesListLoader,
+			})),
+			messageDetail: createRoute("/messages/:id", ({ params }) => ({
+				PageComponent: MessageDetailComponent,
+				loader: () => messageDetailLoader({ params }),
+			})),
+		}),
 	}),
 });
+const resolvedMessagesClientPlugin = {
+	...messagesClientPlugin.resolve({} as never),
+	id: "messages" as const,
+};
 
 describe("3rd Party Plugin Support", () => {
 	describe("Backend Plugin", () => {
 		it("should create backend with custom plugin", () => {
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -202,7 +228,7 @@ describe("3rd Party Plugin Support", () => {
 			};
 
 			const notificationsPlugin = defineBackendPlugin({
-				name: "notifications",
+				id: "notifications",
 				dbPlugin: createDbPlugin("notifications", notificationsSchema),
 				routes: (adapter) => ({
 					list: endpoint(
@@ -223,7 +249,7 @@ describe("3rd Party Plugin Support", () => {
 				}),
 			});
 
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -237,7 +263,7 @@ describe("3rd Party Plugin Support", () => {
 		});
 
 		it("should generate routes for custom plugin", () => {
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -246,13 +272,13 @@ describe("3rd Party Plugin Support", () => {
 			});
 
 			// Check that routes are properly registered
-			// The router should have routes prefixed with plugin name
+			// The router should have routes prefixed with the plugin ID.
 			expect(backend.router).toBeDefined();
 			expect(typeof backend.router.handler).toBe("function");
 		});
 
 		it("should include plugin schema in database", () => {
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -269,7 +295,7 @@ describe("3rd Party Plugin Support", () => {
 
 	describe("Client Plugin", () => {
 		it("should create client with custom plugin", () => {
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -280,7 +306,7 @@ describe("3rd Party Plugin Support", () => {
 		});
 
 		it("should have routes from custom plugin", () => {
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -293,7 +319,7 @@ describe("3rd Party Plugin Support", () => {
 
 		it("should return correct route shape with Component and loader", async () => {
 			// Test the route object directly from the plugin - types are now preserved!
-			const routes = messagesClientPlugin.routes();
+			const routes = resolvedMessagesClientPlugin.routes();
 			const listRoute = routes.messagesList;
 
 			expect(listRoute).toBeDefined();
@@ -321,7 +347,7 @@ describe("3rd Party Plugin Support", () => {
 
 		it("should return correct route shape with params", async () => {
 			// Test the route object directly from the plugin - types are now preserved!
-			const routes = messagesClientPlugin.routes();
+			const routes = resolvedMessagesClientPlugin.routes();
 			const detailRoute = routes.messageDetail;
 
 			expect(detailRoute).toBeDefined();
@@ -345,7 +371,7 @@ describe("3rd Party Plugin Support", () => {
 		});
 
 		it("should have all expected routes defined", () => {
-			const routes = messagesClientPlugin.routes();
+			const routes = resolvedMessagesClientPlugin.routes();
 
 			// Verify all expected routes exist - types are fully inferred!
 			expect(routes.messagesList).toBeDefined();
@@ -358,7 +384,7 @@ describe("3rd Party Plugin Support", () => {
 
 		it("should maintain type safety across route definitions", async () => {
 			// This test verifies that TypeScript types are preserved
-			const routes = messagesClientPlugin.routes();
+			const routes = resolvedMessagesClientPlugin.routes();
 			const route = routes.messagesList;
 
 			// Route should be a function (Yar's handler)
@@ -388,16 +414,20 @@ describe("3rd Party Plugin Support", () => {
 			};
 
 			const notificationsClientPlugin = defineClientPlugin({
-				name: "notifications",
-				routes: () => ({
-					notificationsList: createRoute("/notifications", () => ({
-						PageComponent: NotificationsComponent,
-						loader: notificationsLoader,
-					})),
+				id: "notifications",
+				resolve: () => ({
+					routes: () => ({
+						notificationsList: createRoute("/notifications", () => ({
+							PageComponent: NotificationsComponent,
+							loader: notificationsLoader,
+						})),
+					}),
 				}),
 			});
+			const resolvedNotificationsClientPlugin =
+				notificationsClientPlugin.resolve({} as never);
 
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 					notifications: notificationsClientPlugin,
@@ -408,8 +438,8 @@ describe("3rd Party Plugin Support", () => {
 			expect(client.router).toBeDefined();
 
 			// Verify both plugin routes are accessible from their definitions - full type safety!
-			const messagesRoutes = messagesClientPlugin.routes();
-			const notificationsRoutes = notificationsClientPlugin.routes();
+			const messagesRoutes = resolvedMessagesClientPlugin.routes();
+			const notificationsRoutes = resolvedNotificationsClientPlugin.routes();
 
 			expect(messagesRoutes.messagesList).toBeDefined();
 			expect(typeof messagesRoutes.messagesList).toBe("function");
@@ -425,7 +455,7 @@ describe("3rd Party Plugin Support", () => {
 		it("should use backend and client plugins independently", () => {
 			// Backend and client plugins are completely separate
 			// This prevents SSR issues and enables better code splitting
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -433,7 +463,7 @@ describe("3rd Party Plugin Support", () => {
 				adapter: testAdapter,
 			});
 
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -447,7 +477,7 @@ describe("3rd Party Plugin Support", () => {
 			// This test mimics the actual usage pattern in a Next.js app
 			// Uses router.getRoute() to match paths and get route handlers
 
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -494,7 +524,7 @@ describe("3rd Party Plugin Support", () => {
 
 		it("should handle parameterized routes correctly", async () => {
 			// Test that router.getRoute() correctly extracts path parameters
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -534,10 +564,10 @@ describe("3rd Party Plugin Support", () => {
 		it("should export all necessary types for building plugins", () => {
 			// This test verifies the types are available at compile time
 			const backendPlugin: BackendPlugin = messagesBackendPlugin;
-			const clientPlugin: ClientPlugin = messagesClientPlugin;
+			const clientPlugin: ClientPlugin = resolvedMessagesClientPlugin;
 
-			expect(backendPlugin.name).toBe("messages");
-			expect(clientPlugin.name).toBe("messages");
+			expect(backendPlugin.id).toBe("messages");
+			expect(clientPlugin.id).toBe("messages");
 		});
 	});
 });